release: 0.33.0

.github/workflows/ci.yml

@@ -55,22 +55,28 @@ jobs:
         run: ./scripts/build
 
       - name: Get GitHub OIDC Token
-        if: github.repository == 'stainless-sdks/hyperspell-typescript'
+        if: |-
+          github.repository == 'stainless-sdks/hyperspell-typescript' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
         id: github-oidc
         uses: actions/github-script@v8
         with:
           script: core.setOutput('github_token', await core.getIDToken());
 
       - name: Upload tarball
-        if: github.repository == 'stainless-sdks/hyperspell-typescript'
+        if: |-
+          github.repository == 'stainless-sdks/hyperspell-typescript' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
         env:
           URL: https://pkg.stainless.com/s
           AUTH: ${{ steps.github-oidc.outputs.github_token }}
           SHA: ${{ github.sha }}
         run: ./scripts/utils/upload-artifact.sh
 
       - name: Upload MCP Server tarball
-        if: github.repository == 'stainless-sdks/hyperspell-typescript'
+        if: |-
+          github.repository == 'stainless-sdks/hyperspell-typescript' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
         env:
           URL: https://pkg.stainless.com/s?subpackage=mcp-server
           AUTH: ${{ steps.github-oidc.outputs.github_token }}

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.32.1"
+  ".": "0.33.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 23
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-ca07e6605f61ae00e12be55df648b38e467a31d505fdeec7879c8a9ea9e1b390.yml
-openapi_spec_hash: 25915d4fcda54adbd8a7f106d8af2d65
-config_hash: fd3005a8f140e5baadd3d25b3c9cd79f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-e94268bb224f0aa46f151c81dba49c8def81c73b48da8a6f31b4f8a60aa5055c.yml
+openapi_spec_hash: 2e2f8148f72a724fbafd05c51b7a62c9
+config_hash: b387daed43fa717ef3ac5811ae06307c

CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.33.0 (2026-03-14)
+
+Full Changelog: [v0.32.1...v0.33.0](https://github.com/hyperspell/node-sdk/compare/v0.32.1...v0.33.0)
+
+### Features
+
+* **api:** api update ([a36859a](https://github.com/hyperspell/node-sdk/commit/a36859af78f57d190f59bbf9352a3412dfff5356))
+* **api:** api update ([f00dec6](https://github.com/hyperspell/node-sdk/commit/f00dec64dd7b4a8fa5bdbb52ee383149d6326898))
+* **api:** api update ([c5c7f31](https://github.com/hyperspell/node-sdk/commit/c5c7f31a366080de58b305429d0bcb84dec91493))
+* **api:** manual updates ([7340a84](https://github.com/hyperspell/node-sdk/commit/7340a849189533a89d897d4dc87a890aa0abf73b))
+
+
+### Bug Fixes
+
+* **client:** preserve URL params already embedded in path ([af6d83b](https://github.com/hyperspell/node-sdk/commit/af6d83b7176a0e8672c1ee54a6db5a4bd48d4bd9))
+
+
+### Chores
+
+* **ci:** skip uploading artifacts on stainless-internal branches ([6a453f9](https://github.com/hyperspell/node-sdk/commit/6a453f9854dd43f6ee2d20674cd31e72743327f4))
+* **internal:** bump @modelcontextprotocol/sdk, @hono/node-server, and minimatch ([16f74a7](https://github.com/hyperspell/node-sdk/commit/16f74a7124c551479b49242ca83b595c85712b20))
+* **internal:** codegen related update ([c49250c](https://github.com/hyperspell/node-sdk/commit/c49250ccd40e962f760fcec44f6ecd85856a1578))
+* **internal:** codegen related update ([e7684c4](https://github.com/hyperspell/node-sdk/commit/e7684c45c0ad25bf0015ccd24d98ea182f8d6055))
+* **internal:** make generated MCP servers compatible with Cloudflare worker environments ([35c5ba8](https://github.com/hyperspell/node-sdk/commit/35c5ba8825288782602fce19cd250aa17d7fa6e4))
+* **internal:** support x-stainless-mcp-client-envs header in MCP servers ([632cb03](https://github.com/hyperspell/node-sdk/commit/632cb03f6161d2c38c78c33753de58f84e97e9b6))
+* **internal:** update dependencies to address dependabot vulnerabilities ([8879f0c](https://github.com/hyperspell/node-sdk/commit/8879f0cbd229d4d09417b38c11a4439380af80ac))
+* **internal:** use x-stainless-mcp-client-envs header for MCP remote code tool calls ([f8b4ea0](https://github.com/hyperspell/node-sdk/commit/f8b4ea07e91449a9262938777c8c32a3b30c9aba))
+* **mcp-server:** improve instructions ([604dcdd](https://github.com/hyperspell/node-sdk/commit/604dcddc6a332f9990e06eacf0edcb64bb2fd171))
+* **mcp-server:** return access instructions for 404 without API key ([2750b02](https://github.com/hyperspell/node-sdk/commit/2750b02b4f1e091728ed4c9d202cd3387ed51294))
+* **test:** do not count install time for mock server timeout ([1d19a8e](https://github.com/hyperspell/node-sdk/commit/1d19a8e8ca7be9782a217c28f12c0329931a725d))
+* update placeholder string ([b91b593](https://github.com/hyperspell/node-sdk/commit/b91b5935f49d8d5be04738bd2cda7dce878ea736))
+
 ## 0.32.1 (2026-03-02)
 
 Full Changelog: [v0.32.0...v0.32.1](https://github.com/hyperspell/node-sdk/compare/v0.32.0...v0.32.1)

README.md

@@ -170,7 +170,7 @@ You can use the `for await … of` syntax to iterate through items across all pa
 async function fetchAllMemoryListResponses(params) {
   const allMemoryListResponses = [];
   // Automatically fetches more pages as needed.
-  for await (const memoryListResponse of client.memories.list({ collection: 'REPLACE_ME' })) {
+  for await (const memoryListResponse of client.memories.list()) {
     allMemoryListResponses.push(memoryListResponse);
   }
   return allMemoryListResponses;
@@ -180,7 +180,7 @@ async function fetchAllMemoryListResponses(params) {
 Alternatively, you can request a single page at a time:
 
 ```ts
-let page = await client.memories.list({ collection: 'REPLACE_ME' });
+let page = await client.memories.list();
 for (const memoryListResponse of page.items) {
   console.log(memoryListResponse);
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperspell",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "The official TypeScript library for the Hyperspell API",
   "author": "Hyperspell <hello@hyperspell.com>",
   "types": "dist/index.d.ts",
@@ -53,6 +53,17 @@
   "bin": {
     "hyperspell": "bin/cli"
   },
+  "overrides": {
+    "minimatch": "^9.0.5"
+  },
+  "pnpm": {
+    "overrides": {
+      "minimatch": "^9.0.5"
+    }
+  },
+  "resolutions": {
+    "minimatch": "^9.0.5"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.mjs",

packages/mcp-server/manifest.json

@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.2",
   "name": "hyperspell-mcp",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "The official MCP Server for the Hyperspell API",
   "author": {
     "name": "Hyperspell",

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperspell-mcp",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "The official MCP Server for the Hyperspell API",
   "author": "Hyperspell <hello@hyperspell.com>",
   "types": "dist/index.d.ts",
@@ -26,21 +26,25 @@
     "format": "prettier --write --cache --cache-strategy metadata . !dist",
     "prepare": "npm run build",
     "tsn": "ts-node -r tsconfig-paths/register",
-    "lint": "eslint --ext ts,js .",
-    "fix": "eslint --fix --ext ts,js ."
+    "lint": "eslint .",
+    "fix": "eslint --fix ."
   },
   "dependencies": {
     "hyperspell": "file:../../dist/",
+    "ajv": "^8.18.0",
     "@cloudflare/cabidela": "^0.2.4",
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@hono/node-server": "^1.19.10",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "hono": "^4.12.4",
     "@valtown/deno-http-worker": "^0.0.21",
     "cookie-parser": "^1.4.6",
     "cors": "^2.8.5",
     "express": "^5.1.0",
     "fuse.js": "^7.1.0",
     "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz",
-    "morgan": "^1.10.0",
-    "morgan-body": "^2.6.9",
+    "pino": "^10.3.1",
+    "pino-http": "^11.0.0",
+    "pino-pretty": "^13.1.3",
     "qs": "^6.14.1",
     "typescript": "5.8.3",
     "yargs": "^17.7.2",
@@ -57,14 +61,13 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^29.4.0",
-    "@types/morgan": "^1.9.10",
     "@types/qs": "^6.14.0",
     "@types/yargs": "^17.0.8",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
-    "eslint": "^8.49.0",
-    "eslint-plugin-prettier": "^5.0.1",
-    "eslint-plugin-unused-imports": "^3.0.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-prettier": "^5.4.1",
+    "eslint-plugin-unused-imports": "^4.1.4",
     "jest": "^29.4.0",
     "prettier": "^3.0.0",
     "ts-jest": "^29.1.0",

packages/mcp-server/src/code-tool-paths.cts

@@ -1,3 +1,5 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export const workerPath = require.resolve('./code-tool-worker.mjs');
+export function getWorkerPath(): string {
+  return require.resolve('./code-tool-worker.mjs');
+}

packages/mcp-server/src/code-tool.ts

@@ -1,10 +1,5 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import fs from 'node:fs';
-import path from 'node:path';
-import url from 'node:url';
-import { newDenoHTTPWorker } from '@valtown/deno-http-worker';
-import { workerPath } from './code-tool-paths.cjs';
 import {
   ContentBlock,
   McpRequestContext,
@@ -17,6 +12,7 @@ import {
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { readEnv, requireValue } from './util';
 import { WorkerInput, WorkerOutput } from './code-tool-types';
+import { getLogger } from './logger';
 import { SdkMethod } from './methods';
 import { McpCodeExecutionMode } from './options';
 import { ClientOptions } from 'hyperspell';
@@ -83,6 +79,8 @@ export function codeTool({
     },
   };
 
+  const logger = getLogger();
+
   const handler = async ({
     reqContext,
     args,
@@ -107,11 +105,27 @@ export function codeTool({
       }
     }
 
+    let result: ToolCallResult;
+    const startTime = Date.now();
+
     if (codeExecutionMode === 'local') {
-      return await localDenoHandler({ reqContext, args });
+      logger.debug('Executing code in local Deno environment');
+      result = await localDenoHandler({ reqContext, args });
     } else {
-      return await remoteStainlessHandler({ reqContext, args });
+      logger.debug('Executing code in remote Stainless environment');
+      result = await remoteStainlessHandler({ reqContext, args });
     }
+
+    logger.info(
+      {
+        codeExecutionMode,
+        durationMs: Date.now() - startTime,
+        isError: result.isError,
+        contentRows: result.content?.length ?? 0,
+      },
+      'Got code tool execution result',
+    );
+    return result;
   };
 
   return { metadata, tool, handler };
@@ -130,19 +144,23 @@ const remoteStainlessHandler = async ({
 
   const codeModeEndpoint = readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
 
+  const localClientEnvs = {
+    HYPERSPELL_API_KEY: requireValue(
+      readEnv('HYPERSPELL_API_KEY') ?? client.apiKey,
+      'set HYPERSPELL_API_KEY environment variable or provide apiKey client option',
+    ),
+    HYPERSPELL_BASE_URL: readEnv('HYPERSPELL_BASE_URL') ?? client.baseURL ?? undefined,
+  };
+  // Merge any upstream client envs from the request header, with upstream values taking precedence.
+  const mergedClientEnvs = { ...localClientEnvs, ...reqContext.upstreamClientEnvs };
+
   // Setting a Stainless API key authenticates requests to the code tool endpoint.
   const res = await fetch(codeModeEndpoint, {
     method: 'POST',
     headers: {
       ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
       'Content-Type': 'application/json',
-      client_envs: JSON.stringify({
-        HYPERSPELL_API_KEY: requireValue(
-          readEnv('HYPERSPELL_API_KEY') ?? client.apiKey,
-          'set HYPERSPELL_API_KEY environment variable or provide apiKey client option',
-        ),
-        HYPERSPELL_BASE_URL: readEnv('HYPERSPELL_BASE_URL') ?? client.baseURL ?? undefined,
-      }),
+      'x-stainless-mcp-client-envs': JSON.stringify(mergedClientEnvs),
     },
     body: JSON.stringify({
       project_name: 'hyperspell',
@@ -153,6 +171,11 @@ const remoteStainlessHandler = async ({
   });
 
   if (!res.ok) {
+    if (res.status === 404 && !reqContext.stainlessApiKey) {
+      throw new Error(
+        'Could not access code tool for this project. You may need to provide a Stainless API key via the STAINLESS_API_KEY environment variable, the --stainless-api-key flag, or the x-stainless-api-key HTTP header.',
+      );
+    }
     throw new Error(
       `${res.status}: ${
         res.statusText
@@ -180,6 +203,13 @@ const localDenoHandler = async ({
   reqContext: McpRequestContext;
   args: unknown;
 }): Promise<ToolCallResult> => {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const url = await import('node:url');
+  const { newDenoHTTPWorker } = await import('@valtown/deno-http-worker');
+  const { getWorkerPath } = await import('./code-tool-paths.cjs');
+  const workerPath = getWorkerPath();
+
   const client = reqContext.client;
   const baseURLHostname = new URL(client.baseURL).hostname;
   const { code } = args as { code: string };
@@ -241,6 +271,9 @@ const localDenoHandler = async ({
     printOutput: true,
     spawnOptions: {
       cwd: path.dirname(workerPath),
+      // Merge any upstream client envs into the Deno subprocess environment,
+      // with the upstream env vars taking precedence.
+      env: { ...process.env, ...reqContext.upstreamClientEnvs },
     },
   });
 
@@ -250,14 +283,18 @@ const localDenoHandler = async ({
         reject(new Error(`Worker exited with code ${exitCode}`));
       });
 
-      const opts: ClientOptions = {
-        baseURL: client.baseURL,
-        apiKey: client.apiKey,
-        userID: client.userID,
-        defaultHeaders: {
-          'X-Stainless-MCP': 'true',
-        },
-      };
+      // Strip null/undefined values so that the worker SDK client can fall back to
+      // reading from environment variables (including any upstreamClientEnvs).
+      const opts: ClientOptions = Object.fromEntries(
+        Object.entries({
+          baseURL: client.baseURL,
+          apiKey: client.apiKey,
+          userID: client.userID,
+          defaultHeaders: {
+            'X-Stainless-MCP': 'true',
+          },
+        }).filter(([_, v]) => v != null),
+      ) as ClientOptions;
 
       const req = worker.request(
         'http://localhost',