beeswax-mcp 2.0.0 → 2.1.0

package/README.md

@@ -143,6 +143,10 @@ reports the same on demand.
 | `list_projects`, `get_project` | `/active_account/projects` |
 | `list_transaction_accounts` | `/active_account/transaction_accounts` |
 | `list_account_transactions` | `/active_account/transaction_accounts/:id/transactions?from=&to=` — one account's posted ledger for a period with opening/running/closing balances (the reconciliation query) |
+| `list_bank_reconciliations`, `get_bank_reconciliation`, `create_bank_reconciliation` (write), `update_bank_reconciliation` (write) | `/reconciliations` — statement checks: the period, its rows (ticked or not) and the processed statement's lines; create from figures or from a local statement PDF (`file_path`) |
+| `reconcile_bank_rows` (write), `unreconcile_bank_rows` (write), `match_bank_statement_line` (write), `unmatch_bank_statement_line` (write) | `/reconciliations/:id/confirm`, `/unconfirm`, `/statement_lines/:line_id/match` — tick rows against the statement and record why; each tick is pushed live to the page |
+| `upload_bank_statement` (write), `get_bank_statement_status` | `/reconciliations/:id/statement` — send a statement PDF for Beeswax's own extraction and matching, then poll |
+| `find_possible_duplicate_payments` | `/reconciliations/possible_duplicates` — a bill paid twice, entered twice, or the same movement twice on the statement |
 | `list_taxes` | `/active_account/taxes` |
 | `list_companies`, `get_company`, `create_company` (write), `update_company` (write) | `/active_account/companies` — clients and suppliers with their contact people; a company must be a client, a supplier or both |
 | `list_task_files`, `list_task_file_versions` | `/tasks/:id/files` (+ per-file version history) |
@@ -154,6 +158,15 @@ reports the same on demand.
 
 ### Notes
 
+- **Working a bank statement.** `get_bank_reconciliation` returns every row
+  Beeswax has for the period and every line of the processed statement PDF.
+  For each statement line, find the row it is, `reconcile_bank_rows` it and
+  `match_bank_statement_line` with a one-line reason; a statement line with no
+  row is a transaction missing from Beeswax (record it, and it appears as a
+  new row); a row still unticked at the end is a query for the bookkeeper.
+  Anyone with the reconciliation page open watches the ticks land live. Run
+  `find_possible_duplicate_payments` before signing off.
+
 - The create tools and `apply_payment` accept `idempotency_key`. Reuse it on a
   retry and the API replays the original result instead of posting twice.
 - Every `list_*` tool accepts `updated_since` (ISO 8601) so an agent can ask

package/dist/client.js

@@ -66,6 +66,10 @@ export class BeeswaxClient {
         const body = await this.request(path);
         return rootKey ? body?.[rootKey] : body;
     }
