financeops-mcp 0.1.0

package/dist/premium/gate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Premium gate — reads PRO_LICENSE dynamically from environment.
+ * CRITICAL: Do NOT cache the env variable at module load time.
+ * Must re-read process.env.PRO_LICENSE on every call to support
+ * runtime license changes (e.g., in tests or when env is updated).
+ */
+export declare class ProRequiredError extends Error {
+    constructor(tool: string);
+}
+export declare function isPro(): boolean;
+export declare function requirePro(tool: string): void;
+//# sourceMappingURL=gate.d.ts.map

package/dist/premium/gate.js

@@ -0,0 +1,22 @@
+/**
+ * Premium gate — reads PRO_LICENSE dynamically from environment.
+ * CRITICAL: Do NOT cache the env variable at module load time.
+ * Must re-read process.env.PRO_LICENSE on every call to support
+ * runtime license changes (e.g., in tests or when env is updated).
+ */
+export class ProRequiredError extends Error {
+    constructor(tool) {
+        super(`Tool "${tool}" requires a PRO_LICENSE. Set the PRO_LICENSE environment variable.`);
+        this.name = 'ProRequiredError';
+    }
+}
+export function isPro() {
+    // Dynamic read — NOT cached
+    return Boolean(process.env.PRO_LICENSE);
+}
+export function requirePro(tool) {
+    if (!isPro()) {
+        throw new ProRequiredError(tool);
+    }
+}
+//# sourceMappingURL=gate.js.map

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Core domain types for FinanceOps MCP.
+ * All monetary amounts are in the smallest currency unit (cents).
+ * Example: 15000 = €150.00
+ */
+export interface Transaction {
+    id: string;
+    date: string;
+    amount: number;
+    currency: string;
+    description: string;
+    category?: string;
+    type: 'income' | 'expense' | 'transfer';
+    provider: 'stripe' | 'xero';
+    metadata?: Record<string, string>;
+}
+export interface Invoice {
+    id: string;
+    number: string;
+    customer_name: string;
+    customer_email?: string;
+    amount: number;
+    currency: string;
+    status: 'paid' | 'pending' | 'overdue' | 'draft' | 'voided';
+    due_date: string;
+    issued_date: string;
+    paid_date?: string;
+    provider: 'stripe' | 'xero';
+    readonly amount_due?: number;
+    readonly amount_paid?: number;
+    readonly amount_credited?: number;
+}
+export interface Balance {
+    currency: string;
+    available: number;
+    pending: number;
+    provider: 'stripe' | 'xero';
+}
+export interface Expense {
+    id: string;
+    date: string;
+    amount: number;
+    currency: string;
+    description: string;
+    category: string;
+    provider: 'stripe' | 'xero';
+}
+export interface Subscription {
+    id: string;
+    customer_name: string;
+    amount: number;
+    currency: string;
+    interval: 'month' | 'year';
+    status: 'active' | 'canceled' | 'past_due' | 'trialing';
+    current_period_start: string;
+    current_period_end: string;
+    provider: 'stripe' | 'xero';
+}
+export interface PaginatedResult<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor?: string;
+}
+export interface PnLReport {
+    period: string;
+    date_from: string;
+    date_to: string;
+    currency: string;
+    revenue: number;
+    cogs: number;
+    gross_profit: number;
+    gross_margin_pct: number;
+    operating_expenses: number;
+    net_income: number;
+    by_category: Record<string, number>;
+}
+export interface CashFlowForecast {
+    period_months: number;
+    generated_at: string;
+    historical_monthly_income: number;
+    historical_monthly_expenses: number;
+    trend_pct: number;
+    scenarios: {
+        conservative: MonthlyForecast[];
+        realistic: MonthlyForecast[];
+        optimistic: MonthlyForecast[];
+    };
+}
+export interface MonthlyForecast {
+    month: string;
+    income: number;
+    expenses: number;
+    net: number;
+    cumulative_net: number;
+}
+export interface ReconciliationResult {
+    matched: MatchedPair[];
+    unmatched_stripe: Transaction[];
+    unmatched_xero: Transaction[];
+    summary: {
+        total_stripe: number;
+        total_xero: number;
+        matched_count: number;
+        unmatched_stripe_count: number;
+        unmatched_xero_count: number;
+    };
+}
+export interface MatchedPair {
+    stripe: Transaction;
+    xero: Transaction;
+    confidence: number;
+}
+export interface Anomaly {
+    id: string;
+    type: 'duplicate' | 'large_variance' | 'missed_recurring' | 'unusual_timing';
+    severity: 'low' | 'medium' | 'high';
+    transaction?: Transaction;
+    description: string;
+    amount?: number;
+    date?: string;
+}
+export interface TaxSummary {
+    provider: 'stripe' | 'xero';
+    period: 'quarter' | 'year';
+    jurisdiction?: string;
+    total_taxable_amount: number;
+    total_tax_collected: number;
+    total_tax_owed: number;
+    by_rate: TaxByRate[];
+    filing_period: string;
+}
+export interface TaxByRate {
+    rate: number;
+    rate_label: string;
+    taxable_amount: number;
+    tax_amount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Core domain types for FinanceOps MCP.
+ * All monetary amounts are in the smallest currency unit (cents).
+ * Example: 15000 = €150.00
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/mcpize.yaml

@@ -0,0 +1,10 @@
+version: 1
+name: financeops-mcp
+runtime: typescript
+entry: dist/index.js
+build:
+  install: npm ci
+  command: npx tsc
+startCommand:
+  type: stdio
+  command: node dist/index.js

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "financeops-mcp",
+  "version": "0.1.0",
+  "description": "Unified financial intelligence MCP server — Stripe + Xero",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "financeops-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^9.4.3",
+    "stripe": "^14.21.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/node": "^20.11.5",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["mcp", "finance", "stripe", "xero", "accounting"],
+  "license": "MIT"
+}

