beeswax-mcp 1.3.0 → 1.4.0

package/README.md

@@ -6,10 +6,21 @@ for creative businesses. It lets Claude and other MCP clients query your invoice
 quotes, expenses, payments, journals, time entries, milestones, products & services
 and tax returns.
 
-It is **read-mostly**: writes are limited to quotes, manual journals, tax-return
-fields, the products & services catalogue, freeform project documents and custom
-document themes, and each write is gated behind its own token scope — everything
-else is strictly read-only.
+Writes cover quotes, invoices and expenses (create, edit, finalise, void, version
+restore), payments, manual journals, tax-return fields, the products & services
+catalogue, freeform project documents and custom document themes — each gated
+behind its own token scope. Everything else is strictly read-only.
+
+**Ledger rule — read this first.** Every entry the server returns carries a
+`posted` boolean. An entry is on the ledger **only when `posted` is true**.
+Drafts, payroll templates, quotes and voided entries never affect the ledger,
+whatever their `state`, `number` or line items say (a draft manual journal can
+carry a number). Listings return posted entries by default; pass
+`posted: false` for the unposted ones or `include_drafts: true` for both. A
+`list_*_transactions` result for an unposted entry is `{ posted: false,
+reason, transactions: [] }`; lines marked `preview: true` are not postings.
+When summing by account or reconciling, use only results with `posted: true`.
+See the changelog for the 1.4.0 behaviour change.
 
 **Nothing here sends anything to your clients.** The quote tools create and edit
 drafts; emailing a quote, and marking one accepted, stay human actions in the
@@ -113,12 +124,17 @@ reports the same on demand.
 |---|---|
 | `check_beeswax_connection` | `/meta` — connection health check: connector vs latest version, account, user, token scopes (no scope required) |
 | `list_invoices`, `get_invoice`, `list_invoice_transactions` | `/invoices` |
+| `create_invoice` (write), `update_invoice` (write), `finalise_invoice` (write), `void_invoice` (write), `delete_invoice` (write) | `/invoices` — create lands a draft; finalise posts; void retires a finalised unpaid one; delete is drafts only; no unfinalise |
+| `list_invoice_groups`, `add_invoice_group` (write), `update_invoice_group` (write), `delete_invoice_group` (write), `add_invoice_line` (write), `update_invoice_line` (write), `delete_invoice_line` (write) | `/invoices/:id/transaction_groups[/:group_id/transactions]` |
+| `list_invoice_versions`, `get_invoice_version`, `restore_invoice_version` (write) | `/invoices/:id/versions` — append-only history; restore lands as the next version |
 | `list_quotes`, `get_quote`, `list_quote_transactions` | `/quotes` |
 | `create_quote` (write), `update_quote` (write), `finalise_quote` (write), `delete_quote` (write) | `/quotes` |
 | `list_quote_groups`, `add_quote_group` (write), `update_quote_group` (write), `delete_quote_group` (write), `reorder_quote_groups` (write) | `/quotes/:id/transaction_groups` |
 | `add_quote_line` (write), `update_quote_line` (write), `delete_quote_line` (write), `reorder_quote_lines` (write) | `/quotes/:id/transaction_groups/:group_id/transactions` |
 | `list_expenses`, `get_expense`, `list_expense_transactions` | `/expenses` |
+| `create_expense`, `update_expense`, `finalise_expense`, `void_expense`, `delete_expense`, `list_expense_groups`, `add_expense_group`, `update_expense_group`, `delete_expense_group`, `add_expense_line`, `update_expense_line`, `delete_expense_line`, `list_expense_versions`, `get_expense_version`, `restore_expense_version` (writes as for invoices) | `/expenses` … |
 | `query_payments`, `get_payment`, `list_payment_transactions` | `/payments` |
+| `apply_payment` (write), `remove_payment` (write) | `/payments` — one payment per allocated document, one money side per call, all-or-nothing; no update |
 | `query_journal_entries`, `get_journal_entry`, `list_journal_entry_transactions` | `/journal_entries` |
 | `list_time_entries`, `get_time_entry` | `/time_entries` |
 | `list_events`, `get_event` | `/events` (visibility-filtered) |
