feat(mcp): customize MCP outputs

packages/mcp-server/package.json

@@ -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'));
+};

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

@@ -0,0 +1,39 @@
+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(`\nFound ${items.length}+ chats (showing ${items.length})`);
+    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(`\nFound ${items.length} chat${items.length === 1 ? '' : 's'}`);
+  }
+
+  if (items.length === 0) {
+    lines.push('\nNo chats found.');
+  } else {
+    for (const chat of items) {
+      lines.push(formatChatToMarkdown(chat, undefined));
+    }
+  }
+  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/search-messages.ts

@@ -0,0 +1,8 @@
+import type { HandlerFunction } from '../tools/types';
+import { mapMessagesToText, asMarkdownContentResult } from './utils';
+
+export const handler: HandlerFunction = async (client, args) => {
+  const body = args as any;
+  const output = await client.messages.search(body);
+  return asMarkdownContentResult(mapMessagesToText(output, body, undefined));
+};

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

@@ -0,0 +1,24 @@
+import type { HandlerFunction } from '../tools/types';
+import { asMarkdownContentResult, formatChatToMarkdown, mapMessagesToText } from './utils';
+
+export const handler: HandlerFunction = async (client, args) => {
+  const body = args as any;
+  const output = await client.search(body);
+
+  const lines: string[] = [];
+  if (body?.query) lines.push(`Query: "${body.query}"`);
+  const results = output?.results;
+  if (results?.chats?.length) {
+    lines.push('\n# Chats');
+    for (const chat of results.chats) lines.push(formatChatToMarkdown(chat, undefined));
+  }
+  if (results?.in_groups?.length) {
+    lines.push('\n# In Groups');
+    for (const chat of results.in_groups) lines.push(formatChatToMarkdown(chat, undefined));
+  }
+  if (results?.messages?.items?.length) {
+    lines.push('\n# Messages');
+    lines.push(mapMessagesToText(results.messages as any, body, undefined));
+  }
+  return asMarkdownContentResult(lines);
+};

packages/mcp-server/src/handlers/send-message.ts

@@ -0,0 +1,17 @@
+import type { HandlerFunction } from '../tools/types';
+import { asMarkdownContentResult, createOpenLink } from './utils';
+
+export const handler: HandlerFunction = async (client, args) => {
+  const body = args as any;
+  const output = await client.messages.send(body);
+
+  const lines: string[] = [];
+  if (output.pendingMessageID) {
+    const deeplink = createOpenLink('', body?.chatID ?? '');
+    if (deeplink) lines.push(`**Open the chat in Beeper**: ${deeplink}`);
+  } else {
+    lines.push('Failed to send message.');
+  }
+
+  return asMarkdownContentResult(lines);
+};