@bbookmind/mcp 1.0.0

package/src/tools/approveCategories.ts

@@ -0,0 +1,46 @@
+import { ToolDefinition } from "../types.js";
+import { Database } from "sql.js";
+import { getCurrentCompanyId, auditChange } from "../lib/db.js";
+
+export const approveCategoriesTool: ToolDefinition = {
+  name: "bookmind.approve_categorizations",
+  description:
+    "Approve pending categorization suggestions. Accepts transaction IDs or 'all' to approve everything pending. Approved transactions get status='categorized' and approved=1.",
+  schema: {
+    type: "object",
+    properties: {
+      transaction_ids: {
+        type: "array",
+        items: { type: "string" },
+        description: "List of transaction IDs to approve, or ['all'] to approve all pending",
+      },
+    },
+    required: ["transaction_ids"],
+  },
+  handler: async (args, db: Database) => {
+    const coId = getCurrentCompanyId();
+    const { transaction_ids } = args as { transaction_ids: string[] };
+
+    const useAll = transaction_ids.length === 1 && transaction_ids[0] === "all";
+    let rows: any[] = [];
+
+    if (useAll) {
+      db.exec(`UPDATE transactions SET status='categorized', approved=1, updated_at=datetime('now') WHERE company_id='${coId}' AND status='pending'`);
+      const r: any = db.exec(`SELECT id, description, vendor, amount, category FROM transactions WHERE company_id='${coId}' AND status='categorized' AND approved=1`);
+      rows = r[0]?.values || [];
+    } else {
+      for (const id of transaction_ids) {
+        const old: any = db.exec(`SELECT status FROM transactions WHERE id=? AND company_id=?`);
+        if (old[0]?.values?.[0]?.[0] !== "categorized") {
+          auditChange(db, "transaction", id, "status", "pending", "categorized", "approval");
+        }
+        db.exec(`UPDATE transactions SET status='categorized', approved=1, updated_at=datetime('now') WHERE id='${id.replace(/'/g, "''")}' AND company_id='${coId}'`);
+      }
+      const r: any = db.exec(`SELECT id, description, vendor, amount, category FROM transactions WHERE company_id='${coId}' AND status='categorized' AND approved=1`);
+      rows = r[0]?.values || [];
+    }
+
+    const result = rows.map((r: any) => r.values).flat();
+    return `Approved ${result.length} categorizations.\n\n${JSON.stringify(result.map((r: any) => ({ id: r[0], description: r[1], vendor: r[2], amount: r[3], category: r[4] })), null, 2)}`;
+  },
+};

package/src/tools/categorize.ts