package/src/adapters/stripe.ts

@@ -0,0 +1,190 @@
+import Stripe from 'stripe';
+import type { FinanceProvider, TransactionQuery, InvoiceQuery, ExpenseQuery } from './types.js';
+import type { Transaction, Invoice, Balance, Expense, Subscription, PaginatedResult } from '../types.js';
+
+export class StripeAdapter implements FinanceProvider {
+  private client: Stripe;
+
+  constructor() {
+    const key = process.env.STRIPE_SECRET_KEY;
+    if (!key) {
+      throw new Error('STRIPE_SECRET_KEY environment variable is required');
+    }
+    this.client = new Stripe(key, { apiVersion: '2023-10-16' });
+  }
+
+  async getTransactions(opts: TransactionQuery): Promise<PaginatedResult<Transaction>> {
+    const params: Stripe.BalanceTransactionListParams = {
+      limit: Math.min(opts.limit ?? 100, 100),
+    };
+
+    if (opts.cursor) params.starting_after = opts.cursor;
+    if (opts.date_from) params.created = { gte: Math.floor(new Date(opts.date_from).getTime() / 1000) };
+    if (opts.date_to) {
+      params.created = {
+        ...(typeof params.created === 'object' && params.created !== null ? params.created : {}),
+        lte: Math.floor(new Date(opts.date_to).getTime() / 1000),
+      };
+    }
+
+    const result = await this.client.balanceTransactions.list(params);
+
+    const transactions: Transaction[] = result.data.map((bt) => ({
+      id: bt.id,
+      date: new Date(bt.created * 1000).toISOString(),
+      amount: bt.amount,  // Stripe already returns amounts in cents
+      currency: bt.currency,
+      description: bt.description ?? bt.type,
+      category: bt.type,
+      type: this.mapStripeType(bt.type),
+      provider: 'stripe' as const,
+      metadata: undefined,
+    }));
+
+    return {
+      data: transactions,
+      has_more: result.has_more,
+      next_cursor: result.has_more ? result.data[result.data.length - 1]?.id : undefined,
+    };
+  }
+
+  async getBalances(): Promise<Balance[]> {
+    const balance = await this.client.balance.retrieve();
+
+    const balances: Balance[] = [];
+
+    for (const available of balance.available) {
+      const pending = balance.pending.find((p) => p.currency === available.currency);
+      balances.push({
+        currency: available.currency,
+        available: available.amount,   // Already in cents
+        pending: pending?.amount ?? 0,
+        provider: 'stripe' as const,
+      });
+    }
+
+    return balances;
+  }
+
+  async getInvoices(opts: InvoiceQuery): Promise<PaginatedResult<Invoice>> {
+    const params: Stripe.InvoiceListParams = {
+      limit: 100,
+    };
+
+    if (opts.cursor) params.starting_after = opts.cursor;
+
+    if (opts.status) {
+      if (opts.status === 'paid') params.status = 'paid';
+      else if (opts.status === 'pending') params.status = 'open';
+      // 'overdue' = open past due_date; we post-filter below
+    }
+
+    const result = await this.client.invoices.list(params);
+
+    let invoices: Invoice[] = result.data.map((inv) => ({
+      id: inv.id,
+      number: inv.number ?? '',
+      customer_name: typeof inv.customer_name === 'string' ? inv.customer_name : '',
+      customer_email: typeof inv.customer_email === 'string' ? inv.customer_email : undefined,
+      amount: inv.amount_due,  // Already in cents
+      currency: inv.currency,
+      status: this.mapStripeInvoiceStatus(inv),
+      due_date: inv.due_date ? new Date(inv.due_date * 1000).toISOString() : '',
+      issued_date: new Date(inv.created * 1000).toISOString(),
+      paid_date: inv.status_transitions?.paid_at
+        ? new Date(inv.status_transitions.paid_at * 1000).toISOString()
+        : undefined,
+      provider: 'stripe' as const,
+    }));
+
+    if (opts.date_from) {
+      const from = new Date(opts.date_from).getTime();
+      invoices = invoices.filter((inv) => new Date(inv.issued_date).getTime() >= from);
+    }
+    if (opts.date_to) {
+      const to = new Date(opts.date_to).getTime();
+      invoices = invoices.filter((inv) => new Date(inv.issued_date).getTime() <= to);
+    }
+    if (opts.status === 'overdue') {
+      const now = Date.now();
+      invoices = invoices.filter(
+        (inv) => inv.status !== 'paid' && inv.due_date && new Date(inv.due_date).getTime() < now
+      );
+    }
+
+    return {
+      data: invoices,
+      has_more: result.has_more,
+      next_cursor: result.has_more ? result.data[result.data.length - 1]?.id : undefined,
+    };
+  }
+
+  async getExpenses(opts: ExpenseQuery): Promise<PaginatedResult<Expense>> {
+    // Stripe expenses = charges (fees), refunds, and payouts
+    const params: Stripe.BalanceTransactionListParams = {
+      limit: 100,
+      type: 'payout',
+    };
+
+    if (opts.cursor) params.starting_after = opts.cursor;
+
+    const result = await this.client.balanceTransactions.list(params);
+
+    const expenses: Expense[] = result.data.map((bt) => ({
+      id: bt.id,
+      date: new Date(bt.created * 1000).toISOString(),
+      amount: Math.abs(bt.amount),  // Cents
+      currency: bt.currency,
+      description: bt.description ?? bt.type,
+      category: bt.type === 'payout' ? 'Payouts' : bt.type,
+      provider: 'stripe' as const,
+    }));
+
+    return {
+      data: expenses,
+      has_more: result.has_more,
+      next_cursor: result.has_more ? result.data[result.data.length - 1]?.id : undefined,
+    };
+  }
+
+  async getSubscriptions(): Promise<Subscription[]> {
+    const result = await this.client.subscriptions.list({ limit: 100, status: 'all' });
+
+    return result.data.map((sub) => ({
+      id: sub.id,
+      customer_name: typeof sub.customer === 'string' ? sub.customer : (sub.customer as Stripe.Customer)?.name ?? '',
+      amount: sub.items.data.reduce((sum, item) => sum + (item.price.unit_amount ?? 0), 0),
+      currency: sub.currency,
+      interval: (sub.items.data[0]?.price.recurring?.interval ?? 'month') as 'month' | 'year',
+      status: this.mapStripeSubStatus(sub.status),
+      current_period_start: new Date(sub.current_period_start * 1000).toISOString(),
+      current_period_end: new Date(sub.current_period_end * 1000).toISOString(),
+      provider: 'stripe' as const,
+    }));
+  }
+
+  private mapStripeType(type: string): 'income' | 'expense' | 'transfer' {
+    if (['charge', 'payment', 'adjustment'].includes(type)) return 'income';
+    if (['refund', 'payout', 'stripe_fee', 'application_fee'].includes(type)) return 'expense';
+    return 'transfer';
+  }
+
+  private mapStripeInvoiceStatus(inv: Stripe.Invoice): 'paid' | 'pending' | 'overdue' | 'draft' | 'voided' {
+    if (inv.status === 'paid') return 'paid';
+    if (inv.status === 'draft') return 'draft';
+    if (inv.status === 'void') return 'voided';
+    if (inv.status === 'open') {
+      if (inv.due_date && Date.now() > inv.due_date * 1000) return 'overdue';
+      return 'pending';
+    }
+    return 'pending';
+  }
+
+  private mapStripeSubStatus(status: Stripe.Subscription.Status): 'active' | 'canceled' | 'past_due' | 'trialing' {
+    if (status === 'active') return 'active';
+    if (status === 'canceled') return 'canceled';
+    if (status === 'past_due' || status === 'unpaid') return 'past_due';
+    if (status === 'trialing') return 'trialing';
+    return 'active';
+  }
+}

package/src/adapters/types.ts

@@ -0,0 +1,34 @@
+import type { Transaction, Invoice, Balance, Expense, Subscription, PaginatedResult } from '../types.js';
+
+export type { Transaction, Invoice, Balance, Expense, Subscription, PaginatedResult };
+
+export interface TransactionQuery {
+  date_from?: string;
+  date_to?: string;
+  limit?: number;
+  cursor?: string;
+  status?: string;
+}
+
+export interface InvoiceQuery {
+  status?: 'paid' | 'pending' | 'overdue';
+  date_from?: string;
+  date_to?: string;
+  cursor?: string;
+}
+
+export interface ExpenseQuery {
+  period?: string;
+  categories?: string[];
+  date_from?: string;
+  date_to?: string;
+  cursor?: string;
+}
+
+export interface FinanceProvider {
+  getTransactions(opts: TransactionQuery): Promise<PaginatedResult<Transaction>>;
+  getBalances(): Promise<Balance[]>;
+  getInvoices(opts: InvoiceQuery): Promise<PaginatedResult<Invoice>>;
+  getExpenses(opts: ExpenseQuery): Promise<PaginatedResult<Expense>>;
+  getSubscriptions?(): Promise<Subscription[]>;
+}