beeswax-mcp 0.2.1 → 1.0.0

package/README.md

@@ -6,9 +6,13 @@ 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 manual journals and tax-return fields,
-and each write is gated behind its own token scope — everything else is strictly
-read-only.
+It is **read-mostly**: writes are limited to quotes, manual journals, tax-return
+fields and the products & services catalogue, and each write is gated behind its
+own token scope — everything else is strictly read-only.
+
+**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
+Beeswax web UI, and the API exposes no route for either.
 
 ## Quick start
 
@@ -23,7 +27,7 @@ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
   "mcpServers": {
     "beeswax": {
       "command": "npx",
-      "args": ["-y", "beeswax-mcp"],
+      "args": ["-y", "beeswax-mcp@latest"],
       "env": {
         "BEESWAX_API_TOKEN": "your-token"
       }
@@ -35,13 +39,14 @@ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 ### Claude Code
 
 ```bash
-claude mcp add beeswax --env BEESWAX_API_TOKEN=your-token -- npx -y beeswax-mcp
+claude mcp add beeswax --env BEESWAX_API_TOKEN=your-token -- npx -y beeswax-mcp@latest
 ```
 
 ### Any other MCP client
 
-Run `npx -y beeswax-mcp` as a stdio server with `BEESWAX_API_TOKEN` set in the
-environment.
+Run `npx -y beeswax-mcp@latest` as a stdio server with `BEESWAX_API_TOKEN` set in
+the environment. (`@latest` matters: without it, npx caches the first download
+forever and you silently fall behind releases.)
 
 ## Getting an API token
 
@@ -50,11 +55,17 @@ Super Admin only; requires the accounting add-on). The token is bound to one
 account.
 
 **Grant only the scopes you need.** Tick individual read scopes
-(`invoices:read`, `payments:read`, `transactions:read`, `journal_entries:read`,
-`tax_returns:read`, `events:read`, `milestones:read`, `projects:read`,
-`time_entries:read`, `transaction_templates:read`, …) rather than `all` — `all` grants read **and** write. Add
-`journal_entries:write` / `tax_returns:write` only if the agent should be able to
-use the write tools.
+(`invoices:read`, `quotes:read`, `payments:read`, `transactions:read`,
+`journal_entries:read`, `tax_returns:read`, `events:read`, `milestones:read`,
+`projects:read`, `time_entries:read`, `transaction_templates:read`,
+`transaction_accounts:read`, …) rather than `all` — `all` grants read **and**
+write. Add `quotes:write`, `journal_entries:write`, `tax_returns:write` or
+`transaction_templates:write` only if the agent should be able to use the
+matching write tools.
+
+To build quotes you need `quotes:write` plus the three lookups a quote is
+assembled from: `companies:read` (the client), `projects:read` (the project) and
+`transaction_accounts:read` (the chart of accounts each line bills to).
 
 **Keep the token secret.** It sits in plain text in your client's config file, and
 anyone who can read that file can read your account data. Revoke tokens you no
@@ -67,21 +78,36 @@ longer use from the same settings page.
 | `BEESWAX_API_TOKEN` | yes | — |
 | `BEESWAX_BASE_URL`  | no  | `https://app.beeswaxapp.com/new_api/v1` |
 
+### Versions & updates
+
+`npx -y beeswax-mcp@latest --version` prints the current release. The server
+identifies itself to the API (`User-Agent: beeswax-mcp/<version>`), and every API
+response advertises the newest release; when this copy is behind, the assistant is
+asked — once per session — to tell the user, with a link to the update guide at
+<https://www.beeswaxapp.com/support/mcp-setup#updating>. `check_beeswax_connection`
+reports the same on demand.
+
 ## Tools
 
 | Tool | Endpoint |
 |---|---|
+| `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` |
 | `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` |
 | `query_payments`, `get_payment`, `list_payment_transactions` | `/payments` |
 | `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) |
 | `list_milestones`, `get_milestone` | `/milestones` |
-| `get_project` | `/active_account/projects/:id` |
+| `list_projects`, `get_project` | `/active_account/projects` |
+| `list_transaction_accounts` | `/active_account/transaction_accounts` |
+| `list_companies` | `/active_account/companies` |
 | `list_task_files`, `list_task_file_versions` | `/tasks/:id/files` (+ per-file version history) |
-| `list_products_services`, `get_product_service` | `/transaction_templates` |
+| `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` |
 
@@ -99,9 +125,40 @@ longer use from the same settings page.
 - **Dates.** `from` / `to` accept ISO (`2026-01-01`) or loose strings
   (`Jan 1 2026`); they are normalized to `YYYY-MM-DD` before being sent.
 - **Products & services.** Beeswax stores the catalogue as *transaction
-  templates*; the tools filter with `kind: "product"` / `"service"` and need the
-  `transaction_templates:read` scope. Internal system templates are excluded
-  unless `system: "true"`.
+  templates*. `kind` is the **buy/sell mode**, not a product-vs-service label:
+  `"sell"` offers the item on invoices and quotes, `"buy"` on expenses,
+  `"buy_and_sell"` on both, and that is what decides which line-item picker
+  shows it. (`"product"` / `"service"` are a legacy classification carried by a
+  handful of old rows and honoured by no picker — filter with `side: "sell"` /
+  `"buy"` for "what can I put on this document?", and each item reports its
+  `sides` on read.) Writes require the account explicitly: the income account an
+  item is sold to, plus the expense account it is bought to for `"buy"` and
+  `"buy_and_sell"`. Nothing is defaulted, and the sell/buy accounts are
+  type-checked, so an item cannot land on a wrong-side or another tenant's
+  account. `update_product_service` changes only the fields you pass — use
+  `active: false` to archive rather than deleting. System templates are excluded
+  from listings unless `system: "true"` and are never writable, and publishing an
+  item to the account's public rates card stays a human action in the web UI.
+  Reads need `transaction_templates:read`, writes `transaction_templates:write`.
+- **Pricing a quote line from a product.** Give a line a
+  `transaction_template_id` and it inherits the product's rate, income account,
+  tax, wording and unit for everything you did not set yourself — an explicit
+  value always wins — and takes the product's `gantt_color` on the quote's Gantt
+  preview, which is what gives a long quote one colour per discipline instead of
+  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.
+- **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
+  do the lines inside them. A line gives `quantity` and `unit_amount` (the
+  per-unit price); Beeswax computes the line total and works out the debit/credit
+  side from the account's classification, so you never pass debit or credit.
+  Quotes land as **drafts** unless you pass `status: "finalised"` — and neither
+  state sends anything to the client. Ids must belong to your account: resolve
+  them first with `list_companies`, `list_projects` and
+  `list_transaction_accounts`. Needs `quotes:write`; a quote marked accepted in
+  the UI is locked and refuses further edits.
 - **Manual journals.** Balanced double-entry enforced by the API (≥ 2 lines, one of
   debit/credit per line, debits = credits). Created finalised by default; pass
   `status: "draft"` and use `finalise_manual_journal` for a review step. Needs

package/dist/client.js

@@ -4,13 +4,28 @@
 //   - Bearer-token auth (from BEESWAX_API_TOKEN)
 //   - collapsing pagination into "fetch every page"
 //   - turning non-2xx responses into clear Error messages
+import { VERSION, isNewerVersion } from "./version.js";
+const USER_AGENT = `beeswax-mcp/${VERSION}`;
+const LATEST_VERSION_HEADER = "x-beeswax-mcp-latest-version";
 export class BeeswaxClient {
     token;
     baseUrl;
+    // Set once the API advertises a newer connector release than the one running.
+    updateAvailable = null;
     constructor(baseUrl, token) {
         this.token = token;
         this.baseUrl = baseUrl.replace(/\/+$/, "");
     }
+    get origin() {
+        return this.baseUrl;
+    }
+    // Every response carries X-Beeswax-MCP-Latest-Version — remember when we're behind.
+    noteLatestVersion(res) {
+        const latest = res.headers.get(LATEST_VERSION_HEADER);
+        if (latest && isNewerVersion(latest, VERSION)) {
+            this.updateAvailable = { running: VERSION, latest };
+        }
+    }
     async request(path, params = {}) {
         const url = new URL(this.baseUrl + path);
         for (const [key, value] of Object.entries(params)) {
@@ -21,12 +36,17 @@ export class BeeswaxClient {
         let res;
         try {
             res = await fetch(url, {
-                headers: { Authorization: `Bearer ${this.token}`, Accept: "application/json" },
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    Accept: "application/json",
+                    "User-Agent": USER_AGENT,
+                },
             });
         }
         catch (err) {
             throw new Error(`Could not reach Beeswax at ${url.origin}: ${err.message}`);
         }
+        this.noteLatestVersion(res);
         const text = await res.text();
         let body;
         try {
@@ -79,6 +99,7 @@ export class BeeswaxClient {
                     Authorization: `Bearer ${this.token}`,
                     Accept: "application/json",
                     "Content-Type": "application/json",
+                    "User-Agent": USER_AGENT,
                 },
                 body: JSON.stringify(body),
             });
@@ -86,6 +107,7 @@ export class BeeswaxClient {
         catch (err) {
             throw new Error(`Could not reach Beeswax at ${url.origin}: ${err.message}`);
         }
+        this.noteLatestVersion(res);
         const text = await res.text();
         let parsed;
         try {

package/dist/index.js

@@ -4,6 +4,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { BeeswaxClient } from "./client.js";
 import { TOOLS } from "./tools.js";
+import { VERSION } from "./version.js";
+// `npx -y beeswax-mcp@latest --version` must work with no token set.
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+    console.log(`beeswax-mcp ${VERSION}`);
+    process.exit(0);
+}
 const token = process.env.BEESWAX_API_TOKEN;
 const baseUrl = process.env.BEESWAX_BASE_URL ?? "https://app.beeswaxapp.com/new_api/v1";
 if (!token) {
@@ -14,10 +20,13 @@ 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: "0.2.1" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "beeswax-mcp", version: VERSION }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
 }));
+// Mention an available update at most once per session (check_beeswax_connection
+// always reports it regardless — this is just the unprompted nudge).
+let updateNoticeShown = false;
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const tool = toolsByName.get(request.params.name);
     if (!tool) {
@@ -25,7 +34,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     try {
         const result = await tool.handler(client, request.params.arguments ?? {});
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        let text = JSON.stringify(result, null, 2);
+        const update = client.updateAvailable;
+        if (update && !updateNoticeShown && request.params.name !== "check_beeswax_connection") {
+            updateNoticeShown = true;
+            text +=
+                `\n\n[beeswax-mcp] Update available: this connector is v${update.running}, ` +
+                    `v${update.latest} is out and may have tools or fields this version lacks. ` +
+                    `Tell the user, and point them to ` +
+                    `https://www.beeswaxapp.com/support/mcp-setup#updating for the one-minute update steps.`;
+        }
+        return { content: [{ type: "text", text }] };
     }
     catch (err) {
         return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
@@ -34,7 +53,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     await server.connect(new StdioServerTransport());
     // stderr only — stdout is the MCP protocol channel.
-    console.error(`beeswax-mcp ready → ${baseUrl}; ${TOOLS.length} tools (read + tax-return write)`);
+    console.error(`beeswax-mcp v${VERSION} ready → ${baseUrl}; ${TOOLS.length} tools`);
 }
 main().catch((err) => {
     console.error("Fatal:", err);

package/dist/tools.js

@@ -1,4 +1,29 @@
 import { normalizeDate } from "./client.js";
+import { VERSION, isNewerVersion } from "./version.js";
+// The writable half of a catalogue item. `id` is the route, not a body field,
+// and anything undefined is left out so a PATCH only changes what was asked for.
+function productAttributes(args) {
+    const attributes = {
+        title: args.title,
+        description: args.description,
+        kind: args.kind,
+        unit: args.unit,
+        item_category: args.item_category,
+        sell_amount: args.sell_amount,
+        sell_transaction_account_id: args.sell_transaction_account_id,
+        sell_tax_id: args.sell_tax_id,
+        buy_amount: args.buy_amount,
+        buy_transaction_account_id: args.buy_transaction_account_id,
+        buy_tax_id: args.buy_tax_id,
+        gantt_color: args.gantt_color,
+        active: args.active,
+    };
+    for (const key of Object.keys(attributes)) {
+        if (attributes[key] === undefined)
+            delete attributes[key];
+    }
+    return attributes;
+}
 const SYSTEM_PROP = {
     system: {
         type: "string",
@@ -68,6 +93,31 @@ function accountingTools(resource, singular, label, listName, opts = {}) {
     ];
 }
 export const TOOLS = [
+    {
+        name: "check_beeswax_connection",
+        description: "Health-check the Beeswax connection: reports the connector version you are running, the latest released version " +
+            "(and whether an update is available, with the update guide URL), plus which Beeswax account and user the API token " +
+            "belongs to and the scopes it grants. Use this whenever the user asks whether their Beeswax connection is working, " +
+            "up to date, what version they are on, which account is connected, or what this integration is allowed to do. " +
+            "Needs no scopes — any valid token works.",
+        inputSchema: { type: "object", properties: {} },
+        handler: async (client) => {
+            const meta = await client.getOne("/meta", "");
+            const latest = meta?.latest_mcp_version ?? null;
+            const updateAvailable = latest ? isNewerVersion(latest, VERSION) : false;
+            return {
+                connector_version: VERSION,
+                latest_version: latest,
+                up_to_date: latest ? !updateAvailable : null,
+                update_guide: updateAvailable ? "https://www.beeswaxapp.com/support/mcp-setup#updating" : undefined,
+                account: meta?.account,
+                user: meta?.user,
+                token_scopes: meta?.scopes,
+                server_time: meta?.server_time,
+                api_base_url: client.origin,
+            };
+        },
+    },
     ...accountingTools("invoices", "invoice", "invoices", "list_invoices", { payable: true }),
     ...accountingTools("quotes", "quote", "quotes", "list_quotes"),
     ...accountingTools("expenses", "expense", "expense documents", "list_expenses", { payable: true }),
@@ -154,9 +204,15 @@ export const TOOLS = [
         inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
         handler: (client, args) => client.getOne(`/milestones/${args.id}`, "milestone"),
     },
+    {
+        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"),
+    },
     {
         name: "get_project",
-        description: "Get a single project by id.",
+        description: "Get a single project by id. Requires a token with projects:read.",
         inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
         handler: (client, args) => client.getOne(`/active_account/projects/${args.id}`, "project"),
     },
@@ -186,8 +242,13 @@ export const TOOLS = [
             properties: {
                 kind: {
                     type: "string",
-                    enum: ["product", "service"],
-                    description: "Only products, or only services/activities. Omit for both.",
+                    enum: ["sell", "buy", "buy_and_sell", "product", "service"],
+                    description: "Exact match on the item's buy/sell mode. 'product' and 'service' are a legacy classification that only a handful of old rows still carry — for \"what can I put on an invoice?\" use `side` instead.",
+                },
+                side: {
+                    type: "string",
+                    enum: ["sell", "buy"],
+                    description: "What a line-item picker would offer on that side of a document: 'sell' = invoices and quotes (kind sell + buy_and_sell), 'buy' = expenses (kind buy + buy_and_sell). This is usually the filter you want.",
                 },
                 active: { type: "boolean", description: "Filter by active flag (false = archived items)." },
                 query: { type: "string", description: "Case-insensitive substring match on title or description." },
@@ -200,6 +261,7 @@ export const TOOLS = [
         },
         handler: (client, args) => client.fetchAll("/transaction_templates", "transaction_templates", {
             kind: args.kind,
+            side: args.side,
             active: args.active,
             query: args.query,
             system: args.system,
@@ -211,6 +273,139 @@ export const TOOLS = [
         inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
         handler: (client, args) => client.getOne(`/transaction_templates/${args.id}`, "transaction_template"),
     },
+    // ── Catalogue authoring ──────────────────────────────────────────────
+    // `kind` is the buy/sell MODE, not a product-vs-service label. It decides
+    // which line-item picker offers the item, so it is an enum here rather than a
+    // free string: an item written with the legacy 'product' / 'service' values
+    // appears in NO picker and can never be put on a document.
+    {
+        name: "create_product_service",
+        description: "Add a product or service to the account's catalogue (a 'transaction template') — the priced line items that can then be dropped onto invoices, quotes and expenses. " +
+            "`kind` is the BUY/SELL MODE and decides where the item can be used: 'sell' offers it on invoices and quotes, 'buy' on expenses, 'buy_and_sell' on both. It is not a product-vs-service label — there is no such setting. " +
+            "You must name the income account the item is sold to (and, for 'buy'/'buy_and_sell', the expense account it is bought to). Beeswax will NOT pick one for you: the web form's habit of silently defaulting to the alphabetically-first account is what mis-filed 40 of one account's 82 products. Resolve ids with list_transaction_accounts — the sell account must be an income account and the buy account an expense account, or the call is refused. " +
+            "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: {
+                title: { type: "string", description: "Catalogue name, e.g. 'Shaker Door — Painted'. Must be unique in the account." },
+                kind: {
+                    type: "string",
+                    enum: ["sell", "buy", "buy_and_sell"],
+                    description: "Buy/sell mode: 'sell' = offered on invoices and quotes, 'buy' = offered on expenses, 'buy_and_sell' = both.",
+                },
+                unit: {
+                    type: "string",
+                    enum: ["Units", "Hours", "Days"],
+                    description: "How the item is quantified on a document line.",
+                },
+                item_category: {
+                    type: "string",
+                    description: "Category this item is filed under, by name — an existing one is reused, a new name creates it. Read the existing names off list_products_services first so you don't invent a near-duplicate.",
+                },
+                sell_transaction_account_id: {
+                    type: "integer",
+                    description: "Income account the item is sold to. Required. Must be an income account from list_transaction_accounts.",
+                },
+                buy_transaction_account_id: {
+                    type: "integer",
+                    description: "Expense account the item is bought to. Required for kind 'buy' and 'buy_and_sell'. Must be an expense account.",
+                },
+                sell_amount: { type: "number", description: "Sell price per unit. Defaults to 0 — pass it." },
+                buy_amount: { type: "number", description: "Buy price per unit. Defaults to 0." },
+                sell_tax_id: { type: "integer", description: "Tax code applied when the item is sold." },
+                buy_tax_id: { type: "integer", description: "Tax code applied when the item is bought." },
+                description: { type: "string", description: "Longer description shown on documents." },
+                item_category_id: { type: "integer", description: "Category by id instead of by name. Takes precedence over item_category." },
+                active: { type: "boolean", description: "Defaults to true. false files it as archived." },
+                physical_resource: { type: "boolean", description: "true for equipment, rooms and other bookable physical resources." },
+                gantt_color: { type: "string", description: "Custom colour as #RRGGBB." },
+            },
+            required: ["title", "kind", "unit", "item_category", "sell_transaction_account_id"],
+        },
+        handler: (client, args) => client.mutate("POST", "/transaction_templates", {
+            transaction_template: {
+                title: args.title,
+                kind: args.kind,
+                unit: args.unit,
+                description: args.description,
+                item_category: args.item_category,
+                item_category_id: args.item_category_id,
+                sell_amount: args.sell_amount,
+                buy_amount: args.buy_amount,
+                sell_transaction_account_id: args.sell_transaction_account_id,
+                buy_transaction_account_id: args.buy_transaction_account_id,
+                sell_tax_id: args.sell_tax_id,
+                buy_tax_id: args.buy_tax_id,
+                active: args.active,
+                physical_resource: args.physical_resource,
+                gantt_color: args.gantt_color,
+            },
+        }),
+    },
+    {
+        name: "update_product_service",
+        description: "Update one catalogue item (product or service). ONLY the fields you pass change — everything else, including accounts already on the row, is left alone. " +
+            "This is the tool for correcting an item filed against the wrong income or expense account, repricing it, or archiving it with active:false (the reversible alternative to deleting). " +
+            "The sell account must be an income account and the buy account an expense account, both from this Beeswax account, or the call is refused. Changing `kind` to include 'buy' requires an expense account. " +
+            "System items maintained by Beeswax cannot be edited, and publishing an item to your public rates card is not available here — that stays a human action in the Beeswax UI. Requires transaction_templates:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Product / service id — see list_products_services." },
+                title: { type: "string" },
+                kind: {
+                    type: "string",
+                    enum: ["sell", "buy", "buy_and_sell"],
+                    description: "Buy/sell mode: where the item is offered. 'sell' = invoices and quotes, 'buy' = expenses, 'buy_and_sell' = both.",
+                },
+                unit: { type: "string", enum: ["Units", "Hours", "Days"] },
+                item_category: { type: "string", description: "Re-file under this category name (created if new)." },
+                item_category_id: { type: "integer", description: "Re-file by category id. Takes precedence over item_category." },
+                sell_transaction_account_id: { type: "integer", description: "Income account the item is sold to." },
+                buy_transaction_account_id: { type: "integer", description: "Expense account the item is bought to." },
+                sell_amount: { type: "number" },
+                buy_amount: { type: "number" },
+                sell_tax_id: { type: "integer" },
+                buy_tax_id: { type: "integer" },
+                description: { type: "string" },
+                active: { type: "boolean", description: "false archives the item — it stays on existing documents but is no longer offered." },
+                physical_resource: { type: "boolean" },
+                gantt_color: { type: "string", description: "#RRGGBB." },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/transaction_templates/${args.id}`, {
+            transaction_template: {
+                title: args.title,
+                kind: args.kind,
+                unit: args.unit,
+                description: args.description,
+                item_category: args.item_category,
+                item_category_id: args.item_category_id,
+                sell_amount: args.sell_amount,
+                buy_amount: args.buy_amount,
+                sell_transaction_account_id: args.sell_transaction_account_id,
+                buy_transaction_account_id: args.buy_transaction_account_id,
+                sell_tax_id: args.sell_tax_id,
+                buy_tax_id: args.buy_tax_id,
+                active: args.active,
+                physical_resource: args.physical_resource,
+                gantt_color: args.gantt_color,
+            },
+        }),
+    },
+    {
+        name: "delete_product_service",
+        description: "Permanently delete a catalogue item. This is NOT a soft delete and cannot be undone. " +
+            "Prefer update_product_service with active:false, which archives the item — it disappears from the pickers, keeps its history, and can be switched back on. " +
+            "The API refuses to delete an item that any document or task still points at, an item Beeswax maintains itself, or the account's last active hourly item (time tracking needs one). Requires transaction_templates:write.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Product / service id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("DELETE", `/transaction_templates/${args.id}`),
+    },
     // ── Tax returns (Australian company / sole-trader) ──────────────────
     {
         name: "list_tax_returns",
@@ -290,6 +485,189 @@ export const TOOLS = [
         },
         handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/sections/${args.section_key}/confirm`, {}),
     },
+    {
+        name: "unconfirm_tax_return_section",
+        description: "Unlock a previously-confirmed tax-return section for editing again. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string", description: "Section key to unlock." },
+            },
+            required: ["id", "section_key"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/sections/${args.section_key}/unconfirm`, {}),
+    },
+    {
+        name: "tax_return_preflight_check",
+        description: "Run the pre-creation reconciliation checks for a financial year (BAS periods locked, bank accounts reconciled, unallocated transactions, unmapped accounts). Blockers must be fixed in Beeswax before a tax return can be created; warnings are informational.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                financial_year: { type: "integer", description: "Financial year ending, e.g. 2025 for FY2024-25." },
+            },
+            required: ["financial_year"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/preflight_check?financial_year=${args.financial_year}`, ""),
+    },
+    {
+        name: "create_tax_return",
+        description: "Create a draft tax return for a financial year and auto-populate it from the ledger. Runs the preflight reconciliation checks first and fails with the blockers if any exist. return_type defaults to the account's business structure. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                financial_year: { type: "integer", description: "Financial year ending, e.g. 2025 for FY2024-25." },
+                return_type: { type: "string", description: "Optional: sole_trader or company." },
+            },
+            required: ["financial_year"],
+        },
+        handler: (client, args) => client.mutate("POST", "/tax_returns", {
+            financial_year: args.financial_year,
+            return_type: args.return_type,
+        }),
+    },
+    {
+        name: "repopulate_tax_return",
+        description: "Refresh a draft tax return's auto-filled figures from the latest ledger data (after new transactions or mapping changes). Manual overrides are preserved. 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}/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.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Tax return id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/finalise`, {}),
+    },
+    {
+        name: "list_tax_return_field_notes",
+        description: "The note timeline for one tax-return field, oldest first — who wrote what, when, and from where (web, api, or assistant). This is the durable record of WHY a figure is what it is; read it before changing a field that has notes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string" },
+                field_key: { type: "string" },
+            },
+            required: ["id", "section_key", "field_key"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/${args.id}/sections/${args.section_key}/fields/${args.field_key}/notes`, ""),
+    },
+    {
+        name: "add_tax_return_field_note",
+        description: "Append a dated, attributed note to a tax-return field's timeline — a decision, its reasoning, a follow-up, or context for next year. Notes are never deleted (you can correct your own with edit_tax_return_field_note). Recorded as written by the assistant. Requires tax_returns:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string" },
+                field_key: { type: "string" },
+                text: { type: "string", description: "The note (up to 4000 characters)." },
+            },
+            required: ["id", "section_key", "field_key", "text"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/sections/${args.section_key}/fields/${args.field_key}/notes`, {
+            text: args.text,
+            source: "mcp",
+        }),
+    },
+    {
+        name: "edit_tax_return_field_note",
+        description: "Correct a field note you wrote earlier (a typo, a wrong figure). The note keeps its place in the timeline and is marked as edited. You can only edit notes written under this token's user. Requires tax_returns:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string" },
+                note_id: { type: "integer" },
+                text: { type: "string", description: "The corrected note text." },
+            },
+            required: ["id", "section_key", "note_id", "text"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/tax_returns/${args.id}/sections/${args.section_key}/notes/${args.note_id}`, { text: args.text }),
+    },
+    {
+        name: "get_tax_return_conversation",
+        description: "The discussion thread on a tax return — the same conversation the business owner, bookkeeper and accountant see in Beeswax. Read it to pick up questions, decisions and context before working on the return.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                limit: { type: "integer", description: "Most recent messages to return (default 100)." },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/${args.id}/conversation?limit=${args.limit ?? 100}`, ""),
+    },
+    {
+        name: "post_tax_return_message",
+        description: "Post a message into the tax return's discussion thread, visible to everyone on the return in Beeswax. Use it to ask the owner or accountant a question, report what you did, or flag something for a human decision. Requires tax_returns:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                body: { type: "string" },
+            },
+            required: ["id", "body"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/conversation/messages`, { body: args.body }),
+    },
+    {
+        name: "compare_tax_returns",
+        description: "Field-by-field comparison of a tax return against the same-type return for another financial year: prior value, current value, delta and % change per field. Fields blank in both years are omitted.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id (the current-year return)." },
+                financial_year: { type: "integer", description: "The other financial year to compare against, e.g. 2024." },
+            },
+            required: ["id", "financial_year"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/${args.id}/compare?financial_year=${args.financial_year}`, ""),
+    },
+    {
+        name: "unfinalise_tax_return",
+        description: "Unlock a finalised (not lodged) tax return back to draft for further editing. 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}/unfinalise`, {}),
+    },
     // ── Manual / general journal entries (RawJournalEntry) ──────────────────
     {
         name: "list_manual_journals",
@@ -360,4 +738,379 @@ export const TOOLS = [
         },
         handler: (client, args) => client.mutate("POST", `/raw_journal_entries/${args.id}/finalise`, {}),
     },