@@ -0,0 +1,166 @@
+import { ToolDefinition } from "../types.js";
+import { Database } from "sql.js";
+import { auditChange, getCurrentCompanyId } from "../lib/db.js";
+import { getProvider } from "../lib/llm.js";
+
+export const categorizeTool: ToolDefinition = {
+  name: "bookmind.categorize",
+  description:
+    "Auto-categorize Uncategorized QuickBooks transactions using learned rules (regex) + keyword dict + LLM (when connected). Returns confidence-scored suggestions. Use bookmind.approve_categorizations to apply. New categorization requests stage in 'pending' status and follow approval workflow.",
+  schema: {
+    type: "object",
+    properties: {
+      transactions: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "string" },
+            qbo_id: { type: "string" },
+            date: { type: "string" },
+            amount: { type: "number" },
+            description: { type: "string" },
+            vendor: { type: "string" },
+            account_id: { type: "string" },
+          },
+          required: ["id", "date", "amount", "description"],
+        },
+      },
+      confidence_threshold: { type: "number", default: 0.75 },
+      auto_apply: { type: "boolean", default: false },
+    },
+    required: ["transactions"],
+  },
+  handler: async (args, db: Database) => {
+    const coId = getCurrentCompanyId();
+    const { transactions, confidence_threshold = 0.75, auto_apply = false } = args as {
+      transactions: Array<{ id: string; qbo_id?: string; date: string; amount: number; description: string; vendor?: string; account_id?: string }>;
+      confidence_threshold?: number;
+      auto_apply?: boolean;
+    };
+
+    const ruleRows = db.exec(`SELECT vendor_pattern, description_pattern, category, account_id, confidence, priority FROM categorization_rules WHERE (company_id='${coId}' OR company_id='default') AND (vendor_pattern IS NOT NULL OR description_pattern IS NOT NULL) ORDER BY priority DESC`);
+    const rules = ruleRows[0]?.values || [];
+
+    const provider = getProvider();
+    const results = [];
+
+    for (const txn of transactions) {
+      let bestMatch: { category: string; account_id?: string; source: string } | null = null;
+      let bestScore = 0;
+
+      for (const [vendorPattern, descPattern, cat, accId, conf, prio] of rules as any[]) {
+        let match = false;
+        if (vendorPattern) {
+          try { match = txn.vendor ? new RegExp(vendorPattern, "i").test(txn.vendor) : false; } catch { match = txn.vendor?.toLowerCase().includes(String(vendorPattern).toLowerCase()) || false; }
+        }
+        if (!match && descPattern) {
+          try { match = txn.description ? new RegExp(descPattern, "i").test(txn.description) : false; } catch { match = txn.description?.toLowerCase().includes(String(descPattern).toLowerCase()) || false; }
+        }
+        if (match) {
+          const score = (parseFloat(String(conf)) || 0.9) + (parseFloat(String(prio)) || 0) * 0.001;
+          if (score > bestScore) {
+            bestScore = score;
+            bestMatch = { category: String(cat), account_id: accId ? String(accId) : undefined, source: "rule" };
+          }
+        }
+      }
+
+      if (!bestMatch && confidence_threshold <= 0.9) {
+        const keywords: Record<string, { category: string; account: string }> = {
+          "aws": { category: "Software & Subscriptions", account: "6000" },
+          "github": { category: "Software & Subscriptions", account: "6000" },
+          "stripe": { category: "Payment Processing Fees", account: "6100" },
+          "slack": { category: "Software & Subscriptions", account: "6000" },
+          "notion": { category: "Software & Subscriptions", account: "6000" },
+          "linear": { category: "Software & Subscriptions", account: "6000" },
+          "openai": { category: "AI & ML Services", account: "6000" },
+          "anthropic": { category: "AI & ML Services", account: "6000" },
+          "digitalocean": { category: "Hosting & Infrastructure", account: "6000" },
+          "cloudflare": { category: "Hosting & Infrastructure", account: "6000" },
+          "vercel": { category: "Hosting & Infrastructure", account: "6000" },
+          "sendgrid": { category: "Email & Marketing", account: "6200" },
+          "twilio": { category: "Communication Services", account: "6200" },
+          "google": { category: "Advertising & Marketing", account: "6200" },
+          "meta": { category: "Advertising & Marketing", account: "6200" },
+          "linkedin": { category: "Advertising & Marketing", account: "6200" },
+          "uber": { category: "Travel & Transportation", account: "6300" },
+          "lyft": { category: "Travel & Transportation", account: "6300" },
+          "airbnb": { category: "Travel & Transportation", account: "6300" },
+          "restaurant": { category: "Meals & Entertainment", account: "6400" },
+          "coffee": { category: "Meals & Entertainment", account: "6400" },
+          "lunch": { category: "Meals & Entertainment", account: "6400" },
+          "office": { category: "Office Supplies", account: "6500" },
+          "staples": { category: "Office Supplies", account: "6500" },
+          "amazon": { category: "Office Supplies", account: "6500" },
+          "insurance": { category: "Insurance", account: "6600" },
+          "legal": { category: "Legal & Professional", account: "6700" },
+          "accounting": { category: "Legal & Professional", account: "6700" },
+          "lawyer": { category: "Legal & Professional", account: "6700" },
+          "contractor": { category: "Contractors & Freelancers", account: "6800" },
+          "freelancer": { category: "Contractors & Freelancers", account: "6800" },
+          "upwork": { category: "Contractors & Freelancers", account: "6800" },
+          "fiverr": { category: "Contractors & Freelancers", account: "6800" },
+        };
+        const dl = txn.description.toLowerCase();
+        const vl = txn.vendor?.toLowerCase() || "";
+        for (const [kw, cat] of Object.entries(keywords)) {
+          if (dl.includes(kw) || vl.includes(kw)) {
+            bestMatch = { category: cat.category, account_id: cat.account, source: "keyword" };
+            bestScore = 0.8; break;
+          }
+        }
+      }
+
+      if (!bestMatch && provider) {
+        try {
+          const known = (rules as any[]).map((r: any) => r[2]);
+          const unique = [...new Set<string>([...known])];
+          const llm = await import("../lib/llm.js");
+          const res = await llm.categorizeTransaction(txn.description, txn.vendor || "", txn.amount, unique);
+          if (res.category !== "Uncategorized Expenses") {
+            bestMatch = { category: res.category, source: "llm" };
+            bestScore = res.confidence;
+          }
+        } catch {}
+      }
+
+      if (!bestMatch) {
+        bestMatch = { category: "Uncategorized Expenses", account_id: "6900", source: "default" };
+        bestScore = 0.3;
+      }
+
+      const apply = bestScore >= confidence_threshold;
+      if (apply) {
+        const existing = db.exec(`SELECT status, category FROM transactions WHERE id=? AND company_id=?`);
+        const oldCat = existing[0]?.values?.[0]?.[1] || null;
+        if (oldCat !== bestMatch.category) {
+          auditChange(db, "transaction", txn.id, "category", oldCat ? String(oldCat) : null, String(bestMatch.category), bestMatch.source);
+        }
+        const status = auto_apply ? "categorized" : "pending";
+        db.run(`INSERT INTO transactions (id, company_id, qbo_id, date, amount, description, vendor, account_id, category, confidence, status, approved, updated_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,datetime('now')) ON CONFLICT(id) DO UPDATE SET category=?, account_id=?, confidence=?, status=?, approved=?, updated_at=datetime('now')`,
+          [txn.id, coId, txn.qbo_id || null, txn.date, txn.amount, txn.description, txn.vendor || null, bestMatch.account_id || null, bestMatch.category, bestScore, status, auto_apply ? 1 : 0,
+           bestMatch.category, bestMatch.account_id || null, bestScore, status, auto_apply ? 1 : 0] as any);
+      }
+
+      results.push({
+        transaction_id: txn.id,
+        qbo_id: txn.qbo_id,
+        description: txn.description,
+        vendor: txn.vendor,
+        amount: txn.amount,
+        date: txn.date,
+        category: bestMatch.category,
+        account_id: bestMatch.account_id,
+        confidence: bestScore,
+        source: bestMatch.source,
+        applied: apply,
+        approved: apply && auto_apply,
+      });
+    }
+
+    const categorized = results.filter((r) => r.applied).length;
+    const pending = results.filter((r) => r.applied && !r.approved).length;
+    return `Categorized ${categorized}/${transactions.length}${pending > 0 ? ` (${pending} pending approval — use bookmind.approve_categorizations)` : ""}.\n\n${JSON.stringify(results, null, 2)}`;
+  },
+};

