@beeper/desktop-mcp 0.1.2

package/src/server.ts

@@ -0,0 +1,184 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Endpoint, endpoints, HandlerFunction, query } from './tools';
+import {
+  CallToolRequestSchema,
+  Implementation,
+  ListToolsRequestSchema,
+  Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { ClientOptions } from '@beeper/desktop-api';
+import BeeperDesktop from '@beeper/desktop-api';
+import {
+  applyCompatibilityTransformations,
+  ClientCapabilities,
+  defaultClientCapabilities,
+  knownClients,
+  parseEmbeddedJSON,
+} from './compat';
+import { dynamicTools } from './dynamic-tools';
+import { codeTool } from './code-tool';
+import { McpOptions } from './options';
+
+export { McpOptions } from './options';
+export { ClientType } from './compat';
+export { Filter } from './tools';
+export { ClientOptions } from '@beeper/desktop-api';
+export { endpoints } from './tools';
+
+export const newMcpServer = () =>
+  new McpServer(
+    {
+      name: 'beeper_desktop_api_api',
+      version: '0.1.2',
+    },
+    {
+      capabilities: { tools: {}, logging: {} },
+      instructions:
+        'This MCP server provides access to your Beeper Desktop messages and chats. Use the search and find tools to locate messages and conversations, then use send_message to respond.',
+    },
+  );
+
+// Create server instance
+export const server = newMcpServer();
+
+/**
+ * Initializes the provided MCP Server with the given tools and handlers.
+ * If not provided, the default client, tools and handlers will be used.
+ */
+export function initMcpServer(params: {
+  server: Server | McpServer;
+  clientOptions?: ClientOptions;
+  mcpOptions?: McpOptions;
+}) {
+  const server = params.server instanceof McpServer ? params.server.server : params.server;
+  const mcpOptions = params.mcpOptions ?? {};
+
+  let providedEndpoints: Endpoint[] | null = null;
+  let endpointMap: Record<string, Endpoint> | null = null;
+
+  const initTools = (implementation?: Implementation) => {
+    if (implementation && (!mcpOptions.client || mcpOptions.client === 'infer')) {
+      mcpOptions.client =
+        implementation.name.toLowerCase().includes('claude') ? 'claude'
+        : implementation.name.toLowerCase().includes('cursor') ? 'cursor'
+        : undefined;
+      mcpOptions.capabilities = {
+        ...(mcpOptions.client && knownClients[mcpOptions.client]),
+        ...mcpOptions.capabilities,
+      };
+    }
+    providedEndpoints = selectTools(endpoints, mcpOptions);
+    endpointMap = Object.fromEntries(providedEndpoints.map((endpoint) => [endpoint.tool.name, endpoint]));
+  };
+
+  const logAtLevel =
+    (level: 'debug' | 'info' | 'warning' | 'error') =>
+    (message: string, ...rest: unknown[]) => {
+      void server.sendLoggingMessage({
+        level,
+        data: { message, rest },
+      });
+    };
+  const logger = {
+    debug: logAtLevel('debug'),
+    info: logAtLevel('info'),
+    warn: logAtLevel('warning'),
+    error: logAtLevel('error'),
+  };
+
+  const client = new BeeperDesktop({
+    logger,
+    ...params.clientOptions,
+    defaultHeaders: {
+      ...params.clientOptions?.defaultHeaders,
+      'X-Stainless-MCP': 'true',
+    },
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    if (providedEndpoints === null) {
+      initTools(server.getClientVersion());
+    }
+    return {
+      tools: providedEndpoints!.map((endpoint) => endpoint.tool),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (endpointMap === null) {
+      initTools(server.getClientVersion());
+    }
+    const { name, arguments: args } = request.params;
+    const endpoint = endpointMap![name];
+    if (!endpoint) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return executeHandler(endpoint.tool, endpoint.handler, client, args, mcpOptions.capabilities);
+  });
+}
+
+/**
+ * Selects the tools to include in the MCP Server based on the provided options.
+ */
+export function selectTools(endpoints: Endpoint[], options?: McpOptions): Endpoint[] {
+  const filteredEndpoints = query(options?.filters ?? [], endpoints);
+
+  let includedTools = filteredEndpoints;
+
+  if (includedTools.length > 0) {
+    if (options?.includeDynamicTools) {
+      includedTools = dynamicTools(includedTools);
+    }
+  } else {
+    if (options?.includeAllTools) {
+      includedTools = endpoints;
+    } else if (options?.includeDynamicTools) {
+      includedTools = dynamicTools(endpoints);
+    } else if (options?.includeCodeTools) {
+      includedTools = [codeTool()];
+    } else {
+      includedTools = endpoints;
+    }
+  }
+
+  const capabilities = { ...defaultClientCapabilities, ...options?.capabilities };
+  return applyCompatibilityTransformations(includedTools, capabilities);
+}
+
+/**
+ * Runs the provided handler with the given client and arguments.
+ */
+export async function executeHandler(
+  tool: Tool,
+  handler: HandlerFunction,
+  client: BeeperDesktop,
+  args: Record<string, unknown> | undefined,
+  compatibilityOptions?: Partial<ClientCapabilities>,
+) {
+  const options = { ...defaultClientCapabilities, ...compatibilityOptions };
+  if (!options.validJson && args) {
+    args = parseEmbeddedJSON(args, tool.inputSchema);
+  }
+  return await handler(client, args || {});
+}
+
+export const readEnv = (env: string): string | undefined => {
+  if (typeof (globalThis as any).process !== 'undefined') {
+    return (globalThis as any).process.env?.[env]?.trim();
+  } else if (typeof (globalThis as any).Deno !== 'undefined') {
+    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+  }
+  return;
+};
+
+export const readEnvOrError = (env: string): string => {
+  let envValue = readEnv(env);
+  if (envValue === undefined) {
+    throw new Error(`Environment variable ${env} is not set`);
+  }
+  return envValue;
+};

package/src/stdio.ts

@@ -0,0 +1,13 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { initMcpServer, newMcpServer } from './server';
+import { McpOptions } from './options';
+
+export const launchStdioServer = async (options: McpOptions) => {
+  const server = newMcpServer();
+
+  initMcpServer({ server, mcpOptions: options });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP Server running on stdio');
+};

package/src/tools/accounts/get-accounts.ts

@@ -0,0 +1,34 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@beeper/desktop-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import BeeperDesktop from '@beeper/desktop-api';
+
+export const metadata: Metadata = {
+  resource: 'accounts',
+  operation: 'read',
+  tags: ['accounts'],
+  httpMethod: 'get',
+  httpPath: '/v0/get-accounts',
+  operationId: 'get_accounts',
+};
+
+export const tool: Tool = {
+  name: 'get_accounts',
+  description: 'List connected accounts on this device. Use to pick account context.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: [],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+export const handler = async (client: BeeperDesktop, args: Record<string, unknown> | undefined) => {
+  return asTextContentResult(await client.accounts.list());
+};
+
+export default { metadata, tool, handler };

package/src/tools/app/open-app.ts

@@ -0,0 +1,47 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@beeper/desktop-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import BeeperDesktop from '@beeper/desktop-api';
+
+export const metadata: Metadata = {
+  resource: 'app',
+  operation: 'write',
+  tags: ['app'],
+  httpMethod: 'post',
+  httpPath: '/v0/open-app',
+  operationId: 'open_app',
+};
+
+export const tool: Tool = {
+  name: 'open_app',
+  description: 'Open Beeper, optionally focusing a chat or message, or pre-filling a draft.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      chatID: {
+        type: 'string',
+        description:
+          'Optional Beeper chat ID to focus after opening the app. If omitted, only opens/focuses the app.',
+      },
+      draftText: {
+        type: 'string',
+        description: 'Optional draft text to populate in the message input field.',
+      },
+      messageSortKey: {
+        type: 'string',
+        description: 'Optional message sort key. Jumps to that message in the chat when opening.',
+      },
+    },
+    required: [],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: BeeperDesktop, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  return asTextContentResult(await client.app.focus(body));
+};
+
+export default { metadata, tool, handler };

