release: 0.1.5

.github/workflows/ci.yml

@@ -75,7 +75,7 @@ jobs:
           URL: https://pkg.stainless.com/s?subpackage=mcp-server
           AUTH: ${{ steps.github-oidc.outputs.github_token }}
           SHA: ${{ github.sha }}
-          BUILD_PATH: packages/mcp-server/dist
+          BASE_PATH: packages/mcp-server
         run: ./scripts/utils/upload-artifact.sh
   test:
     timeout-minutes: 10

.github/workflows/publish-npm.yml

@@ -16,6 +16,8 @@ jobs:
   publish:
     name: publish
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
 
     steps:
       - uses: actions/checkout@v4
@@ -39,3 +41,10 @@ jobs:
           yarn tsn scripts/publish-packages.ts "{ \"paths_released\": \"$PATHS_RELEASED\" }"
         env:
           NPM_TOKEN: ${{ secrets.BEEPER_DESKTOP_NPM_TOKEN || secrets.NPM_TOKEN }}
+
+      - name: Upload MCP Server DXT GitHub release asset
+        run: |
+          gh release upload ${{ github.event.release.tag_name }} \
+            packages/mcp-server/beeper_desktop_api_api.mcpb
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -7,4 +7,5 @@ dist
 dist-deno
 /*.tgz
 .idea/
-
+dist-bundle
+*.mcpb

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.4"
+  ".": "0.1.5"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 11
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-097cbf5de83619d0b40ba59377494db32816f2a5369d4e986a94568f3d79c7c8.yml
-openapi_spec_hash: cbb791aa1e4b75740911af7a0d93529d
-config_hash: 35aeee58f2bef9a9f5354e4c8504e26e
+configured_endpoints: 14
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-8c712fe19f280b0b89ecc8a3ce61e9f6b165cee97ce33f66c66a7a5db339c755.yml
+openapi_spec_hash: 1ea71129cc1a1ccc3dc8a99566082311
+config_hash: 061b75b88f80bb43b4121e5e7c1255e2

CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.1.5 (2025-09-19)
+
+Full Changelog: [v0.1.4...v0.1.5](https://github.com/beeper/desktop-api-js/compare/v0.1.4...v0.1.5)
+
+### Features
+
+* **api:** fix typo in bearerAuth ([76ac2e1](https://github.com/beeper/desktop-api-js/commit/76ac2e16ba6422053a24de98270016f90abe77a7))
+* **api:** manual updates ([3c711d9](https://github.com/beeper/desktop-api-js/commit/3c711d9190aed783a3c80c994bdc1a44107cd1be))
+* **api:** manual updates ([6f43810](https://github.com/beeper/desktop-api-js/commit/6f43810bf528676498df6ee81380fdf181ef5363))
+* **api:** manual updates ([2bc9e1b](https://github.com/beeper/desktop-api-js/commit/2bc9e1b7b6006cf9341b0bbf7ad5fba6ae482822))
+* **api:** manual updates ([49f039b](https://github.com/beeper/desktop-api-js/commit/49f039bbfb9080e425ea0756bdab767107de711d))
+* **api:** small tweaks ([ab7267b](https://github.com/beeper/desktop-api-js/commit/ab7267b120d2f009050bf8944cb43f6a27631de5))
+* **mcp:** add docs search tool ([d90bd86](https://github.com/beeper/desktop-api-js/commit/d90bd86e672737b397e15d388f4e9ad1a8bd43e3))
+* **mcp:** allow setting logging level ([6f2169f](https://github.com/beeper/desktop-api-js/commit/6f2169fd4bb1aaf12dbc7765c304fc9b722b0c32))
+* **mcp:** expose client options in `streamableHTTPApp` ([9afd751](https://github.com/beeper/desktop-api-js/commit/9afd7510b1c96fe5624d1f37f84521c1be1a6353))
+
+
+### Bug Fixes
+
+* **ci:** set permissions for DXT publish action ([5a6b63d](https://github.com/beeper/desktop-api-js/commit/5a6b63d7d7ba2514901ff5524890294feeaa981c))
+* coerce nullable values to undefined ([f43ac68](https://github.com/beeper/desktop-api-js/commit/f43ac6875858be2d27c31cbe7acc3d1fbac76c40))
+* **mcp:** fix query options parsing ([4f00241](https://github.com/beeper/desktop-api-js/commit/4f00241e35309ff7441fd842ba787a87caf17cae))
+* **mcp:** fix uploading dxt release assets ([1189099](https://github.com/beeper/desktop-api-js/commit/118909952860f420b4bc3f63b3de7e31d486c967))
+
+
+### Chores
+
+* ci build action ([b63fda2](https://github.com/beeper/desktop-api-js/commit/b63fda25086cfcc8758df9b5fcb32b49a78df28c))
+* **internal:** codegen related update ([b244e26](https://github.com/beeper/desktop-api-js/commit/b244e2647d3fd792e3764127ebdd8dc0c0f6df7f))
+* **internal:** codegen related update ([b961076](https://github.com/beeper/desktop-api-js/commit/b961076bf7533638f00eebb1b2a81508db35ad7b))
+* **internal:** codegen related update ([dd44c80](https://github.com/beeper/desktop-api-js/commit/dd44c803559a85fe7bc1f34fe7a5c4a356ec3460))
+* **internal:** gitignore .mcpb files ([5a8ade3](https://github.com/beeper/desktop-api-js/commit/5a8ade3b8c2fff3764893114e5eb862604fc5c6b))
+* **mcp:** rename dxt to mcpb ([343d030](https://github.com/beeper/desktop-api-js/commit/343d0303c26c103a763be49e7319bee88aa71b7e))
+* **mcp:** upload dxt as release asset ([55f6005](https://github.com/beeper/desktop-api-js/commit/55f6005d92b7f26a46c49ba76f17f7ea34b8c4b9))
+
 ## 0.1.4 (2025-09-01)
 
 Full Changelog: [v0.1.3...v0.1.4](https://github.com/beeper/desktop-api-js/compare/v0.1.3...v0.1.4)

api.md

@@ -24,20 +24,36 @@ Methods:
 
 Types:
 
+- <code><a href="./src/resources/app.ts">AppDownloadAssetResponse</a></code>
 - <code><a href="./src/resources/app.ts">AppOpenResponse</a></code>
+- <code><a href="./src/resources/app.ts">AppSearchResponse</a></code>
 
 Methods:
 
+- <code title="post /v0/download-asset">client.app.<a href="./src/resources/app.ts">downloadAsset</a>({ ...params }) -> AppDownloadAssetResponse</code>
 - <code title="post /v0/open-app">client.app.<a href="./src/resources/app.ts">open</a>({ ...params }) -> AppOpenResponse</code>
+- <code title="get /v0/search">client.app.<a href="./src/resources/app.ts">search</a>({ ...params }) -> AppSearchResponse</code>
+
+# Contacts
+
+Types:
+
+- <code><a href="./src/resources/contacts.ts">ContactSearchResponse</a></code>
+
+Methods:
+
+- <code title="get /v0/search-users">client.contacts.<a href="./src/resources/contacts.ts">search</a>({ ...params }) -> ContactSearchResponse</code>
 
 # Chats
 
 Types:
 
 - <code><a href="./src/resources/chats/chats.ts">Chat</a></code>
+- <code><a href="./src/resources/chats/chats.ts">ChatCreateResponse</a></code>
 
 Methods:
 
+- <code title="post /v0/create-chat">client.chats.<a href="./src/resources/chats/chats.ts">create</a>({ ...params }) -> ChatCreateResponse</code>
 - <code title="get /v0/get-chat">client.chats.<a href="./src/resources/chats/chats.ts">retrieve</a>({ ...params }) -> Chat</code>
 - <code title="post /v0/archive-chat">client.chats.<a href="./src/resources/chats/chats.ts">archive</a>({ ...params }) -> BaseResponse</code>
 - <code title="get /v0/search-chats">client.chats.<a href="./src/resources/chats/chats.ts">search</a>({ ...params }) -> ChatsCursor</code>
@@ -53,22 +69,12 @@ Methods:
 
 Types:
 
-- <code><a href="./src/resources/messages/messages.ts">MessageSendResponse</a></code>
-
-Methods:
-
-- <code title="get /v0/search-messages">client.messages.<a href="./src/resources/messages/messages.ts">search</a>({ ...params }) -> MessagesCursor</code>
-- <code title="post /v0/send-message">client.messages.<a href="./src/resources/messages/messages.ts">send</a>({ ...params }) -> MessageSendResponse</code>
-
-## Attachments
-
-Types:
-
-- <code><a href="./src/resources/messages/attachments.ts">AttachmentDownloadResponse</a></code>
+- <code><a href="./src/resources/messages.ts">MessageSendResponse</a></code>
 
 Methods:
 
-- <code title="post /v0/download-attachment">client.messages.attachments.<a href="./src/resources/messages/attachments.ts">download</a>({ ...params }) -> AttachmentDownloadResponse</code>
+- <code title="get /v0/search-messages">client.messages.<a href="./src/resources/messages.ts">search</a>({ ...params }) -> MessagesCursor</code>
+- <code title="post /v0/send-message">client.messages.<a href="./src/resources/messages.ts">send</a>({ ...params }) -> MessageSendResponse</code>
 
 # Token
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeper/desktop-api",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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

@@ -218,13 +218,14 @@ The following tools are available in this MCP server.
 
 ### Resource `app`:
 
-- `open_in_app` (`write`) tags: [app]: Open Beeper, optionally focusing a chat or message, or pre-filling a draft.
+- `open_in_app` (`write`) tags: [app]: Open Beeper Desktop and optionally navigate to a specific chat, message, or pre-fill draft text and attachment.
+- `search` (`read`) tags: [app]: Search for chats, participant name matches in groups, and the first page of messages in one call. Use this when the user asks for a specific chat, group, or person.
 
 ### Resource `chats`:
 
 - `get_chat` (`read`) tags: [chats]: Get chat details: metadata, participants (limited), last activity.
 - `archive_chat` (`write`) tags: [chats]: Archive or unarchive a chat.
-- `search_chats` (`read`) tags: [chats]: Search chats by inbox, type, unread status, or text. Paginates.
+- `search_chats` (`read`) tags: [chats]: Search chats by title/network or participants using Beeper Desktop's renderer algorithm. Optional 'scope'.
 
 ### Resource `chats.reminders`:
 
@@ -239,17 +240,11 @@ The following tools are available in this MCP server.
     • ✅ RIGHT: query="dinner" or query="sick" or query="error" (single words users type)
     • ❌ WRONG: query="dinner plans tonight" or query="health issues" (phrases/concepts)
     • The query matches ALL words provided (in any order). Example: query="flight booking" finds messages with both "flight" AND "booking".
-  - Media filters: Use onlyWithMedia for any media, or specific filters like onlyWithVideo, onlyWithImage, onlyWithLink, onlyWithFile for specific types.
-  - Pagination: use 'oldestCursor' + direction='before' for older; 'newestCursor' + direction='after' for newer.
   - Performance: provide chatIDs/accountIDs when known. Omitted 'query' returns results based on filters only. Partial matches enabled; 'excludeLowPriority' defaults to true.
   - Workflow tip: To search messages in specific conversations: 1) Use find-chats to get chatIDs, 2) Use search-messages with those chatIDs.
   - IMPORTANT: Chat names vary widely. ASK the user for clarification:
     • "Which chat do you mean by family?" (could be "The Smiths", "Mom Dad Kids", etc.)
     • "What's the name of your work chat?" (could be "Team", company name, project name)
-    • "Who are the participants?" (use participantQuery in find-chats)
+    • "Who are the participants?" (use scope="participants" in search-chats)
     Returns: matching messages and referenced chats.
 - `send_message` (`write`) tags: [messages]: Send a text message to a specific chat. Supports replying to existing messages. Returns the sent message ID and a deeplink to the chat
-
-### Resource `messages.attachments`:
-
-- `download_attachment` (`write`) tags: [messages]: Download a message attachment and return the local file path.

packages/mcp-server/build

@@ -30,3 +30,27 @@ cp tsconfig.dist-src.json dist/src/tsconfig.json
 chmod +x dist/index.js
 
 DIST_PATH=./dist PKG_IMPORT_PATH=@beeper/desktop-mcp/ node ../../scripts/utils/postprocess-files.cjs
+
+# mcp bundle
+rm -rf dist-bundle beeper_desktop_api_api.mcpb; mkdir dist-bundle
+
+# copy package.json
+PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist-bundle/package.json
+
+# copy files
+node scripts/copy-bundle-files.cjs
+
+# install runtime deps
+cd dist-bundle
+npm install
+cd ..
+
+# pack bundle
+cp manifest.json dist-bundle
+
+npx mcpb pack dist-bundle beeper_desktop_api_api.mcpb
+
+npx mcpb sign beeper_desktop_api_api.mcpb --self-signed
+
+# clean up
+rm -rf dist-bundle

packages/mcp-server/manifest.json

@@ -0,0 +1,43 @@
+{
+  "dxt_version": "0.2",
+  "name": "@beeper/desktop-mcp",
+  "version": "0.1.4",
+  "description": "The official MCP Server for the Beeper Desktop API",
+  "author": {
+    "name": "Beeper Desktop",
+    "email": "[email protected]"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beeper/desktop-api-js.git"
+  },
+  "homepage": "https://github.com/beeper/desktop-api-js/tree/main/packages/mcp-server#readme",
+  "documentation": "https://developers.beeper.com/desktop-api/",
+  "server": {
+    "type": "node",
+    "entry_point": "index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/index.js"],
+      "env": {
+        "BEEPER_ACCESS_TOKEN": "${user_config.BEEPER_ACCESS_TOKEN}"
+      }
+    }
+  },
+  "user_config": {
+    "BEEPER_ACCESS_TOKEN": {
+      "title": "access_token",
+      "description": "Bearer access token obtained via OAuth2 PKCE flow or created in-app. Required for all API operations.",
+      "required": true,
+      "type": "string"
+    }
+  },
+  "tools": [],
+  "tools_generated": true,
+  "compatibility": {
+    "runtimes": {
+      "node": ">=18.0.0"
+    }
+  },
+  "keywords": ["api"]
+}

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeper/desktop-mcp",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "The official MCP Server for the Beeper Desktop API",
   "author": "Beeper Desktop <[email protected]>",
   "types": "dist/index.d.ts",
@@ -47,6 +47,7 @@
     "mcp-server": "dist/index.js"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^1.1.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^29.4.0",

packages/mcp-server/scripts/copy-bundle-files.cjs

@@ -0,0 +1,36 @@
+const fs = require('fs');
+const path = require('path');
+const pkgJson = require('../dist-bundle/package.json');
+
+const distDir = path.resolve(__dirname, '..', 'dist');
+const distBundleDir = path.resolve(__dirname, '..', 'dist-bundle');
+const distBundlePkgJson = path.join(distBundleDir, 'package.json');
+
+async function* walk(dir) {
+  for await (const d of await fs.promises.opendir(dir)) {
+    const entry = path.join(dir, d.name);
+    if (d.isDirectory()) yield* walk(entry);
+    else if (d.isFile()) yield entry;
+  }
+}
+
+async function copyFiles() {
+  // copy runtime files
+  for await (const file of walk(distDir)) {
+    if (!/[cm]?js$/.test(file)) continue;
+    const dest = path.join(distBundleDir, path.relative(distDir, file));
+    await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+    await fs.promises.copyFile(file, dest);
+  }
+
+  // replace package.json reference with local reference
+  for (const dep in pkgJson.dependencies) {
+    if (dep === '@beeper/desktop-api') {
+      pkgJson.dependencies[dep] = 'file:../../../dist/';
+    }
+  }
+
+  await fs.promises.writeFile(distBundlePkgJson, JSON.stringify(pkgJson, null, 2));
+}
+
+copyFiles();

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

@@ -7,9 +7,7 @@ import { Endpoint, ContentBlock, Metadata } from './tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 
-import { newDenoHTTPWorker } from '@valtown/deno-http-worker';
 import { WorkerInput, WorkerError, WorkerSuccess } from './code-tool-types';
-import { workerPath } from './code-tool-paths.cjs';
 
 /**
  * A tool that runs code against a copy of the SDK.
@@ -20,7 +18,7 @@ import { workerPath } from './code-tool-paths.cjs';
  *
  * @param endpoints - The endpoints to include in the list.
  */
-export function codeTool(): Endpoint {
+export async function codeTool(): Promise<Endpoint> {
   const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] };
   const tool: Tool = {
     name: 'execute',
@@ -29,6 +27,10 @@ export function codeTool(): Endpoint {
     inputSchema: { type: 'object', properties: { code: { type: 'string' } } },
   };
 
+  // Import dynamically to avoid failing at import time in cases where the environment is not well-supported.
+  const { newDenoHTTPWorker } = await import('@valtown/deno-http-worker');
+  const { workerPath } = await import('./code-tool-paths.cjs');
+
   const handler = async (client: BeeperDesktop, args: unknown) => {
     const baseURLHostname = new URL(client.baseURL).hostname;
     const { code } = args as { code: string };