+    // ── Reference data ───────────────────────────────────────────────────
+    // A quote cannot be built without these: every line needs a chart-of-accounts
+    // id, and the quote itself needs a client id.
+    {
+        name: "list_transaction_accounts",
+        description: "List the account's chart of accounts — the transaction_account ids every document line has to point at. " +
+            "`account_type` (income / expense / asset / loan / equity / transfer) tells you which side a line will post on: a quote line against an income account posts as a credit. " +
+            "Use this to resolve an account name to an id before calling create_quote. Inactive accounts are hidden unless you pass active:\"all\". " +
+            "Requires a token with transaction_accounts:read.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_type: {
+                    type: "string",
+                    enum: ["income", "expense", "asset", "loan", "equity", "transfer"],
+                    description: "Filter to one ledger classification.",
+                },
+                active: { type: "string", enum: ["true", "false", "all"], description: "Default 'true' — active accounts only." },
+                bank: { type: "boolean", description: "true returns only bank accounts." },
+            },
+        },
+        handler: (client, args) => client.getList("/active_account/transaction_accounts", "transaction_accounts", {
+            account_type: args.account_type,
+            active: args.active,
+            bank: args.bank,
+        }),
+    },
+    {
+        name: "list_companies",
+        description: "List the account's clients and suppliers. Use this to resolve a client name to the company_id create_quote needs. " +
+            "Fetches every page. Requires a token with companies:read.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                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 }),
+    },
+    // ── Quote authoring ──────────────────────────────────────────────────
+    // The boundary here is deliberate: create and edit, never send. There is no
+    // tool that emails a quote to a client or marks one accepted — those stay
+    // human actions in the Beeswax web UI, and the API exposes no route for them.
+    {
+        name: "create_quote",
+        description: "Create a whole quote in one call — header, sections, and each section's lines. A realistic quote is several phases and dozens of lines, so build the entire structure in this single call rather than adding lines one at a time. " +
+            "PRICE THE LINES FROM THE CATALOGUE where you can: give a line a transaction_template_id (see list_products_services, create_product_service) and it inherits that product's rate, income account, tax and unit, and takes the product's colour on the quote's Gantt preview — which is what makes a long quote's chart readable, one colour per discipline. " +
+            "Sections (`groups`) are the phases of the quote and keep the order you give them; so do the lines within each section. " +
+            "LANDS AS A DRAFT unless you pass status:\"finalised\". Creating a quote never emails anyone — sending it to the client, and marking it accepted, stay human actions in the Beeswax UI. " +
+            "Rules enforced by the API: project_id and company_id are required and must belong to your account (a quote is reachable through its project, so it cannot be created without one); every line needs a transaction_account_id from your chart of accounts, unless it names a product that carries one; any tax_id or transaction_template_id must be yours too; quantity cannot be negative. " +
+            "Resolve ids first with list_companies, list_projects and list_transaction_accounts. " +
+            "`unit_amount` is the PER-UNIT price — the line total is unit_amount x quantity — and Beeswax works out the debit/credit side from the account's classification, so you never set debit or credit yourself. " +
+            "Requires a token with the quotes:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                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'." },
+                content: { type: "string", description: "Free-text body / scope notes shown on the quote." },
+                sent_on: { type: "string", description: "Document date, e.g. '2026-08-24'. Defaults to today." },
+                status: {
+                    type: "string",
+                    enum: ["draft", "finalised"],
+                    description: "Default 'draft'. 'finalised' moves it out of draft. Neither one sends anything to the client.",
+                },
+                tax_inclusive: { type: "boolean", description: "Whether the line amounts already include tax." },
+                default_transaction_account_id: { type: "integer", description: "Fallback account for lines that omit one." },
+                default_tax_id: { type: "integer", description: "Fallback tax code for the quote." },
+                groups: {
+                    type: "array",
+                    description: "The sections (phases) of the quote, in the order they should appear.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string", description: "Section name, e.g. 'Phase 1 — Discovery'." },
+                            start_on: { type: "string", description: "Optional section start date. If you date the sections they must run in order." },
+                            lines: {
+                                type: "array",
+                                description: "The lines in this section, in order.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        description: { type: "string", description: "What the line is for." },
+                                        transaction_account_id: { type: "integer", description: "Chart-of-accounts id — the discipline/revenue line this bills to. Not needed if the product supplies one." },
+                                        transaction_template_id: {
+                                            type: "integer",
+                                            description: "Product/service from the catalogue to price this line from — see list_products_services. " +
+                                                "The line inherits the product's rate, income account, tax, wording and unit for everything you do not set yourself, and takes the product's colour on the Gantt preview. Anything you DO set here 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 shown on the quote, e.g. 'Days' or 'Units'." },
+                                        tax_id: { type: "integer", description: "Tax code for this line." },
+                                    },
+                                    anyOf: [{ required: ["transaction_account_id"] }, { required: ["transaction_template_id"] }],
+                                },
+                            },
+                        },
+                        required: ["name"],
+                    },
+                },
+            },
+            required: ["project_id", "company_id", "title"],
+        },
+        handler: (client, args) => client.mutate("POST", "/quotes", {
+            quote: {
+                project_id: args.project_id,
+                company_id: args.company_id,
+                title: args.title,
+                content: args.content,
+                sent_on: normalizeDate(args.sent_on),
+                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((group) => ({
+                    ...group,
+                    start_on: normalizeDate(group.start_on),
+                })),
+            },
+        }),
+    },
+    {
+        name: "update_quote",
+        description: "Update a quote's HEADER — title, body text, date, client, project, tax settings. Sections and lines are not touched, so this can never silently drop line items; use the section and line tools for structural edits. " +
+            "Only the fields you pass are changed. Refused once the quote has been marked accepted in the UI. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Quote id." },
+                title: { type: "string" },
+                content: { type: "string" },
+                sent_on: { type: "string", description: "Document date, e.g. '2026-08-24'." },
+                company_id: { type: "integer" },
+                project_id: { type: "integer" },
+                tax_inclusive: { type: "boolean" },
+                default_transaction_account_id: { type: "integer" },
+                default_tax_id: { type: "integer" },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/quotes/${args.id}`, {
+            quote: {
+                title: args.title,
+                content: args.content,
+                sent_on: normalizeDate(args.sent_on),
+                company_id: args.company_id,
+                project_id: args.project_id,
+                tax_inclusive: args.tax_inclusive,
+                default_transaction_account_id: args.default_transaction_account_id,
+                default_tax_id: args.default_tax_id,
+            },
+        }),
+    },
+    {
+        name: "finalise_quote",
+        description: "Move a DRAFT quote to finalised. This is internal only — it does NOT email the quote to the client and does not mark it accepted; both of those stay human actions in the Beeswax UI. " +
+            "Call it once the draft has been reviewed. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Quote id (must be a draft)." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/quotes/${args.id}/finalise`, {}),
+    },
+    {
+        name: "delete_quote",
+        description: "Delete a quote (a soft delete — it can be restored in Beeswax). Refused once the quote has been marked accepted. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Quote id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("DELETE", `/quotes/${args.id}`),
+    },
+    // ── Quote sections and lines (incremental edits) ──────────────────────
+    {
+        name: "list_quote_groups",
+        description: "List a quote's sections (phases) in order, each with its own lines and section total. Use this to see the structure before editing it — the ids returned are what the section and line tools need. Requires quotes:read.",
+        inputSchema: {
+            type: "object",
+            properties: { quote_id: { type: "integer" } },
+            required: ["quote_id"],
+        },
+        handler: (client, args) => client.getList(`/quotes/${args.quote_id}/transaction_groups`, "transaction_groups"),
+    },
+    {
+        name: "add_quote_group",
+        description: "Append a section (phase) to a quote. `lines` may be supplied to create the section and its lines in one call. " +
+            "The section goes on the end; use reorder_quote_groups to move it. Refused once the quote is accepted. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                quote_id: { type: "integer" },
+                name: { type: "string", description: "Section name, e.g. 'Phase 3 — Launch'." },
+                start_on: { type: "string", description: "Optional section start date." },
+                lines: {
+                    type: "array",
+                    description: "Lines to create in the new section, in order.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            description: { type: "string" },
+                            transaction_account_id: { type: "integer", description: "Must belong to your account." },
+                            quantity: { type: "number" },
+                            unit_amount: { type: "number", description: "Per-unit price." },
+                            kind: { type: "string" },
+                            tax_id: { type: "integer" },
+                        },
+                        required: ["transaction_account_id"],
+                    },
+                },
+            },
+            required: ["quote_id", "name"],
+        },
+        handler: (client, args) => client.mutate("POST", `/quotes/${args.quote_id}/transaction_groups`, {
+            transaction_group: { name: args.name, start_on: normalizeDate(args.start_on), lines: args.lines },
+        }),
+    },
+    {
+        name: "update_quote_group",
+        description: "Rename a quote section or change its start date. Lines are untouched — use the line tools for those. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                quote_id: { type: "integer" },
+                group_id: { type: "integer", description: "Section id — see list_quote_groups." },
+                name: { type: "string" },
+                start_on: { type: "string" },
+            },
+            required: ["quote_id", "group_id"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/quotes/${args.quote_id}/transaction_groups/${args.group_id}`, {
+            transaction_group: { name: args.name, start_on: normalizeDate(args.start_on) },
+        }),
+    },
+    {
+        name: "delete_quote_group",
+        description: "Delete a quote section AND every line in it. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: { quote_id: { type: "integer" }, group_id: { type: "integer" } },
+            required: ["quote_id", "group_id"],
+        },
+        handler: (client, args) => client.mutate("DELETE", `/quotes/${args.quote_id}/transaction_groups/${args.group_id}`),
+    },
+    {
+        name: "reorder_quote_groups",
+        description: "Reorder a quote's sections. Pass the section ids in the order you want them; ids you leave out keep their existing relative order and follow on. " +
+            "Every id must belong to this quote. If the sections carry start dates, an order that puts those dates out of sequence is rejected and nothing moves. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                quote_id: { type: "integer" },
+                group_ids: { type: "array", items: { type: "integer" }, description: "Section ids in the desired order." },
+            },
+            required: ["quote_id", "group_ids"],
+        },
+        // Unwrapped to a bare array so it matches list_quote_groups — the reorder
+        // tools are list-shaped reads of the new order, not single-resource writes.
+        handler: (client, args) => client
+            .mutate("POST", `/quotes/${args.quote_id}/transaction_groups/reorder`, { group_ids: args.group_ids })
+            .then((body) => body?.transaction_groups ?? body),
+    },
+    {
+        name: "add_quote_line",
+        description: "Append one line to a quote section. For building a quote from scratch use create_quote instead — a hundred separate calls is the wrong shape. " +
+            "`unit_amount` is the per-unit price; the line total is unit_amount x quantity. Beeswax derives the debit/credit side from the account, so never pass debit or credit. " +
+            "Naming a transaction_template_id prices the line from that catalogue product — its rate, income account, tax, wording and unit fill in whatever you do not set yourself, and anything you do set wins. " +
+            "transaction_account_id, any tax_id and any transaction_template_id must belong to your account. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                quote_id: { type: "integer" },
+                group_id: { type: "integer", description: "Section to append to — see list_quote_groups." },
+                description: { type: "string" },
+                transaction_account_id: { type: "integer", description: "Not needed if the product supplies one." },
+                transaction_template_id: {
+                    type: "integer",
+                    description: "Product/service to price this line from — see list_products_services.",
+                },
+                quantity: { type: "number", description: "Defaults to 1. Cannot be negative." },
+                unit_amount: { type: "number", description: "Per-unit price. Omit to use the product's rate." },
+                kind: { type: "string", description: "Unit label, e.g. 'Days'." },
+                tax_id: { type: "integer" },
+            },
+            anyOf: [
+                { required: ["quote_id", "group_id", "transaction_account_id"] },
+                { required: ["quote_id", "group_id", "transaction_template_id"] },
+            ],
+        },
+        handler: (client, args) => client.mutate("POST", `/quotes/${args.quote_id}/transaction_groups/${args.group_id}/transactions`, {
+            transaction: {
+                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,
+            },
+        }),
+    },
+    {
+        name: "update_quote_line",
+        description: "Change one line on a quote. Only the fields you pass are changed — anything omitted is left alone. " +
+            "That holds for transaction_template_id too: attaching a product here links the line to the catalogue and takes the product's Gantt colour, but does NOT reprice it or move its account — use this to point an existing, correctly-priced quote at the catalogue without touching a single number. " +
+            "Pass transaction_template_id: null to detach the product. To price a line FROM a product instead, set the product on a new line (add_quote_line) or clear the fields you want inherited. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                quote_id: { type: "integer" },
+                group_id: { type: "integer" },
+                line_id: { type: "integer", description: "Line id — see list_quote_groups or list_quote_transactions." },
+                description: { type: "string" },
+                transaction_account_id: { type: "integer" },
+                transaction_template_id: {
+                    type: ["integer", "null"],
+                    description: "Catalogue product this line bills against. Linking one here changes nothing else on the line; null detaches it.",
+                },
+                quantity: { type: "number" },
+                unit_amount: { type: "number", description: "Per-unit price." },
+                kind: { type: "string" },
+                tax_id: { type: "integer" },
+            },
+            required: ["quote_id", "group_id", "line_id"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/quotes/${args.quote_id}/transaction_groups/${args.group_id}/transactions/${args.line_id}`, {
+            transaction: {
+                description: args.description,
+                transaction_account_id: args.transaction_account_id,
+                // Deliberately not stripped when null — JSON.stringify drops the key
+                // when it is undefined (omitted), and an explicit null is how a
+                // caller detaches the product.
+                transaction_template_id: args.transaction_template_id,
+                quantity: args.quantity,
+                unit_amount: args.unit_amount,
+                kind: args.kind,
+                tax_id: args.tax_id,
+            },
+        }),
+    },
+    {
+        name: "delete_quote_line",
+        description: "Delete one line from a quote section. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                quote_id: { type: "integer" },
+                group_id: { type: "integer" },
+                line_id: { type: "integer" },
+            },
+            required: ["quote_id", "group_id", "line_id"],
+        },
+        handler: (client, args) => client.mutate("DELETE", `/quotes/${args.quote_id}/transaction_groups/${args.group_id}/transactions/${args.line_id}`),
+    },
+    {
+        name: "reorder_quote_lines",
+        description: "Reorder the lines within one quote section. Pass the line ids in the order you want them; ids you leave out keep their existing relative order and follow on. Every id must belong to that section. Requires quotes:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                quote_id: { type: "integer" },
+                group_id: { type: "integer" },
+                transaction_ids: { type: "array", items: { type: "integer" }, description: "Line ids in the desired order." },
+            },
+            required: ["quote_id", "group_id", "transaction_ids"],
+        },
+        // Unwrapped to a bare array, matching list_quote_transactions.
+        handler: (client, args) => client
+            .mutate("POST", `/quotes/${args.quote_id}/transaction_groups/${args.group_id}/transactions/reorder`, { transaction_ids: args.transaction_ids })
+            .then((body) => body?.transactions ?? body),
+    },
 ];

