release: 4.2.3

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.2.2"
+  ".": "4.2.3"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 15
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-0763b61997721da6f4514241bf0f7bb5f7a88c7298baf0f1b2d58036aaf7e2f1.yml
-openapi_spec_hash: 5158475919c04bb52fb03c6a4582188d
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-bea2e5f3b01053a66261a824c75c2640856d0ba00ad795ab71734c4ab9ae33b0.yml
+openapi_spec_hash: d766f6e344c12ca6d23e6ef6713b38c4
 config_hash: 5fa7ded4bfdffe4cc1944a819da87f9f

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 4.2.3 (2025-11-08)
+
+Full Changelog: [v4.2.2...v4.2.3](https://github.com/beeper/desktop-api-js/compare/v4.2.2...v4.2.3)
+
+### Features
+
+* **api:** add `description` field to chats, make `title` optional ([b18ee1e](https://github.com/beeper/desktop-api-js/commit/b18ee1edc0d59fedaf31c71f7d5cae677061d1e6))
+* **mcp:** enable optional code execution tool on http mcp servers ([02de91e](https://github.com/beeper/desktop-api-js/commit/02de91e3fd9b820b471fa31690da7b1de98dda07))
+
+
+### Bug Fixes
+
+* **mcpb:** pin @anthropic-ai/mcpb version ([7592b25](https://github.com/beeper/desktop-api-js/commit/7592b25fd496231d0991b74ef1b4887235edba5e))
+
+
+### Chores
+
+* **internal:** codegen related update ([e45eb2c](https://github.com/beeper/desktop-api-js/commit/e45eb2ce64c47e5e1558d9558ead0fd21e40a447))
+* **internal:** codegen related update ([06efc95](https://github.com/beeper/desktop-api-js/commit/06efc9525352b8deec8fa9cc8180c02cd1ebb139))
+* **internal:** grammar fix (it's -> its) ([10090e9](https://github.com/beeper/desktop-api-js/commit/10090e9af4b4aefa51df078357710493f518888f))
+* mcp code tool explicit error message when missing a run function ([1bc0f3e](https://github.com/beeper/desktop-api-js/commit/1bc0f3ee57009ecb1e4153165feac2c5fc74ff3b))
+* **mcp:** add friendlier MCP code tool errors on incorrect method invocations ([a2c4ebe](https://github.com/beeper/desktop-api-js/commit/a2c4ebef0fb8d807348281385a856bb73f1bc0e2))
+* **mcp:** add line numbers to code tool errors ([e9eb036](https://github.com/beeper/desktop-api-js/commit/e9eb036ce4bef49f1a9f2c18c1509e4a83f1e604))
+* use structured error when code execution tool errors ([ee2d35b](https://github.com/beeper/desktop-api-js/commit/ee2d35be66aa8dd332c69ac8ec1b83fd2cbb8d49))
+
+
+### Documentation
+
+* **mcp:** add a README button for one-click add to Cursor ([238e178](https://github.com/beeper/desktop-api-js/commit/238e1787c5d6e34cf49def65b2de48fefd2822c7))
+* **mcp:** add a README link to add server to VS Code or Claude Code ([0f7efe8](https://github.com/beeper/desktop-api-js/commit/0f7efe85bbbbcfd50c472f4654bb8b2bf8fb991a))
+
 ## 4.2.2 (2025-10-18)
 
 Full Changelog: [v4.2.1...v4.2.2](https://github.com/beeper/desktop-api-js/compare/v4.2.1...v4.2.2)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeper/desktop-api",
-  "version": "4.2.2",
+  "version": "4.2.3",
   "description": "The official TypeScript library for the Beeper Desktop API",
   "author": "Beeper Desktop <[email protected]>",
   "types": "dist/index.d.ts",

packages/mcp-server/README.md

@@ -36,12 +36,36 @@ For clients with a configuration JSON, it might look something like this:
 }
 ```
 
+### Cursor
+
+If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables
+in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=@beeper/desktop-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBiZWVwZXIvZGVza3RvcC1tY3AiXSwiZW52Ijp7IkJFRVBFUl9BQ0NFU1NfVE9LRU4iOiJTZXQgeW91ciBCRUVQRVJfQUNDRVNTX1RPS0VOIGhlcmUuIn19)
+
+### VS Code
+
+If you use MCP, you can install the MCP server by clicking the link below. You will need to set your environment variables
+in VS Code's `mcp.json`, which can be found via Command Palette > MCP: Open User Configuration.
+
+[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40beeper%2Fdesktop-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40beeper%2Fdesktop-mcp%22%5D%2C%22env%22%3A%7B%22BEEPER_ACCESS_TOKEN%22%3A%22Set%20your%20BEEPER_ACCESS_TOKEN%20here.%22%7D%7D)
+
+### Claude Code
+
+If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your
+environment variables in Claude Code's `.claude.json`, which can be found in your home directory.
+
+```
+claude mcp add --transport stdio beeper_desktop_api_api --env BEEPER_ACCESS_TOKEN="Your BEEPER_ACCESS_TOKEN here." -- npx -y @beeper/desktop-mcp
+```
+
 ## Exposing endpoints to your MCP Client
 
-There are two ways to expose endpoints as tools in the MCP server:
+There are three ways to expose endpoints as tools in the MCP server:
 
 1. Exposing one tool per endpoint, and filtering as necessary
 2. Exposing a set of tools to dynamically discover and invoke endpoints from the API
+3. Exposing a docs search tool and a code execution tool, allowing the client to write code to be executed against the TypeScript client
 
 ### Filtering endpoints and tools
 
@@ -77,6 +101,18 @@ All of these command-line options can be repeated, combined together, and have c
 
 Use `--list` to see the list of available tools, or see below.
 
+### Code execution
+
+If you specify `--tools=code` to the MCP server, it will expose just two tools:
+
+- `search_docs` - Searches the API documentation and returns a list of markdown results
+- `execute` - Runs code against the TypeScript client
+
+This allows the LLM to implement more complex logic by chaining together many API calls without loading
+intermediary results into its context window.
+
+The code execution itself happens in a Deno sandbox that has network access only to the base URL for the API.
+
 ### Specifying the MCP Client
 
 Different clients have varying abilities to handle arbitrary tools and schemas.

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeper/desktop-mcp",
-  "version": "4.2.2",
+  "version": "4.2.3",
   "description": "The official MCP Server for the Beeper Desktop API",
   "author": "Beeper Desktop <[email protected]>",
   "types": "dist/index.d.ts",
@@ -37,8 +37,10 @@
     "cors": "^2.8.5",
     "date-fns": "^4.1.0",
     "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",
     "yargs": "^17.7.2",
     "zod": "^3.25.20",
     "zod-to-json-schema": "^3.24.5",
@@ -48,7 +50,7 @@
     "mcp-server": "dist/index.js"
   },
   "devDependencies": {
-    "@anthropic-ai/mcpb": "^1.1.0",
+    "@anthropic-ai/mcpb": "1.1.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^29.4.0",
@@ -65,8 +67,7 @@
     "ts-morph": "^19.0.0",
     "ts-node": "^10.5.0",
     "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.9/tsc-multi.tgz",
-    "tsconfig-paths": "^4.0.0",
-    "typescript": "5.8.3"
+    "tsconfig-paths": "^4.0.0"
   },
   "imports": {
     "@beeper/desktop-mcp": ".",

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

@@ -1,11 +1,178 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import util from 'node:util';
+
+import Fuse from 'fuse.js';
+import ts from 'typescript';
+
 import { WorkerInput, WorkerSuccess, WorkerError } from './code-tool-types';
 import { BeeperDesktop } from '@beeper/desktop-api';
 
+function getRunFunctionNode(
+  code: string,
+): ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | null {
+  const sourceFile = ts.createSourceFile('code.ts', code, ts.ScriptTarget.Latest, true);
+
+  for (const statement of sourceFile.statements) {
+    // Check for top-level function declarations
+    if (ts.isFunctionDeclaration(statement)) {
+      if (statement.name?.text === 'run') {
+        return statement;
+      }
+    }
+
+    // Check for variable declarations: const run = () => {} or const run = function() {}
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name) && declaration.name.text === 'run') {
+          // Check if it's initialized with a function
+          if (
+            declaration.initializer &&
+            (ts.isFunctionExpression(declaration.initializer) || ts.isArrowFunction(declaration.initializer))
+          ) {
+            return declaration.initializer;
+          }
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+const fuse = new Fuse(
+  [
+    'client.focus',
+    'client.search',
+    'client.accounts.list',
+    'client.accounts.contacts.search',
+    'client.chats.archive',
+    'client.chats.create',
+    'client.chats.list',
+    'client.chats.retrieve',
+    'client.chats.search',
+    'client.chats.reminders.create',
+    'client.chats.reminders.delete',
+    'client.messages.list',
+    'client.messages.search',
+    'client.messages.send',
+    'client.assets.download',
+  ],
+  { 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;
+}
+
+function parseError(code: string, error: unknown): string | undefined {
+  if (!(error instanceof Error)) return;
+  const message = error.name ? `${error.name}: ${error.message}` : error.message;
+  try {
+    // Deno uses V8; the first "<anonymous>:LINE:COLUMN" is the top of stack.
+    const lineNumber = error.stack?.match(/<anonymous>:([0-9]+):[0-9]+/)?.[1];
+    // -1 for the zero-based indexing
+    const line =
+      lineNumber &&
+      code
+        .split('\n')
+        .at(parseInt(lineNumber, 10) - 1)
+        ?.trim();
+    return line ? `${message}\n  at line ${lineNumber}\n    ${line}` : message;
+  } catch {
+    return message;
+  }
+}
+
 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) {
+    return Response.json(
+      {
+        message:
+          'The code is missing 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 client = new BeeperDesktop({
     ...opts,
   });
@@ -22,21 +189,17 @@ const fetch = async (req: Request): Promise<Response> => {
   };
   try {
     let run_ = async (client: any) => {};
-    eval(`
-      ${code}
-      run_ = run;
-    `);
-    const result = await run_(client);
+    eval(`${code}\nrun_ = run;`);
+    const result = await run_(makeSdkProxy(client, { path: ['client'] }));
     return Response.json({
       result,
       logLines,
       errLines,
     } satisfies WorkerSuccess);
   } catch (e) {
-    const message = e instanceof Error ? e.message : undefined;
     return Response.json(
       {
-        message,
+        message: parseError(code, e),
       } satisfies WorkerError,
       { status: 400, statusText: 'Code execution error' },
     );