beeswax-mcp 1.1.0 → 1.2.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,9 +60,9 @@ 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
@@ -108,6 +109,7 @@ reports the same on demand.
 | `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` |

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",

package/package.json

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