release: 0.35.1

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
     timeout-minutes: 10
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/hyperspell-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     steps:
       - uses: actions/checkout@v6
 
@@ -43,7 +43,7 @@ jobs:
     timeout-minutes: 5
     name: build
     runs-on: ${{ github.repository == 'stainless-sdks/hyperspell-typescript' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     permissions:
       contents: read
       id-token: write

.github/workflows/publish-npm.yml

@@ -37,12 +37,14 @@ jobs:
 
       - name: Publish to NPM
         run: |
-          if [ -n "${{ github.event.inputs.path }}" ]; then
-            PATHS_RELEASED='[\"${{ github.event.inputs.path }}\"]'
+          if [ -n "$INPUT_PATH" ]; then
+            PATHS_RELEASED="[\"$INPUT_PATH\"]"
           else
             PATHS_RELEASED='[\".\", \"packages/mcp-server\"]'
           fi
           pnpm tsn scripts/publish-packages.ts "{ \"paths_released\": \"$PATHS_RELEASED\" }"
+        env:
+          INPUT_PATH: ${{ github.event.inputs.path }}
 
       - name: Upload MCP Server DXT GitHub release asset
         run: |

.gitignore

@@ -1,4 +1,5 @@
 .prism.log
+.stdy.log
 node_modules
 yarn-error.log
 codegen.log
@@ -10,3 +11,4 @@ dist-deno
 .eslintcache
 dist-bundle
 *.mcpb
+oidc

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.35.0"
+  ".": "0.35.1"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 30
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-b1f2b7cb843e6f4e6123e838ce29cbbaea0a48b1a72057632de1d0d21727c5d8.yml
-openapi_spec_hash: 21a354f587a2fe19797860c7b6da81a9
-config_hash: 0ed970a9634b33d0af471738b478740d
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-460d7c66cd5e8cf979cd761066c51d8f813a119a20e2149fcfcf847eb650d545.yml
+openapi_spec_hash: 8ee512464a88de45c86faf4f46f4905c
+config_hash: bd8505e17db740d82e578d0edaa9bfe0

CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.35.1 (2026-04-09)
+
+Full Changelog: [v0.35.0...v0.35.1](https://github.com/hyperspell/node-sdk/compare/v0.35.0...v0.35.1)
+
+### Features
+
+* add 'mood' to memory type unions ([#89](https://github.com/hyperspell/node-sdk/issues/89)) ([76d16b8](https://github.com/hyperspell/node-sdk/commit/76d16b8175736cfd019f10f7363bb0d1b9d274a0))
+* **api:** api update ([9451cde](https://github.com/hyperspell/node-sdk/commit/9451cde625b2736fee26be6e5181e6b1a0ffc5c2))
+* **api:** api update ([138925b](https://github.com/hyperspell/node-sdk/commit/138925b62920e96037ff82db171bd96b8a049a98))
+* **api:** api update ([1394392](https://github.com/hyperspell/node-sdk/commit/13943920182f9150b8222e5dc27d6fe69ecbc7eb))
+* **api:** api update ([acf8988](https://github.com/hyperspell/node-sdk/commit/acf8988fd0e5ace07a871bbc2160db7d072effab))
+* **api:** api update ([408ed83](https://github.com/hyperspell/node-sdk/commit/408ed8311554d2110d88031dad7a11f0943ce06c))
+* **api:** api update ([62d04a2](https://github.com/hyperspell/node-sdk/commit/62d04a239910847ecbc4b644a13956f9b246a506))
+* **api:** manual updates ([1b7ca39](https://github.com/hyperspell/node-sdk/commit/1b7ca39a9894d6649349ceb7d4f61de8d981c9f8))
+
+
+### Bug Fixes
+
+* **internal:** gitignore generated `oidc` dir ([a305f3d](https://github.com/hyperspell/node-sdk/commit/a305f3d8f340bbb1838b0e75ed0ca2e7da0d6cff))
+
+
+### Chores
+
+* **ci:** escape input path in publish-npm workflow ([40c8402](https://github.com/hyperspell/node-sdk/commit/40c84026a515ae0b62f676b71b8746ebfd254177))
+* **ci:** skip lint on metadata-only changes ([14012e7](https://github.com/hyperspell/node-sdk/commit/14012e72febb7af66800c6e0f4c389cf5104a1d3))
+* configure new SDK language ([2b1db35](https://github.com/hyperspell/node-sdk/commit/2b1db353a21ecb4c3200e44d7853587c90c7625c))
+* **internal:** fix MCP server import ordering ([aa4d800](https://github.com/hyperspell/node-sdk/commit/aa4d8007866d8417cb8af1c9d17c11d59d8c1d3c))
+* **internal:** fix MCP server TS errors that occur with required client options ([b7abcfb](https://github.com/hyperspell/node-sdk/commit/b7abcfb96eac3b96305957762f6cadb399236583))
+* **internal:** improve local docs search for MCP servers ([eee2438](https://github.com/hyperspell/node-sdk/commit/eee2438cecb6267496d8b068d2b6b370dcce586c))
+* **internal:** improve local docs search for MCP servers ([f218072](https://github.com/hyperspell/node-sdk/commit/f218072eee356e59cb1f7b0e3e667902acb30c79))
+* **internal:** support custom-instructions-path flag in MCP servers ([c6d4043](https://github.com/hyperspell/node-sdk/commit/c6d404331011597d4ee14440eeb71faaed16ad95))
+* **internal:** support local docs search in MCP servers ([4a9b2cf](https://github.com/hyperspell/node-sdk/commit/4a9b2cfd823fce71d3a08e435e545a97247abba5))
+* **internal:** support type annotations when running MCP in local execution mode ([41a4e6a](https://github.com/hyperspell/node-sdk/commit/41a4e6a998f03224e0aa765c348f7d4d96a98d01))
+* **internal:** update gitignore ([9270ff5](https://github.com/hyperspell/node-sdk/commit/9270ff5aac78355a25f64d1ccabb773c45120f36))
+* **internal:** update multipart form array serialization ([97f213b](https://github.com/hyperspell/node-sdk/commit/97f213bf19e619a90ca72254e6e9d407aaecb41b))
+* **mcp-server:** add support for session id, forward client info ([9e3018f](https://github.com/hyperspell/node-sdk/commit/9e3018f7649a0533788b5a9a75875dbfde5cd493))
+* **mcp-server:** log client info ([5f1ad6d](https://github.com/hyperspell/node-sdk/commit/5f1ad6d048afabe3d270edf2fd8905053a7cb29f))
+* **tests:** bump steady to v0.19.4 ([e614b67](https://github.com/hyperspell/node-sdk/commit/e614b6739cf3d7398e4d05d806ae0706c3264276))
+* **tests:** bump steady to v0.19.5 ([eadfc98](https://github.com/hyperspell/node-sdk/commit/eadfc98aa8e6dfc6728a8028f01abcb4ffe91c8c))
+* **tests:** bump steady to v0.19.6 ([4ed8bba](https://github.com/hyperspell/node-sdk/commit/4ed8bbac6d2a25580c3355ec7d5309ba18ffd3be))
+* **tests:** bump steady to v0.19.7 ([6aaa435](https://github.com/hyperspell/node-sdk/commit/6aaa43556ea42c3c3440569b051c25adda5046c7))
+* **tests:** bump steady to v0.20.1 ([bb96b8b](https://github.com/hyperspell/node-sdk/commit/bb96b8b039f8a6d906540298e31ebe3e0cd4549e))
+* **tests:** bump steady to v0.20.2 ([2a71a6e](https://github.com/hyperspell/node-sdk/commit/2a71a6e88d24933ce432279a88062fa849454586))
+* update SDK settings ([4ee9dca](https://github.com/hyperspell/node-sdk/commit/4ee9dca0d9d188abab3fabe72c5a9d2e53e49994))
+* update SDK settings ([752879e](https://github.com/hyperspell/node-sdk/commit/752879e4c937f55b93ab0da3a002e18bb71240c5))
+
+
+### Refactors
+
+* **tests:** switch from prism to steady ([75ac934](https://github.com/hyperspell/node-sdk/commit/75ac9345ea6849863c3469f24dc2393046a6dcd0))
+
 ## 0.35.0 (2026-03-18)
 
 Full Changelog: [v0.34.0...v0.35.0](https://github.com/hyperspell/node-sdk/compare/v0.34.0...v0.35.0)

CONTRIBUTING.md

@@ -65,7 +65,7 @@ $ pnpm link --global hyperspell
 
 ## Running tests
 
-Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.
+Most tests require you to [set up a mock server](https://github.com/dgellow/steady) against the OpenAPI spec to run the tests.
 
 ```sh
 $ ./scripts/mock

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperspell",
-  "version": "0.35.0",
+  "version": "0.35.1",
   "description": "The official TypeScript library for the Hyperspell API",
   "author": "Hyperspell <hello@hyperspell.com>",
   "types": "dist/index.d.ts",

packages/mcp-server/manifest.json

@@ -1,7 +1,7 @@
 {
   "dxt_version": "0.2",
   "name": "hyperspell-mcp",
-  "version": "0.35.0",
+  "version": "0.35.1",
   "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.35.0",
+  "version": "0.35.1",
   "description": "The official MCP Server for the Hyperspell API",
   "author": "Hyperspell <hello@hyperspell.com>",
   "types": "dist/index.d.ts",
@@ -40,6 +40,7 @@
     "cors": "^2.8.5",
     "express": "^5.1.0",
     "fuse.js": "^7.1.0",
+    "minisearch": "^7.2.0",
     "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz",
     "pino": "^10.3.1",
     "pino-http": "^11.0.0",

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

@@ -7,6 +7,10 @@ import ts from 'typescript';
 import { WorkerOutput } from './code-tool-types';
 import { Hyperspell, ClientOptions } from 'hyperspell';
 
+async function tseval(code: string) {
+  return import('data:application/typescript;charset=utf-8;base64,' + Buffer.from(code).toString('base64'));
+}
+
 function getRunFunctionSource(code: string): {
   type: 'declaration' | 'expression';
   client: string | undefined;
@@ -266,7 +270,9 @@ const fetch = async (req: Request): Promise<Response> => {
 
   const log_lines: string[] = [];
   const err_lines: string[] = [];
-  const console = {
+  const originalConsole = globalThis.console;
+  globalThis.console = {
+    ...originalConsole,
     log: (...args: unknown[]) => {
       log_lines.push(util.format(...args));
     },
@@ -276,7 +282,7 @@ const fetch = async (req: Request): Promise<Response> => {
   };
   try {
     let run_ = async (client: any) => {};
-    eval(`${code}\nrun_ = run;`);
+    run_ = (await tseval(`${code}\nexport default run;`)).default;
     const result = await run_(makeSdkProxy(client, { path: ['client'] }));
     return Response.json({
       is_error: false,
@@ -294,6 +300,8 @@ const fetch = async (req: Request): Promise<Response> => {
       } satisfies WorkerOutput,
       { status: 400, statusText: 'Code execution error' },
     );
+  } finally {
+    globalThis.console = originalConsole;
   }
 };
 

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

@@ -285,16 +285,14 @@ const localDenoHandler = async ({
 
       // 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 opts = {
+        ...(client.baseURL != null ? { baseURL: client.baseURL } : undefined),
+        ...(client.apiKey != null ? { apiKey: client.apiKey } : undefined),
+        ...(client.userID != null ? { userID: client.userID } : undefined),
+        defaultHeaders: {
+          'X-Stainless-MCP': 'true',
+        },
+      } satisfies Partial<ClientOptions> as ClientOptions;
 
       const req = worker.request(
         'http://localhost',

packages/mcp-server/src/docs-search-tool.ts

@@ -3,6 +3,7 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { Metadata, McpRequestContext, asTextContentResult } from './types';
 import { getLogger } from './logger';
+import type { LocalDocsSearch } from './local-docs-search';
 
 export const metadata: Metadata = {
   resource: 'all',
@@ -43,20 +44,41 @@ export const tool: Tool = {
 const docsSearchURL =
   process.env['DOCS_SEARCH_URL'] || 'https://api.stainless.com/api/projects/hyperspell/docs/search';
 
-export const handler = async ({
-  reqContext,
-  args,
-}: {
-  reqContext: McpRequestContext;
-  args: Record<string, unknown> | undefined;
-}) => {
+let _localSearch: LocalDocsSearch | undefined;
+
+export function setLocalSearch(search: LocalDocsSearch): void {
+  _localSearch = search;
+}
+
+async function searchLocal(args: Record<string, unknown>): Promise<unknown> {
+  if (!_localSearch) {
+    throw new Error('Local search not initialized');
+  }
+
+  const query = (args['query'] as string) ?? '';
+  const language = (args['language'] as string) ?? 'typescript';
+  const detail = (args['detail'] as string) ?? 'default';
+
+  return _localSearch.search({
+    query,
+    language,
+    detail,
+    maxResults: 5,
+  }).results;
+}
+
+async function searchRemote(args: Record<string, unknown>, reqContext: McpRequestContext): Promise<unknown> {
   const body = args as any;
   const query = new URLSearchParams(body).toString();
 
   const startTime = Date.now();
   const result = await fetch(`${docsSearchURL}?${query}`, {
     headers: {
       ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
+      ...(reqContext.mcpSessionId && { 'x-stainless-mcp-session-id': reqContext.mcpSessionId }),
+      ...(reqContext.mcpClientInfo && {
+        'x-stainless-mcp-client-info': JSON.stringify(reqContext.mcpClientInfo),
+      }),
     },
   });
 
@@ -94,7 +116,23 @@ export const handler = async ({
     },
     'Got docs search result',
   );
-  return asTextContentResult(resultBody);
+  return resultBody;
+}
+
+export const handler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: Record<string, unknown> | undefined;
+}) => {
+  const body = args ?? {};
+
+  if (_localSearch) {
+    return asTextContentResult(await searchLocal(body));
+  }
+
+  return asTextContentResult(await searchRemote(body, reqContext));
 };
 
 export default { metadata, tool, handler };

packages/mcp-server/src/http.ts

@@ -23,7 +23,8 @@ const newServer = async ({
   res: express.Response;
 }): Promise<McpServer | null> => {
   const stainlessApiKey = getStainlessApiKey(req, mcpOptions);
-  const server = await newMcpServer(stainlessApiKey);
+  const customInstructionsPath = mcpOptions.customInstructionsPath;
+  const server = await newMcpServer({ stainlessApiKey, customInstructionsPath });
 
   const authOptions = parseClientAuthHeaders(req, false);
 
@@ -68,6 +69,11 @@ const newServer = async ({
     }
   }
 
+  const mcpClientInfo =
+    typeof req.body?.params?.clientInfo?.name === 'string' ?
+      { name: req.body.params.clientInfo.name, version: String(req.body.params.clientInfo.version ?? '') }
+    : undefined;
+
   await initMcpServer({
     server: server,
     mcpOptions: effectiveMcpOptions,
@@ -77,8 +83,14 @@ const newServer = async ({
     },
     stainlessApiKey: stainlessApiKey,
     upstreamClientEnvs,
+    mcpSessionId: (req as any).mcpSessionId,
+    mcpClientInfo,
   });
 
+  if (mcpClientInfo) {
+    getLogger().info({ mcpSessionId: (req as any).mcpSessionId, mcpClientInfo }, 'MCP client connected');
+  }
+
   return server;
 };
 
@@ -134,9 +146,23 @@ export const streamableHTTPApp = ({
   const app = express();
   app.set('query parser', 'extended');
   app.use(express.json());
+  app.use((req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const existing = req.headers['mcp-session-id'];
+    const sessionId = (Array.isArray(existing) ? existing[0] : existing) || crypto.randomUUID();
+    (req as any).mcpSessionId = sessionId;
+    const origWriteHead = res.writeHead.bind(res);
+    res.writeHead = function (statusCode: number, ...rest: any[]) {
+      res.setHeader('mcp-session-id', sessionId);
+      return origWriteHead(statusCode, ...rest);
+    } as typeof res.writeHead;
+    next();
+  });
   app.use(
     pinoHttp({
       logger: getLogger(),
+      customProps: (req) => ({
+        mcpSessionId: (req as any).mcpSessionId,
+      }),
       customLogLevel: (req, res) => {
         if (res.statusCode >= 500) {
           return 'error';