package/dist/version.js

@@ -0,0 +1,34 @@
+// Single source of truth for the running version: package.json, read at
+// startup. Never hand-type the version anywhere else — the 0.5.0/0.6.0
+// handshake drift came from exactly that.
+//
+// Layouts this must resolve in:
+//   npm/dist:      dist/version.js      → ../package.json
+//   .mcpb bundle:  server/version.js    → ../package.json (build-mcpb.sh
+//                  stages package.json beside server/)
+import { readFileSync } from "node:fs";
+function readVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        if (typeof pkg.version === "string" && pkg.version)
+            return pkg.version;
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0"; // unresolvable — better a sentinel than a lie
+}
+export const VERSION = readVersion();
+// "1.2.3" → is `candidate` strictly newer than `running`? Non-semver input → false.
+export function isNewerVersion(candidate, running) {
+    const parse = (v) => v.trim().match(/^(\d+)\.(\d+)\.(\d+)/)?.slice(1, 4).map(Number);
+    const a = parse(candidate);
+    const b = parse(running);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "beeswax-mcp",
-  "version": "0.2.1",
-  "description": "Official MCP server for Beeswax (beeswaxapp.com) — query invoices, quotes, expenses, payments, journals, time entries, projects and tax returns from Claude and other MCP clients.",
+  "version": "1.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",
   "bugs": {
@@ -32,7 +32,9 @@
     "build:mcpb": "bash scripts/build-mcpb.sh",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "release": "bash scripts/release.sh",
+    "smoke": "node scripts/smoke.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"