@@ -179,6 +195,16 @@ reports the same on demand.
   a rotating default. On `update_quote_line` the link is all that changes: the
   line keeps its numbers, so an already-priced quote can be re-pointed at the
   catalogue without moving a total. Pass `null` to detach.
+- **Invoices & expenses.** Same shape as quotes, different lifecycle: `create_*`
+  lands a DRAFT that is invisible to the ledger, tax reporting and Xero until
+  `finalise_*`; a finalised unpaid document is still editable in place; `void_*`
+  retires a finalised unpaid one (number, lines and history kept, Xero receives
+  VOIDED); `delete_*` is drafts only; paid means locked; there is no way back to
+  draft. Every write is refused inside the account lock date. Each document keeps
+  an append-only version history (`list_*_versions`, `restore_*_version`).
+- **Payments.** `apply_payment` records one payment per allocated invoice/expense
+  from a bank account, one money side per call, all-or-nothing; `remove_payment`
+  reverts the document. Overpayment, currency and lock-date rules are the API's.
 - **Quotes.** `create_quote` takes the whole document in one call — header,
   sections and every line — because a real quote is several phases and dozens of
   lines. Sections (`groups`) are the phases and keep the order you give them, as

package/dist/client.js

@@ -71,6 +71,19 @@ export class BeeswaxClient {
         const body = await this.request(path, params);
         return body?.[rootKey] ?? [];
     }
+    // An entry's ledger postings WITH the envelope the API wraps them in:
+    // { transactions, posted, reason?, preview? }. `posted:false` means the
+    // entry has not hit the ledger and `transactions` is empty (unless the
+    // caller asked for a preview, in which case every line is marked preview).
+    async getPostings(path, params = {}) {
+        const body = await this.request(path, params);
+        return {
+            posted: body?.posted ?? null,
+            ...(body?.reason !== undefined ? { reason: body.reason } : {}),
+            ...(body?.preview !== undefined ? { preview: body.preview } : {}),
+            transactions: body?.transactions ?? [],
+        };
+    }
     // Paginated list — walks every page (via meta.total_pages) and returns the
     // merged array. Capped defensively so a malformed meta can't loop forever.
     async fetchAll(path, rootKey, params = {}) {
@@ -120,6 +133,13 @@ export class BeeswaxClient {
             const message = parsed && typeof parsed === "object" && parsed.error ? parsed.error : res.statusText;
             throw new Error(`Beeswax API ${res.status} on ${method} ${path}: ${message}`);
         }
+        // Every API destroy answers `head :no_content` (204, empty body). Returning
+        // `undefined` here made index.ts JSON.stringify to a non-string, which the
+        // MCP SDK rejected — so every successful delete surfaced as "Tool execution
+        // failed" after the record was already gone. Always hand back an object.
+        if (parsed === undefined) {
+            return { ok: true, status: res.status, method, path };
+        }
         return parsed;
     }
 }

package/dist/index.js

@@ -20,7 +20,17 @@ if (!token) {
 }
 const client = new BeeswaxClient(baseUrl, token);
 const toolsByName = new Map(TOOLS.map((tool) => [tool.name, tool]));
-const server = new Server({ name: "beeswax-mcp", version: VERSION }, { capabilities: { tools: {} } });
+// Shown to the model as server instructions on connect. The ledger rule is
+// here because the cost of getting it wrong is a wrong set of accounts: an
+// earlier session summed a draft payroll template's lines as real wages.
+const INSTRUCTIONS = "Beeswax is an accounting, project and time-tracking system. " +
+    "LEDGER RULE: an entry is on the ledger only when its `posted` field is true. " +
+    "Drafts, payroll templates, quotes and voided entries are never ledger activity, whatever their state, " +
+    "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.";
+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 })),
 }));