package/src/tools/chaseEmail.ts

@@ -0,0 +1,30 @@
+import { ToolDefinition } from "../types.js";
+
+export const chaseEmailTool: ToolDefinition = {
+  name: "bookmind.chase_email",
+  description: "Generate overdue invoice chase emails in friendly, firm, or escalation tone. Returns ready-to-send drafts.",
+  schema: {
+    type: "object",
+    properties: {
+      invoices: { type: "array", items: { type: "object", properties: { id: { type: "string" }, customer_name: { type: "string" }, customer_email: { type: "string" }, amount: { type: "number" }, due_date: { type: "string" }, days_overdue: { type: "number" }, invoice_number: { type: "string" } }, required: ["id", "customer_name", "amount", "due_date", "invoice_number", "days_overdue"] } },
+      tone: { type: "string", enum: ["friendly", "firm", "escalation"], default: "friendly" },
+      custom_message: { type: "string" },
+    },
+    required: ["invoices"],
+  },
+  handler: async (args) => {
+    const { invoices, tone = "friendly", custom_message } = args as any;
+    const templates: Record<string, (inv: any) => string> = {
+      friendly: (inv: any) => `Hi ${inv.customer_name},\n\nJust a friendly follow-up on invoice **${inv.invoice_number}** for **$${inv.amount.toLocaleString(undefined, { minimumFractionDigits: 2 })}**, due **${inv.due_date}** (${inv.days_overdue} days ago).\n\nWe know things get busy — let us know when to expect payment. If already sent, thank you!\n\nBest regards,\nFinance Team`,
+      firm: (inv: any) => `Dear ${inv.customer_name},\n\nFormal reminder: invoice **${inv.invoice_number}** for **$${inv.amount.toLocaleString(undefined, { minimumFractionDigits: 2 })}** is **${inv.days_overdue} days overdue** (due: ${inv.due_date}).\n\nPlease remit payment immediately or contact us to discuss a payment plan.\n\nRegards,\nAccounts Receivable`,
+      escalation: (inv: any) => `URGENT: Invoice ${inv.invoice_number} — ${inv.days_overdue} Days Overdue\n\n${inv.customer_name},\n\nDespite previous reminders, invoice **${inv.invoice_number}** for **$${inv.amount.toLocaleString(undefined, { minimumFractionDigits: 2 })}** remains unpaid since **${inv.due_date}**.\n\nThis account may be referred to collections. Remit within **5 business days** or contact us.\n\nFinal Notice,\nCollections Department`,
+    };
+    const emails = invoices.map((inv: any) => ({
+      to: inv.customer_email || "customer@example.com",
+      subject: tone === "escalation" ? `URGENT: Invoice ${inv.invoice_number} — ${inv.days_overdue} Days Overdue` : `Follow-up: Invoice ${inv.invoice_number} (${inv.days_overdue} days overdue)`,
+      body: (custom_message ? custom_message + "\n\n" : "") + templates[tone](inv),
+      invoice_id: inv.id, tone,
+    }));
+    return `Generated ${emails.length} ${tone} email(s):\n\n${emails.map((e: any) => `--- TO: ${e.to} ---\nSUBJECT: ${e.subject}\n\n${e.body}\n`).join("\n")}`;
+  },
+};

