chore(mcp): add friendlier MCP code tool errors on incorrect method invocations

Author: stainless-app[bot]

packages/mcp-server/package.json

@@ -36,6 +36,7 @@
     "@valtown/deno-http-worker": "^0.0.21",
     "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.6/jq-web.tar.gz",
     "qs": "^6.14.0",
     "typescript": "5.8.3",

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

@@ -2,6 +2,7 @@
 
 import util from 'node:util';
 
+import Fuse from 'fuse.js';
 import ts from 'typescript';
 
 import { WorkerInput, WorkerSuccess, WorkerError } from './code-tool-types';
@@ -39,8 +40,160 @@ function getRunFunctionNode(
   return null;
 }
 
+const fuse = new Fuse(
+  [
+    'client.agents.create',
+    'client.agents.createOrUpdate',
+    'client.agents.delete',
+    'client.agents.get',
+    'client.agents.list',
+    'client.agents.listModels',
+    'client.agents.reset',
+    'client.agents.update',
+    'client.agents.tools.create',
+    'client.agents.tools.delete',
+    'client.agents.tools.list',
+    'client.agents.tools.reset',
+    'client.agents.tools.update',
+    'client.agents.docs.bulkDelete',
+    'client.agents.docs.create',
+    'client.agents.docs.delete',
+    'client.agents.docs.list',
+    'client.agents.docs.search',
+    'client.files.create',
+    'client.files.delete',
+    'client.files.get',
+    'client.files.list',
+    'client.sessions.chat',
+    'client.sessions.create',
+    'client.sessions.createOrUpdate',
+    'client.sessions.delete',
+    'client.sessions.get',
+    'client.sessions.history',
+    'client.sessions.list',
+    'client.sessions.render',
+    'client.sessions.reset',
+    'client.sessions.update',
+    'client.users.create',
+    'client.users.createOrUpdate',
+    'client.users.delete',
+    'client.users.get',
+    'client.users.list',
+    'client.users.reset',
+    'client.users.update',
+    'client.users.docs.bulkDelete',
+    'client.users.docs.create',
+    'client.users.docs.delete',
+    'client.users.docs.list',
+    'client.users.docs.search',
+    'client.jobs.get',
+    'client.docs.embed',
+    'client.docs.get',
+    'client.tasks.create',
+    'client.tasks.createOrUpdate',
+    'client.tasks.get',
+    'client.tasks.list',
+    'client.executions.changeStatus',
+    'client.executions.create',
+    'client.executions.get',
+    'client.executions.list',
+    'client.executions.transitions.list',
+    'client.executions.transitions.retrieve',
+    'client.executions.transitions.stream',
+    'client.executions.status.get',
+    'client.executions.status.stream',
+    'client.secrets.create',
+    'client.secrets.delete',
+    'client.secrets.list',
+    'client.secrets.update',
+    'client.projects.create',
+    'client.projects.list',
+    'client.healthz.check',
+  ],
+  { threshold: 1, shouldSort: true },
+);
+
+function getMethodSuggestions(fullyQualifiedMethodName: string): string[] {
+  return fuse
+    .search(fullyQualifiedMethodName)
+    .map(({ item }) => item)
+    .slice(0, 5);
+}
+
+const proxyToObj = new WeakMap<any, any>();
+const objToProxy = new WeakMap<any, any>();
+
+type ClientProxyConfig = {
+  path: string[];
+  isBelievedBad?: boolean;
+};
+
+function makeSdkProxy<T extends object>(obj: T, { path, isBelievedBad = false }: ClientProxyConfig): T {
+  let proxy: T = objToProxy.get(obj);
+
+  if (!proxy) {
+    proxy = new Proxy(obj, {
+      get(target, prop, receiver) {
+        const propPath = [...path, String(prop)];
+        const value = Reflect.get(target, prop, receiver);
+
+        if (isBelievedBad || (!(prop in target) && value === undefined)) {
+          // If we're accessing a path that doesn't exist, it will probably eventually error.
+          // Let's proxy it and mark it bad so that we can control the error message.
+          // We proxy an empty class so that an invocation or construction attempt is possible.
+          return makeSdkProxy(class {}, { path: propPath, isBelievedBad: true });
+        }
+
+        if (value !== null && (typeof value === 'object' || typeof value === 'function')) {
+          return makeSdkProxy(value, { path: propPath, isBelievedBad });
+        }
+
+        return value;
+      },
+
+      apply(target, thisArg, args) {
+        if (isBelievedBad || typeof target !== 'function') {
+          const fullyQualifiedMethodName = path.join('.');
+          const suggestions = getMethodSuggestions(fullyQualifiedMethodName);
+          throw new Error(
+            `${fullyQualifiedMethodName} is not a function. Did you mean: ${suggestions.join(', ')}`,
+          );
+        }
+
+        return Reflect.apply(target, proxyToObj.get(thisArg) ?? thisArg, args);
+      },
+
+      construct(target, args, newTarget) {
+        if (isBelievedBad || typeof target !== 'function') {
+          const fullyQualifiedMethodName = path.join('.');
+          const suggestions = getMethodSuggestions(fullyQualifiedMethodName);
+          throw new Error(
+            `${fullyQualifiedMethodName} is not a constructor. Did you mean: ${suggestions.join(', ')}`,
+          );
+        }
+
+        return Reflect.construct(target, args, newTarget);
+      },
+    });
+
+    objToProxy.set(obj, proxy);
+    proxyToObj.set(proxy, obj);
+  }
+
+  return proxy;
+}
+
 const fetch = async (req: Request): Promise<Response> => {
   const { opts, code } = (await req.json()) as WorkerInput;
+  if (code == null) {
+    return Response.json(
+      {
+        message:
+          'The code param is missing. Provide one containing a top-level `run` function. Write code within this template:\n\n```\nasync function run(client) {\n  // Fill this out\n}\n```',
+      } satisfies WorkerError,
+      { status: 400, statusText: 'Code execution error' },
+    );
+  }
 
   const runFunctionNode = getRunFunctionNode(code);
   if (!runFunctionNode) {
@@ -73,7 +226,7 @@ const fetch = async (req: Request): Promise<Response> => {
       ${code}
       run_ = run;
     `);
-    const result = await run_(client);
+    const result = await run_(makeSdkProxy(client, { path: ['client'] }));
     return Response.json({
       result,
       logLines,

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

@@ -23,7 +23,7 @@ export async function codeTool(): Promise<Endpoint> {
   const tool: Tool = {
     name: 'execute',
     description:
-      'Runs TypeScript code to interact with the API.\nYou are a skilled programmer writing code to interface with the service.\nDefine an async function named "run" that takes a single parameter of an initialized client, and it will be run.\nDo not initialize a client, but instead use the client that you are given as a parameter.\nYou will be returned anything that your function returns, plus the results of any console.log statements.\nIf any code triggers an error, the tool will return an error response, so you do not need to add error handling unless you want to output something more helpful than the raw error.\nIt is not necessary to add comments to code, unless by adding those comments you believe that you can generate better code.\nThis code will run in a container, and you will not be able to use fetch or otherwise interact with the network calls other than through the client you are given.\nAny variables you define won\'t live between successive uses of this call, so make sure to return or log any data you might need later.',
+      'Runs TypeScript code to interact with the API.\n\nYou are a skilled programmer writing code to interface with the service.\nDefine an async function named "run" that takes a single parameter of an initialized client named "client", and it will be run.\nWrite code within this template:\n\n```\nasync function run(client) {\n  // Fill this out\n}\n```\n\nYou will be returned anything that your function returns, plus the results of any console.log statements.\nIf any code triggers an error, the tool will return an error response, so you do not need to add error handling unless you want to output something more helpful than the raw error.\nIt is not necessary to add comments to code, unless by adding those comments you believe that you can generate better code.\nThis code will run in a container, and you will not be able to use fetch or otherwise interact with the network calls other than through the client you are given.\nAny variables you define won\'t live between successive uses of this call, so make sure to return or log any data you might need later.',
     inputSchema: { type: 'object', properties: { code: { type: 'string' } } },
   };