package/src/tools/chats/archive-chat.ts

@@ -0,0 +1,42 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@beeper/desktop-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import BeeperDesktop from '@beeper/desktop-api';
+
+export const metadata: Metadata = {
+  resource: 'chats',
+  operation: 'write',
+  tags: ['chats'],
+  httpMethod: 'post',
+  httpPath: '/v0/archive-chat',
+  operationId: 'archive_chat',
+};
+
+export const tool: Tool = {
+  name: 'archive_chat',
+  description: 'Archive or unarchive a chat.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      chatID: {
+        type: 'string',
+        description: 'The identifier of the chat to archive or unarchive',
+      },
+      archived: {
+        type: 'boolean',
+        description: 'True to archive, false to unarchive',
+      },
+    },
+    required: ['chatID'],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: BeeperDesktop, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  return asTextContentResult(await client.chats.archive(body));
+};
+
+export default { metadata, tool, handler };

package/src/tools/chats/get-chat.ts

@@ -0,0 +1,46 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@beeper/desktop-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import BeeperDesktop from '@beeper/desktop-api';
+
+export const metadata: Metadata = {
+  resource: 'chats',
+  operation: 'read',
+  tags: ['chats'],
+  httpMethod: 'get',
+  httpPath: '/v0/get-chat',
+  operationId: 'get_chat',
+};
+
+export const tool: Tool = {
+  name: 'get_chat',
+  description: 'Get chat details: metadata, participants (limited), last activity.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      chatID: {
+        type: 'string',
+        description:
+          "Unique identifier of the chat to retrieve. Not available for iMessage chats. Participants are limited by 'maxParticipantCount'.",
+      },
+      maxParticipantCount: {
+        type: 'integer',
+        description:
+          'Maximum number of participants to return. Use -1 for all; otherwise 0–500. Defaults to 20.',
+      },
+    },
+    required: ['chatID'],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+export const handler = async (client: BeeperDesktop, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  return asTextContentResult(await client.chats.get(body));
+};
+
+export default { metadata, tool, handler };