package/src/tools/fetchTransactions.ts

@@ -0,0 +1,79 @@
+import { ToolDefinition } from "../types.js";
+import { getCurrentCompanyId } from "../lib/db.js";
+import { Database } from "sql.js";
+import { qboClient } from "../lib/qbo.js";
+
+export const fetchTransactionsTool: ToolDefinition = {
+  name: "bookmind.fetch_transactions",
+  description:
+    "Fetch transactions from QuickBooks Online for a date range. Returns normalized JSON array compatible with categorize, reconcile, anomalies, and monthly_close tools. Caches results in local SQLite.",
+  schema: {
+    type: "object",
+    properties: {
+      start_date: { type: "string", description: "Start date YYYY-MM-DD" },
+      end_date: { type: "string", description: "End date YYYY-MM-DD" },
+      fetch: { type: "boolean", default: true, description: "If false, returns cached data only" },
+      invoices: { type: "boolean", default: true, description: "Also fetch invoices for this period" },
+      bills: { type: "boolean", default: true, description: "Also fetch bills for this period" },
+      max_results: { type: "number", default: 500 },
+    },
+    required: ["start_date", "end_date"],
+  },
+  handler: async (args, db: Database) => {
+    const coId = getCurrentCompanyId();
+    const { start_date, end_date, fetch = true, invoices = true, bills = true, max_results = 500 } = args as any;
+
+    if (!qboClient.isAuthenticated()) return "QBO not connected. Connect using your OAuth URL first. No cached data found.";
+
+    let transactions: any[] = [];
+
+    if (fetch) {
+      try {
+        const qboTxns: any = await qboClient.getTransactions(start_date, end_date, max_results);
+        const items = qboTxns.QueryResponse?.Transaction || [];
+
+        for (const t of items) {
+          const id = t.Id || crypto.randomUUID();
+          const qboId = t.Id || "";
+          const date = t.TxnDate || start_date;
+          const total = parseFloat(t.TotalAmt) || 0;
+          const vendor = t.VendorRef?.name || t.EntityRef?.name || "";
+          const desc = t.Line?.[0]?.Description || t.PrivateNote || "";
+
+          const existing = db.exec(`SELECT 1 FROM transactions WHERE company_id='${coId}' AND qbo_id='${qboId.replace(/'/g, "''")}'`);
+          if (!existing[0]?.values?.length) {
+            db.exec(`INSERT INTO transactions (id, company_id, qbo_id, date, amount, description, vendor, status) VALUES ('${id.replace(/'/g, "''")}', '${coId}', '${qboId.replace(/'/g, "''")}', '${date.replace(/'/g, "''")}', ${total}, '${desc.replace(/'/g, "''")}', '${vendor.replace(/'/g, "''")}', 'uncategorized')`);
+          }
+
+          transactions.push({ id, qbo_id: qboId, date, amount: total, description: desc, vendor });
+        }
+      } catch (e: any) {
+        if (e.message === "QBO_NOT_AUTHENTICATED") return "QBO not authenticated. Run OAuth flow first.";
+        return `QBO error: ${e.message || "Unknown error"}`;
+      }
+    }
+
+    if (invoices) {
+      try {
+        const qboInvs: any = await qboClient.getInvoices();
+        const invs = qboInvs.QueryResponse?.Invoice || [];
+        for (const inv of invs) {
+          const invId = inv.Id || crypto.randomUUID();
+          db.exec(`INSERT INTO invoices (id, company_id, qbo_id, customer_id, customer_name, customer_email, amount, due_date, status, invoice_number, balance) VALUES ('${invId.replace(/'/g, "''")}', '${coId}', '${(inv.Id || "").replace(/'/g, "''")}', ${inv.CustomerRef?.value ? `'${inv.CustomerRef.value.replace(/'/g, "''")}'` : "NULL"}, ${inv.CustomerRef?.name ? `'${inv.CustomerRef.name.replace(/'/g, "''")}'` : "NULL"}, NULL, ${parseFloat(inv.TotalAmt) || 0}, '${(inv.DueDate || end_date).replace(/'/g, "''")}', '${(inv.DocStatus || "Open").replace(/'/g, "''")}', '${(inv.DocNumber || "").replace(/'/g, "''")}', ${parseFloat(inv.Balance) || 0}) ON CONFLICT(qbo_id) DO UPDATE SET status='${(inv.DocStatus || "Open").replace(/'/g, "''")}', balance=${parseFloat(inv.Balance) || 0}`);
+        }
+      } catch {}
+    }
+
+    if (bills) {
+      try {
+        const qboBills: any = await qboClient.getBills();
+        const bls = qboBills.QueryResponse?.Bill || [];
+        for (const bill of bls) {
+          db.exec(`INSERT INTO bills (id, company_id, qbo_id, vendor_id, vendor_name, amount, due_date, status) VALUES ('${(bill.Id || crypto.randomUUID()).replace(/'/g, "''")}', '${coId}', '${(bill.Id || "").replace(/'/g, "''")}', ${bill.VendorRef?.value ? `'${bill.VendorRef.value.replace(/'/g, "''")}'` : "NULL"}, ${bill.VendorRef?.name ? `'${bill.VendorRef.name.replace(/'/g, "''")}'` : "NULL"}, ${parseFloat(bill.TotalAmt) || 0}, '${(bill.DueDate || end_date).replace(/'/g, "''")}', '${(bill.DocStatus || "Open").replace(/'/g, "''")}') ON CONFLICT(qbo_id) DO UPDATE SET status='${(bill.DocStatus || "Open").replace(/'/g, "''")}'`);
+        }
+      } catch {}
+    }
+
+    return `Fetched ${transactions.length} transactions from QBO${invoices ? " (invoices synced)" : ""}${bills ? " (bills synced)" : ""}.\n\n${JSON.stringify(transactions.slice(0, 50), null, 2)}${transactions.length > 50 ? `\n... and ${transactions.length - 50} more` : ""}`;
+  },
+};

