financeops-mcp 0.1.0

package/src/index.ts

@@ -0,0 +1,649 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { logAudit, cleanup } from './lib/audit.js';
+import { getProvider, getProviders } from './lib/providers.js';
+import { generatePnL } from './analysis/pnl.js';
+import { forecastCashFlow } from './analysis/cashflow.js';
+import { reconcile } from './analysis/reconciliation.js';
+import { detectAnomalies } from './analysis/anomaly.js';
+import { calculateTax } from './analysis/tax.js';
+import { requirePro, isPro } from './premium/gate.js';
+
+// ─── Tool input schemas ───────────────────────────────────────────────────────
+
+const ListTransactionsSchema = z.object({
+  provider: z.enum(['stripe', 'xero']),
+  date_from: z.string().optional(),
+  date_to: z.string().optional(),
+  limit: z.number().int().min(1).max(100).optional(),
+  cursor: z.string().optional(),
+  status: z.string().optional(),
+});
+
+const GetBalancesSchema = z.object({
+  provider: z.enum(['stripe', 'xero']),
+});
+
+const ListInvoicesSchema = z.object({
+  provider: z.enum(['stripe', 'xero']),
+  status: z.enum(['paid', 'pending', 'overdue']).optional(),
+  date_from: z.string().optional(),
+  date_to: z.string().optional(),
+  cursor: z.string().optional(),
+});
+
+const RevenueSummarySchema = z.object({
+  provider: z.enum(['stripe', 'xero']),
+  period: z.enum(['day', 'week', 'month', 'quarter', 'year']),
+});
+
+const ExpenseTrackerSchema = z.object({
+  provider: z.enum(['stripe', 'xero']),
+  period: z.string().optional(),
+  categories: z.array(z.string()).optional(),
+});
+
+const FinancialHealthSchema = z.object({
+  providers: z.array(z.enum(['stripe', 'xero'])).min(1),
+});
+
+const GeneratePnLSchema = z.object({
+  providers: z.array(z.enum(['stripe', 'xero'])).min(1),
+  period: z.enum(['month', 'quarter', 'year']),
+  date_from: z.string().optional(),
+  date_to: z.string().optional(),
+});
+
+const CashFlowForecastSchema = z.object({
+  providers: z.array(z.enum(['stripe', 'xero'])).min(1),
+  months_ahead: z.union([z.literal(3), z.literal(6), z.literal(12)]),
+});
+
+const ReconcileSchema = z.object({
+  date_from: z.string().optional(),
+  date_to: z.string().optional(),
+});
+
+const DetectAnomaliesSchema = z.object({
+  providers: z.array(z.enum(['stripe', 'xero'])).min(1),
+  period: z.string().optional(),
+  sensitivity: z.enum(['low', 'medium', 'high']).optional(),
+});
+
+const TaxSummarySchema = z.object({
+  provider: z.enum(['stripe', 'xero']),
+  tax_period: z.enum(['quarter', 'year']),
+  jurisdiction: z.string().optional(),
+});
+
+const MultiCurrencyReportSchema = z.object({
+  providers: z.array(z.enum(['stripe', 'xero'])).min(1),
+  base_currency: z.enum(['EUR', 'USD', 'GBP']),
+  date: z.string().optional(),
+});
+
+// ─── Server ──────────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: 'financeops-mcp', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+);
+
+// ─── List tools ──────────────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const proTools = isPro()
+    ? [
+        {
+          name: 'generate_pnl',
+          description: 'Generate a Profit & Loss statement (PRO)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              providers: { type: 'array', items: { type: 'string', enum: ['stripe', 'xero'] } },
+              period: { type: 'string', enum: ['month', 'quarter', 'year'] },
+              date_from: { type: 'string' },
+              date_to: { type: 'string' },
+            },
+            required: ['providers', 'period'],
+          },
+        },
+        {
+          name: 'cash_flow_forecast',
+          description: 'Predict future cash flow based on historical patterns (PRO)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              providers: { type: 'array', items: { type: 'string', enum: ['stripe', 'xero'] } },
+              months_ahead: { type: 'number', enum: [3, 6, 12] },
+            },
+            required: ['providers', 'months_ahead'],
+          },
+        },
+        {
+          name: 'reconcile',
+          description: 'Cross-reference Stripe payments with Xero records (PRO)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              date_from: { type: 'string' },
+              date_to: { type: 'string' },
+            },
+          },
+        },
+        {
+          name: 'detect_anomalies',
+          description: 'Find unusual financial activity (PRO)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              providers: { type: 'array', items: { type: 'string', enum: ['stripe', 'xero'] } },
+              period: { type: 'string' },
+              sensitivity: { type: 'string', enum: ['low', 'medium', 'high'] },
+            },
+            required: ['providers'],
+          },
+        },
+        {
+          name: 'tax_summary',
+          description: 'VAT/sales tax calculation and summary (PRO)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              provider: { type: 'string', enum: ['stripe', 'xero'] },
+              tax_period: { type: 'string', enum: ['quarter', 'year'] },
+              jurisdiction: { type: 'string' },
+            },
+            required: ['provider', 'tax_period'],
+          },
+        },
+        {
+          name: 'multi_currency_report',
+          description: 'Consolidated reporting across currencies (PRO)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              providers: { type: 'array', items: { type: 'string', enum: ['stripe', 'xero'] } },
+              base_currency: { type: 'string', enum: ['EUR', 'USD', 'GBP'] },
+              date: { type: 'string' },
+            },
+            required: ['providers', 'base_currency'],
+          },
+        },
+      ]
+    : [];
+
+  return {
+    tools: [
+      {
+        name: 'list_transactions',
+        description: 'Fetch transactions from Stripe or Xero',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            provider: { type: 'string', enum: ['stripe', 'xero'] },
+            date_from: { type: 'string' },
+            date_to: { type: 'string' },
+            limit: { type: 'number' },
+            cursor: { type: 'string' },
+            status: { type: 'string' },
+          },
+          required: ['provider'],
+        },
+      },
+      {
+        name: 'get_balances',
+        description: 'Get current account balances',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            provider: { type: 'string', enum: ['stripe', 'xero'] },
+          },
+          required: ['provider'],
+        },
+      },
+      {
+        name: 'list_invoices',
+        description: 'Fetch invoices with status',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            provider: { type: 'string', enum: ['stripe', 'xero'] },
+            status: { type: 'string', enum: ['paid', 'pending', 'overdue'] },
+            date_from: { type: 'string' },
+            date_to: { type: 'string' },
+            cursor: { type: 'string' },
+          },
+          required: ['provider'],
+        },
+      },
+      {
+        name: 'revenue_summary',
+        description: 'Calculate revenue metrics',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            provider: { type: 'string', enum: ['stripe', 'xero'] },
+            period: { type: 'string', enum: ['day', 'week', 'month', 'quarter', 'year'] },
+          },
+          required: ['provider', 'period'],
+        },
+      },
+      {
+        name: 'expense_tracker',
+        description: 'Categorize and summarize expenses',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            provider: { type: 'string', enum: ['stripe', 'xero'] },
+            period: { type: 'string' },
+            categories: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['provider'],
+        },
+      },
+      {
+        name: 'financial_health',
+        description: 'Quick financial health check: burn rate, runway, MRR, churn',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            providers: { type: 'array', items: { type: 'string', enum: ['stripe', 'xero'] } },
+          },
+          required: ['providers'],
+        },
+      },
+      ...proTools,
+    ],
+  };
+});
+
+// ─── Call tool ───────────────────────────────────────────────────────────────
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'list_transactions': {
+        const input = ListTransactionsSchema.parse(args);
+        const provider = getProvider(input.provider);
+        const result = await provider.getTransactions({
+          date_from: input.date_from,
+          date_to: input.date_to,
+          limit: input.limit,
+          cursor: input.cursor,
+          status: input.status,
+        });
+        logAudit({ tool: name, provider: input.provider, input_summary: JSON.stringify({ limit: input.limit }), success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case 'get_balances': {
+        const input = GetBalancesSchema.parse(args);
+        const provider = getProvider(input.provider);
+        const balances = await provider.getBalances();
+        logAudit({ tool: name, provider: input.provider, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(balances, null, 2) }],
+        };
+      }
+
+      case 'list_invoices': {
+        const input = ListInvoicesSchema.parse(args);
+        const provider = getProvider(input.provider);
+        const result = await provider.getInvoices({
+          status: input.status,
+          date_from: input.date_from,
+          date_to: input.date_to,
+          cursor: input.cursor,
+        });
+        logAudit({ tool: name, provider: input.provider, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case 'revenue_summary': {
+        const input = RevenueSummarySchema.parse(args);
+        const provider = getProvider(input.provider);
+
+        const periodDates = getPeriodDates(input.period);
+        const txResult = await provider.getTransactions(periodDates);
+        const incomeTransactions = txResult.data.filter((t) => t.type === 'income');
+        const totalRevenueCents = incomeTransactions.reduce((sum, t) => sum + t.amount, 0);
+
+        const byCustomer: Record<string, number> = {};
+        for (const t of incomeTransactions) {
+          const key = t.description;
+          byCustomer[key] = (byCustomer[key] ?? 0) + t.amount;
+        }
+
+        const topCustomers = Object.entries(byCustomer)
+          .sort(([, a], [, b]) => b - a)
+          .slice(0, 5)
+          .map(([name, amountCents]) => ({ name, amount: amountCents / 100 }));
+
+        const summary = {
+          period: input.period,
+          provider: input.provider,
+          total_revenue: totalRevenueCents / 100,
+          transaction_count: incomeTransactions.length,
+          average_transaction:
+            incomeTransactions.length > 0
+              ? totalRevenueCents / incomeTransactions.length / 100
+              : 0,
+          top_customers: topCustomers,
+        };
+
+        logAudit({ tool: name, provider: input.provider, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
+        };
+      }
+
+      case 'expense_tracker': {
+        const input = ExpenseTrackerSchema.parse(args);
+        const provider = getProvider(input.provider);
+
+        const expResult = await provider.getExpenses({
+          categories: input.categories,
+        });
+
+        const byCategory: Record<string, number> = {};
+        for (const e of expResult.data) {
+          const cat = e.category ?? 'Uncategorized';
+          byCategory[cat] = (byCategory[cat] ?? 0) + e.amount;
+        }
+
+        const total = expResult.data.reduce((sum, e) => sum + e.amount, 0);
+
+        const result = {
+          provider: input.provider,
+          total_expenses: total / 100,
+          by_category: Object.fromEntries(
+            Object.entries(byCategory).map(([k, v]) => [k, v / 100])
+          ),
+          count: expResult.data.length,
+        };
+
+        logAudit({ tool: name, provider: input.provider, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case 'financial_health': {
+        const input = FinancialHealthSchema.parse(args);
+        const providers = getProviders(input.providers);
+
+        const health: Record<string, unknown> = {
+          providers: input.providers,
+          notes: [] as string[],
+        };
+
+        for (let i = 0; i < providers.length; i++) {
+          const provider = providers[i];
+          const providerName = input.providers[i];
+
+          const [balances, txResult] = await Promise.all([
+            provider.getBalances(),
+            provider.getTransactions(getPeriodDates('month')),
+          ]);
+
+          const monthlyIncome = txResult.data
+            .filter((t) => t.type === 'income')
+            .reduce((sum, t) => sum + t.amount, 0);
+          const monthlyExpenses = txResult.data
+            .filter((t) => t.type === 'expense')
+            .reduce((sum, t) => sum + t.amount, 0);
+
+          const totalAvailable = balances.reduce((sum, b) => sum + b.available, 0);
+          const burnRate = monthlyExpenses / 100;
+          const runway = burnRate > 0 ? (totalAvailable / 100) / burnRate : null;
+
+          health[providerName] = {
+            total_balance: totalAvailable / 100,
+            monthly_income: monthlyIncome / 100,
+            monthly_expenses: monthlyExpenses / 100,
+            burn_rate: burnRate,
+            runway_months: runway !== null ? Math.round(runway * 10) / 10 : 'N/A',
+          };
+
+          // Important Fix I4: note when subscription data is unavailable
+          if (!provider.getSubscriptions) {
+            (health.notes as string[]).push(
+              `Subscription data (MRR, churn) only available from Stripe.`
+            );
+          } else {
+            const subscriptions = await provider.getSubscriptions();
+            const activeSubs = subscriptions.filter((s) => s.status === 'active');
+            const mrr = activeSubs.reduce((sum, s) => {
+              const monthly = s.interval === 'year' ? s.amount / 12 : s.amount;
+              return sum + monthly;
+            }, 0);
+            const totalSubs = subscriptions.length;
+            const canceledSubs = subscriptions.filter((s) => s.status === 'canceled').length;
+            const churnRate = totalSubs > 0 ? (canceledSubs / totalSubs) * 100 : 0;
+
+            (health[providerName] as Record<string, unknown>).mrr = mrr / 100;
+            (health[providerName] as Record<string, unknown>).churn_rate_pct =
+              Math.round(churnRate * 10) / 10;
+          }
+        }
+
+        logAudit({ tool: name, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(health, null, 2) }],
+        };
+      }
+
+      // ─── Pro tools ────────────────────────────────────────────────────────
+
+      case 'generate_pnl': {
+        requirePro(name);
+        const input = GeneratePnLSchema.parse(args);
+        const periodDates = input.date_from && input.date_to
+          ? { date_from: input.date_from, date_to: input.date_to }
+          : getPeriodDates(input.period);
+
+        const allTransactions = [];
+        const allExpenses = [];
+
+        for (const providerName of input.providers) {
+          const provider = getProvider(providerName);
+          const [txResult, expResult] = await Promise.all([
+            provider.getTransactions(periodDates),
+            provider.getExpenses({}),
+          ]);
+          allTransactions.push(...txResult.data);
+          allExpenses.push(...expResult.data);
+        }
+
+        const pnl = generatePnL(
+          allTransactions,
+          allExpenses,
+          periodDates.date_from ?? '',
+          periodDates.date_to ?? ''
+        );
+
+        logAudit({ tool: name, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(pnl, null, 2) }],
+        };
+      }
+
+      case 'cash_flow_forecast': {
+        requirePro(name);
+        const input = CashFlowForecastSchema.parse(args);
+
+        const allTransactions = [];
+        for (const providerName of input.providers) {
+          const provider = getProvider(providerName);
+          const txResult = await provider.getTransactions({});
+          allTransactions.push(...txResult.data);
+        }
+
+        const forecast = forecastCashFlow(allTransactions, input.months_ahead);
+        logAudit({ tool: name, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(forecast, null, 2) }],
+        };
+      }
+
+      case 'reconcile': {
+        requirePro(name);
+        const input = ReconcileSchema.parse(args);
+
+        const stripeProvider = getProvider('stripe');
+        const xeroProvider = getProvider('xero');
+
+        const [stripeResult, xeroResult] = await Promise.all([
+          stripeProvider.getTransactions({
+            date_from: input.date_from,
+            date_to: input.date_to,
+          }),
+          xeroProvider.getTransactions({
+            date_from: input.date_from,
+            date_to: input.date_to,
+          }),
+        ]);
+
+        const result = reconcile(stripeResult.data, xeroResult.data);
+        logAudit({ tool: name, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case 'detect_anomalies': {
+        requirePro(name);
+        const input = DetectAnomaliesSchema.parse(args);
+
+        const allTransactions = [];
+        for (const providerName of input.providers) {
+          const provider = getProvider(providerName);
+          const txResult = await provider.getTransactions({});
+          allTransactions.push(...txResult.data);
+        }
+
+        const anomalies = detectAnomalies(allTransactions, input.sensitivity ?? 'medium');
+        logAudit({ tool: name, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(anomalies, null, 2) }],
+        };
+      }
+
+      case 'tax_summary': {
+        requirePro(name);
+        const input = TaxSummarySchema.parse(args);
+        const provider = getProvider(input.provider);
+        const txResult = await provider.getTransactions({});
+        const summary = calculateTax(txResult.data, input.tax_period, input.jurisdiction);
+        logAudit({ tool: name, provider: input.provider, success: true });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
+        };
+      }
+
+      case 'multi_currency_report': {
+        requirePro(name);
+        const input = MultiCurrencyReportSchema.parse(args);
+        // Placeholder — full FX logic handled separately
+        logAudit({ tool: name, success: true });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({
+                message: 'multi_currency_report requires EXCHANGERATE_API_KEY. See docs.',
+                base_currency: input.base_currency,
+                providers: input.providers,
+              }),
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    logAudit({ tool: name, success: false, error: message });
+    return {
+      content: [{ type: 'text', text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getPeriodDates(period: string): { date_from: string; date_to: string } {
+  const now = new Date();
+  const to = now.toISOString().substring(0, 10);
+
+  let from: Date;
+  switch (period) {
+    case 'day':
+      from = new Date(now);
+      from.setDate(from.getDate() - 1);
+      break;
+    case 'week':
+      from = new Date(now);
+      from.setDate(from.getDate() - 7);
+      break;
+    case 'month':
+      from = new Date(now);
+      from.setMonth(from.getMonth() - 1);
+      break;
+    case 'quarter':
+      from = new Date(now);
+      from.setMonth(from.getMonth() - 3);
+      break;
+    case 'year':
+      from = new Date(now);
+      from.setFullYear(from.getFullYear() - 1);
+      break;
+    default:
+      from = new Date(now);
+      from.setMonth(from.getMonth() - 1);
+  }
+
+  return {
+    date_from: from.toISOString().substring(0, 10),
+    date_to: to,
+  };
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Clean up audit entries older than 90 days (Important Fix I9: only here, not in getAuditLog)
+  try {
+    cleanup(90);
+  } catch {
+    // Audit cleanup failure should not prevent server start
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[financeops-mcp] Server started');
+}
+
+main().catch((err) => {
+  console.error('[financeops-mcp] Fatal error:', err);
+  process.exit(1);
+});