beeswax-mcp 1.5.0 → 1.7.0

package/README.md

@@ -134,6 +134,7 @@ reports the same on demand.
 | `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` |
+| `list_invoice_files`, `attach_invoice_file` (write), `delete_invoice_file` (write), and the same for expenses and quotes | `/invoices/:id/files` … — attachments; the file rides inline as base64 (25 MB cap) |
 | `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` |
@@ -143,7 +144,7 @@ reports the same on demand.
 | `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_taxes` | `/active_account/taxes` |
-| `list_companies` | `/active_account/companies` |
+| `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) |
 | `list_project_documents`, `get_project_document`, `create_project_document` (write), `update_project_document` (write), `list_project_document_versions`, `get_project_document_version`, `restore_project_document_version` (write) | `/project_documents` (+ per-document version history) |
 | `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) |
@@ -153,6 +154,12 @@ reports the same on demand.
 
 ### 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",
@@ -441,6 +461,71 @@ const PAYMENT_TOOLS = [
         handler: (client, args) => client.mutate("DELETE", `/payments/${args.id}`),
     },
 ];
+// Which tool groups a token's scopes leave unusable. `all` unlocks everything;
+// a :write scope implies its :read. Surfaced by check_beeswax_connection so a
+// "403 on list_transaction_accounts" is explained before it happens.
+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: "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: "" },
+    { scope: "expenses:read", tools: "list_expenses, get_expense, list_expense_versions", why: "" },
+    { scope: "payments:read", tools: "query_payments, get_payment", why: "" },
+    { scope: "journal_entries:read", tools: "list_manual_journals, get_manual_journal", why: "" },
+];
+function scopeGaps(scopes) {
+    if (scopes.includes("all"))
+        return [];
+    const has = (scope) => scopes.includes(scope) || scopes.includes(scope.replace(/:read$/, ":write"));
+    return SCOPE_TOOL_GROUPS.filter((g) => !has(g.scope)).map((g) => ({
+        missing_scope: g.scope,
+        blocks: g.tools,
+        ...(g.why ? { why: g.why } : {}),
+    }));
+}
+// ── Attachments on documents ─────────────────────────────────────────────
+// Files ride along inline as base64 — an MCP client has no other way to send
+// bytes — so this is for receipts and signed documents, not bulk transfer.
+function attachmentTools(resource) {
+    const singular = resource.slice(0, -1);
+    const idKey = `${singular}_id`;
+    const scope = `${resource}:write`;
+    return [
+        {
+            name: `list_${singular}_files`,
+            description: `List the files attached to a ${singular} (receipts, purchase orders, signed documents), newest first, with download URLs. Requires ${resource}:read.`,
+            inputSchema: { type: "object", properties: { [idKey]: { type: "integer" } }, required: [idKey] },
+            handler: (client, args) => client.getList(`/${resource}/${args[idKey]}/files`, "files"),
+        },
+        {
+            name: `attach_${singular}_file`,
+            description: `Attach a file to a ${singular}. Send the file inline as base64 (name, content_type, base64) — keep it to receipts and documents, not large media; the API caps this at 25 MB. ` +
+                `The file counts towards the account's storage quota. A voided ${singular} is refused. Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    [idKey]: { type: "integer" },
+                    name: { type: "string", description: "File name with extension, e.g. receipt.pdf." },
+                    content_type: { type: "string", description: "MIME type; detected from the content if omitted." },
+                    base64: { type: "string", description: "The file's bytes, base64-encoded." },
+                    description: { type: "string" },
+                },
+                required: [idKey, "name", "base64"],
+            },
+            handler: (client, args) => client.mutate("POST", `/${resource}/${args[idKey]}/files`, {
+                description: args.description,
+                file: { name: args.name, content_type: args.content_type, base64: args.base64 },
+            }),
+        },
+        {
+            name: `delete_${singular}_file`,
+            description: `Delete a file attached to a ${singular}. The uploader, or a manager of the document. Confirm with the user first. Requires ${scope}.`,
+            inputSchema: { type: "object", properties: { [idKey]: { type: "integer" }, file_id: { type: "integer" } }, required: [idKey, "file_id"] },
+            handler: (client, args) => client.mutate("DELETE", `/${resource}/${args[idKey]}/files/${args.file_id}`),
+        },
+    ];
+}
 export const TOOLS = [
     {
         name: "check_beeswax_connection",
@@ -462,6 +547,7 @@ export const TOOLS = [
                 account: meta?.account,
                 user: meta?.user,
                 token_scopes: meta?.scopes,
+                scope_gaps: scopeGaps(meta?.scopes ?? []),
                 server_time: meta?.server_time,
                 api_base_url: client.origin,
             };
@@ -474,6 +560,9 @@ export const TOOLS = [
     ...ledgerDocumentTools("invoices"),
     ...ledgerDocumentTools("expenses"),
     ...PAYMENT_TOOLS,
+    ...attachmentTools("invoices"),
+    ...attachmentTools("expenses"),
+    ...attachmentTools("quotes"),
     // Generic journal-entries reader for the long tail.
     {
         name: "query_journal_entries",
@@ -484,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,
         }),
     },
@@ -514,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",
@@ -532,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),
@@ -551,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",
@@ -567,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",
@@ -599,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,
         }),
@@ -620,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" },
@@ -630,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",
@@ -760,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"],
@@ -780,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,
@@ -807,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",
@@ -861,7 +950,7 @@ export const TOOLS = [
                 physical_resource: args.physical_resource,
                 gantt_color: args.gantt_color,
             },
-        }),
+        }, { idempotencyKey: args.idempotency_key }),
     },
     {
         name: "update_product_service",
@@ -1197,12 +1286,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,
         }),
     },
@@ -1224,9 +1313,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",
@@ -1252,7 +1341,7 @@ export const TOOLS = [
                 status: args.status,
                 lines: args.lines,
             },
-        }),
+        }, { idempotencyKey: args.idempotency_key }),
     },
     {
         name: "finalise_manual_journal",
@@ -1275,7 +1364,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"],
@@ -1285,7 +1374,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,
@@ -1335,12 +1424,93 @@ 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",
+        description: "Get one client or supplier by id, with its contact people. Requires companies:read.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/active_account/companies/${args.id}`, "company"),
+    },
+    {
+        name: "create_company",
+        description: "Create a client or supplier (a company / contact) so an invoice or quote can be addressed to it without a trip to the web app. " +
+            "It must be a client (you sell to them), a supplier (you buy from them), or both. `people` are optional; the first becomes the contact documents are addressed to. " +
+            "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: { ...IDEMPOTENCY_PROP,
+                name: { type: "string" },
+                client: { type: "boolean", description: "You sell to them." },
+                supplier: { type: "boolean", description: "You buy from them." },
+                phone: { type: "string" },
+                address: { type: "string" },
+                city: { type: "string" },
+                state: { type: "string" },
+                postcode: { type: "string" },
+                country: { type: "string" },
+                web_address: { type: "string" },
+                invoice_details: { type: "string", description: "Free text printed on documents: ABN / tax number, reference lines." },
+                default_tax_id: { type: "integer", description: "See list_taxes." },
+                people: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            first_name: { type: "string" }, last_name: { type: "string" }, email: { type: "string" },
+                            phone: { type: "string" }, mobile: { type: "string" },
+                        },
+                        required: ["first_name", "last_name", "email"],
+                    },
+                },
+            },
+            required: ["name"],
+        },
+        handler: (client, args) => client.mutate("POST", "/active_account/companies", { company: args }, { idempotencyKey: args.idempotency_key }),
+    },
+    {
+        name: "update_company",
+        description: "Update a client or supplier. Only the fields you pass change. `people` APPENDS contacts (an existing email is left alone); removing a person stays a web-app action. " +
+            "A company must remain a client, a supplier, or both. The business's own company and system companies are refused. Requires companies:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                client: { type: "boolean" },
+                supplier: { type: "boolean" },
+                phone: { type: "string" },
+                address: { type: "string" },
+                city: { type: "string" },
+                state: { type: "string" },
+                postcode: { type: "string" },
+                country: { type: "string" },
+                web_address: { type: "string" },
+                invoice_details: { type: "string" },
+                default_tax_id: { type: ["integer", "null"] },
+                people: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            first_name: { type: "string" }, last_name: { type: "string" }, email: { type: "string" },
+                            phone: { type: "string" }, mobile: { type: "string" },
+                        },
+                        required: ["first_name", "last_name", "email"],
+                    },
+                },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => {
+            const { id, ...body } = args;
+            return client.mutate("PATCH", `/active_account/companies/${id}`, { company: body });
+        },
     },
     // ── Quote authoring ──────────────────────────────────────────────────
     // The boundary here is deliberate: create and edit, never send. There is no
@@ -1358,7 +1528,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'." },
@@ -1424,7 +1594,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.5.0",
+  "version": "1.7.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",