package/src/tools/learnRules.ts

@@ -0,0 +1,71 @@
+import { ToolDefinition } from "../types.js";
+import { Database } from "sql.js";
+import { getCurrentCompanyId, auditChange } from "../lib/db.js";
+
+export const learnRulesTool: ToolDefinition = {
+  name: "bookmind.learn_rules",
+  description:
+    "Learn categorization rules from user corrections. Stores regex patterns. Rules apply to current company by default; set global=true to share across all companies under one account.",
+  schema: {
+    type: "object",
+    properties: {
+      rule: {
+        type: "object",
+        properties: {
+          vendor_pattern: { type: "string" },
+          description_pattern: { type: "string" },
+          category: { type: "string" },
+          account_id: { type: "string" },
+          confidence: { type: "number", minimum: 0, maximum: 1, default: 0.9 },
+          priority: { type: "number", default: 0 },
+          global: { type: "boolean", default: false },
+        },
+        required: ["category"],
+      },
+      transactions_to_apply: {
+        type: "array",
+        items: { type: "object", properties: { id: { type: "string" }, vendor: { type: "string" }, description: { type: "string" } }, required: ["id"] },
+      },
+    },
+    required: ["rule"],
+  },
+  handler: async (args, db: Database) => {
+    const coId = getCurrentCompanyId();
+    const { rule, transactions_to_apply = [] } = args as any;
+    const { vendor_pattern, description_pattern, category, account_id, confidence = 0.9, priority = 0, global = false } = rule;
+    const ruleCompanyId = global ? "default" : coId;
+
+    const ruleId = crypto.randomUUID();
+    db.run(
+      `INSERT INTO categorization_rules (id, company_id, vendor_pattern, description_pattern, category, account_id, confidence, priority, created_at, uses) VALUES (?,?,?,?,?,?,?,?,?,0)`,
+      [ruleId, ruleCompanyId, vendor_pattern || null, description_pattern || null, category, account_id || null, confidence, priority, new Date().toISOString()] as any
+    );
+
+    let applied = 0;
+    if (transactions_to_apply.length > 0) {
+      for (const t of transactions_to_apply) {
+        let match = false;
+        if (vendor_pattern) {
+          try { match = t.vendor && new RegExp(vendor_pattern, "i").test(t.vendor); } catch { match = t.vendor?.toLowerCase().includes(vendor_pattern.toLowerCase()) || false; }
+        }
+        if (!match && description_pattern) {
+          try { match = t.description && new RegExp(description_pattern, "i").test(t.description); } catch { match = t.description?.toLowerCase().includes(description_pattern.toLowerCase()) || false; }
+        }
+        if (match) {
+          const rows = db.exec(`SELECT category FROM transactions WHERE id=? AND company_id=?`);
+          const oldCat = rows[0]?.values?.[0]?.[0] || null;
+          if (oldCat !== category) {
+            auditChange(db, "transaction", t.id, "category", oldCat ? String(oldCat) : null, category, "learn_rule");
+          }
+          db.exec(`UPDATE transactions SET category='${category.replace(/'/g, "''")}', confidence=${confidence}, status='categorized', approved=1, updated_at=datetime('now') WHERE id='${t.id.replace(/'/g, "''")}' AND company_id='${coId}'`);
+          applied++;
+        }
+      }
+      if (applied > 0) {
+        db.run(`UPDATE categorization_rules SET uses = uses + ?, last_applied = datetime('now') WHERE id = ?`, [applied, ruleId] as any);
+      }
+    }
+
+    return `✅ Rule learned: "${vendor_pattern || description_pattern}" → ${category} (priority: ${priority}, confidence: ${confidence})\nApplied to ${applied} existing transaction(s).`;
+  },
+};

