beeswax-mcp 1.6.0 → 2.0.0

package/README.md

@@ -150,10 +150,16 @@ reports the same on demand.
 | `list_themes`, `get_theme_spec`, `get_theme`, `upsert_theme` (write), `validate_theme` (write), `preview_theme`, `activate_theme` (write), `delete_theme` (write) | `/themes` (custom document themes, THEME_SPEC v1) |
 | `list_products_services`, `get_product_service`, `create_product_service` (write), `update_product_service` (write), `delete_product_service` (write) | `/transaction_templates` |
 | `list_manual_journals`, `get_manual_journal`, `create_manual_journal` (write), `finalise_manual_journal` (write) | `/raw_journal_entries` |
-| `list_tax_returns`, `get_tax_return`, `get_tax_return_field_transactions`, `list_tax_return_findings`, `update_tax_return_field` (write), `confirm_tax_return_section` (write) | `/tax_returns` |
+| `list_tax_returns`, `get_tax_return`, `get_tax_return_field_transactions`, `compare_tax_returns`, `tax_return_preflight_check`, `list_tax_return_field_notes`, `get_tax_return_conversation`, `create_tax_return` (write), `repopulate_tax_return` (write), `update_tax_return_field` (write), `add_tax_return_field_note` (write), `edit_tax_return_field_note` (write), `post_tax_return_message` (write), `confirm_tax_return_section` / `unconfirm_tax_return_section` (write), `finalise_tax_return` / `unfinalise_tax_return` (write) | `/tax_returns` — the assistant is the reviewer: it reads the figures and the transactions behind them and records its reasoning as field notes and discussion messages |
 
 ### Notes
 
+- 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
+  for "what changed since yesterday" instead of re-reading everything; rows
+  carry `updated_at`.
+
 - **Scopes.** `query_journal_entries` / `get_journal_entry` need an `all`-scoped
   token for a bare listing, a show, or a long-tail type (credits, bank_transfers,
   payrolls); a typed listing (`type: "invoices"`) accepts that type's read scope.

package/dist/client.js

@@ -124,18 +124,23 @@ export class BeeswaxClient {
     }
     // Write request (POST / PATCH / DELETE) with a JSON body. Returns the parsed
     // response body, or throws with the API's error message on a non-2xx.
-    async mutate(method, path, body = {}) {
+    async mutate(method, path, body = {}, opts = {}) {
         const url = new URL(this.baseUrl + path);
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        };
+        // Idempotency-Key: the API replays the original response for a retried
+        // write instead of posting twice (see the API tokens help).
+        if (opts.idempotencyKey)
+            headers["Idempotency-Key"] = String(opts.idempotencyKey).slice(0, 255);
         let res;
         try {
             res = await fetch(url, {
                 method,
-                headers: {
-                    Authorization: `Bearer ${this.token}`,
-                    Accept: "application/json",
-                    "Content-Type": "application/json",
-                    "User-Agent": USER_AGENT,
-                },
+                headers,
                 body: JSON.stringify(body),
             });
         }

package/dist/tools.js

@@ -38,7 +38,26 @@ const DATE_PROPS = {
     },
     to: { type: "string", description: "Latest document date (sent_on). Same format as `from`." },
 };
