beeswax-mcp 1.1.0 → 1.3.0

package/README.md

@@ -7,8 +7,9 @@ quotes, expenses, payments, journals, time entries, milestones, products & servi
 and tax returns.
 
 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.
+fields, the products & services catalogue, freeform project documents and custom
+document themes, and each write is gated behind its own token scope — everything
+else is strictly read-only.
 
 **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
@@ -59,18 +60,37 @@ account.
 `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.
+write. Add `quotes:write`, `journal_entries:write`, `tax_returns:write`,
+`transaction_templates:write`, `project_documents:write` or `themes: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).
+`transaction_accounts:read` (the chart of accounts each line bills to — the same
+scope also covers the account's tax codes).
 
 **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
 longer use from the same settings page.
 
+## Multiple accounts
+
+A token is bound to one account, so you connect several accounts by registering **one
+server entry per account**, each with its own token and a distinct name
+(`beeswax-acme`, `beeswax-steamuk`, …). Tools are namespaced by server name, so the
+agent picks the account by picking the tool.
+
+In Claude Desktop the one-click `.mcpb` extension and manual
+`claude_desktop_config.json` entries can be enabled side by side. Two things catch
+people out. A freshly installed extension is **disabled** until you flip the toggle at
+the top of its settings — saving the token does not enable it, and while it is
+disabled it exposes no tools at all. And the config file is read only at launch, so
+adding an entry or changing a token in one needs a **full restart** of the app; a
+Cowork or cloud session already linked to your computer needs that restart *and* a
+re-link before it sees the change. The Connectors screen, the naming trade-offs and
+the Cowork details are in the setup guide:
+<https://www.beeswaxapp.com/support/mcp-setup#connecting-more-than-one-account>
+
 ## Configuration
 
 | Environment variable | Required | Default |
@@ -105,9 +125,11 @@ reports the same on demand.
 | `list_milestones`, `get_milestone` | `/milestones` |
 | `list_projects`, `get_project` | `/active_account/projects` |
 | `list_transaction_accounts` | `/active_account/transaction_accounts` |
+| `list_taxes` | `/active_account/taxes` |
 | `list_companies` | `/active_account/companies` |
 | `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) |
 | `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` |
@@ -125,6 +147,14 @@ reports the same on demand.
   fetches. `outstanding: true` is the looser "not paid/draft, any due date" set.
 - **Dates.** `from` / `to` accept ISO (`2026-01-01`) or loose strings
   (`Jan 1 2026`); they are normalized to `YYYY-MM-DD` before being sent.
+- **Tax codes.** `list_taxes` is the lookup a product's `sell_tax_id` /
+  `buy_tax_id` needs. Read `sides` rather than `tax_type` to decide whether a
+  code can be used on a document: an account that is not registered for GST/VAT
+  still carries usable zero-rated codes, and those are stored as `tax_type`
+  `"none"` rather than income or expense. `side: "sell"` returns what a sale
+  (invoice or quote) offers, `"buy"` what an expense offers, `"payroll"` the
+  withholding codes. `default` marks the code Beeswax reaches for on its own.
+  Needs `transaction_accounts:read`.
 - **Products & services.** Beeswax stores the catalogue as *transaction
   templates*. `kind` is the **buy/sell mode**, not a product-vs-service label:
   `"sell"` offers the item on invoices and quotes, `"buy"` on expenses,

package/dist/tools.js

@@ -315,6 +315,85 @@ export const TOOLS = [
         },
         handler: (client, args) => client.mutate("POST", `/project_documents/${args.id}/versions/${args.version_number}/restore`, {}),
     },
+    // ── Document themes (built-in + custom, THEME_SPEC v1 authoring) ────────
+    {
+        name: "list_themes",
+        description: "All document themes available to the account: the user's custom themes (with validation state) plus the built-in registry, and active_theme_key showing which one is live. Themes style every invoice, quote and freeform document the account sends.",
+        inputSchema: { type: "object", properties: {} },
+        handler: (client) => client.getOne("/themes", ""),
+    },
+    {
+        name: "get_theme_spec",
+        description: "THEME_SPEC v1 — the complete contract for authoring a custom theme (page structure, required CSS variables, every data-bx marker, the mirrored font list, forbidden constructs). Read this BEFORE writing theme HTML; validation enforces it exactly.",
+        inputSchema: { type: "object", properties: {} },
+        handler: (client) => client.getOne("/themes/spec", ""),
+    },
+    {
+        name: "get_theme",
+        description: "A single custom theme including its stored invoice_html / document_html layouts and current validation errors.",
+        inputSchema: { type: "object", properties: { key: { type: "string" } }, required: ["key"] },
+        handler: (client, args) => client.getOne(`/themes/${args.key}`, "theme"),
+    },
+    {
+        name: "upsert_theme",
+        description: "Create or update a custom theme. Pass `key` to update an existing theme (only the fields you pass change); omit it to create one (the key derives from the name). Layout HTML must follow THEME_SPEC v1 (get_theme_spec); validation runs on every save and failures come back as the theme's validation_errors list — fix and resend. Requires themes:write and an admin-level user.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                key: { type: "string", description: "Existing theme key to update; omit to create" },
+                name: { type: "string" },
+                description: { type: "string" },
+                invoice_html: { type: "string", description: "Complete THEME_SPEC v1 invoice layout (required on create)" },
+                document_html: { type: "string", description: "Optional freeform-document layout (data-bx=\"document-body\")" },
+                accent_color: { type: "string", description: "#rrggbb default accent (the account's own accent overrides it)" },
+                font: { type: "string", description: "Primary font family, from the mirrored set in the spec" },
+            },
+        },
+        handler: (client, args) => {
+            const theme = {
+                name: args.name,
+                description: args.description,
+                invoice_html: args.invoice_html,
+                document_html: args.document_html,
+                accent_color: args.accent_color,
+                font: args.font,
+            };
+            return args.key
+                ? client.mutate("PATCH", `/themes/${args.key}`, { theme })
+                : client.mutate("POST", "/themes", { theme });
+        },
+    },
+    {
+        name: "validate_theme",
+        description: "Re-run THEME_SPEC validation on a stored theme. Returns { valid, validation_errors, state } — a theme becomes selectable once valid.",
+        inputSchema: { type: "object", properties: { key: { type: "string" } }, required: ["key"] },
+        handler: (client, args) => client.mutate("POST", `/themes/${args.key}/validate`, {}),
+    },
+    {
+        name: "preview_theme",
+        description: "Render a sample through the theme and return the full HTML: a synthetic invoice by default, or the sample markdown document with document: \"markdown\". Works on drafts that pass validation — this is the iteration loop before activating.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                key: { type: "string" },
+                document: { type: "string", enum: ["invoice", "markdown"], description: "Which layout to preview (default invoice)" },
+            },
+            required: ["key"],
+        },
+        handler: (client, args) => client.getOne(`/themes/${args.key}/preview${args.document ? `?document=${args.document}` : ""}`, ""),
+    },
+    {
+        name: "activate_theme",
+        description: "Switch the account's active theme — every invoice, quote and freeform document restyles immediately. Accepts a custom theme's resolver key (\"custom/<slug>\", must be validated) or any built-in key from list_themes (e.g. \"swiss\"). Requires themes:write and an admin-level user.",
+        inputSchema: { type: "object", properties: { key: { type: "string" } }, required: ["key"] },
+        handler: (client, args) => client.mutate("POST", "/themes/activate", { key: args.key }),
+    },
+    {
+        name: "delete_theme",
+        description: "Disable a custom theme (soft delete — it leaves the picker; an account still pointing at it falls back to the default theme). Requires themes:write and an admin-level user.",
+        inputSchema: { type: "object", properties: { key: { type: "string" } }, required: ["key"] },
+        handler: (client, args) => client.mutate("DELETE", `/themes/${args.key}`),
+    },
     // ── Products & services catalogue (transaction templates) ──────────────
     {
         name: "list_products_services",
@@ -394,8 +473,8 @@ export const TOOLS = [
                 },
                 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." },
+                sell_tax_id: { type: "integer", description: "Tax code applied when the item is sold — resolve it with list_taxes (side 'sell')." },
+                buy_tax_id: { type: "integer", description: "Tax code applied when the item is bought — resolve it with list_taxes (side 'buy')." },
                 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." },
@@ -447,8 +526,8 @@ export const TOOLS = [
                 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" },
+                sell_tax_id: { type: "integer", description: "Tax code applied when the item is sold — see list_taxes." },
+                buy_tax_id: { type: "integer", description: "Tax code applied when the item is bought — see list_taxes." },
                 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" },
@@ -847,6 +926,24 @@ export const TOOLS = [
             bank: args.bank,
         }),
     },
+    {
+        name: "list_taxes",
+        description: "List the account's tax codes — the ids `sell_tax_id` / `buy_tax_id` on a product, and a document line's tax, have to point at. " +
+            "Read `sides` rather than `tax_type` to decide whether a code can be used: 'sell' means invoices and quotes, 'buy' means expenses, and a zero-rated 'no tax' code often appears on both. " +
+            "An account that is not registered for GST/VAT still has usable codes here — they are the zero-percent ones. `default` marks the code Beeswax applies when nothing else is chosen. " +
+            "Requires a token with transaction_accounts:read.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                side: {
+                    type: "string",
+                    enum: ["sell", "buy", "payroll"],
+                    description: "Return only the codes offered on this side: 'sell' = invoices and quotes, 'buy' = expenses, 'payroll' = payroll withholding codes.",
+                },
+            },
+        },
+        handler: (client, args) => client.getList("/active_account/taxes", "taxes", { side: args.side }),
+    },
     {
         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. " +

package/package.json

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