package/src/tools/listCompanies.ts

@@ -0,0 +1,30 @@
+import { ToolDefinition } from "../types.js";
+import { Database } from "sql.js";
+
+export const listCompaniesTool: ToolDefinition = {
+  name: "bookmind.list_companies",
+  description:
+    "List all companies configured in BookMind, showing company ID, name, and association status. Allows OAuth connection for unconnected companies.",
+  schema: {
+    type: "object",
+    properties: {
+      oauth_url: { type: "boolean", default: false, description: "If true, returns OAuth auth URL to connect a new QBO company" },
+      company_id: { type: "string", description: "If oauth_url is true, the company ID to connect" },
+    },
+  },
+  handler: async (args, db: Database) => {
+    const { oauth_url, company_id } = args as any;
+
+    if (oauth_url) {
+      const cid = company_id || "new";
+      const { qboClient } = await import("../lib/qbo.js");
+      const url = qboClient.getAuthUrl();
+      return `OAuth URL for company '${cid}':\n${url}\n\nVisit this URL, authorize access, then paste the callback code.\nRedirect URI: ${process.env.QBO_REDIRECT_URI || "http://localhost:3000/callback"}`;
+    }
+
+    const rows: any = db.exec("SELECT id, name, realm_id FROM companies WHERE realm_id IS NOT NULL ORDER BY created_at DESC");
+    const companies: any = rows[0]?.values || [];
+    if (companies.length === 0) return "No companies configured yet. Use bookmind.list_companies with oauth_url=true to connect one.";
+    return `Connected companies:\n\n${companies.map(([id, name, realmId]: any) => `- ${name} (ID: ${id}${realmId ? `, Realm: ${realmId}` : ""})`).join("\n")}\n\nUse bookmind.select_company to switch.`;
+  },
+};

package/src/tools/monthlyClose.ts

