@opencapstack/mcp-server 0.1.3 → 0.1.5

package/src/tools/financialReports.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceInt, coerceBool } from '../schema.js';
 import { type ToolDefinition } from '../types.js';
 
 export const financialReportTools: ToolDefinition[] = [
@@ -18,7 +19,7 @@ export const financialReportTools: ToolDefinition[] = [
         ])
         .optional()
         .describe('Filter by report type'),
-      limit: z.number().optional().default(20).describe('Max results to return'),
+      limit: coerceInt('Max results to return').optional().default(20),
     }),
     handler: async (input, client) => {
       const { data } = await client.get('/api/v1/financial-reports', { params: input });
@@ -30,9 +31,12 @@ export const financialReportTools: ToolDefinition[] = [
   },
   {
     name: 'get_financial_report',
-    description: 'Get the full contents of a specific financial report by ID.',
+    description:
+      'Get the full contents of a specific financial report by ID. Use the `row_id` field from `list_financial_reports`.',
     inputSchema: z.object({
-      id: z.string().describe('Financial report ID'),
+      id: z
+        .string()
+        .describe('Financial report ID — use the `row_id` field from list_financial_reports'),
     }),
     handler: async (input, client) => {
       const { data } = await client.get(`/api/v1/financial-reports/${input.id}`);
@@ -58,25 +62,41 @@ export const financialReportTools: ToolDefinition[] = [
         .string()
         .optional()
         .describe('Generate the report as of this date (ISO 8601 YYYY-MM-DD). Defaults to today.'),
-      includeConvertibles: z
-        .boolean()
+      includeConvertibles: coerceBool(
+        'Include convertible instruments (SAFEs, notes) in the report'
+      )
         .optional()
-        .default(true)
-        .describe('Include convertible instruments (SAFEs, notes) in the report'),
-      includeOptionPool: z
-        .boolean()
+        .default(true),
+      includeOptionPool: coerceBool(
+        'Include option pool (granted and unissued) in the report'
+      )
         .optional()
-        .default(true)
-        .describe('Include option pool (granted and unissued) in the report'),
+        .default(true),
       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)}` },
-        ],
-      };
+      const { data: created } = await client.post('/api/v1/financial-reports', input);
+      const id = created.row_id ?? created._id;
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/financial-reports/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Financial report created:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Financial report created (could not confirm persisted state — verify with get_financial_report):\n${JSON.stringify(created, null, 2)}`,
+            },
+          ],
+        };
+      }
     },
   },
 ];