@@ -34,7 +44,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     try {
         const result = await tool.handler(client, request.params.arguments ?? {});
-        let text = JSON.stringify(result, null, 2);
+        // JSON.stringify(undefined) is undefined, not a string — a text-less
+        // content block fails the SDK's result schema and reads as a failed call.
+        let text = JSON.stringify(result ?? { ok: true }, null, 2) ?? "{}";
         const update = client.updateAvailable;
         if (update && !updateNoticeShown && request.params.name !== "check_beeswax_connection") {
             updateNoticeShown = true;

package/dist/tools.js

@@ -59,16 +59,47 @@ const PAYABLE_LIST_PROPS = {
 };
 // invoices / quotes / expenses / payments all share list + show + transactions.
 // `payable` adds the overdue/outstanding filters + due_on/overdue list fields.
+// Every listing accepts these. The API returns only posted entries unless
+// told otherwise; `posted:false` asks for the unposted ones, `include_drafts`
+// for both. An explicit `state` filter switches the posted default off.
+const POSTED_PROPS = {
+    posted: {
+        type: "boolean",
+        description: "Default true: only entries posted to the ledger. false: only unposted entries (drafts, templates, voided). " +
+            "Unposted entries never affect the ledger.",
+    },
+    include_drafts: { type: "boolean", description: "true: return posted and unposted entries together." },
+};
+const PREVIEW_PROP = {
+    preview: {
+        type: "boolean",
+        description: "For an UNPOSTED entry only: return the would-be postings, each marked preview:true. " +
+            "Never sum preview lines into balances.",
+    },
+};
+// One line per document type: which `state` values mean "on the ledger".
+const LEDGER_STATES = {
+    invoices: "Ledger-effective states: finalised, pdf_sent, marked_sent, first_notice, second_notice, final_notice, partial_paid, paid. draft and voided are NOT on the ledger.",
+    expenses: "Ledger-effective states: finalised, pdf_sent, marked_sent, partial_paid, paid. draft and voided are NOT on the ledger.",
+    quotes: "Quotes are never on the ledger (posted is always false), whatever their state.",
+    payments: "Payments are posted on creation (state finalised/paid); a payment with posted:false is an anomaly, not activity.",
+};
 function accountingTools(resource, singular, label, listName, opts = {}) {
     const payable = opts.payable ?? false;
     const listProps = payable ? { ...ACCOUNTING_LIST_PROPS, ...PAYABLE_LIST_PROPS } : { ...ACCOUNTING_LIST_PROPS };
     return [
         {
             name: listName,
-            description: `List all ${label} for the configured account. Fetches every page and returns the merged array.` +
+            description: (resource === "quotes"
+                ? `List all ${label} for the configured account. Quotes are never on the ledger (posted is always false). `
+                : `List ${label} posted to the ledger, unless posted:false or include_drafts:true. Drafts, templates and voided entries never affect the ledger. `) +
+                `Every entry carries \`posted\`; that flag — not state or number — says whether it is ledger activity. ` +
+                `Fetches every page and returns the merged array.` +
                 (payable ? " Pass overdue:true to get just the overdue ones (with due dates) in a single call." : ""),
-            inputSchema: { type: "object", properties: { ...listProps } },
+            inputSchema: { type: "object", properties: { ...listProps, ...POSTED_PROPS } },
             handler: (client, args) => client.fetchAll(`/${resource}`, resource, {
+                posted: args.posted,
+                include_drafts: args.include_drafts,
                 state: args.state,
                 project_id: args.project_id,
                 company_id: args.company_id,
@@ -80,18 +111,336 @@ function accountingTools(resource, singular, label, listName, opts = {}) {
         },
         {
             name: `get_${singular}`,
-            description: `Get a single ${singular} by id (full detail incl. totals and, where applicable, payment status).`,
+            description: `Get a single ${singular} by id (full detail incl. totals and, where applicable, payment status). ` +
+                `\`posted\` says whether it is on the ledger. ${LEDGER_STATES[resource] ?? ""}`,
             inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
             handler: (client, args) => client.getOne(`/${resource}/${args.id}`, singular),
         },
         {
             name: `list_${singular}_transactions`,
-            description: `List the ledger postings (debit/credit lines) beneath a ${singular}.`,
-            inputSchema: { type: "object", properties: { id: { type: "integer" }, ...SYSTEM_PROP }, required: ["id"] },
-            handler: (client, args) => client.getList(`/${resource}/${args.id}/transactions`, "transactions", { system: args.system }),
+            description: `List the ledger postings (debit/credit lines) beneath a ${singular}. ` +
+                `An unposted ${singular} (draft, template, voided) has NO postings: the result is posted:false with an empty ` +
+                `transactions array and a reason. Only sum lines from results with posted:true.`,
+            inputSchema: { type: "object", properties: { id: { type: "integer" }, ...SYSTEM_PROP, ...PREVIEW_PROP }, required: ["id"] },
+            handler: (client, args) => client.getPostings(`/${resource}/${args.id}/transactions`, { system: args.system, preview: args.preview }),
         },
     ];
 }
+// ── Ledger documents: invoices and expenses (write) ─────────────────────
+//
+// Same shape as the quote tools, generated per document type. The lifecycle
+// differs from quotes because these post to the ledger: create lands a
+// DRAFT (invisible to the ledger, tax reporting and Xero until finalised),
+// `finalise` posts it, `void` retires a finalised unpaid one (the number,
+// lines and history are kept; Xero receives VOIDED), DELETE is drafts only,
+// paid means locked, and there is NO way back to draft.
+const LINE_INPUT_PROPS = {
+    description: { type: "string", description: "What the line is for." },
+    transaction_account_id: { type: "integer", description: "Chart-of-accounts id. Not needed if the product supplies one." },
+    transaction_template_id: {
+        type: "integer",
+        description: "Product/service to price this line from — see list_products_services. Anything you set yourself wins over the product's default.",
+    },
+    quantity: { type: "number", description: "Defaults to 1. Cannot be negative." },
+    unit_amount: { type: "number", description: "Per-unit price. Line total = unit_amount x quantity. Omit to use the product's rate." },
+    kind: { type: "string", description: "Unit label, e.g. 'Hours' or 'Units'." },
+    tax_id: { type: "integer", description: "Tax code — see list_taxes." },
+};
+function lineBody(args) {
+    return {
+        description: args.description,
+        transaction_account_id: args.transaction_account_id,
+        transaction_template_id: args.transaction_template_id,
+        quantity: args.quantity,
+        unit_amount: args.unit_amount,
+        kind: args.kind,
+        tax_id: args.tax_id,
+    };
+}
+function ledgerDocumentTools(resource) {
+    const singular = resource === "invoices" ? "invoice" : "expense";
+    const Label = resource === "invoices" ? "invoice" : "expense (supplier bill)";
+    const scope = `${resource}:write`;
+    const readScope = `${resource}:read`;
+    const side = resource === "invoices" ? "sell" : "buy";
+    const partyProp = resource === "invoices"
+        ? { company_id: { type: "integer", description: "Client the invoice is addressed to. Defaults to the project's client — see list_companies." } }
+        : { company_id: { type: "integer", description: "Supplier the bill is from. Defaults to the account's default contact — see list_companies." } };
+    const extraHeader = resource === "expenses" ? { external_number: { type: "string", description: "The supplier's own invoice number." } } : {};
+    const idKey = `${singular}_id`;
+    const lifecycle = `LIFECYCLE: creating lands a DRAFT — numbered, but NOT on the ledger, not in tax reporting and not sent to Xero until you call finalise_${singular}. ` +
+        `A finalised unpaid ${singular} can still be edited in place; once a payment is recorded it is locked. ` +
+        `There is no way back to draft: a finalised ${singular} that should not exist is voided (void_${singular}), never deleted. ` +
+        `Nothing here emails anyone.`;
+    return [
+        {
+            name: `create_${singular}`,
+            description: `Create a whole ${Label} in one call — header, sections and each section's lines. ${lifecycle} ` +
+                `Pass status:"finalised" to post it in the same call (refused, and nothing is created, if the total is negative, the project is locked, or the date falls on or before the account lock date). ` +
+                `Price lines from the catalogue with transaction_template_id where you can (${side}-side account, tax and rate are inherited). ` +
+                `project_id is required; company_id defaults as described. Every id must belong to your account — resolve them with list_projects, list_companies, list_transaction_accounts, list_taxes. ` +
+                `Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_id: { type: "integer", description: "Project the document belongs to. Required." },
+                    ...partyProp,
+                    title: { type: "string" },
+                    content: { type: "string", description: "Free-text notes." },
+                    sent_on: { type: "string", description: "Document date, e.g. '2026-09-04'. Defaults to today." },
+                    ...extraHeader,
+                    status: { type: "string", enum: ["draft", "finalised"], description: "Default 'draft'. 'finalised' posts it to the ledger in the same call." },
+                    tax_inclusive: { type: "boolean" },
+                    default_transaction_account_id: { type: "integer" },
+                    default_tax_id: { type: "integer" },
+                    groups: {
+                        type: "array",
+                        description: "Sections, in order.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: { type: "string" },
+                                due_on: { type: "string", description: "Optional section date." },
+                                lines: {
+                                    type: "array",
+                                    items: {
+                                        type: "object",
+                                        properties: LINE_INPUT_PROPS,
+                                        anyOf: [{ required: ["transaction_account_id"] }, { required: ["transaction_template_id"] }],
+                                    },
+                                },
+                            },
+                            required: ["name"],
+                        },
+                    },
+                },
+                required: ["project_id", "title"],
+            },
+            handler: (client, args) => client.mutate("POST", `/${resource}`, {
+                [singular]: {
+                    project_id: args.project_id,
+                    company_id: args.company_id,
+                    title: args.title,
+                    content: args.content,
+                    sent_on: normalizeDate(args.sent_on),
+                    external_number: args.external_number,
+                    status: args.status,
+                    tax_inclusive: args.tax_inclusive,
+                    default_transaction_account_id: args.default_transaction_account_id,
+                    default_tax_id: args.default_tax_id,
+                    groups: (args.groups ?? []).map((g) => ({ ...g, due_on: normalizeDate(g.due_on) })),
+                },
+            }),
+        },
+        {
+            name: `update_${singular}`,
+            description: `Update a ${singular}'s HEADER — title, notes, date, ${resource === "invoices" ? "client" : "supplier, supplier reference"}, project, tax settings. Sections and lines are untouched; use the section and line tools for those. ` +
+                `Allowed while draft or finalised-unpaid; refused (422) once paid, part-paid, voided, or dated on or before the account lock date. Only the fields you pass change. Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "integer" },
+                    title: { type: "string" },
+                    content: { type: "string" },
+                    sent_on: { type: "string" },
+                    company_id: { type: "integer" },
+                    project_id: { type: "integer" },
+                    ...extraHeader,
+                    tax_inclusive: { type: "boolean" },
+                    default_transaction_account_id: { type: "integer" },
+                    default_tax_id: { type: "integer" },
+                },
+                required: ["id"],
+            },
+            handler: (client, args) => client.mutate("PATCH", `/${resource}/${args.id}`, {
+                [singular]: {
+                    title: args.title,
+                    content: args.content,
+                    sent_on: normalizeDate(args.sent_on),
+                    company_id: args.company_id,
+                    project_id: args.project_id,
+                    external_number: args.external_number,
+                    tax_inclusive: args.tax_inclusive,
+                    default_transaction_account_id: args.default_transaction_account_id,
+                    default_tax_id: args.default_tax_id,
+                },
+            }),
+        },
+        {
+            name: `finalise_${singular}`,
+            description: `Post a DRAFT ${singular} to the ledger (draft → finalised). From then on it counts in reports and tax, and on Xero-connected accounts the next sync pushes it. ` +
+                `Refused if the total is negative, the project is locked, or the date is on or before the account lock date. There is no un-finalise. Does not email anyone. Requires ${scope}.`,
+            inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+            handler: (client, args) => client.mutate("POST", `/${resource}/${args.id}/finalise`, {}),
+        },
+        {
+            name: `void_${singular}`,
+            description: `Void a finalised, UNPAID ${singular}: it keeps its number, lines and history and stays visible with state "voided", but leaves the ledger, tax reporting and ${resource === "invoices" ? "receivables" : "payables"}; Xero receives VOIDED on the next sync. Locked afterwards. ` +
+                `Refused for drafts (delete them instead), for a ${singular} with payments recorded (remove the payments first), for one already voided, and inside the account lock date. Requires ${scope}.`,
+            inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+            handler: (client, args) => client.mutate("POST", `/${resource}/${args.id}/void`, {}),
+        },
+        {
+            name: `delete_${singular}`,
+            description: `Delete a DRAFT ${singular}. A finalised ${singular} is never deleted — void it instead (void_${singular}); the API says so with a 422. Requires ${scope}.`,
+            inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+            handler: (client, args) => client.mutate("DELETE", `/${resource}/${args.id}`),
+        },
+        // Sections and lines.
+        {
+            name: `list_${singular}_groups`,
+            description: `List a ${singular}'s sections in order, each with its lines and total — the ids the section and line tools need. Requires ${readScope}.`,
+            inputSchema: { type: "object", properties: { [idKey]: { type: "integer" } }, required: [idKey] },
+            handler: (client, args) => client.getList(`/${resource}/${args[idKey]}/transaction_groups`, "transaction_groups"),
+        },
+        {
+            name: `add_${singular}_group`,
+            description: `Append a section to a ${singular}, optionally with its lines. Refused once the ${singular} is locked (paid, voided, lock date). Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    [idKey]: { type: "integer" },
+                    name: { type: "string" },
+                    due_on: { type: "string" },
+                    lines: {
+                        type: "array",
+                        items: { type: "object", properties: LINE_INPUT_PROPS, anyOf: [{ required: ["transaction_account_id"] }, { required: ["transaction_template_id"] }] },
+                    },
+                },
+                required: [idKey, "name"],
+            },
+            handler: (client, args) => client.mutate("POST", `/${resource}/${args[idKey]}/transaction_groups`, {
+                transaction_group: { name: args.name, due_on: normalizeDate(args.due_on), lines: args.lines },
+            }),
+        },
+        {
+            name: `update_${singular}_group`,
+            description: `Rename a ${singular} section or change its date. Lines are untouched. Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: { [idKey]: { type: "integer" }, group_id: { type: "integer" }, name: { type: "string" }, due_on: { type: "string" } },
+                required: [idKey, "group_id"],
+            },
+            handler: (client, args) => client.mutate("PATCH", `/${resource}/${args[idKey]}/transaction_groups/${args.group_id}`, {
+                transaction_group: { name: args.name, due_on: normalizeDate(args.due_on) },
+            }),
+        },
+        {
+            name: `delete_${singular}_group`,
+            description: `Delete a ${singular} section AND every line in it. Requires ${scope}.`,
+            inputSchema: { type: "object", properties: { [idKey]: { type: "integer" }, group_id: { type: "integer" } }, required: [idKey, "group_id"] },
+            handler: (client, args) => client.mutate("DELETE", `/${resource}/${args[idKey]}/transaction_groups/${args.group_id}`),
+        },
+        {
+            name: `add_${singular}_line`,
+            description: `Append one line to a ${singular} section. For a new document use create_${singular}. unit_amount is the per-unit price; Beeswax derives debit/credit from the account. ` +
+                `A transaction_template_id prices the line from that product (${side} side). Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: { [idKey]: { type: "integer" }, group_id: { type: "integer" }, ...LINE_INPUT_PROPS },
+                anyOf: [{ required: [idKey, "group_id", "transaction_account_id"] }, { required: [idKey, "group_id", "transaction_template_id"] }],
+            },
+            handler: (client, args) => client.mutate("POST", `/${resource}/${args[idKey]}/transaction_groups/${args.group_id}/transactions`, { transaction: lineBody(args) }),
+        },
+        {
+            name: `update_${singular}_line`,
+            description: `Change one line on a ${singular}. Only the fields you pass change; attaching a transaction_template_id links the product without repricing (null detaches). Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    [idKey]: { type: "integer" },
+                    group_id: { type: "integer" },
+                    line_id: { type: "integer" },
+                    ...LINE_INPUT_PROPS,
+                    transaction_template_id: { type: ["integer", "null"], description: "Catalogue product; null detaches." },
+                },
+                required: [idKey, "group_id", "line_id"],
+            },
+            handler: (client, args) => client.mutate("PATCH", `/${resource}/${args[idKey]}/transaction_groups/${args.group_id}/transactions/${args.line_id}`, {
+                transaction: lineBody(args),
+            }),
+        },
+        {
+            name: `delete_${singular}_line`,
+            description: `Delete one line from a ${singular} section. Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: { [idKey]: { type: "integer" }, group_id: { type: "integer" }, line_id: { type: "integer" } },
+                required: [idKey, "group_id", "line_id"],
+            },
+            handler: (client, args) => client.mutate("DELETE", `/${resource}/${args[idKey]}/transaction_groups/${args.group_id}/transactions/${args.line_id}`),
+        },
+        // Version history.
+        {
+            name: `list_${singular}_versions`,
+            description: `List a ${singular}'s version history, newest first. A version is a whole-document snapshot (header, sections, lines) taken once per API write, once per web editing session, and on every state change; identical content is never stored twice. ` +
+                `Each entry says whether it is restorable (false once the ${singular} is paid, voided or inside the lock date). Requires ${readScope}.`,
+            inputSchema: { type: "object", properties: { [idKey]: { type: "integer" } }, required: [idKey] },
+            handler: (client, args) => client.getList(`/${resource}/${args[idKey]}/versions`, "versions"),
+        },
+        {
+            name: `get_${singular}_version`,
+            description: `Get one version of a ${singular} with its full payload — the header, sections and lines as they stood. Requires ${readScope}.`,
+            inputSchema: {
+                type: "object",
+                properties: { [idKey]: { type: "integer" }, version_number: { type: "integer" } },
+                required: [idKey, "version_number"],
+            },
+            handler: (client, args) => client.getOne(`/${resource}/${args[idKey]}/versions/${args.version_number}`, "version"),
+        },
+        {
+            name: `restore_${singular}_version`,
+            description: `Restore a ${singular} to an earlier version: header, sections and lines are rewritten to match it, and the result is recorded as the next version (history is never rewound). ` +
+                `Refused once the ${singular} is paid, part-paid, voided or inside the account lock date. Confirm with the user before restoring — it replaces the current lines. Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: { [idKey]: { type: "integer" }, version_number: { type: "integer" } },
+                required: [idKey, "version_number"],
+            },
+            handler: (client, args) => client.mutate("POST", `/${resource}/${args[idKey]}/versions/${args.version_number}/restore`, {}),
+        },
+    ];
+}
+// ── Payments (write) ────────────────────────────────────────────────────
+const PAYMENT_TOOLS = [
+    {
+        name: "apply_payment",
+        description: "Record a payment from a bank account against one or more FINALISED invoices (money in) or expenses (money out) — one side per call, never both. " +
+            "Each allocation becomes its own payment document and moves the settled invoice/expense to partial_paid or paid; the result lists the payments created and each document's new state and remaining balance. " +
+            "ALL-OR-NOTHING: if any allocation is refused, nothing is recorded. Refused when: the bank account is not this account's (see list_transaction_accounts, bank accounts only), the document is a draft or voided, the amount is not positive or exceeds what is still owing, the document is already fully paid, a document appears twice, the bank's currency differs from the document's, or the date is on or before the account lock date. " +
+            "There is no edit: remove a wrong payment (remove_payment) and apply it again. Confirm amounts with the user first. Requires payments:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                bank_account_id: { type: "integer", description: "A transaction account flagged as a bank account." },
+                paid_on: { type: "string", description: "Payment date, e.g. '2026-09-04'." },
+                allocations: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "object",
+                        properties: {
+                            journal_entry_id: { type: "integer", description: "A finalised invoice, expense or refund document." },
+                            amount: { type: "number", description: "Positive; at most the amount still owing." },
+                        },
+                        required: ["journal_entry_id", "amount"],
+                    },
+                },
+            },
+            required: ["bank_account_id", "paid_on", "allocations"],
+        },
+        handler: (client, args) => client.mutate("POST", "/payments", {
+            payment: { bank_account_id: args.bank_account_id, paid_on: normalizeDate(args.paid_on), allocations: args.allocations },
+        }),
+    },
+    {
+        name: "remove_payment",
+        description: "Remove a payment (by payment id — see query_payments or the result of apply_payment). The settled invoice/expense goes back to finalised or partial_paid and any bank-feed line allocated to it returns to pending. " +
+            "Refused for payroll payments and for payments dated on or before the account lock date. Confirm with the user first. Requires payments:write.",
+        inputSchema: { type: "object", properties: { id: { type: "integer", description: "Payment id." } }, required: ["id"] },
+        handler: (client, args) => client.mutate("DELETE", `/payments/${args.id}`),
+    },
+];
 export const TOOLS = [
     {
         name: "check_beeswax_connection",
@@ -122,31 +471,42 @@ export const TOOLS = [
     ...accountingTools("quotes", "quote", "quotes", "list_quotes"),
     ...accountingTools("expenses", "expense", "expense documents", "list_expenses", { payable: true }),
     ...accountingTools("payments", "payment", "payments (income / expense / payroll)", "query_payments"),
+    ...ledgerDocumentTools("invoices"),
+    ...ledgerDocumentTools("expenses"),
+    ...PAYMENT_TOOLS,
     // Generic journal-entries reader for the long tail.
     {
         name: "query_journal_entries",
-        description: "List journal entries of any type. `type` accepts a URL segment (invoices) or class name (Invoice). " +
+        description: "Returns only entries posted to the ledger unless posted:false (unposted only) or include_drafts:true (both). " +
+            "Drafts, payroll templates, quotes and voided entries never affect the ledger; every entry carries `posted`, " +
+            "and that flag — not state or number — is the ledger signal (a draft manual journal can carry a number). " +
+            "`type` accepts a URL segment (invoices) or class name (Invoice). " +
             "Long-tail types (credits, bank_transfers, payrolls) and bare listings require an `all`-scoped token.",
         inputSchema: {
             type: "object",
             properties: {
                 type: { type: "string", description: "STI type filter, e.g. invoices, payments, payrolls, credits, bank_transfers." },
-                state: { type: "string", description: "Filter by state." },
+                state: { type: "string", description: "Filter by state (switches the posted default off)." },
+                ...POSTED_PROPS,
             },
         },
-        handler: (client, args) => client.fetchAll("/journal_entries", "journal_entries", { type: args.type, state: args.state }),
+        handler: (client, args) => client.fetchAll("/journal_entries", "journal_entries", {
+            type: args.type, state: args.state, posted: args.posted, include_drafts: args.include_drafts,
+        }),
     },
     {
         name: "get_journal_entry",
-        description: "Get a single journal entry by id (any type). Requires an `all`-scoped token.",
+        description: "Get a single journal entry by id (any type). `posted` says whether it is on the ledger. Requires an `all`-scoped token.",
         inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
         handler: (client, args) => client.getOne(`/journal_entries/${args.id}`, "journal_entry"),
     },
     {
         name: "list_journal_entry_transactions",
-        description: "List the ledger postings beneath any journal entry by id.",
-        inputSchema: { type: "object", properties: { id: { type: "integer" }, ...SYSTEM_PROP }, required: ["id"] },
-        handler: (client, args) => client.getList(`/journal_entries/${args.id}/transactions`, "transactions", { system: args.system }),
+        description: "List the ledger postings beneath any journal entry by id. An unposted entry (draft, payroll template, quote, " +
+            "voided) has NO postings: the result is posted:false with an empty transactions array and a reason. " +
+            "Only sum lines from results with posted:true.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" }, ...SYSTEM_PROP, ...PREVIEW_PROP }, required: ["id"] },
+        handler: (client, args) => client.getPostings(`/journal_entries/${args.id}/transactions`, { system: args.system, preview: args.preview }),
     },
     // Project / work cluster.
     {
@@ -832,14 +1192,19 @@ export const TOOLS = [
     // ── Manual / general journal entries (RawJournalEntry) ──────────────────
     {
         name: "list_manual_journals",
-        description: "List manual (general) journal entries for the account, newest first. Optional state filter ('draft' or 'finalised'). Requires journal_entries:read (write implies read).",
+        description: "List manual (general) journal entries posted to the ledger, newest first, unless posted:false (drafts only) or " +
+            "include_drafts:true (both). A draft may already carry a number — `posted` is the ledger signal, `number` is not. " +
+            "Requires journal_entries:read (write implies read).",
         inputSchema: {
             type: "object",
             properties: {
-                state: { type: "string", enum: ["draft", "finalised"], description: "Optional state filter." },
+                state: { type: "string", enum: ["draft", "finalised"], description: "Optional state filter (switches the posted default off)." },
+                ...POSTED_PROPS,
             },
         },
-        handler: (client, args) => client.fetchAll("/raw_journal_entries", "raw_journal_entries", { state: args.state }),
+        handler: (client, args) => client.fetchAll("/raw_journal_entries", "raw_journal_entries", {
+            state: args.state, posted: args.posted, include_drafts: args.include_drafts,
+        }),
     },
     {
         name: "get_manual_journal",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beeswax-mcp",
-  "version": "1.3.0",
+  "version": "1.4.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",