beeswax-mcp 1.0.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
@@ -107,6 +108,8 @@ reports the same on demand.
 | `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_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

@@ -233,6 +233,167 @@ export const TOOLS = [
         },
         handler: (client, args) => client.getOne(`/tasks/${args.task_id}/files/${args.file_id}/versions`, ""),
     },
+    // ── Project documents (freeform markdown documents) ─────────────────────
+    {
+        name: "list_project_documents",
+        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: {
+                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", {
+            project_id: args.project_id,
+            document_type: args.document_type,
+        }),
+    },
+    {
+        name: "get_project_document",
+        description: "A single project document including its full markdown `body` and editing_lock status. Check editing_lock before proposing edits — if someone has it open in the web editor, writes will be refused with a conflict until they finish.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/project_documents/${args.id}`, "project_document"),
+    },
+    {
+        name: "create_project_document",
+        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: {
+                project_id: { type: "integer" },
+                name: { type: "string", description: "Document title (defaults to 'Untitled document')" },
+                body: { type: "string", description: "Markdown content" },
+                note: { type: "string", description: "Optional 'what changed' note for the first version" },
+            },
+            required: ["project_id"],
+        },
+        handler: (client, args) => client.mutate("POST", "/project_documents", {
+            project_document: { project_id: args.project_id, name: args.name, body: args.body, note: args.note },
+        }),
+    },
+    {
+        name: "update_project_document",
+        description: "Update a freeform document's markdown `body` and/or `name`. Only the fields you pass are changed; `body` REPLACES the whole content, so read the document first and send the complete edited markdown. Each successful update lands as exactly ONE new version in the history — pass `note` to label it. Refused while someone is editing in the web (409), and once the document is finalised or archived. Requires `project_documents:write`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                body: { type: "string", description: "The complete replacement markdown" },
+                note: { type: "string", description: "Optional 'what changed' note for this version" },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/project_documents/${args.id}`, {
+            project_document: { name: args.name, body: args.body, note: args.note },
+        }),
+    },
+    {
+        name: "list_project_document_versions",
+        description: "Version history of a project document, newest first. History is append-only — one version per web editing session (with the author's optional note), one per API update, plus 'Autosaved checkpoint' entries during long sessions and 'Restored from vN' entries for restores. Bodies are omitted here; read one with get_project_document_version.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/project_documents/${args.id}/versions`, ""),
+    },
+    {
+        name: "get_project_document_version",
+        description: "One version of a project document, addressed by its version_number (the 'v3' in the UI), including the full markdown body as it was at that point.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer" }, version_number: { type: "integer" } },
+            required: ["id", "version_number"],
+        },
+        handler: (client, args) => client.getOne(`/project_documents/${args.id}/versions/${args.version_number}`, "version"),
+    },
+    {
+        name: "restore_project_document_version",
+        description: "Restore a project document to an earlier version. Append-only: the restore itself becomes the next version ('Restored from vN'), so nothing is lost. Returns the document plus restored_version (null when the content already matched). Refused while someone is editing in the web. Requires `project_documents:write`.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer" }, version_number: { type: "integer" } },
+            required: ["id", "version_number"],
+        },
+        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.0.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",