package/src/tools/chats/search-chats.ts

@@ -0,0 +1,101 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@beeper/desktop-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import BeeperDesktop from '@beeper/desktop-api';
+
+export const metadata: Metadata = {
+  resource: 'chats',
+  operation: 'read',
+  tags: ['chats'],
+  httpMethod: 'get',
+  httpPath: '/v0/search-chats',
+  operationId: 'search_chats',
+};
+
+export const tool: Tool = {
+  name: 'search_chats',
+  description: 'Search chats by inbox, type, unread status, or text. Paginates.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      accountIDs: {
+        type: 'array',
+        description: 'Provide an array of account IDs to filter chats from specific messaging accounts only',
+        items: {
+          type: 'string',
+        },
+      },
+      cursor: {
+        type: 'string',
+        description: 'Pagination cursor from previous response. Use with direction to navigate results',
+      },
+      direction: {
+        type: 'string',
+        description:
+          'Pagination direction: "after" for newer page, "before" for older page. Defaults to "before" when only cursor is provided.',
+        enum: ['after', 'before'],
+      },
+      inbox: {
+        type: 'string',
+        description:
+          'Filter by inbox type: "primary" (non-archived, non-low-priority), "low-priority", or "archive". If not specified, shows all chats.',
+        enum: ['primary', 'low-priority', 'archive'],
+      },
+      includeMuted: {
+        type: 'boolean',
+        description:
+          'Include chats marked as Muted by the user, which are usually less important. Default: true. Set to false if the user wants a more refined search.',
+      },
+      lastActivityAfter: {
+        type: 'string',
+        description:
+          'Provide an ISO datetime string to only retrieve chats with last activity after this time',
+        format: 'date-time',
+      },
+      lastActivityBefore: {
+        type: 'string',
+        description:
+          'Provide an ISO datetime string to only retrieve chats with last activity before this time',
+        format: 'date-time',
+      },
+      limit: {
+        type: 'integer',
+        description: 'Set the maximum number of chats to retrieve. Valid range: 1-200, default is 50',
+      },
+      participantQuery: {
+        type: 'string',
+        description:
+          'Search string to filter chats by participant names. When multiple words provided, ALL words must match. Searches in username, displayName, and fullName fields.',
+      },
+      query: {
+        type: 'string',
+        description:
+          'Search string to filter chats by title. When multiple words provided, ALL words must match. Matches are case-insensitive substrings.',
+      },
+      type: {
+        type: 'string',
+        description:
+          'Specify the type of chats to retrieve: use "single" for direct messages, "group" for group chats, "channel" for channels, or "any" to get all types',
+        enum: ['single', 'group', 'channel', 'any'],
+      },
+      unreadOnly: {
+        type: 'boolean',
+        description: 'Set to true to only retrieve chats that have unread messages',
+      },
+    },
+    required: [],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+export const handler = async (client: BeeperDesktop, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  const response = await client.chats.search(body).asResponse();
+  return asTextContentResult(await response.json());
+};
+
+export default { metadata, tool, handler };