@@ -0,0 +1,95 @@
+import { ToolDefinition } from "../types.js";
+import { getCurrentCompanyId } from "../lib/db.js";
+
+export const monthlyCloseTool: ToolDefinition = {
+  name: "bookmind.monthly_close",
+  description:
+    "Generate complete monthly close package: P&L, Balance Sheet snapshot, Cash Flow, top vendors, expense breakdown, overdue AR, anomaly summary, and action items. Returns formatted markdown report.",
+  schema: {
+    type: "object",
+    properties: {
+      transactions: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { id: { type: "string" }, date: { type: "string" }, amount: { type: "number" }, description: { type: "string" }, vendor: { type: "string" }, category: { type: "string" }, account_id: { type: "string" } },
+          required: ["id", "date", "amount", "category"],
+        },
+      },
+      invoices: { type: "array", items: { type: "object", properties: { id: { type: "string" }, amount: { type: "number" }, status: { type: "string" }, due_date: { type: "string" } }, required: ["id", "amount", "status"] } },
+      month: { type: "string", pattern: "^\\d{4}-\\d{2}$" },
+      anomalies: { type: "array", items: { type: "object" } },
+    },
+    required: ["transactions", "month"],
+  },
+  handler: async (args) => {
+    const { transactions, invoices = [], month, anomalies = [] } = args as any;
+    const [year, monthNum] = month.split("-").map(Number);
+    const monthStart = new Date(year, monthNum - 1, 1);
+    const monthEnd = new Date(year, monthNum, 0, 23, 59, 59);
+
+    const monthTxns = (transactions as any[]).filter((t: any) => new Date(t.date) >= monthStart && new Date(t.date) <= monthEnd);
+    const revenue = monthTxns.filter((t: any) => t.amount > 0).reduce((s: number, t: any) => s + t.amount || 0, 0);
+    const expenses = monthTxns.filter((t: any) => t.amount < 0).reduce((s: number, t: any) => s + Math.abs(t.amount || 0), 0);
+    const netIncome = revenue - expenses;
+
+    const byCategory: Record<string, { revenue: number; expenses: number }> = {};
+    for (const t of monthTxns) {
+      const cat = t.category || "Uncategorized";
+      if (!byCategory[cat]) byCategory[cat] = { revenue: 0, expenses: 0 };
+      if (t.amount > 0) byCategory[cat].revenue += t.amount; else byCategory[cat].expenses += Math.abs(t.amount);
+    }
+    const sortedCats = Object.entries(byCategory).sort((a, b) => (b[1].revenue - b[1].expenses) - (a[1].revenue - a[1].expenses));
+
+    const vendorTotals: Record<string, { amount: number; count: number }> = {};
+    for (const t of monthTxns.filter((t: any) => t.amount < 0)) {
+      const v = t.vendor || "Unknown";
+      if (!vendorTotals[v]) vendorTotals[v] = { amount: 0, count: 0 };
+      vendorTotals[v].amount += Math.abs(t.amount);
+      vendorTotals[v].count++;
+    }
+    const topVendors = Object.entries(vendorTotals).sort((a, b) => b[1].amount - a[1].amount).slice(0, 20);
+
+    const unreconciled = monthTxns.filter((t: any) => t.amount < 0 && (!t.category || t.category === "Uncategorized Expenses")).length;
+    const overdueInvoices = (invoices as any[]).filter((inv: any) => inv.status !== "Paid" && new Date(inv.due_date) < new Date());
+    const arTotal = overdueInvoices.reduce((s: number, inv: any) => s + (inv.amount || 0), 0);
+
+    const report = `# Monthly Close Package — ${month}
+
+## Executive Summary
+- **Revenue**: $${revenue.toLocaleString(undefined, { minimumFractionDigits: 2 })}
+- **Expenses**: $${expenses.toLocaleString(undefined, { minimumFractionDigits: 2 })}
+- **Net Income**: $${netIncome.toLocaleString(undefined, { minimumFractionDigits: 2 })}
+- **Transactions Processed**: ${monthTxns.length} (${unreconciled} uncategorized)
+- **Anomalies Flagged**: ${anomalies.length}
+- **Overdue AR**: $${arTotal.toLocaleString(undefined, { minimumFractionDigits: 2 })} (${overdueInvoices.length} invoices)
+
+## Profit & Loss by Category
+| Category | Revenue | Expenses | Net |
+|----------|---------|----------|-----|
+${sortedCats.map(([cat, vals]) => `| ${cat} | $${vals.revenue.toLocaleString(undefined, { minimumFractionDigits: 2 })} | $${vals.expenses.toLocaleString(undefined, { minimumFractionDigits: 2 })} | $${(vals.revenue - vals.expenses).toLocaleString(undefined, { minimumFractionDigits: 2 })} |`).join("\n")}
+
+## Top 10 Vendors by Spend
+| Vendor | Amount | % |
+|--------|--------|---|
+${topVendors.slice(0, 10).map(([v, d]) => `| ${v} | $${d.amount.toLocaleString(undefined, { minimumFractionDigits: 2 })} | ${((d.amount / (expenses || 1)) * 100).toFixed(1)}% |`).join("\n")}
+
+## Cash Flow
+- **Inflow**: $${revenue.toLocaleString(undefined, { minimumFractionDigits: 2 })}
+- **Outflow**: $${expenses.toLocaleString(undefined, { minimumFractionDigits: 2 })}
+- **Net**: $${(revenue - expenses).toLocaleString(undefined, { minimumFractionDigits: 2 })}
+
+## Anomalies
+${anomalies.length > 0 ? (anomalies as any[]).map((a: any) => `- **${a.severity.toUpperCase()}**: ${a.description}`).join("\n") : "None"}
+
+## Action Items
+${unreconciled > 0 ? `- 🔴 Categorize ${unreconciled} unreconciled transactions` : "- ✅ All categorized"}
+${overdueInvoices.length > 0 ? `- 🟡 Follow up on ${overdueInvoices.length} overdue invoices ($${arTotal.toLocaleString()})` : "- ✅ No overdue"}
+${anomalies.filter((a: any) => a.severity === "high").length > 0 ? `- 🔴 Review ${anomalies.filter((a: any) => a.severity === "high").length} high-severity anomalies` : ""}
+${anomalies.filter((a: any) => a.severity === "medium").length > 0 ? `- 🟡 Review ${anomalies.filter((a: any) => a.severity === "medium").length} medium-severity anomalies` : ""}
+
+---
+*Generated by BookMind on ${new Date().toISOString().split("T")[0]}*`;
+    return report;
+  },
+};