package/src/tools/meta.ts

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+import { type ToolDefinition } from '../types.js';
+
+export const metaTools: ToolDefinition[] = [
+  {
+    name: 'whoami',
+    description:
+      'Verify your API key is working and return your account details (email, role, companyId). ' +
+      'Run this first to confirm your MCP setup is correct.',
+    inputSchema: z.object({}),
+    handler: async (_input, client) => {
+      const { data } = await client.get('/api/v1/auth/me');
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Authenticated as:\n${JSON.stringify(data, null, 2)}`,
+          },
+        ],
+      };
+    },
+  },
+  {
+    name: 'list_workflows',
+    description:
+      'Get step-by-step workflow guides for common cap table operations. ' +
+      'Call this when you are unsure what tools to use or in what order.',
+    inputSchema: z.object({}),
+    handler: async () => {
+      const workflows = {
+        add_advisor_with_equity: [
+          {
+            step: 1,
+            tool: 'create_stakeholder',
+            required: ['name', 'email', 'role: advisor', 'companyId'],
+          },
+          {
+            step: 2,
+            tool: 'create_equity_plan',
+            note: 'Skip if plan exists — use list_equity_plans first',
+            required: ['name', 'planType: NSO', 'sharesReserved', 'companyId'],
+          },
+          {
+            step: 3,
+            tool: 'create_equity_grant',
+            required: [
+              'companyId',
+              'employeeId: <stakeholder row_id>',
+              'equityPlanId: <plan row_id>',
+              'grantType: NSO',
+              'numberOfShares',
+              'grantDate',
+            ],
+          },
+        ],
+        record_safe_investment: [
+          {
+            step: 1,
+            tool: 'create_stakeholder',
+            note: 'Skip if investor exists — use list_stakeholders first',
+            required: ['name', 'email', 'role: investor', 'companyId'],
+          },
+          {
+            step: 2,
+            tool: 'create_safe',
+            required: [
+              'investmentAmount',
+              'safeType',
+              'investorId: <stakeholder row_id>',
+              'companyId',
+              'investmentDate',
+            ],
+          },
+        ],
+        set_up_share_classes: [
+          {
+            step: 1,
+            tool: 'create_share_class',
+            note: 'Common stock first',
+            required: ['name: Common', 'classType: common', 'authorizedShares', 'companyId'],
+          },
+          {
+            step: 2,
+            tool: 'create_share_class',
+            note: 'Preferred if needed',
+            required: [
+              'name: Series A Preferred',
+              'classType: preferred',
+              'authorizedShares',
+              'companyId',
+            ],
+          },
+        ],
+        record_409a_valuation: [
+          {
+            step: 1,
+            tool: 'create_valuation_request',
+            required: ['companyId', 'valuationType: 409A', 'valuationDate', 'commonStockFMV'],
+          },
+          {
+            step: 2,
+            tool: 'create_financial_report',
+            note: 'Optional',
+            required: ['companyId', 'reportType: 409A_report'],
+          },
+        ],
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(workflows, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'cap_table_summary',
+    description:
+      'Get a quick overview of the current cap table state — stakeholder count, share classes, ' +
+      'open SAFEs, active grants. Use this to understand what is already set up before starting workflows.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+    }),
+    handler: async (input, client) => {
+      const params = { companyId: input.companyId, limit: 100 };
+      const [stakeholdersRes, shareClassesRes, safesRes, equityPlansRes, grantsRes] =
+        await Promise.allSettled([
+          client.get('/api/v1/stakeholders', { params }),
+          client.get('/api/v1/share-classes', { params }),
+          client.get('/api/v1/safes', { params }),
+          client.get('/api/v1/equity-plans', { params }),
+          client.get('/api/v1/equity-grants', { params }),
+        ]);
+
+      const extract = (res: PromiseSettledResult<{ data: unknown }>, keys: string[]): unknown[] => {
+        if (res.status === 'rejected') return [];
+        const d = res.value.data as Record<string, unknown>;
+        for (const k of keys) {
+          if (Array.isArray(d[k])) return d[k] as unknown[];
+        }
+        return Array.isArray(d) ? d : [];
+      };
+
+      const stakeholders = extract(stakeholdersRes, ['stakeholders']);
+      const shareClasses = extract(shareClassesRes, ['shareClasses']);
+      const safes = extract(safesRes, ['safes']);
+      const equityPlans = extract(equityPlansRes, ['equityPlans']);
+      const grants = extract(grantsRes, ['grants']);
+
+      const summary = {
+        companyId: input.companyId,
+        stakeholders: stakeholders.length,
+        shareClasses: shareClasses.length,
+        openSafes: (safes as { status?: string }[]).filter(
+          (s) => s.status === 'open' || s.status === 'draft'
+        ).length,
+        equityPlans: equityPlans.length,
+        activeGrants: (grants as { status?: string }[]).filter((g) => g.status === 'active').length,
+        unavailable: [
+          stakeholdersRes.status === 'rejected' ? 'stakeholders' : null,
+          shareClassesRes.status === 'rejected' ? 'share-classes' : null,
+          safesRes.status === 'rejected' ? 'safes' : null,
+          equityPlansRes.status === 'rejected' ? 'equity-plans' : null,
+          grantsRes.status === 'rejected' ? 'equity-grants' : null,
+        ].filter(Boolean),
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
+      };
+    },
+  },
+];

package/src/tools/safes.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceFloat, coerceBool, coerceInt } from '../schema.js';
 import { type ToolDefinition } from '../types.js';
 
 export const safeTools: ToolDefinition[] = [
@@ -9,7 +10,7 @@ export const safeTools: ToolDefinition[] = [
     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'),
+      limit: coerceInt('Max results to return').optional().default(50),
     }),
     handler: async (input, client) => {
       const { data } = await client.get('/api/v1/safes', { params: input });
@@ -21,9 +22,10 @@ export const safeTools: ToolDefinition[] = [
   },
   {
     name: 'get_safe',
-    description: 'Get details for a specific SAFE instrument by ID.',
+    description:
+      'Get details for a specific SAFE instrument by ID. Use the `safeId` field (e.g. `safe_xxx`) from `list_safes`, not the `_id` field.',
     inputSchema: z.object({
-      id: z.string().describe('SAFE ID'),
+      id: z.string().describe('SAFE ID — use the `safeId` field from list_safes, not `_id`'),
     }),
     handler: async (input, client) => {
       const { data } = await client.get(`/api/v1/safes/${input.id}`);
@@ -34,47 +36,52 @@ export const safeTools: ToolDefinition[] = [
     name: 'create_safe',
     description: 'Record a new SAFE instrument (e.g. post-money SAFE from a YC-style round).',
     inputSchema: z.object({
-      investmentAmount: z
-        .union([z.number(), z.string()])
-        .transform((v) => parseFloat(String(v)))
-        .describe('Investment amount in USD'),
-      valuationCap: z
-        .union([z.number(), z.string()])
-        .transform((v) => parseFloat(String(v)))
-        .optional()
-        .describe('Valuation cap in USD (for valuation cap SAFEs)'),
-      discountRate: z
-        .union([z.number(), z.string()])
-        .transform((v) => parseFloat(String(v)))
-        .optional()
-        .describe('Discount rate percentage (e.g. 20 for 20%)'),
+      investmentAmount: coerceFloat('Investment amount in USD'),
+      valuationCap: coerceFloat('Valuation cap in USD (for valuation cap SAFEs)')
+        .optional(),
+      discountRate: coerceFloat('Discount rate percentage (e.g. 20 for 20%)')
+        .optional(),
       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
-        .union([z.boolean(), z.string()])
-        .transform((v) => v === true || v === 'true')
+      proRataRights: coerceBool('Whether the investor has pro-rata rights')
         .optional()
-        .default(false)
-        .describe('Whether the investor has pro-rata rights'),
+        .default(false),
     }),
     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)}` },
-        ],
-      };
+      const { data: created } = await client.post('/api/v1/safes', input);
+      const id = created.safeId ?? created.row_id ?? created._id;
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/safes/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `SAFE created:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `SAFE created (could not confirm persisted state — verify with get_safe):\n${JSON.stringify(created, null, 2)}`,
+            },
+          ],
+        };
+      }
     },
   },
   {
     name: 'update_safe',
-    description: 'Update an existing SAFE instrument (e.g. record conversion).',
+    description:
+      'Update an existing SAFE instrument (e.g. record conversion). Use the `safeId` field (e.g. `safe_xxx`) from `list_safes`, not the `_id` field.',
     inputSchema: z.object({
-      id: z.string().describe('SAFE ID'),
+      id: z.string().describe('SAFE ID — use the `safeId` field from list_safes, not `_id`'),
       status: z
         .enum(['open', 'converted', 'cancelled'])
         .optional()
@@ -87,21 +94,31 @@ export const safeTools: ToolDefinition[] = [
         .string()
         .optional()
         .describe('Share class ID that this SAFE converted into'),
-      convertedShares: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe('Number of shares issued upon conversion'),
+      convertedShares: coerceInt('Number of shares issued upon conversion').optional(),
     }),
     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)}` },