package/src/tools/index.ts

@@ -0,0 +1,89 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, Endpoint, HandlerFunction } from './types';
+
+export { Metadata, Endpoint, HandlerFunction };
+
+import get_accounts from './accounts/get-accounts';
+import open_app from './app/open-app';
+import archive_chat from './chats/archive-chat';
+import get_chat from './chats/get-chat';
+import search_chats from './chats/search-chats';
+import get_attachment from './messages/get-attachment';
+import search_messages from './messages/search-messages';
+import send_message from './messages/send-message';
+import clear_chat_reminder from './reminders/clear-chat-reminder';
+import set_chat_reminder from './reminders/set-chat-reminder';
+
+export const endpoints: Endpoint[] = [];
+
+function addEndpoint(endpoint: Endpoint) {
+  endpoints.push(endpoint);
+}
+
+addEndpoint(get_accounts);
+addEndpoint(open_app);
+addEndpoint(archive_chat);
+addEndpoint(get_chat);
+addEndpoint(search_chats);
+addEndpoint(get_attachment);
+addEndpoint(search_messages);
+addEndpoint(send_message);
+addEndpoint(clear_chat_reminder);
+addEndpoint(set_chat_reminder);
+
+export type Filter = {
+  type: 'resource' | 'operation' | 'tag' | 'tool';
+  op: 'include' | 'exclude';
+  value: string;
+};
+
+export function query(filters: Filter[], endpoints: Endpoint[]): Endpoint[] {
+  const allExcludes = filters.length > 0 && filters.every((filter) => filter.op === 'exclude');
+  const unmatchedFilters = new Set(filters);
+
+  const filtered = endpoints.filter((endpoint: Endpoint) => {
+    let included = false || allExcludes;
+
+    for (const filter of filters) {
+      if (match(filter, endpoint)) {
+        unmatchedFilters.delete(filter);
+        included = filter.op === 'include';
+      }
+    }
+
+    return included;
+  });
+
+  // Check if any filters didn't match
+  const unmatched = Array.from(unmatchedFilters).filter((f) => f.type === 'tool' || f.type === 'resource');
+  if (unmatched.length > 0) {
+    throw new Error(
+      `The following filters did not match any endpoints: ${unmatched
+        .map((f) => `${f.type}=${f.value}`)
+        .join(', ')}`,
+    );
+  }
+
+  return filtered;
+}
+
+function match({ type, value }: Filter, endpoint: Endpoint): boolean {
+  switch (type) {
+    case 'resource': {
+      const regexStr = '^' + normalizeResource(value).replace(/\*/g, '.*') + '$';
+      const regex = new RegExp(regexStr);
+      return regex.test(normalizeResource(endpoint.metadata.resource));
+    }
+    case 'operation':
+      return endpoint.metadata.operation === value;
+    case 'tag':
+      return endpoint.metadata.tags.includes(value);
+    case 'tool':
+      return endpoint.tool.name === value;
+  }
+}
+
+function normalizeResource(resource: string): string {
+  return resource.toLowerCase().replace(/[^a-z.*\-_]*/g, '');
+}

package/src/tools/messages/get-attachment.ts

@@ -0,0 +1,42 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@beeper/desktop-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import BeeperDesktop from '@beeper/desktop-api';
+
+export const metadata: Metadata = {
+  resource: 'messages',
+  operation: 'write',
+  tags: ['messages'],
+  httpMethod: 'post',
+  httpPath: '/v0/get-attachment',
+  operationId: 'get_attachment',
+};
+
+export const tool: Tool = {
+  name: 'get_attachment',
+  description: 'Download a message attachment and return the local file path.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      chatID: {
+        type: 'string',
+        description: 'Unique identifier of the chat (supports both chatID and localChatID).',
+      },
+      messageID: {
+        type: 'string',
+        description: 'The message ID (eventID) containing the attachment.',
+      },
+    },
+    required: ['chatID', 'messageID'],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: BeeperDesktop, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  return asTextContentResult(await client.messages.getAttachment(body));
+};
+
+export default { metadata, tool, handler };