@opencapstack/mcp-server 0.1.0

package/src/auth.ts

@@ -0,0 +1,19 @@
+/**
+ * Authentication utilities for the OpenCap MCP server.
+ * Reads OPENCAP_API_KEY and OPENCAP_BASE_URL from the environment.
+ */
+
+export function getApiKey(): string {
+  const key = process.env.OPENCAP_API_KEY;
+  if (!key) {
+    throw new Error(
+      'Set OPENCAP_API_KEY to your OpenCap JWT token. ' +
+        'Get one at https://api.opencapstack.com/api/v1/auth/login'
+    );
+  }
+  return key;
+}
+
+export function getBaseUrl(): string {
+  return process.env.OPENCAP_BASE_URL ?? 'https://api.opencapstack.com';
+}

package/src/client.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared HTTP client with auth and error handling.
+ */
+
+import axios, { type AxiosInstance } from 'axios';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getBaseUrl } from './auth.js';
+
+export function createClient(apiKey: string): AxiosInstance {
+  const client = axios.create({
+    baseURL: getBaseUrl(),
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    timeout: 30_000,
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    (error) => {
+      const status = error.response?.status;
+
+      if (status === 401) {
+        throw new McpError(
+          ErrorCode.InvalidRequest,
+          'API key rejected or expired — regenerate at https://app.opencapstack.com/settings'
+        );
+      }
+
+      if (status === 403) {
+        throw new McpError(
+          ErrorCode.InvalidRequest,
+          'Access denied — check your account permissions'
+        );
+      }
+
+      // Re-throw other errors with the server message when available
+      const message =
+        error.response?.data?.message ?? error.message ?? 'Unknown API error';
+      throw new McpError(ErrorCode.InternalError, `OpenCap API error: ${message}`);
+    }
+  );
+
+  return client;
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * OpenCap MCP Server entry point.
+ *
+ * Supports two transport modes:
+ *   TRANSPORT=stdio  (default) — for Claude Desktop / Claude Code
+ *   TRANSPORT=sse             — HTTP + SSE, useful for web-based clients
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { createServer } from './server.js';
+import { getApiKey } from './auth.js';
+import { createClient } from './client.js';
+
+async function main() {
+  // Fail fast if the API key is missing
+  const apiKey = getApiKey();
+  const client = createClient(apiKey);
+  const server = createServer(client);
+
+  const transport = process.env.TRANSPORT ?? 'stdio';
+
+  if (transport === 'sse') {
+    // Dynamically import express so it doesn't slow down the stdio path
+    const { default: express } = await import('express');
+    const app = express();
+    const port = Number(process.env.PORT ?? 3001);
+
+    // Map to hold active SSE transports keyed by session
+    const transports = new Map<string, SSEServerTransport>();
+
+    app.get('/sse', async (req, res) => {
+      const sseTransport = new SSEServerTransport('/messages', res);
+      transports.set(sseTransport.sessionId, sseTransport);
+
+      res.on('close', () => {
+        transports.delete(sseTransport.sessionId);
+      });
+
+      await server.connect(sseTransport);
+    });
+
+    app.post('/messages', express.json(), async (req, res) => {
+      const sessionId = req.query['sessionId'] as string;
+      const sseTransport = transports.get(sessionId);
+
+      if (!sseTransport) {
+        res.status(404).json({ error: 'Session not found' });
+        return;
+      }
+
+      await sseTransport.handlePostMessage(req, res);
+    });
+
+    app.listen(port, () => {
+      console.error(`OpenCap MCP server listening on http://localhost:${port}`);
+    });
+  } else {
+    // stdio transport (default)
+    const stdioTransport = new StdioServerTransport();
+    await server.connect(stdioTransport);
+    console.error('OpenCap MCP server running on stdio');
+  }
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/src/server.ts

@@ -0,0 +1,93 @@
+/**
+ * MCP server setup and tool registration.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  CallToolResultSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+  type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { type AxiosInstance } from 'axios';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+import { stakeholderTools } from './tools/stakeholders.js';
+import { shareClassTools } from './tools/shareClasses.js';
+import { equityPlanTools } from './tools/equityPlans.js';
+import { safeTools } from './tools/safes.js';
+import { documentTools } from './tools/documents.js';
+import { valuationTools } from './tools/valuations.js';
+import { dilutionTools } from './tools/dilution.js';
+import { waterfallTools } from './tools/waterfall.js';
+import { financialReportTools } from './tools/financialReports.js';
+import { type ToolDefinition } from './types.js';
+
+const ALL_TOOLS: ToolDefinition[] = [
+  ...stakeholderTools,
+  ...shareClassTools,
+  ...equityPlanTools,
+  ...safeTools,
+  ...documentTools,
+  ...valuationTools,
+  ...dilutionTools,
+  ...waterfallTools,
+  ...financialReportTools,
+];
+
+export function createServer(client: AxiosInstance): Server {
+  const server = new Server(
+    {
+      name: 'opencap-mcp',
+      version: '0.1.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // List tools handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools: Tool[] = ALL_TOOLS.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: zodToJsonSchema(tool.inputSchema) as Tool['inputSchema'],
+    }));
+    return { tools };
+  });
+
+  // Call tool handler
+  server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
+    const { name, arguments: args } = request.params;
+
+    const tool = ALL_TOOLS.find((t) => t.name === name);
+    if (!tool) {
+      return {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+    }
+
+    try {
+      const parsed = tool.inputSchema.parse(args ?? {});
+      const result = await tool.handler(parsed, client);
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: 'text', text: `Tool error: ${message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  return server;
+}
+
+// Keep the schema reference to avoid unused-import warnings
+void CallToolResultSchema;
+
+export { ALL_TOOLS };

package/src/tools/dilution.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const dilutionTools: ToolDefinition[] = [
+  {
+    name: 'calculate_dilution',
+    description:
+      'Calculate dilution impact for a hypothetical new funding round or equity issuance. ' +
+      'Returns pre- and post-dilution ownership percentages for each stakeholder.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+      newSharesIssued: z
+        .number()
+        .int()
+        .positive()
+        .describe('Number of new shares to be issued in the scenario'),
+      includeOptionPool: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Whether to include unissued option pool shares in the denominator'),
+      includeSafes: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Whether to include SAFEs in conversion when calculating dilution'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.post('/api/v1/dilution/calculate', input);
+      return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'get_fully_diluted_shares',
+    description:
+      'Get the current fully diluted share count including outstanding shares, ' +
+      'options (granted and reserved), warrants, and convertible instruments.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+      asOfDate: z
+        .string()
+        .optional()
+        .describe('Calculate as of a specific date (ISO 8601 YYYY-MM-DD). Defaults to today.'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/dilution/fully-diluted', {
+        params: input,
+      });
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+];

package/src/tools/documents.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const documentTools: ToolDefinition[] = [
+  {
+    name: 'list_documents',
+    description:
+      'List documents stored in OpenCap (shareholder agreements, option grants, board consents, etc.).',
+    inputSchema: z.object({
+      companyId: z.string().optional().describe('Filter by company ID'),
+      documentType: z
+        .enum([
+          'shareholder_agreement',
+          'option_grant',
+          'board_consent',
+          'safe',
+          'certificate',
+          'other',
+        ])
+        .optional()
+        .describe('Filter by document type'),
+      stakeholderId: z
+        .string()
+        .optional()
+        .describe('Filter documents associated with a stakeholder'),
+      limit: z.number().optional().default(50).describe('Max results to return'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/documents', { params: input });
+      const documents = data.documents ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(documents, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'get_document',
+    description: 'Get metadata and details for a specific document by ID.',
+    inputSchema: z.object({
+      id: z.string().describe('Document ID'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(`/api/v1/documents/${input.id}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+  {
+    name: 'search_documents',
+    description: 'Search documents by keyword or metadata across all company documents.',
+    inputSchema: z.object({
+      query: z.string().describe('Search query string'),
+      companyId: z.string().optional().describe('Limit search to a specific company'),
+      documentType: z
+        .enum([
+          'shareholder_agreement',
+          'option_grant',
+          'board_consent',
+          'safe',
+          'certificate',
+          'other',
+        ])
+        .optional()
+        .describe('Filter by document type'),
+      limit: z.number().optional().default(20).describe('Max results to return'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/documents/search', { params: input });
+      const results = data.results ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+      };
+    },
+  },
+];

package/src/tools/equityPlans.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const equityPlanTools: ToolDefinition[] = [
+  {
+    name: 'list_equity_plans',
+    description:
+      'List all equity plans (stock option plans, RSU plans, etc.) in the company.',
+    inputSchema: z.object({
+      companyId: z.string().optional().describe('Filter by company ID'),
+      limit: z.number().optional().default(50).describe('Max results to return'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/equity-plans', { params: input });
+      const plans = data.equityPlans ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(plans, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'get_equity_plan',
+    description: 'Get details for a specific equity plan by ID.',
+    inputSchema: z.object({
+      id: z.string().describe('Equity plan ID'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(`/api/v1/equity-plans/${input.id}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+  {
+    name: 'create_equity_plan',
+    description: 'Create a new equity incentive plan for employees or advisors.',
+    inputSchema: z.object({
+      name: z.string().describe('Plan name, e.g. "2024 Stock Option Plan"'),
+      planType: z
+        .enum(['ISO', 'NSO', 'RSA', 'RSU', 'SAR', 'other'])
+        .describe('Type of equity plan'),
+      sharesReserved: z
+        .number()
+        .int()
+        .positive()
+        .describe('Number of shares reserved for this plan'),
+      companyId: z.string().describe('Company ID this plan belongs to'),
+      expirationDate: z
+        .string()
+        .optional()
+        .describe('Plan expiration date in ISO 8601 format (YYYY-MM-DD)'),
+      defaultVestingSchedule: z
+        .object({
+          totalMonths: z.number().int().positive().describe('Total vesting period in months'),
+          cliffMonths: z.number().int().min(0).describe('Cliff period in months'),
+        })
+        .optional()
+        .describe('Default vesting schedule for grants under this plan'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.post('/api/v1/equity-plans', input);
+      return {
+        content: [
+          { type: 'text', text: `Equity plan created: ${JSON.stringify(data, null, 2)}` },
+        ],
+      };
+    },
+  },
+];

package/src/tools/financialReports.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const financialReportTools: ToolDefinition[] = [
+  {
+    name: 'list_financial_reports',
+    description:
+      'List all financial reports (equity summaries, cap table snapshots, tax reports, etc.).',
+    inputSchema: z.object({
+      companyId: z.string().optional().describe('Filter by company ID'),
+      reportType: z
+        .enum([
+          'cap_table_summary',
+          'equity_summary',
+          'tax_report',
+          '409A_report',
+          'custom',
+        ])
+        .optional()
+        .describe('Filter by report type'),
+      limit: z.number().optional().default(20).describe('Max results to return'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/financial-reports', { params: input });
+      const reports = data.reports ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(reports, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'get_financial_report',
+    description: 'Get the full contents of a specific financial report by ID.',
+    inputSchema: z.object({
+      id: z.string().describe('Financial report ID'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(`/api/v1/financial-reports/${input.id}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+  {
+    name: 'create_financial_report',
+    description:
+      'Generate a new financial report or cap table snapshot for the company.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+      reportType: z
+        .enum([
+          'cap_table_summary',
+          'equity_summary',
+          'tax_report',
+          '409A_report',
+          'custom',
+        ])
+        .describe('Type of report to generate'),
+      asOfDate: z
+        .string()
+        .optional()
+        .describe('Generate the report as of this date (ISO 8601 YYYY-MM-DD). Defaults to today.'),
+      includeConvertibles: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Include convertible instruments (SAFEs, notes) in the report'),
+      includeOptionPool: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Include option pool (granted and unissued) in the report'),
+      title: z.string().optional().describe('Custom report title'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.post('/api/v1/financial-reports', input);
+      return {
+        content: [
+          { type: 'text', text: `Financial report created: ${JSON.stringify(data, null, 2)}` },
+        ],
+      };
+    },
+  },
+];

package/src/tools/safes.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const safeTools: ToolDefinition[] = [
+  {
+    name: 'list_safes',
+    description:
+      'List all SAFE (Simple Agreement for Future Equity) instruments in the cap table.',
+    inputSchema: z.object({
+      companyId: z.string().optional().describe('Filter by company ID'),
+      investorId: z.string().optional().describe('Filter by investor stakeholder ID'),
+      limit: z.number().optional().default(50).describe('Max results to return'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/safes', { params: input });
+      const safes = data.safes ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(safes, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'get_safe',
+    description: 'Get details for a specific SAFE instrument by ID.',
+    inputSchema: z.object({
+      id: z.string().describe('SAFE ID'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(`/api/v1/safes/${input.id}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+  {
+    name: 'create_safe',
+    description: 'Record a new SAFE instrument (e.g. post-money SAFE from a YC-style round).',
+    inputSchema: z.object({
+      investmentAmount: z.number().positive().describe('Investment amount in USD'),
+      valuationCap: z
+        .number()
+        .positive()
+        .optional()
+        .describe('Valuation cap in USD (for valuation cap SAFEs)'),
+      discountRate: z
+        .number()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe('Discount rate percentage (e.g. 20 for 20%)'),
+      safeType: z
+        .enum(['valuation_cap', 'discount', 'mfn', 'valuation_cap_and_discount'])
+        .describe('Type of SAFE'),
+      investorId: z.string().describe('Stakeholder ID of the investor'),
+      companyId: z.string().describe('Company ID'),
+      investmentDate: z.string().describe('Investment date in ISO 8601 format (YYYY-MM-DD)'),
+      proRataRights: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Whether the investor has pro-rata rights'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.post('/api/v1/safes', input);
+      return {
+        content: [
+          { type: 'text', text: `SAFE created: ${JSON.stringify(data, null, 2)}` },
+        ],
+      };
+    },
+  },
+  {
+    name: 'update_safe',
+    description: 'Update an existing SAFE instrument (e.g. record conversion).',
+    inputSchema: z.object({
+      id: z.string().describe('SAFE ID'),
+      status: z
+        .enum(['open', 'converted', 'cancelled'])
+        .optional()
+        .describe('Current status of the SAFE'),
+      conversionDate: z
+        .string()
+        .optional()
+        .describe('Conversion date in ISO 8601 format (YYYY-MM-DD)'),
+      convertedShareClassId: z
+        .string()
+        .optional()
+        .describe('Share class ID that this SAFE converted into'),
+      convertedShares: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Number of shares issued upon conversion'),
+    }),
+    handler: async (input, client) => {
+      const { id, ...body } = input;
+      const { data } = await client.put(`/api/v1/safes/${id}`, body);
+      return {
+        content: [
+          { type: 'text', text: `SAFE updated: ${JSON.stringify(data, null, 2)}` },
+        ],
+      };
+    },
+  },
+];

package/src/tools/shareClasses.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const shareClassTools: ToolDefinition[] = [
+  {
+    name: 'list_share_classes',
+    description:
+      'List all share classes defined in the cap table (e.g. Common, Series A Preferred).',
+    inputSchema: z.object({
+      companyId: z.string().optional().describe('Filter by company ID'),
+      limit: z.number().optional().default(50).describe('Max results to return'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/share-classes', { params: input });
+      const shareClasses = data.shareClasses ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(shareClasses, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'get_share_class',
+    description: 'Get details for a specific share class by ID.',
+    inputSchema: z.object({
+      id: z.string().describe('Share class ID'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(`/api/v1/share-classes/${input.id}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+  {
+    name: 'create_share_class',
+    description: 'Create a new share class (e.g. Series B Preferred).',
+    inputSchema: z.object({
+      name: z.string().describe('Share class name, e.g. "Series A Preferred"'),
+      classType: z
+        .enum(['common', 'preferred', 'warrant', 'option'])
+        .describe('Type of share class'),
+      authorizedShares: z
+        .number()
+        .int()
+        .positive()
+        .describe('Total number of authorized shares'),
+      parValue: z.number().optional().describe('Par value per share in USD'),
+      companyId: z.string().describe('Company ID this share class belongs to'),
+      liquidationPreference: z
+        .number()
+        .optional()
+        .describe('Liquidation preference multiplier (e.g. 1 for 1x)'),
+      participationRights: z
+        .enum(['none', 'full', 'capped'])
+        .optional()
+        .describe('Participation rights type'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.post('/api/v1/share-classes', input);
+      return {
+        content: [
+          { type: 'text', text: `Share class created: ${JSON.stringify(data, null, 2)}` },
+        ],
+      };
+    },
+  },
+];