@bbookmind/mcp 1.0.0

package/mcp-server.toml

@@ -0,0 +1,30 @@
+[server]
+id = "io.bookmind.mcp"
+name = "BookMind"
+version = "1.0.0"
+description = "AI bookkeeping for QuickBooks Online — auto-categorize, reconcile, monthly close, anomalies, vendor search, chase emails"
+homepage = "https://github.com/bbookmind/mcp"
+repository = "https://github.com/bbookmind/mcp"
+license = "MIT"
+
+[author]
+name = "BookMind"
+email = "support@bookmind.dev"
+
+[install]
+npm = "@bbookmind/mcp"
+npx = "npx @bookmind/mcp"
+
+[transport]
+type = "stdio"
+command = "npx"
+args = ["-y", "@bbookmind/mcp"]
+
+[capabilities]
+tools = true
+resources = true
+prompts = true
+
+[features]
+data_storage = "local_sqlite"
+offline_mode = true

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bbookmind/mcp",
+  "version": "1.0.0",
+  "description": "AI bookkeeping for QuickBooks Online. Use any model, any provider.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts"
+  },
+  "keywords": [
+    "mcp",
+    "quickbooks",
+    "bookkeeping",
+    "accounting",
+    "ai-agent"
+  ],
+  "author": "bbookmind",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bbookmind/mcp.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "sql.js": "^1.10.0",
+    "zod": "^3.23.0",
+    "axios": "^1.7.0",
+    "date-fns": "^3.6.0",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "@types/uuid": "^9.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.5.0",
+    "eslint": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@types/sql.js": "^1.4.7"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/server.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "https://registry.modelcontextprotocol.io/schemas/server-schema.json",
+  "id": "io.bookmind.mcp",
+  "name": "BookMind",
+  "description": "AI bookkeeping for QuickBooks Online. Auto-categorize transactions, reconcile bank feeds, generate monthly close packages, detect anomalies, and draft chase emails — all from your AI agent. Provider-agnostic, agent-agnostic, rules-first.",
+  "version": "1.0.0",
+  "categories": ["finance", "accounting", "bookkeeping", "quickbooks"],
+  "tags": ["quickbooks", "bookkeeping", "accounting", "mcp", "finance", "qbo", "ai-agent"],
+  "homepage": "https://github.com/bbookmind/mcp",
+  "repository": "https://github.com/bbookmind/mcp",
+  "license": "MIT",
+  "author": {
+    "name": "BookMind",
+    "email": "support@bookmind.dev"
+  },
+  "install": {
+    "npm": "@bbookmind/mcp",
+    "npx": "npx @bookmind/mcp"
+  },
+  "transport": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@bbookmind/mcp"]
+  },
+  "env": {
+    "QBO_CLIENT_ID": {
+      "description": "QuickBooks Online OAuth Client ID",
+      "required": true
+    },
+    "QBO_CLIENT_SECRET": {
+      "description": "QuickBooks Online OAuth Client Secret",
+      "required": true
+    },
+    "QBO_REDIRECT_URI": {
+      "description": "OAuth redirect URI",
+      "default": "http://localhost:3000/callback",
+      "required": false
+    },
+    "QBO_ENVIRONMENT": {
+      "description": "QuickBooks environment (sandbox or production)",
+      "default": "sandbox",
+      "required": false
+    }
+  },
+  "tools": [
+    {
+      "name": "bookmind.categorize",
+      "description": "Auto-categorize uncategorized transactions using learned rules + any LLM provider",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.reconcile",
+      "description": "Match bank transactions to invoices/bills by amount, date, and vendor",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.monthly_close",
+      "description": "Generate full monthly close package: P&L, Balance Sheet, Cash Flow, action items",
+      "risk": "read"
+    },
+    {
+      "name": "bookmind.anomalies",
+      "description": "Detect duplicate payments, vendor cost drift, outliers, and frequency anomalies",
+      "risk": "read"
+    },
+    {
+      "name": "bookmind.vendor_search",
+      "description": "Natural language vendor transaction search",
+      "risk": "read"
+    },
+    {
+      "name": "bookmind.chase_email",
+      "description": "Generate professional overdue invoice emails in friendly/firm/escalation tones",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.fetch_transactions",
+      "description": "Pull transactions, invoices, bills from QuickBooks Online",
+      "risk": "read"
+    },
+    {
+      "name": "bookmind.sync_to_qbo",
+      "description": "Push approved categorizations back to QuickBooks",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.approve_categorizations",
+      "description": "Approve pending categorizations in batch",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.reject_categorizations",
+      "description": "Reject categorizations with feedback, auto-create rules from corrections",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.undo_categorize",
+      "description": "Rollback categorization changes from audit log",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.learn_rules",
+      "description": "Create persistent categorization rules from user corrections",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.select_company",
+      "description": "Switch between connected QuickBooks companies",
+      "risk": "write"
+    },
+    {
+      "name": "bookmind.list_companies",
+      "description": "List all connected QuickBooks companies with OAuth status",
+      "risk": "read"
+    }
+  ],
+  "features": {
+    "auth": {
+      "type": "oauth2",
+      "provider": "intuit"
+    },
+    "ai_providers": ["openai", "anthropic", "google", "groq", "mistral", "nvidia", "ollama"],
+    "data_storage": "local_sqlite",
+    "offline_mode": true
+  },
+  "screenshots": [
+    {
+      "url": "https://raw.githubusercontent.com/bookmind/mcp/main/assets/screenshot-cli.png",
+      "alt": "BookMind CLI running monthly close"
+    },
+    {
+      "url": "https://raw.githubusercontent.com/bookmind/mcp/main/assets/screenshot-categorize.png",
+      "alt": "AI categorization in action"
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ErrorCode,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+import { getDb, saveDb, getCurrentCompanyId } from "./lib/db.js";
+import { activeCompanyId } from "./types.js";
+import { categorizeTool } from "./tools/categorize.js";
+import { reconcileTool } from "./tools/reconcile.js";
+import { anomaliesTool } from "./tools/anomalies.js";
+import { monthlyCloseTool } from "./tools/monthlyClose.js";
+import { vendorSearchTool } from "./tools/vendorSearch.js";
+import { chaseEmailTool } from "./tools/chaseEmail.js";
+import { learnRulesTool } from "./tools/learnRules.js";
+import { approveCategoriesTool } from "./tools/approveCategories.js";
+import { rejectCategoriesTool } from "./tools/rejectCategories.js";
+import { undoCategoriesTool } from "./tools/undoCategories.js";
+import { fetchTransactionsTool } from "./tools/fetchTransactions.js";
+import { syncToQboTool } from "./tools/syncToQbo.js";
+import { selectCompanyTool } from "./tools/selectCompany.js";
+import { listCompaniesTool } from "./tools/listCompanies.js";
+
+const server = new Server(
+  {
+    name: "bookmind",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+      prompts: {},
+    },
+  }
+);
+
+const tools = [
+  categorizeTool,
+  reconcileTool,
+  anomaliesTool,
+  monthlyCloseTool,
+  vendorSearchTool,
+  chaseEmailTool,
+  learnRulesTool,
+  approveCategoriesTool,
+  rejectCategoriesTool,
+  undoCategoriesTool,
+  fetchTransactionsTool,
+  syncToQboTool,
+  selectCompanyTool,
+  listCompaniesTool,
+];
+
+const resourceTemplates = [
+  {
+    uriTemplate: "bookmind://rules",
+    name: "Categorization Rules",
+    description: "List all categorization rules for the current company",
+    mimeType: "application/json",
+  },
+  {
+    uriTemplate: "bookmind://accounts",
+    name: "QBO Accounts",
+    description: "List QuickBooks Online accounts",
+    mimeType: "application/json",
+  },
+  {
+    uriTemplate: "bookmind://anomalies/{id}",
+    name: "Anomaly Details",
+    description: "Get details of a specific anomaly by ID",
+    mimeType: "application/json",
+  },
+];
+
+const prompts = [
+  {
+    name: "monthly-close",
+    description: "Generate a monthly close report with reconciliation and anomaly review",
+    arguments: [
+      { name: "month", description: "Month to close (YYYY-MM)", required: true },
+      { name: "year", description: "Year (optional, defaults to current year)", required: false },
+    ],
+  },
+  {
+    name: "categorize",
+    description: "Interactive transaction categorization workflow",
+    arguments: [
+      { name: "transaction_ids", description: "Comma-separated list of transaction IDs, or 'all' for pending", required: true },
+      { name: "auto_approve", description: "Auto-approve high-confidence suggestions", required: false },
+    ],
+  },
+  {
+    name: "reconcile",
+    description: "Reconcile transactions with bank statements",
+    arguments: [
+      { name: "start_date", description: "Start date (YYYY-MM-DD)", required: true },
+      { name: "end_date", description: "End date (YYYY-MM-DD)", required: true },
+      { name: "account_id", description: "Account ID to reconcile", required: false },
+    ],
+  },
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.schema,
+  })),
+}));
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: resourceTemplates.map((rt) => ({
+    uri: rt.uriTemplate.replace("{id}", "*"),
+    name: rt.name,
+    description: rt.description,
+    mimeType: rt.mimeType,
+  })),
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri;
+  const db = await getDb();
+  const coId = getCurrentCompanyId();
+
+  if (uri === "bookmind://rules") {
+    const rows = db.exec(`SELECT id, vendor_pattern, description_pattern, category, confidence, priority, uses FROM categorization_rules WHERE company_id='${coId}' OR company_id='default' ORDER BY priority DESC`);
+    const rules = rows[0]?.values || [];
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(rules.map(([id, vp, dp, cat, conf, pri, uses]) => ({ id, vendor_pattern: vp, description_pattern: dp, category: cat, confidence: conf, priority: pri, uses })), null, 2),
+        },
+      ],
+    };
+  }
+
+  if (uri === "bookmind://accounts") {
+    try {
+      const { qboClient } = await import("./lib/qbo.js");
+      if (!qboClient.isAuthenticated()) {
+        return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ error: "QBO not connected" }, null, 2) }] };
+      }
+      const accounts: any = await qboClient.getAccounts();
+      const accList = accounts.QueryResponse?.Account || [];
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify(accList.map((a: any) => ({ id: a.Id, name: a.Name, type: a.AccountType, balance: a.CurrentBalance })), null, 2),
+          },
+        ],
+      };
+    } catch (e: any) {
+      return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ error: e.message }, null, 2) }] };
+    }
+  }
+
+  const anomalyMatch = uri.match(/^bookmind:\/\/anomalies\/(.+)$/);
+  if (anomalyMatch) {
+    const anomalyId = anomalyMatch[1];
+    const rows: any = db.exec(`SELECT id, type, severity, description, transaction_id, vendor, amount, detected_at FROM anomalies WHERE id='${anomalyId.replace(/'/g, "''")}' AND company_id='${coId}'`);
+    const anomaly: any = rows[0]?.values?.[0];
+    if (!anomaly) {
+      return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ error: "Anomaly not found" }, null, 2) }] };
+    }
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify({ id: anomaly[0], type: anomaly[1], severity: anomaly[2], description: anomaly[3], transaction_id: anomaly[4], vendor: anomaly[5], amount: anomaly[6], detected_at: anomaly[7] }, null, 2),
+        },
+      ],
+    };
+  }
+
+  throw new McpError(ErrorCode.MethodNotFound, `Unknown resource: ${uri}`);
+});
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: prompts.map((p) => ({
+    name: p.name,
+    description: p.description,
+    arguments: p.arguments,
+  })),
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const db = await getDb();
+  const coId = getCurrentCompanyId();
+
+  if (name === "monthly-close") {
+    const month = args?.month;
+    if (!month) throw new McpError(ErrorCode.InvalidParams, "Missing required argument: month");
+    const [year, mon] = month.split("-");
+    const startDate = `${year}-${mon}-01`;
+    const endDate = new Date(parseInt(year), parseInt(mon), 0).toISOString().split("T")[0];
+
+    const rows: any = db.exec(`SELECT COUNT(*), SUM(amount), SUM(CASE WHEN status='categorized' THEN 1 ELSE 0 END), SUM(CASE WHEN status='uncategorized' THEN 1 ELSE 0 END) FROM transactions WHERE company_id='${coId}' AND date >= '${startDate}' AND date <= '${endDate}'`);
+    const stats: any = rows[0]?.values?.[0] || [0, 0, 0, 0];
+    const anomalyRows: any = db.exec(`SELECT COUNT(*), SUM(CASE WHEN acknowledged=0 THEN 1 ELSE 0 END) FROM anomalies WHERE company_id='${coId}' AND detected_at >= '${startDate}'`);
+    const anomalies: any = anomalyRows[0]?.values?.[0] || [0, 0];
+
+    return {
+      description: `Monthly close for ${month}`,
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Generate monthly close report for ${month}:
+- Total transactions: ${stats[0]}
+- Total volume: $${parseFloat(stats[1] || 0).toLocaleString(undefined, { minimumFractionDigits: 2 })}
+- Categorized: ${stats[2]}
+- Uncategorized: ${stats[3]}
+- Anomalies detected: ${anomalies[0]}
+- Unacknowledged anomalies: ${anomalies[1]}
+
+Run reconcile, review anomalies, then generate close report.`,
+          },
+        },
+      ],
+    };
+  }
+
+  if (name === "categorize") {
+    const txIds = args?.transaction_ids;
+    if (!txIds) throw new McpError(ErrorCode.InvalidParams, "Missing required argument: transaction_ids");
+    const autoApprove = args?.auto_approve === "true";
+
+    return {
+      description: "Categorize transactions",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Categorize transactions: ${txIds}
+Auto-approve high-confidence suggestions: ${autoApprove}
+
+1. Run bookmind.categorize with the transaction IDs
+2. Review suggestions
+3. Run bookmind.approve_categorizations or bookmind.reject_categorizations as needed
+4. Optionally run bookmind.learn_rules to create rules from corrections`,
+          },
+        },
+      ],
+    };
+  }
+
+  if (name === "reconcile") {
+    const startDate = args?.start_date;
+    const endDate = args?.end_date;
+    if (!startDate || !endDate) throw new McpError(ErrorCode.InvalidParams, "Missing required arguments: start_date, end_date");
+
+    return {
+      description: "Reconcile transactions",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Reconcile transactions from ${startDate} to ${endDate}
+Account: ${args?.account_id || "all"}
+
+1. Run bookmind.fetch_transactions with the date range
+2. Run bookmind.reconcile with the fetched transactions
+3. Review matches and exceptions
+4. Approve reconciliations`,
+          },
+        },
+      ],
+    };
+  }
+
+  throw new McpError(ErrorCode.MethodNotFound, `Unknown prompt: ${name}`);
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const tool = tools.find((t) => t.name === request.params.name);
+  if (!tool) {
+    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+  }
+
+  try {
+    const db = await getDb();
+    const result = await tool.handler(request.params.arguments ?? {}, db);
+    await saveDb();
+    return {
+      content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) }],
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new McpError(ErrorCode.InternalError, message);
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`BookMind v1.0.0 — ${tools.length} tools, ${resourceTemplates.length} resources, ${prompts.length} prompts registered`);
+console.error(`Active company: ${activeCompanyId.current || "default"}`);