+// Optional on every create/apply tool: reuse the same key when retrying a call
+// that may have gone through (timeout, unclear error) and the API returns the
+// original result instead of creating a second record.
+const IDEMPOTENCY_PROP = {
+    idempotency_key: {
+        type: "string",
+        description: "Optional. A unique string (e.g. a UUID) for this operation. If you retry the same call after a timeout or an unclear error, pass the SAME key and Beeswax returns the original result instead of creating a duplicate. Use a new key for a genuinely new record.",
+    },
+};
+// Incremental sync: every listing accepts updated_since (ISO 8601) and the
+// API echoes meta.filter.updated_since + meta.server_time.
+const SYNC_PROPS = {
+    updated_since: {
+        type: "string",
+        description: "Incremental sync: only rows updated on or after this ISO 8601 instant (e.g. 2026-09-05T00:00:00Z). " +
+            "Line and contact-person edits touch their parent, so a changed line surfaces the document.",
+    },
+};
 const ACCOUNTING_LIST_PROPS = {
+    ...SYNC_PROPS,
     state: { type: "string", description: "Filter by state (draft, finalised, pdf_sent, partial_paid, paid, …)." },
     project_id: { type: "integer", description: "Filter to a single project." },
     company_id: { type: "integer", description: "Filter to a single client/supplier company by id." },
@@ -98,6 +117,7 @@ function accountingTools(resource, singular, label, listName, opts = {}) {
                 (payable ? " Pass overdue:true to get just the overdue ones (with due dates) in a single call." : ""),
             inputSchema: { type: "object", properties: { ...listProps, ...POSTED_PROPS } },
             handler: (client, args) => client.fetchAll(`/${resource}`, resource, {
+                updated_since: args.updated_since,
                 posted: args.posted,
                 include_drafts: args.include_drafts,
                 state: args.state,
@@ -182,7 +202,7 @@ function ledgerDocumentTools(resource) {
                 `Requires ${scope}.`,
             inputSchema: {
                 type: "object",
-                properties: {
+                properties: { ...IDEMPOTENCY_PROP,
                     project_id: { type: "integer", description: "Project the document belongs to. Required." },
                     ...partyProp,
                     title: { type: "string" },
@@ -230,7 +250,7 @@ function ledgerDocumentTools(resource) {
                     default_tax_id: args.default_tax_id,
                     groups: (args.groups ?? []).map((g) => ({ ...g, due_on: normalizeDate(g.due_on) })),
                 },
-            }),
+            }, { idempotencyKey: args.idempotency_key }),
         },
         {
             name: `update_${singular}`,
@@ -411,7 +431,7 @@ const PAYMENT_TOOLS = [
             "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: {
+            properties: { ...IDEMPOTENCY_PROP,
                 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: {
@@ -431,7 +451,7 @@ const PAYMENT_TOOLS = [
         },
         handler: (client, args) => client.mutate("POST", "/payments", {
             payment: { bank_account_id: args.bank_account_id, paid_on: normalizeDate(args.paid_on), allocations: args.allocations },
-        }),
+        }, { idempotencyKey: args.idempotency_key }),
     },
     {
         name: "remove_payment",
@@ -553,13 +573,13 @@ export const TOOLS = [
             "Long-tail types (credits, bank_transfers, payrolls) and bare listings require an `all`-scoped token.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...SYNC_PROPS,
                 type: { type: "string", description: "STI type filter, e.g. invoices, payments, payrolls, credits, bank_transfers." },
                 state: { type: "string", description: "Filter by state (switches the posted default off)." },
                 ...POSTED_PROPS,
             },
         },
-        handler: (client, args) => client.fetchAll("/journal_entries", "journal_entries", {
+        handler: (client, args) => client.fetchAll("/journal_entries", "journal_entries", { updated_since: args.updated_since,
             type: args.type, state: args.state, posted: args.posted, include_drafts: args.include_drafts,
         }),
     },
@@ -583,12 +603,12 @@ export const TOOLS = [
         description: "List all time entries for the configured account (every page).",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...SYNC_PROPS,
                 project_id: { type: "integer", description: "Filter to a single project." },
                 billable: { type: "boolean", description: "Filter by billable flag." },
             },
         },
-        handler: (client, args) => client.fetchAll("/time_entries", "time_entries", { project_id: args.project_id, billable: args.billable }),
+        handler: (client, args) => client.fetchAll("/time_entries", "time_entries", { updated_since: args.updated_since, project_id: args.project_id, billable: args.billable }),
     },
     {
         name: "get_time_entry",
@@ -601,9 +621,9 @@ export const TOOLS = [
         description: "List calendar events visible to the token's user (private events the user is not invited to are excluded).",
         inputSchema: {
             type: "object",
-            properties: { project_id: { type: "integer", description: "Filter to a single project." }, ...DATE_PROPS },
+            properties: { ...SYNC_PROPS, project_id: { type: "integer", description: "Filter to a single project." }, ...DATE_PROPS },
         },
-        handler: (client, args) => client.fetchAll("/events", "events", {
+        handler: (client, args) => client.fetchAll("/events", "events", { updated_since: args.updated_since,
             project_id: args.project_id,
             from: normalizeDate(args.from),
             to: normalizeDate(args.to),
@@ -620,12 +640,12 @@ export const TOOLS = [
         description: "List all milestones (project TaskLists) for the configured account.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...SYNC_PROPS,
                 project_id: { type: "integer", description: "Filter to a single project." },
                 complete: { type: "boolean", description: "Filter by completion." },
             },
         },
-        handler: (client, args) => client.fetchAll("/milestones", "milestones", { project_id: args.project_id, complete: args.complete }),
+        handler: (client, args) => client.fetchAll("/milestones", "milestones", { updated_since: args.updated_since, project_id: args.project_id, complete: args.complete }),
     },
     {
         name: "get_milestone",
@@ -636,8 +656,8 @@ export const TOOLS = [
     {
         name: "list_projects",
         description: "List the account's active projects. Use this to resolve a project name to the project_id that create_quote and the other document tools need.",
-        inputSchema: { type: "object", properties: {} },
-        handler: (client) => client.getList("/active_account/projects", "projects"),
+        inputSchema: { type: "object", properties: { ...SYNC_PROPS } },
+        handler: (client, args) => client.getList("/active_account/projects", "projects", { updated_since: args.updated_since }),
     },
     {
         name: "get_project",
@@ -668,12 +688,12 @@ export const TOOLS = [
         description: "List project documents. Freeform documents are markdown written in Beeswax's document editor — proposals, briefs, meeting notes — styled by the account's invoice theme; other document_types are generated from library templates and are read-only via this API. Each row carries state (draft/published/finalized/archived), current_version_number, and editing_lock (who has it open in the web editor right now). Filter with project_id and/or document_type (e.g. 'freeform').",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...SYNC_PROPS,
                 project_id: { type: "integer", description: "Only documents on this project" },
                 document_type: { type: "string", description: "e.g. 'freeform' for markdown documents" },
             },
         },
-        handler: (client, args) => client.fetchAll("/project_documents", "project_documents", {
+        handler: (client, args) => client.fetchAll("/project_documents", "project_documents", { updated_since: args.updated_since,
             project_id: args.project_id,
             document_type: args.document_type,
         }),
@@ -689,7 +709,7 @@ export const TOOLS = [
         description: "Create a freeform (markdown) document on a project. `body` is markdown (headings, lists, tables, blockquotes all render through the account's invoice theme). The optional `note` becomes the first version's 'what changed' line. Requires a token with the `project_documents:write` scope.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...IDEMPOTENCY_PROP,
                 project_id: { type: "integer" },
                 name: { type: "string", description: "Document title (defaults to 'Untitled document')" },
                 body: { type: "string", description: "Markdown content" },
@@ -699,7 +719,7 @@ export const TOOLS = [
         },
         handler: (client, args) => client.mutate("POST", "/project_documents", {
             project_document: { project_id: args.project_id, name: args.name, body: args.body, note: args.note },
-        }),
+        }, { idempotencyKey: args.idempotency_key }),
     },
     {
         name: "update_project_document",
@@ -829,7 +849,7 @@ export const TOOLS = [
         description: "List the account's products & services catalogue (stored as 'transaction templates'): everything the business sells or buys as a line item — products and services/activities with their unit, sell/buy prices, linked income/expense accounts and taxes. Use this whenever the user asks about products, services, price lists, rates or catalogue items.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...SYNC_PROPS,
                 kind: {
                     type: "string",
                     enum: ["sell", "buy", "buy_and_sell", "product", "service"],
@@ -849,7 +869,7 @@ export const TOOLS = [
                 },
             },
         },
-        handler: (client, args) => client.fetchAll("/transaction_templates", "transaction_templates", {
+        handler: (client, args) => client.fetchAll("/transaction_templates", "transaction_templates", { updated_since: args.updated_since,
             kind: args.kind,
             side: args.side,
             active: args.active,
@@ -876,7 +896,7 @@ export const TOOLS = [
             "Titles must be unique within the account, and prices default to 0 if you omit them, so pass them explicitly. Requires a token with transaction_templates:write.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...IDEMPOTENCY_PROP,
                 title: { type: "string", description: "Catalogue name, e.g. 'Shaker Door — Painted'. Must be unique in the account." },
                 kind: {
                     type: "string",
@@ -930,7 +950,7 @@ export const TOOLS = [
                 physical_resource: args.physical_resource,
                 gantt_color: args.gantt_color,
             },
-        }),
+        }, { idempotencyKey: args.idempotency_key }),
     },
     {
         name: "update_product_service",
@@ -999,7 +1019,7 @@ export const TOOLS = [
     // ── Tax returns (Australian company / sole-trader) ──────────────────
     {
         name: "list_tax_returns",
-        description: "List the account's tax returns (most recent financial year first) with status, completion %, and pending-findings count. Australian accounts only.",
+        description: "List the account's tax returns (most recent financial year first) with status and completion %. Australian accounts only.",
         inputSchema: { type: "object", properties: {} },
         handler: (client) => client.getList("/tax_returns", "tax_returns"),
     },
@@ -1027,22 +1047,9 @@ export const TOOLS = [
         },
         handler: (client, args) => client.getOne(`/tax_returns/${args.id}/sections/${args.section_key}/fields/${args.field_key}/transactions`, ""),
     },
-    {
-        name: "list_tax_return_findings",
-        description: "List the AI review findings for a tax return. Optionally filter by status (pending, accepted, rejected, deferred, stale).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                id: { type: "integer", description: "Tax return id." },
-                status: { type: "string", description: "Optional status filter." },
-            },
-            required: ["id"],
-        },
-        handler: (client, args) => client.getList(`/tax_returns/${args.id}/findings`, "findings", { status: args.status }),
-    },
     {
         name: "update_tax_return_field",
-        description: "Set a manual override on one tax-return field — the same as a person editing it in the web form. Recomputes the totals and marks any now-stale AI findings. Pass an empty value to clear an override and revert to the auto-filled figure. Fails on calculated/read-only fields and on finalised or lodged returns. Requires a token with the tax_returns:write scope.",
+        description: "Set a manual override on one tax-return field — the same as a person editing it in the web form. Recomputes the totals. Pass an empty value to clear an override and revert to the auto-filled figure. Fails on calculated/read-only fields and on finalised or lodged returns. Requires a token with the tax_returns:write scope.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1126,32 +1133,6 @@ export const TOOLS = [
         },
         handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/repopulate`, {}),
     },
-    {
-        name: "request_tax_return_ai_review",
-        description: "Start an AI review of the tax return. The review runs in the background — poll get_tax_return (latest_review) or list_tax_return_findings to see the outcome. Requires a token with the tax_returns:write scope.",
-        inputSchema: {
-            type: "object",
-            properties: { id: { type: "integer", description: "Tax return id." } },
-            required: ["id"],
-        },
-        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/review`, {}),
-    },
-    {
-        name: "resolve_tax_return_finding",
-        description: "Resolve one pending AI review finding: accept (applies the suggested value to the field), reject, or defer. Every pending finding in a section must be resolved before that section can be confirmed. Requires a token with the tax_returns:write scope.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                id: { type: "integer", description: "Tax return id." },
-                finding_id: { type: "integer", description: "Finding id (from list_tax_return_findings)." },
-                resolution: { type: "string", enum: ["accept", "reject", "defer"], description: "How to resolve the finding." },
-            },
-            required: ["id", "finding_id", "resolution"],
-        },
-        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/findings/${args.finding_id}/resolve`, {
-            resolution: args.resolution,
-        }),
-    },
     {
         name: "finalise_tax_return",
         description: "Finalise a tax return once every section is confirmed. A finalised return is locked against edits (use unfinalise_tax_return to unlock it). This does NOT lodge the return with the ATO. Requires a token with the tax_returns:write scope.",
@@ -1266,12 +1247,12 @@ export const TOOLS = [
             "Requires journal_entries:read (write implies read).",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...SYNC_PROPS,
                 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", {
+        handler: (client, args) => client.fetchAll("/raw_journal_entries", "raw_journal_entries", { updated_since: args.updated_since,
             state: args.state, posted: args.posted, include_drafts: args.include_drafts,
         }),
     },
@@ -1293,9 +1274,9 @@ export const TOOLS = [
             "Requires a token with the journal_entries:write scope.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...IDEMPOTENCY_PROP,
                 date: { type: "string", description: "Entry date, e.g. '2024-04-01'." },
-                narration: { type: "string", description: "What the journal is for, e.g. 'BMW write-off'." },
+                narration: { type: "string", maxLength: 255, description: "What the journal is for, e.g. 'BMW write-off'. At most 255 characters — put detail in the line descriptions." },
                 status: { type: "string", enum: ["finalised", "draft"], description: "Optional. Default 'finalised' posts to the ledger immediately; 'draft' stages it for review." },
                 lines: {
                     type: "array",
@@ -1321,7 +1302,7 @@ export const TOOLS = [
                 status: args.status,
                 lines: args.lines,
             },
-        }),
+        }, { idempotencyKey: args.idempotency_key }),
     },
     {
         name: "finalise_manual_journal",
@@ -1344,7 +1325,7 @@ export const TOOLS = [
             "Requires a token with transaction_accounts:read.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...SYNC_PROPS,
                 account_type: {
                     type: "string",
                     enum: ["income", "expense", "asset", "loan", "equity", "transfer"],
@@ -1354,7 +1335,7 @@ export const TOOLS = [
                 bank: { type: "boolean", description: "true returns only bank accounts." },
             },
         },
-        handler: (client, args) => client.getList("/active_account/transaction_accounts", "transaction_accounts", {
+        handler: (client, args) => client.getList("/active_account/transaction_accounts", "transaction_accounts", { updated_since: args.updated_since,
             account_type: args.account_type,
             active: args.active,
             bank: args.bank,
@@ -1404,12 +1385,12 @@ export const TOOLS = [
             "Fetches every page. Requires a token with companies:read.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...SYNC_PROPS,
                 role: { type: "string", enum: ["client", "supplier"], description: "Filter to one role. A quote is addressed to a client." },
                 name: { type: "string", description: "Case-insensitive substring match on the company name." },
             },
         },
-        handler: (client, args) => client.fetchAll("/active_account/companies", "companies", { role: args.role, name: args.name }),
+        handler: (client, args) => client.fetchAll("/active_account/companies", "companies", { updated_since: args.updated_since, role: args.role, name: args.name }),
     },
     {
         name: "get_company",
@@ -1424,7 +1405,7 @@ export const TOOLS = [
             "Check list_companies first — names are unique per account and a duplicate is refused. Nothing here emails anyone. Requires companies:write.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...IDEMPOTENCY_PROP,
                 name: { type: "string" },
                 client: { type: "boolean", description: "You sell to them." },
                 supplier: { type: "boolean", description: "You buy from them." },
@@ -1451,7 +1432,7 @@ export const TOOLS = [
             },
             required: ["name"],
         },
-        handler: (client, args) => client.mutate("POST", "/active_account/companies", { company: args }),
+        handler: (client, args) => client.mutate("POST", "/active_account/companies", { company: args }, { idempotencyKey: args.idempotency_key }),
     },
     {
         name: "update_company",
@@ -1508,7 +1489,7 @@ export const TOOLS = [
             "Requires a token with the quotes:write scope.",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { ...IDEMPOTENCY_PROP,
                 project_id: { type: "integer", description: "Project the quote belongs to. Required." },
                 company_id: { type: "integer", description: "Client the quote is addressed to. Required — see list_companies." },
                 title: { type: "string", description: "Quote title, e.g. 'Cambridge Market Admin App Website'." },
@@ -1574,7 +1555,7 @@ export const TOOLS = [
                     start_on: normalizeDate(group.start_on),
                 })),
             },
-        }),
+        }, { idempotencyKey: args.idempotency_key }),
     },
     {
         name: "update_quote",

package/package.json

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