release: 4.1.295 (#16)

* feat(mcp): customize MCP outputs (#15)

* release: 4.2.0

---------

Co-authored-by: batuhan <[email protected]>
Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.1.293"
+  ".": "4.2.0"
 }

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.2.0 (2025-10-16)
+
+Full Changelog: [v4.1.293...v4.2.0](https://github.com/beeper/desktop-api-js/compare/v4.1.293...v4.2.0)
+
+### Features
+
+* **mcp:** customize MCP outputs ([#15](https://github.com/beeper/desktop-api-js/issues/15)) ([21f3016](https://github.com/beeper/desktop-api-js/commit/21f30161ea06481f442648d03fd904a4e8395e99))
+
 ## 4.1.293 (2025-10-16)
 
 Full Changelog: [v0.1.5...v4.1.293](https://github.com/beeper/desktop-api-js/compare/v0.1.5...v4.1.293)

package.json

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

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeper/desktop-mcp",
-  "version": "4.1.293",
+  "version": "4.2.0",
   "description": "The official MCP Server for the Beeper Desktop API",
   "author": "Beeper Desktop <[email protected]>",
   "types": "dist/index.d.ts",
@@ -35,6 +35,7 @@
     "@modelcontextprotocol/sdk": "^1.11.5",
     "@valtown/deno-http-worker": "^0.0.21",
     "cors": "^2.8.5",
+    "date-fns": "^4.1.0",
     "express": "^5.1.0",
     "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.6/jq-web.tar.gz",
     "qs": "^6.14.0",

packages/mcp-server/src/handlers/get-accounts.ts

@@ -0,0 +1,28 @@
+import type { HandlerFunction } from '../tools/types';
+import { asMarkdownContentResult } from './utils';
+
+export const handler: HandlerFunction = async (client) => {
+  const accounts = await client.accounts.list();
+  if (!accounts || accounts.length === 0)
+    throw new Error('No accounts found. This should never happen, please contact [email protected].');
+  const lines: string[] = [];
+  lines.push('# Accounts');
+  for (const acc of accounts) {
+    if (!acc.user) {
+      lines.push(`\n## ${acc.network}`);
+      lines.push(`**Account ID**: \`${acc.accountID}\``);
+      lines.push('**User**: Unknown');
+      continue;
+    }
+
+    const name = acc.user.fullName || acc.user.username || acc.user.id;
+    lines.push(`\n## ${acc.network}`);
+    lines.push(`**Account ID**: \`${acc.accountID}\``);
+    lines.push(`**User**: ${name}`);
+    if (acc.user.email) lines.push(`**Email**: ${acc.user.email}`);
+    if (acc.user.phoneNumber) lines.push(`**Phone**: ${acc.user.phoneNumber}`);
+  }
+  lines.push('\n# Using this information\n');
+  lines.push('- Pass accountIDs to narrow chat/message queries when known.');
+  return asMarkdownContentResult(lines);
+};

packages/mcp-server/src/handlers/get-chat.ts

@@ -0,0 +1,18 @@
+import type { HandlerFunction } from '../tools/types';
+import { asMarkdownContentResult, formatChatToMarkdown } from './utils';
+
+export const handler: HandlerFunction = async (client, args) => {
+  const { chatID, ...queryParams } = args as any;
+  const chat = await client.chats.retrieve(chatID, queryParams);
+
+  const lines: string[] = [];
+  if (!chat) {
+    lines.push('Chat not found.');
+    return asMarkdownContentResult(lines);
+  }
+  lines.push(formatChatToMarkdown(chat, undefined));
+  lines.push('\n# Using this information\n');
+  lines.push('- Use search_messages to find specific content in this chat.');
+  lines.push('- Link the "open" link to the user to allow them to view the chat in Beeper Desktop.');
+  return asMarkdownContentResult(lines);
+};

packages/mcp-server/src/handlers/index.ts

@@ -0,0 +1,29 @@
+import type { Endpoint, HandlerFunction } from '../tools';
+
+import { handler as get_accounts } from './get-accounts';
+import { handler as open_in_app } from './open-app';
+import { handler as search } from './search';
+import { handler as get_chat } from './get-chat';
+import { handler as search_chats } from './search-chats';
+import { handler as search_messages } from './search-messages';
+import { handler as send_message } from './send-message';
+
+const HANDLER_OVERRIDES: Record<string, HandlerFunction> = {
+  get_accounts,
+  open_in_app,
+  focus_app: open_in_app,
+  search,
+  get_chat,
+  search_chats,
+  search_messages,
+  send_message,
+};
+
+export function mapEndpoint(endpoint: Endpoint): Endpoint {
+  const handler = HANDLER_OVERRIDES[endpoint.tool.name];
+  if (!handler) return endpoint;
+  return {
+    ...endpoint,
+    handler,
+  };
+}

packages/mcp-server/src/handlers/list-chats.ts

@@ -0,0 +1,47 @@
+import type { HandlerFunction } from '../tools/types';
+import { asMarkdownContentResult, formatChatToMarkdown } from './utils';
+
+export const handler: HandlerFunction = async (client, args) => {
+  const body = args as any;
+  const output = await client.chats.search(body);
+
+  const lines: string[] = [];
+  lines.push('# Chats');
+
+  const items = output.items || [];
+  const hasMore = !!output.hasMore;
+
+  if (hasMore) {
+    lines.push(`\nShowing ${items.length} chats (more available)`);
+    if (output.oldestCursor) {
+      lines.push(`Next page (older): cursor='${output.oldestCursor}', direction='before'`);
+    }
+    if (output.newestCursor) {
+      lines.push(`Previous page (newer): cursor='${output.newestCursor}', direction='after'`);
+    }
+  } else if (items.length > 0) {
+    lines.push(`\nShowing ${items.length} chat${items.length === 1 ? '' : 's'}`);
+  }
+
+  if (items.length === 0) {
+    lines.push('\nNo chats found.');
+  } else {
+    for (const chatWithPreview of items) {
+      lines.push(formatChatToMarkdown(chatWithPreview, undefined));
+      const preview = (chatWithPreview as any).preview;
+      if (preview) {
+        lines.push(`**Last message**: ${preview.text || '(no text)'}`);
+        if (preview.senderName) {
+          lines.push(`**From**: ${preview.senderName}`);
+        }
+        lines.push(`**Timestamp**: ${preview.timestamp}`);
+      }
+    }
+  }
+  lines.push('\n# Using this information\n');
+  lines.push(
+    '- Pass the "chatID" to get_chat or search_messages for details about a chat, or send_message to send a message to a chat.',
+  );
+  lines.push('- Link the "open" link to the user to allow them to view the chat in Beeper Desktop.');
+  return asMarkdownContentResult(lines);
+};

packages/mcp-server/src/handlers/list-messages.ts

@@ -0,0 +1,33 @@
+import { asTextContentResult, type HandlerFunction } from '../tools/types';
+import { mapMessagesToText } from './utils';
+
+export const handler: HandlerFunction = async (client, args) => {
+  const body = args as any;
+  const output = await client.messages.search(body);
+
+  const lines: string[] = [];
+  lines.push('# Messages');
+
+  const items = (output as any).items || [];
+  const hasMore = !!(output as any).hasMore;
+
+  if (hasMore) {
+    lines.push(`\nShowing ${items.length} messages (more available)`);
+    if ((output as any).oldestCursor) {
+      lines.push(`Next page (older): cursor='${(output as any).oldestCursor}', direction='before'`);
+    }
+    if ((output as any).newestCursor) {
+      lines.push(`Previous page (newer): cursor='${(output as any).newestCursor}', direction='after'`);
+    }
+  } else if (items.length > 0) {
+    lines.push(`\nShowing ${items.length} message${items.length === 1 ? '' : 's'}`);
+  }
+
+  if (items.length === 0) {
+    lines.push('\nNo messages found.');
+  } else {
+    lines.push(mapMessagesToText(output as any, body, undefined));
+  }
+
+  return asTextContentResult(lines.join('\n'));
+};

packages/mcp-server/src/handlers/open-app.ts

@@ -0,0 +1,20 @@
+import { asTextContentResult, type HandlerFunction } from '../tools/types';
+
+export const handler: HandlerFunction = async (client, args) => {
+  const body = args as any;
+  const output = await client.focus(body);
+
+  const lines: string[] = [];
+  if (output.success) {
+    lines.push('Beeper was opened.');
+    if (body?.chatID) {
+      const chatRef = String(body.chatID);
+      lines.push(`Focused chat: ${chatRef}`);
+    }
+    if (body?.draftText) lines.push(`Draft text populated: ${body.draftText}`);
+    if (body?.draftAttachmentPath) lines.push(`Draft attachment populated: ${body.draftAttachmentPath}`);
+  } else {
+    lines.push('Failed to open Beeper.');
+  }
+  return asTextContentResult(lines.join('\n'));
+};