-        ],
-      };
+      const { data: updated } = await client.put(`/api/v1/safes/${id}`, body);
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/safes/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `SAFE updated:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `SAFE updated (could not confirm persisted state — verify with get_safe):\n${JSON.stringify(updated, null, 2)}`,
+            },
+          ],
+        };
+      }
     },
   },
 ];

package/src/tools/shareClasses.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceInt, coerceFloat } from '../schema.js';
 import { type ToolDefinition } from '../types.js';
 
 export const shareClassTools: ToolDefinition[] = [
@@ -8,7 +9,7 @@ export const shareClassTools: ToolDefinition[] = [
       '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'),
+      limit: coerceInt('Max results to return').optional().default(50),
     }),
     handler: async (input, client) => {
       const { data } = await client.get('/api/v1/share-classes', { params: input });
@@ -20,9 +21,10 @@ export const shareClassTools: ToolDefinition[] = [
   },
   {
     name: 'get_share_class',
-    description: 'Get details for a specific share class by ID.',
+    description:
+      'Get details for a specific share class by ID. Use the `row_id` field from `list_share_classes`.',
     inputSchema: z.object({
-      id: z.string().describe('Share class ID'),
+      id: z.string().describe('Share class ID — use the `row_id` field from list_share_classes'),
     }),
     handler: async (input, client) => {
       const { data } = await client.get(`/api/v1/share-classes/${input.id}`);
@@ -37,33 +39,42 @@ export const shareClassTools: ToolDefinition[] = [
       classType: z
         .enum(['common', 'preferred', 'warrant', 'option'])
         .describe('Type of share class'),
-      authorizedShares: z
-        .union([z.number(), z.string()])
-        .transform((v) => parseInt(String(v), 10))
-        .describe('Total number of authorized shares'),
-      parValue: z
-        .union([z.number(), z.string()])
-        .transform((v) => parseFloat(String(v)))
-        .optional()
-        .describe('Par value per share in USD'),
+      authorizedShares: coerceInt('Total number of authorized shares').refine(
+        (v) => v > 0,
+        { message: 'authorizedShares must be a positive integer' }
+      ),
+      parValue: coerceFloat('Par value per share in USD').optional(),
       companyId: z.string().describe('Company ID this share class belongs to'),
-      liquidationPreference: z
-        .union([z.number(), z.string()])
-        .transform((v) => parseFloat(String(v)))
-        .optional()
-        .describe('Liquidation preference multiplier (e.g. 1 for 1x)'),
+      liquidationPreference: coerceFloat('Liquidation preference multiplier (e.g. 1 for 1x)')
+        .optional(),
       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)}` },