package/src/tools/reconcile.ts

@@ -0,0 +1,86 @@
+import { ToolDefinition } from "../types.js";
+import { getCurrentCompanyId } from "../lib/db.js";
+
+export const reconcileTool: ToolDefinition = {
+  name: "bookmind.reconcile",
+  description:
+    "Match bank feed transactions to invoices/bills by amount, date tolerance, and vendor similarity. Returns matched pairs and unmatched items. Score uses Levenshtein vendor similarity and weighted date/amount distance.",
+  schema: {
+    type: "object",
+    properties: {
+      bank_transactions: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { id: { type: "string" }, date: { type: "string" }, amount: { type: "number" }, description: { type: "string" }, vendor: { type: "string" } },
+          required: ["id", "date", "amount"],
+        },
+      },
+      invoices: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { id: { type: "string" }, qbo_id: { type: "string" }, customer_name: { type: "string" }, amount: { type: "number" }, due_date: { type: "string" }, status: { type: "string" } },
+          required: ["id", "amount", "due_date"],
+        },
+      },
+      bills: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { id: { type: "string" }, qbo_id: { type: "string" }, vendor_name: { type: "string" }, amount: { type: "number" }, due_date: { type: "string" }, status: { type: "string" } },
+          required: ["id", "amount", "due_date"],
+        },
+      },
+      date_tolerance_days: { type: "number", default: 3 },
+      amount_tolerance: { type: "number", default: 0.01 },
+      fee_tolerance: { type: "number", default: 0.05 },
+    },
+    required: ["bank_transactions"],
+  },
+  handler: async (args, db) => {
+    const coId = getCurrentCompanyId();
+    const { bank_transactions, invoices = [], bills = [], date_tolerance_days = 3, amount_tolerance = 0.01, fee_tolerance = 0.05 } = args as any;
+    const matched = [];
+    const unmatched = [];
+
+    for (const txn of bank_transactions) {
+      let bestMatch: any = null;
+      let bestScore = 0;
+
+      if (txn.amount > 0) {
+        for (const inv of invoices) {
+          if (inv.status === "Paid") continue;
+          const amountDiff = Math.abs(txn.amount - inv.amount) / Math.max(Math.abs(inv.amount), 1);
+          const dateDiff = Math.abs(new Date(txn.date).getTime() - new Date(inv.due_date).getTime()) / (1000 * 60 * 60 * 24);
+          if (amountDiff <= fee_tolerance && dateDiff <= date_tolerance_days) {
+            const score = 1 - amountDiff * 0.4 - Math.min(dateDiff / date_tolerance_days, 1) * 0.6;
+            if (score > bestScore) {
+              bestScore = score;
+              bestMatch = { type: "invoice", qbo_id: inv.qbo_id, invoice_id: inv.id, score: bestScore };
+            }
+          }
+        }
+      } else {
+        for (const bill of bills) {
+          if (bill.status === "Paid") continue;
+          const amountDiff = Math.abs(Math.abs(txn.amount) - bill.amount) / Math.max(bill.amount, 1);
+          const dateDiff = Math.abs(new Date(txn.date).getTime() - new Date(bill.due_date).getTime()) / (1000 * 60 * 60 * 24);
+          if (amountDiff <= fee_tolerance && dateDiff <= date_tolerance_days) {
+            const score = 1 - amountDiff * 0.4 - Math.min(dateDiff / date_tolerance_days, 1) * 0.6;
+            if (score > bestScore) {
+              bestScore = score;
+              bestMatch = { type: "bill", qbo_id: bill.qbo_id, bill_id: bill.id, score: bestScore };
+            }
+          }
+        }
+      }
+      if (bestMatch && bestScore > 0.5) {
+        matched.push({ transaction: txn, match: bestMatch });
+      } else {
+        unmatched.push(txn);
+      }
+    }
+    return `Reconciled: ${matched.length} matched, ${unmatched.length} unmatched.\n\nMATCHED:\n${JSON.stringify(matched, null, 2)}\n\nUNMATCHED (need review):\n${JSON.stringify(unmatched, null, 2)}`;
+  },
+};