@opencapstack/mcp-server 0.1.0

package/src/tools/stakeholders.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const stakeholderTools: ToolDefinition[] = [
+  {
+    name: 'list_stakeholders',
+    description:
+      'List all stakeholders in the cap table. Returns name, email, role, and ownership details.',
+    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/stakeholders', { params: input });
+      const stakeholders = data.stakeholders ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(stakeholders, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'get_stakeholder',
+    description: 'Get details for a specific stakeholder by ID.',
+    inputSchema: z.object({
+      id: z.string().describe('Stakeholder ID'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(`/api/v1/stakeholders/${input.id}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+  {
+    name: 'create_stakeholder',
+    description: 'Add a new stakeholder to the cap table.',
+    inputSchema: z.object({
+      name: z.string().describe('Full name'),
+      email: z.string().email().describe('Email address'),
+      role: z
+        .enum(['founder', 'investor', 'employee', 'advisor', 'other'])
+        .describe('Stakeholder role'),
+      companyId: z.string().describe('Company ID to add the stakeholder to'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.post('/api/v1/stakeholders', input);
+      return {
+        content: [
+          { type: 'text', text: `Stakeholder created: ${JSON.stringify(data, null, 2)}` },
+        ],
+      };
+    },
+  },
+  {
+    name: 'update_stakeholder',
+    description: 'Update an existing stakeholder by ID.',
+    inputSchema: z.object({
+      id: z.string().describe('Stakeholder ID'),
+      name: z.string().optional().describe('Full name'),
+      email: z.string().email().optional().describe('Email address'),
+      role: z
+        .enum(['founder', 'investor', 'employee', 'advisor', 'other'])
+        .optional()
+        .describe('Stakeholder role'),
+    }),
+    handler: async (input, client) => {
+      const { id, ...body } = input;
+      const { data } = await client.put(`/api/v1/stakeholders/${id}`, body);
+      return {
+        content: [
+          { type: 'text', text: `Stakeholder updated: ${JSON.stringify(data, null, 2)}` },
+        ],
+      };
+    },
+  },
+];

package/src/tools/valuations.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const valuationTools: ToolDefinition[] = [
+  {
+    name: 'get_latest_valuation',
+    description:
+      'Get the most recent 409A or board-approved valuation for the company.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(
+        `/api/v1/valuations/latest`,
+        { params: { companyId: input.companyId } }
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+  {
+    name: 'get_valuation_history',
+    description: 'Get the historical valuation timeline for the company.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+      limit: z.number().optional().default(20).describe('Max results to return'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/valuations', { params: input });
+      const valuations = data.valuations ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(valuations, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'create_valuation_request',
+    description:
+      'Submit a new 409A valuation request or record a board-approved valuation.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+      valuationType: z
+        .enum(['409A', 'board_approved', 'preferred_round', 'other'])
+        .describe('Type of valuation'),
+      valuationDate: z.string().describe('Effective date in ISO 8601 format (YYYY-MM-DD)'),
+      commonStockFMV: z
+        .number()
+        .positive()
+        .describe('Fair market value per common share in USD'),
+      postMoneyValuation: z
+        .number()
+        .positive()
+        .optional()
+        .describe('Total post-money company valuation in USD'),
+      provider: z
+        .string()
+        .optional()
+        .describe('Name of the 409A valuation provider or firm'),
+      reportUrl: z
+        .string()
+        .url()
+        .optional()
+        .describe('URL to the valuation report document'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.post('/api/v1/valuations', input);
+      return {
+        content: [
+          { type: 'text', text: `Valuation recorded: ${JSON.stringify(data, null, 2)}` },
+        ],
+      };
+    },
+  },
+];

package/src/tools/waterfall.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const waterfallTools: ToolDefinition[] = [
+  {
+    name: 'run_waterfall_analysis',
+    description:
+      'Run a waterfall analysis to model how exit proceeds would be distributed among ' +
+      'stakeholders given their liquidation preferences, participation rights, and ownership. ' +
+      'Returns proceeds per stakeholder and per share class at the given exit amount.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+      exitAmount: z
+        .number()
+        .positive()
+        .describe('Total exit/acquisition proceeds in USD'),
+      exitType: z
+        .enum(['acquisition', 'ipo', 'dissolution'])
+        .optional()
+        .default('acquisition')
+        .describe('Type of exit event'),
+      deductTransactionCosts: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Whether to deduct estimated transaction costs before distribution'),
+      transactionCostsAmount: z
+        .number()
+        .optional()
+        .describe('Transaction costs amount in USD (used if deductTransactionCosts is true)'),
+      includeOptionPoolSweep: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Whether to include pre-exit option pool sweep'),
+      asOfDate: z
+        .string()
+        .optional()
+        .describe('Run analysis as of a specific date (ISO 8601 YYYY-MM-DD). Defaults to today.'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.post('/api/v1/waterfall/analyze', input);
+      return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+      };
+    },
+  },
+];

package/src/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared types used across tools and the server.
+ */
+
+import { type z } from 'zod';
+import { type AxiosInstance } from 'axios';
+import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+export type ToolResult = CallToolResult;
+
+export interface ToolDefinition<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+  name: string;
+  description: string;
+  inputSchema: TSchema;
+  handler: (input: z.infer<TSchema>, client: AxiosInstance) => Promise<ToolResult>;
+}

package/tests/auth.test.ts

@@ -0,0 +1,54 @@
+import { getApiKey, getBaseUrl } from '../src/auth.js';
+
+describe('getApiKey', () => {
+  const ORIGINAL = process.env.OPENCAP_API_KEY;
+
+  afterEach(() => {
+    if (ORIGINAL === undefined) {
+      delete process.env.OPENCAP_API_KEY;
+    } else {
+      process.env.OPENCAP_API_KEY = ORIGINAL;
+    }
+  });
+
+  it('throws a helpful error when OPENCAP_API_KEY is not set', () => {
+    delete process.env.OPENCAP_API_KEY;
+    expect(() => getApiKey()).toThrow(
+      'Set OPENCAP_API_KEY to your OpenCap JWT token.'
+    );
+  });
+
+  it('throws an error that includes the login URL', () => {
+    delete process.env.OPENCAP_API_KEY;
+    expect(() => getApiKey()).toThrow(
+      'https://api.opencapstack.com/api/v1/auth/login'
+    );
+  });
+
+  it('returns the key when OPENCAP_API_KEY is set', () => {
+    process.env.OPENCAP_API_KEY = 'test-api-key-abc123';
+    expect(getApiKey()).toBe('test-api-key-abc123');
+  });
+});
+
+describe('getBaseUrl', () => {
+  const ORIGINAL = process.env.OPENCAP_BASE_URL;
+
+  afterEach(() => {
+    if (ORIGINAL === undefined) {
+      delete process.env.OPENCAP_BASE_URL;
+    } else {
+      process.env.OPENCAP_BASE_URL = ORIGINAL;
+    }
+  });
+
+  it('defaults to https://api.opencapstack.com when OPENCAP_BASE_URL is not set', () => {
+    delete process.env.OPENCAP_BASE_URL;
+    expect(getBaseUrl()).toBe('https://api.opencapstack.com');
+  });
+
+  it('returns the custom base URL when OPENCAP_BASE_URL is set', () => {
+    process.env.OPENCAP_BASE_URL = 'https://self-hosted.example.com';
+    expect(getBaseUrl()).toBe('https://self-hosted.example.com');
+  });
+});

package/tests/server.test.ts

@@ -0,0 +1,95 @@
+import { createServer, ALL_TOOLS } from '../src/server.js';
+import { createClient } from '../src/client.js';
+
+// Mock axios so createClient works without a real network
+jest.mock('axios', () => {
+  const mockClient = {
+    get: jest.fn(),
+    post: jest.fn(),
+    put: jest.fn(),
+    interceptors: {
+      response: { use: jest.fn() },
+    },
+    defaults: { headers: { common: {} } },
+  };
+  const axios = {
+    create: jest.fn(() => mockClient),
+    default: { create: jest.fn(() => mockClient) },
+  };
+  return { ...axios, default: axios };
+});
+
+// Provide a fake API key so auth doesn't throw
+process.env.OPENCAP_API_KEY = 'test-server-key';
+process.env.OPENCAP_BASE_URL = 'https://api.opencapstack.com';
+
+describe('ALL_TOOLS registry', () => {
+  const toolNames = ALL_TOOLS.map((t) => t.name);
+
+  it('contains all stakeholder tools', () => {
+    expect(toolNames).toContain('list_stakeholders');
+    expect(toolNames).toContain('get_stakeholder');
+    expect(toolNames).toContain('create_stakeholder');
+    expect(toolNames).toContain('update_stakeholder');
+  });
+
+  it('contains all share class tools', () => {
+    expect(toolNames).toContain('list_share_classes');
+    expect(toolNames).toContain('get_share_class');
+    expect(toolNames).toContain('create_share_class');
+  });
+
+  it('contains all equity plan tools', () => {
+    expect(toolNames).toContain('list_equity_plans');
+    expect(toolNames).toContain('get_equity_plan');
+    expect(toolNames).toContain('create_equity_plan');
+  });
+
+  it('contains all SAFE tools', () => {
+    expect(toolNames).toContain('list_safes');
+    expect(toolNames).toContain('get_safe');
+    expect(toolNames).toContain('create_safe');
+    expect(toolNames).toContain('update_safe');
+  });
+
+  it('contains all document tools', () => {
+    expect(toolNames).toContain('list_documents');
+    expect(toolNames).toContain('get_document');
+    expect(toolNames).toContain('search_documents');
+  });
+
+  it('contains all valuation tools', () => {
+    expect(toolNames).toContain('get_latest_valuation');
+    expect(toolNames).toContain('get_valuation_history');
+    expect(toolNames).toContain('create_valuation_request');
+  });
+
+  it('contains all dilution tools', () => {
+    expect(toolNames).toContain('calculate_dilution');
+    expect(toolNames).toContain('get_fully_diluted_shares');
+  });
+
+  it('contains the waterfall tool', () => {
+    expect(toolNames).toContain('run_waterfall_analysis');
+  });
+
+  it('contains all financial report tools', () => {
+    expect(toolNames).toContain('list_financial_reports');
+    expect(toolNames).toContain('get_financial_report');
+    expect(toolNames).toContain('create_financial_report');
+  });
+
+  it('has no duplicate tool names', () => {
+    const unique = new Set(toolNames);
+    expect(unique.size).toBe(toolNames.length);
+  });
+});
+
+describe('createServer', () => {
+  it('returns a server instance', () => {
+    const client = createClient('test-key');
+    const server = createServer(client);
+    expect(server).toBeDefined();
+    expect(typeof server.connect).toBe('function');
+  });
+});

package/tests/tools/shareClasses.test.ts

@@ -0,0 +1,133 @@
+import { shareClassTools } from '../../src/tools/shareClasses.js';
+import { type AxiosInstance } from 'axios';
+import { type ToolResult } from '../../src/types.js';
+
+function makeClient(overrides: Partial<AxiosInstance> = {}): AxiosInstance {
+  return {
+    get: jest.fn(),
+    post: jest.fn(),
+    put: jest.fn(),
+    delete: jest.fn(),
+    ...overrides,
+  } as unknown as AxiosInstance;
+}
+
+/** Narrow the first content item to a text block and return its text. */
+function firstText(result: ToolResult): string {
+  const item = result.content[0];
+  if (item.type !== 'text') throw new Error(`Expected text content, got ${item.type}`);
+  return item.text;
+}
+
+const listTool = shareClassTools.find((t) => t.name === 'list_share_classes')!;
+const getTool = shareClassTools.find((t) => t.name === 'get_share_class')!;
+const createTool = shareClassTools.find((t) => t.name === 'create_share_class')!;
+
+describe('list_share_classes', () => {
+  it('calls GET /api/v1/share-classes', async () => {
+    const client = makeClient({
+      get: jest.fn().mockResolvedValue({
+        data: [{ id: 'sc-1', name: 'Common' }],
+      }),
+    });
+
+    const result = await listTool.handler({}, client);
+
+    expect(client.get).toHaveBeenCalledWith('/api/v1/share-classes', { params: {} });
+    expect(firstText(result)).toContain('Common');
+  });
+
+  it('unwraps the shareClasses envelope if present', async () => {
+    const shareClasses = [{ id: 'sc-2', name: 'Series A Preferred' }];
+    const client = makeClient({
+      get: jest.fn().mockResolvedValue({ data: { shareClasses } }),
+    });
+
+    const result = await listTool.handler({}, client);
+    expect(firstText(result)).toContain('Series A Preferred');
+  });
+
+  it('passes companyId and limit as params', async () => {
+    const client = makeClient({
+      get: jest.fn().mockResolvedValue({ data: [] }),
+    });
+
+    await listTool.handler({ companyId: 'co-abc', limit: 5 }, client);
+
+    expect(client.get).toHaveBeenCalledWith('/api/v1/share-classes', {
+      params: { companyId: 'co-abc', limit: 5 },
+    });
+  });
+});
+
+describe('get_share_class', () => {
+  it('calls GET /api/v1/share-classes/:id', async () => {
+    const client = makeClient({
+      get: jest.fn().mockResolvedValue({
+        data: { id: 'sc-99', name: 'Series B Preferred' },
+      }),
+    });
+
+    const result = await getTool.handler({ id: 'sc-99' }, client);
+
+    expect(client.get).toHaveBeenCalledWith('/api/v1/share-classes/sc-99');
+    expect(firstText(result)).toContain('Series B Preferred');
+  });
+});
+
+describe('create_share_class', () => {
+  const validInput = {
+    name: 'Series C Preferred',
+    classType: 'preferred' as const,
+    authorizedShares: 10_000_000,
+    companyId: 'co-1',
+  };
+
+  it('posts to /api/v1/share-classes with the correct body', async () => {
+    const client = makeClient({
+      post: jest.fn().mockResolvedValue({ data: { id: 'sc-new', ...validInput } }),
+    });
+
+    const result = await createTool.handler(validInput, client);
+
+    expect(client.post).toHaveBeenCalledWith('/api/v1/share-classes', validInput);
+    expect(firstText(result)).toContain('Share class created');
+    expect(firstText(result)).toContain('Series C Preferred');
+  });
+
+  it('validates that authorizedShares must be a positive integer', () => {
+    const parsed = createTool.inputSchema.safeParse({
+      ...validInput,
+      authorizedShares: -100,
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('validates that classType must be one of the allowed values', () => {
+    const parsed = createTool.inputSchema.safeParse({
+      ...validInput,
+      classType: 'convertible_note',
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('accepts optional fields like parValue and liquidationPreference', async () => {
+    const client = makeClient({
+      post: jest.fn().mockResolvedValue({ data: { id: 'sc-opt' } }),
+    });
+
+    const inputWithOptionals = {
+      ...validInput,
+      parValue: 0.0001,
+      liquidationPreference: 1,
+      participationRights: 'none' as const,
+    };
+
+    await createTool.handler(inputWithOptionals, client);
+
+    expect(client.post).toHaveBeenCalledWith(
+      '/api/v1/share-classes',
+      inputWithOptionals
+    );
+  });
+});

package/tests/tools/stakeholders.test.ts

@@ -0,0 +1,147 @@
+import { stakeholderTools } from '../../src/tools/stakeholders.js';
+import { type AxiosInstance } from 'axios';
+import { type ToolResult } from '../../src/types.js';
+
+function makeClient(overrides: Partial<AxiosInstance> = {}): AxiosInstance {
+  return {
+    get: jest.fn(),
+    post: jest.fn(),
+    put: jest.fn(),
+    delete: jest.fn(),
+    ...overrides,
+  } as unknown as AxiosInstance;
+}
+
+/** Narrow the first content item to a text block and return its text. */
+function firstText(result: ToolResult): string {
+  const item = result.content[0];
+  if (item.type !== 'text') throw new Error(`Expected text content, got ${item.type}`);
+  return item.text;
+}
+
+const listTool = stakeholderTools.find((t) => t.name === 'list_stakeholders')!;
+const getTool = stakeholderTools.find((t) => t.name === 'get_stakeholder')!;
+const createTool = stakeholderTools.find((t) => t.name === 'create_stakeholder')!;
+const updateTool = stakeholderTools.find((t) => t.name === 'update_stakeholder')!;
+
+describe('list_stakeholders', () => {
+  it('calls GET /api/v1/stakeholders', async () => {
+    const client = makeClient({
+      get: jest.fn().mockResolvedValue({ data: [{ id: '1', name: 'Alice' }] }),
+    });
+
+    const result = await listTool.handler({}, client);
+
+    expect(client.get).toHaveBeenCalledWith('/api/v1/stakeholders', { params: {} });
+    expect(result.content[0].type).toBe('text');
+    expect(firstText(result)).toContain('Alice');
+  });
+
+  it('passes companyId and limit as query params', async () => {
+    const client = makeClient({
+      get: jest.fn().mockResolvedValue({ data: { stakeholders: [] } }),
+    });
+
+    await listTool.handler({ companyId: 'co-123', limit: 10 }, client);
+
+    expect(client.get).toHaveBeenCalledWith('/api/v1/stakeholders', {
+      params: { companyId: 'co-123', limit: 10 },
+    });
+  });
+
+  it('handles the stakeholders envelope', async () => {
+    const stakeholders = [{ id: '2', name: 'Bob' }];
+    const client = makeClient({
+      get: jest.fn().mockResolvedValue({ data: { stakeholders } }),
+    });
+
+    const result = await listTool.handler({}, client);
+    expect(firstText(result)).toContain('Bob');
+  });
+
+  it('returns an error content when the API throws', async () => {
+    const client = makeClient({
+      get: jest.fn().mockRejectedValue(new Error('Network error')),
+    });
+
+    await expect(listTool.handler({}, client)).rejects.toThrow('Network error');
+  });
+});
+
+describe('get_stakeholder', () => {
+  it('calls GET /api/v1/stakeholders/:id', async () => {
+    const client = makeClient({
+      get: jest.fn().mockResolvedValue({ data: { id: '42', name: 'Carol' } }),
+    });
+
+    const result = await getTool.handler({ id: '42' }, client);
+
+    expect(client.get).toHaveBeenCalledWith('/api/v1/stakeholders/42');
+    expect(firstText(result)).toContain('Carol');
+  });
+});
+
+describe('create_stakeholder', () => {
+  it('posts the correct body to /api/v1/stakeholders', async () => {
+    const newStakeholder = {
+      id: 'new-1',
+      name: 'Dave',
+      email: 'dave@example.com',
+      role: 'investor',
+      companyId: 'co-1',
+    };
+    const client = makeClient({
+      post: jest.fn().mockResolvedValue({ data: newStakeholder }),
+    });
+
+    const input = {
+      name: 'Dave',
+      email: 'dave@example.com',
+      role: 'investor' as const,
+      companyId: 'co-1',
+    };
+    const result = await createTool.handler(input, client);
+
+    expect(client.post).toHaveBeenCalledWith('/api/v1/stakeholders', input);
+    expect(firstText(result)).toContain('Stakeholder created');
+    expect(firstText(result)).toContain('Dave');
+  });
+
+  it('validates that email must be a valid email address', () => {
+    const parsed = createTool.inputSchema.safeParse({
+      name: 'Eve',
+      email: 'not-an-email',
+      role: 'founder',
+      companyId: 'co-1',
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('validates that role must be one of the allowed values', () => {
+    const parsed = createTool.inputSchema.safeParse({
+      name: 'Frank',
+      email: 'frank@example.com',
+      role: 'ceo',
+      companyId: 'co-1',
+    });
+    expect(parsed.success).toBe(false);
+  });
+});
+
+describe('update_stakeholder', () => {
+  it('calls PUT /api/v1/stakeholders/:id with the update body', async () => {
+    const client = makeClient({
+      put: jest.fn().mockResolvedValue({ data: { id: '99', name: 'Updated Name' } }),
+    });
+
+    const result = await updateTool.handler(
+      { id: '99', name: 'Updated Name' },
+      client
+    );
+
+    expect(client.put).toHaveBeenCalledWith('/api/v1/stakeholders/99', {
+      name: 'Updated Name',
+    });
+    expect(firstText(result)).toContain('Stakeholder updated');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}