-        ],
-      };
+      const { data: created } = await client.post('/api/v1/share-classes', input);
+      const id = created.row_id ?? created._id;
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/share-classes/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Share class created:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Share class created (could not confirm persisted state — verify with get_share_class):\n${JSON.stringify(created, null, 2)}`,
+            },
+          ],
+        };
+      }
     },
   },
 ];

package/src/tools/stakeholders.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceInt } from '../schema.js';
 import { type ToolDefinition } from '../types.js';
 
 export const stakeholderTools: ToolDefinition[] = [
@@ -8,7 +9,7 @@ export const stakeholderTools: ToolDefinition[] = [
       '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'),
+      limit: coerceInt('Max results to return').optional().default(50),
     }),
     handler: async (input, client) => {
       const { data } = await client.get('/api/v1/stakeholders', { params: input });
@@ -20,9 +21,10 @@ export const stakeholderTools: ToolDefinition[] = [
   },
   {
     name: 'get_stakeholder',
-    description: 'Get details for a specific stakeholder by ID.',
+    description:
+      'Get details for a specific stakeholder by ID. Use the `row_id` field from `list_stakeholders`.',
     inputSchema: z.object({
-      id: z.string().describe('Stakeholder ID'),
+      id: z.string().describe('Stakeholder ID — use the `row_id` field from list_stakeholders'),
     }),
     handler: async (input, client) => {
       const { data } = await client.get(`/api/v1/stakeholders/${input.id}`);
@@ -41,19 +43,36 @@ export const stakeholderTools: ToolDefinition[] = [
       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)}` },
-        ],
-      };
+      const { data: created } = await client.post('/api/v1/stakeholders', input);
+      const id = created.row_id ?? created._id;
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/stakeholders/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Stakeholder created:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Stakeholder created (could not confirm persisted state — verify with get_stakeholder):\n${JSON.stringify(created, null, 2)}`,
+            },
+          ],
+        };
+      }
     },
   },
   {
     name: 'update_stakeholder',
-    description: 'Update an existing stakeholder by ID.',
+    description:
+      'Update an existing stakeholder by ID. Use the `row_id` field from `list_stakeholders`.',
     inputSchema: z.object({
-      id: z.string().describe('Stakeholder ID'),
+      id: z.string().describe('Stakeholder ID — use the `row_id` field from list_stakeholders'),
       name: z.string().optional().describe('Full name'),
       email: z.string().email().optional().describe('Email address'),
       role: z
@@ -63,12 +82,27 @@ export const stakeholderTools: ToolDefinition[] = [
     }),
     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)}` },
-        ],
-      };
+      const { data: updated } = await client.put(`/api/v1/stakeholders/${id}`, body);
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/stakeholders/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Stakeholder updated:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Stakeholder updated (could not confirm persisted state — verify with get_stakeholder):\n${JSON.stringify(updated, null, 2)}`,
+            },
+          ],
+        };
+      }
     },
   },
 ];