+    // A whole response body, query params included (reports with several top-level keys).
+    async getBody(path, params = {}) {
+        return this.request(path, params);
+    }
     // Non-paginated array (e.g. an entry's transactions).
     async getList(path, rootKey, params = {}) {
         const body = await this.request(path, params);

package/dist/index.js

@@ -29,7 +29,9 @@ const INSTRUCTIONS = "Beeswax is an accounting, project and time-tracking system
     "number or lines — never count them as transactions, wages, income or expenses. " +
     "Listings return posted entries by default; pass posted:false or include_drafts:true only when the user " +
     "wants drafts. A transactions result with posted:false has no postings; lines marked preview:true are " +
-    "not postings. When reconciling or summing by account, use only results with posted:true.";
+    "not postings. When reconciling or summing by account, use only results with posted:true. " +
+    "BANK STATEMENT CHECKS: tick a row (reconcile_bank_rows) only when you have found the statement line it is; " +
+    "a statement line with no row is a transaction missing from Beeswax; a row with no statement line stays unticked and is reported to the user.";
 const server = new Server({ name: "beeswax-mcp", version: VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),

package/dist/tools.js

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
 import { normalizeDate } from "./client.js";
 import { VERSION, isNewerVersion } from "./version.js";
 // The writable half of a catalogue item. `id` is the route, not a body field,
@@ -467,6 +469,7 @@ const PAYMENT_TOOLS = [
 const SCOPE_TOOL_GROUPS = [
     { scope: "transaction_accounts:read", tools: "list_transaction_accounts, list_taxes, list_account_transactions", why: "chart of accounts, tax codes and the per-account ledger — needed for any reconciliation and for pricing document lines" },
     { scope: "transactions:read", tools: "list_*_transactions, list_journal_entry_transactions, list_account_transactions", why: "ledger postings" },
+    { scope: "reconciliations:read", tools: "list_bank_reconciliations, get_bank_reconciliation, get_bank_statement_status, find_possible_duplicate_payments", why: "reading a bank statement check and its rows; add reconciliations:write to tick rows, upload statements and record matches" },
     { scope: "companies:read", tools: "list_companies, get_company", why: "resolving a client or supplier by name" },
     { scope: "projects:read", tools: "list_projects, get_project", why: "resolving a project by name" },
     { scope: "invoices:read", tools: "list_invoices, get_invoice, list_invoice_versions", why: "" },
@@ -526,7 +529,205 @@ function attachmentTools(resource) {
         },
     ];
 }
+// ── Bank reconciliations (statement checks) ──────────────────────────────
+// The reconciliation page as tools: read the period and its rows, tick the
+// rows that appear on the statement, tie statement lines to rows with a
+// reason, upload the statement PDF, and ask what looks doubled up. Every
+// write is pushed to the page over Turbo Streams, so a person with the page
+// open watches the rows tick off as the assistant works.
+const RECONCILIATION_ROW_IDS = {
+    remittance_ids: {
+        type: "array",
+        items: { type: "integer" },
+        description: "remittance_id values from get_bank_reconciliation rows (individual payments, transfers, manual journals).",
+    },
+    line_item_ids: {
+        type: "array",
+        items: { type: "integer" },
+        description: "line_item_id values from rows that group several payments on one bank-feed line (they tick as one).",
+    },
+};
+function readStatementFile(args) {
+    if (args.base64) {
+        return { name: args.name ?? "statement.pdf", content_type: args.content_type ?? "application/pdf", base64: args.base64 };
+    }
+    if (!args.file_path)
+        throw new Error("Give file_path (a local PDF) or base64.");
+    const path = String(args.file_path).replace(/^~(?=$|\/)/, process.env.HOME ?? "~");
+    const bytes = readFileSync(path);
+    return { name: args.name ?? basename(path), content_type: "application/pdf", base64: bytes.toString("base64") };
+}
+const RECONCILIATION_TOOLS = [
+    {
+        name: "list_bank_reconciliations",
+        description: "List bank reconciliations (statement checks): one per bank account per statement period, newest first, with the statement's opening/closing balances, what Beeswax has ticked (total_received, total_spent), the signed difference and a state: " +
+            "pending_statement (created from a PDF still being read), reconciled, balanced (difference zero but rows still unticked) or unreconciled. " +
+            "Use list_transaction_accounts (bank accounts only) to find bank_account_id. Requires reconciliations:read.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                bank_account_id: { type: "integer" },
+                state: { type: "string", enum: ["pending_statement", "reconciled", "balanced", "unreconciled"] },
+                ...SYNC_PROPS,
+            },
+        },
+        handler: (client, args) => client.getList("/reconciliations", "reconciliations", { bank_account_id: args.bank_account_id, state: args.state, updated_since: args.updated_since }),
+    },
+    {
+        name: "get_bank_reconciliation",
+        description: "The whole reconciliation page in one call: the header, every ROW of the table (a Beeswax transaction on the bank account in the period, ticked or not, with received/spent, the document and what it pays for), row_counts, and the STATEMENT LINES of the most recently processed statement PDF with what each was matched to (status unmatched = nothing in Beeswax for it). " +
+            "A row is addressed by remittance_id, or by line_item_id when several payments sit on one bank-feed line and tick together. " +
+            "Reconciling means: for each statement line find the row it is, tick the row (reconcile_bank_rows) and record the reason (match_bank_statement_line); a statement line with no row is a transaction missing from Beeswax — record it (create_expense/apply_payment) and it becomes a new row; a row still unticked after the whole statement is walked is a query for the bookkeeper, never something to force. " +
+            "web_url is the page a person can watch while you work. Requires reconciliations:read.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/reconciliations/${args.id}`, ""),
+    },
+    {
+        name: "create_bank_reconciliation",
+        description: "Create a statement check for a bank account. Either give the statement period and balances (start_on, finish_on, opening_balance, closing_balance) to start ticking immediately, or give file_path (a local statement PDF) and Beeswax extracts the period and balances and runs its own matcher first — the result is pending_statement until get_bank_statement_status reports completed. " +
+            "Requires reconciliations:write and an owner or accountant role.",
+        inputSchema: {
+            type: "object",
+            properties: { ...IDEMPOTENCY_PROP,
+                bank_account_id: { type: "integer", description: "A transaction account flagged as a bank account." },
+                start_on: { type: "string", description: "Statement start date, e.g. '2026-04-01'." },
+                finish_on: { type: "string", description: "Statement end date." },
+                opening_balance: { type: "number", description: "The statement's opening balance." },
+                closing_balance: { type: "number", description: "The statement's closing balance." },
+                file_path: { type: "string", description: "Local path to the statement PDF (read by this connector and sent to Beeswax). Alternative to the four period fields." },
+                base64: { type: "string", description: "The PDF's bytes, base64-encoded — for clients that cannot read files." },
+                name: { type: "string", description: "File name for the upload, e.g. 'april.pdf'." },
+            },
+            required: ["bank_account_id"],
+        },
+        handler: (client, args) => {
+            const body = {
+                reconciliation: {
+                    bank_account_id: args.bank_account_id,
+                    start_on: normalizeDate(args.start_on),
+                    finish_on: normalizeDate(args.finish_on),
+                    opening_balance: args.opening_balance,
+                    closing_balance: args.closing_balance,
+                },
+            };
+            if (args.file_path || args.base64)
+                body.statement = readStatementFile(args);
+            return client.mutate("POST", "/reconciliations", body, { idempotencyKey: args.idempotency_key });
+        },
+    },
+    {
+        name: "update_bank_reconciliation",
+        description: "Change a statement check's period or balances (e.g. the closing balance was mistyped). The page's table is re-broadcast. Requires reconciliations:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                start_on: { type: "string" },
+                finish_on: { type: "string" },
+                opening_balance: { type: "number" },
+                closing_balance: { type: "number" },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/reconciliations/${args.id}`, {
+            reconciliation: {
+                start_on: normalizeDate(args.start_on),
+                finish_on: normalizeDate(args.finish_on),
+                opening_balance: args.opening_balance,
+                closing_balance: args.closing_balance,
+            },
+        }),
+    },
+    {
+        name: "reconcile_bank_rows",
+        description: "Tick rows of a statement check as appearing on the bank statement. Pass remittance_ids and/or line_item_ids exactly as get_bank_reconciliation reports them. Ids that are not rows of this reconciliation come back under `unknown` and nothing is written for them. " +
+            "The response carries the updated rows and the reconciliation header (difference, state). Each tick is shown live to anyone viewing the page. " +
+            "Tick only rows you have matched to a statement line; if the statement does not show a transaction, leave it unticked and say so. Requires reconciliations:write.",
+        inputSchema: { type: "object", properties: { id: { type: "integer", description: "Reconciliation id." }, ...RECONCILIATION_ROW_IDS }, required: ["id"] },
+        handler: (client, args) => client.mutate("POST", `/reconciliations/${args.id}/confirm`, { remittance_ids: args.remittance_ids ?? [], line_item_ids: args.line_item_ids ?? [] }),
+    },
+    {
+        name: "unreconcile_bank_rows",
+        description: "Untick rows of a statement check (the inverse of reconcile_bank_rows, same arguments). Requires reconciliations:write.",
+        inputSchema: { type: "object", properties: { id: { type: "integer", description: "Reconciliation id." }, ...RECONCILIATION_ROW_IDS }, required: ["id"] },
+        handler: (client, args) => client.mutate("POST", `/reconciliations/${args.id}/unconfirm`, { remittance_ids: args.remittance_ids ?? [], line_item_ids: args.line_item_ids ?? [] }),
+    },
+    {
+        name: "upload_bank_statement",
+        description: "Upload a bank statement PDF to an existing statement check and let Beeswax extract its lines and run its own matcher (exact, amount/date, then AI). Give file_path (a local PDF; this connector reads it) or base64. Poll get_bank_statement_status until completed, then get_bank_reconciliation shows the statement lines with their matches. PDF only, 25 MB. Requires reconciliations:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Reconciliation id." },
+                file_path: { type: "string", description: "Local path to the PDF." },
+                base64: { type: "string", description: "Alternative to file_path." },
+                name: { type: "string", description: "File name, e.g. 'april.pdf'." },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/reconciliations/${args.id}/statement`, { statement: readStatementFile(args) }),
+    },
+    {
+        name: "get_bank_statement_status",
+        description: "Status of the latest statement PDF run on a statement check: idle, pending, extracting, matching, completed (with matched/unmatched counts), failed (with the error) or date_mismatch. Runs usually take under a minute. Requires reconciliations:read.",
+        inputSchema: { type: "object", properties: { id: { type: "integer", description: "Reconciliation id." } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/reconciliations/${args.id}/statement_status`, ""),
+    },
+    {
+        name: "match_bank_statement_line",
+        description: "Record that a statement line (from get_bank_reconciliation's statement_lines) IS a given row, with your reasoning, and tick the row. The line then shows as matched on the page's statement log with the reason. Refused if the line is already matched to a different row — unmatch_bank_statement_line first. Requires reconciliations:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Reconciliation id." },
+                statement_line_id: { type: "integer", description: "The statement line's id." },
+                remittance_id: { type: "integer", description: "The row's remittance_id (for a grouped row, any of its remittance_ids)." },
+                reasoning: { type: "string", description: "Why this line is that row, in one sentence — shown to the bookkeeper." },
+            },
+            required: ["id", "statement_line_id", "remittance_id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/reconciliations/${args.id}/statement_lines/${args.statement_line_id}/match`, { remittance_id: args.remittance_id, reasoning: args.reasoning }),
+    },
+    {
+        name: "unmatch_bank_statement_line",
+        description: "Clear a statement line's match. untick:true also unticks the row it was matched to. Requires reconciliations:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Reconciliation id." },
+                statement_line_id: { type: "integer" },
+                untick: { type: "boolean" },
+                reasoning: { type: "string" },
+            },
+            required: ["id", "statement_line_id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/reconciliations/${args.id}/statement_lines/${args.statement_line_id}/unmatch`, { untick: args.untick ?? false, reasoning: args.reasoning }),
+    },
+    {
+        name: "find_possible_duplicate_payments",
+        description: "Possible double payments, three ways: `payments` (two or more payments from the same bank account for the same amount to the same company within window_days; same_document:true = one bill settled twice — the strongest signal), `documents` (two or more posted bills or invoices from the same company for the same total within the window — the same bill entered twice) and `statement` (the same amount and description twice on the processed statement PDF; only with reconciliation_id). " +
+            "Give reconciliation_id (its bank account and period become the scope) or bank_account_id with from/to. Suggestions only — rent is the same every month — so present each group to the user with the reason; never remove a payment on this alone. Requires reconciliations:read.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                reconciliation_id: { type: "integer" },
+                bank_account_id: { type: "integer" },
+                from: { type: "string" },
+                to: { type: "string" },
+                window_days: { type: "integer", description: "Days apart that still count as a pair. Default 7, max 90." },
+            },
+        },
+        handler: (client, args) => client.getBody("/reconciliations/possible_duplicates", {
+            reconciliation_id: args.reconciliation_id,
+            bank_account_id: args.bank_account_id,
+            from: normalizeDate(args.from),
+            to: normalizeDate(args.to),
+            window_days: args.window_days,
+        }),
+    },
+];
 export const TOOLS = [
+    ...RECONCILIATION_TOOLS,
     {
         name: "check_beeswax_connection",
         description: "Health-check the Beeswax connection: reports the connector version you are running, the latest released version " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beeswax-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Official MCP server for Beeswax (beeswaxapp.com) — query invoices, quotes, expenses, payments, journals, time entries, projects, products & services and tax returns from Claude and other MCP clients, and build quotes priced from your catalogue.",
   "license": "MIT",
   "homepage": "https://www.beeswaxapp.com/support/mcp-setup",