beeswax-mcp 1.5.0 → 1.6.0

package/README.md

@@ -134,6 +134,7 @@ reports the same on demand.
 | `list_expenses`, `get_expense`, `list_expense_transactions` | `/expenses` |
 | `create_expense`, `update_expense`, `finalise_expense`, `void_expense`, `delete_expense`, `list_expense_groups`, `add_expense_group`, `update_expense_group`, `delete_expense_group`, `add_expense_line`, `update_expense_line`, `delete_expense_line`, `list_expense_versions`, `get_expense_version`, `restore_expense_version` (writes as for invoices) | `/expenses` … |
 | `query_payments`, `get_payment`, `list_payment_transactions` | `/payments` |
+| `list_invoice_files`, `attach_invoice_file` (write), `delete_invoice_file` (write), and the same for expenses and quotes | `/invoices/:id/files` … — attachments; the file rides inline as base64 (25 MB cap) |
 | `apply_payment` (write), `remove_payment` (write) | `/payments` — one payment per allocated document, one money side per call, all-or-nothing; no update |
 | `query_journal_entries`, `get_journal_entry`, `list_journal_entry_transactions` | `/journal_entries` |
 | `list_time_entries`, `get_time_entry` | `/time_entries` |
@@ -143,7 +144,7 @@ reports the same on demand.
 | `list_transaction_accounts` | `/active_account/transaction_accounts` |
 | `list_account_transactions` | `/active_account/transaction_accounts/:id/transactions?from=&to=` — one account's posted ledger for a period with opening/running/closing balances (the reconciliation query) |
 | `list_taxes` | `/active_account/taxes` |
-| `list_companies` | `/active_account/companies` |
+| `list_companies`, `get_company`, `create_company` (write), `update_company` (write) | `/active_account/companies` — clients and suppliers with their contact people; a company must be a client, a supplier or both |
 | `list_task_files`, `list_task_file_versions` | `/tasks/:id/files` (+ per-file version history) |
 | `list_project_documents`, `get_project_document`, `create_project_document` (write), `update_project_document` (write), `list_project_document_versions`, `get_project_document_version`, `restore_project_document_version` (write) | `/project_documents` (+ per-document version history) |
 | `list_themes`, `get_theme_spec`, `get_theme`, `upsert_theme` (write), `validate_theme` (write), `preview_theme`, `activate_theme` (write), `delete_theme` (write) | `/themes` (custom document themes, THEME_SPEC v1) |

package/dist/tools.js

@@ -441,6 +441,71 @@ const PAYMENT_TOOLS = [
         handler: (client, args) => client.mutate("DELETE", `/payments/${args.id}`),
     },
 ];
+// Which tool groups a token's scopes leave unusable. `all` unlocks everything;
+// a :write scope implies its :read. Surfaced by check_beeswax_connection so a
+// "403 on list_transaction_accounts" is explained before it happens.
+const SCOPE_TOOL_GROUPS = [
+    { scope: "transaction_accounts:read", tools: "list_transaction_accounts, list_taxes, list_account_transactions", why: "chart of accounts, tax codes and the per-account ledger — needed for any reconciliation and for pricing document lines" },
+    { scope: "transactions:read", tools: "list_*_transactions, list_journal_entry_transactions, list_account_transactions", why: "ledger postings" },
+    { scope: "companies:read", tools: "list_companies, get_company", why: "resolving a client or supplier by name" },
+    { scope: "projects:read", tools: "list_projects, get_project", why: "resolving a project by name" },
+    { scope: "invoices:read", tools: "list_invoices, get_invoice, list_invoice_versions", why: "" },
+    { scope: "expenses:read", tools: "list_expenses, get_expense, list_expense_versions", why: "" },
+    { scope: "payments:read", tools: "query_payments, get_payment", why: "" },
+    { scope: "journal_entries:read", tools: "list_manual_journals, get_manual_journal", why: "" },
+];
+function scopeGaps(scopes) {
+    if (scopes.includes("all"))
+        return [];
+    const has = (scope) => scopes.includes(scope) || scopes.includes(scope.replace(/:read$/, ":write"));
+    return SCOPE_TOOL_GROUPS.filter((g) => !has(g.scope)).map((g) => ({
+        missing_scope: g.scope,
+        blocks: g.tools,
+        ...(g.why ? { why: g.why } : {}),
+    }));
+}
+// ── Attachments on documents ─────────────────────────────────────────────
+// Files ride along inline as base64 — an MCP client has no other way to send
+// bytes — so this is for receipts and signed documents, not bulk transfer.
+function attachmentTools(resource) {
+    const singular = resource.slice(0, -1);
+    const idKey = `${singular}_id`;
+    const scope = `${resource}:write`;
+    return [
+        {
+            name: `list_${singular}_files`,
+            description: `List the files attached to a ${singular} (receipts, purchase orders, signed documents), newest first, with download URLs. Requires ${resource}:read.`,
+            inputSchema: { type: "object", properties: { [idKey]: { type: "integer" } }, required: [idKey] },
+            handler: (client, args) => client.getList(`/${resource}/${args[idKey]}/files`, "files"),
+        },
+        {
+            name: `attach_${singular}_file`,
+            description: `Attach a file to a ${singular}. Send the file inline as base64 (name, content_type, base64) — keep it to receipts and documents, not large media; the API caps this at 25 MB. ` +
+                `The file counts towards the account's storage quota. A voided ${singular} is refused. Requires ${scope}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    [idKey]: { type: "integer" },
+                    name: { type: "string", description: "File name with extension, e.g. receipt.pdf." },
+                    content_type: { type: "string", description: "MIME type; detected from the content if omitted." },
+                    base64: { type: "string", description: "The file's bytes, base64-encoded." },
+                    description: { type: "string" },
+                },
+                required: [idKey, "name", "base64"],
+            },
+            handler: (client, args) => client.mutate("POST", `/${resource}/${args[idKey]}/files`, {
+                description: args.description,
+                file: { name: args.name, content_type: args.content_type, base64: args.base64 },
+            }),
+        },
+        {
+            name: `delete_${singular}_file`,
+            description: `Delete a file attached to a ${singular}. The uploader, or a manager of the document. Confirm with the user first. Requires ${scope}.`,
+            inputSchema: { type: "object", properties: { [idKey]: { type: "integer" }, file_id: { type: "integer" } }, required: [idKey, "file_id"] },
+            handler: (client, args) => client.mutate("DELETE", `/${resource}/${args[idKey]}/files/${args.file_id}`),
+        },
+    ];
+}
 export const TOOLS = [
     {
         name: "check_beeswax_connection",
@@ -462,6 +527,7 @@ export const TOOLS = [
                 account: meta?.account,
                 user: meta?.user,
                 token_scopes: meta?.scopes,
+                scope_gaps: scopeGaps(meta?.scopes ?? []),
                 server_time: meta?.server_time,
                 api_base_url: client.origin,
             };
@@ -474,6 +540,9 @@ export const TOOLS = [
     ...ledgerDocumentTools("invoices"),
     ...ledgerDocumentTools("expenses"),
     ...PAYMENT_TOOLS,
+    ...attachmentTools("invoices"),
+    ...attachmentTools("expenses"),
+    ...attachmentTools("quotes"),
     // Generic journal-entries reader for the long tail.
     {
         name: "query_journal_entries",
@@ -1342,6 +1411,87 @@ export const TOOLS = [
         },
         handler: (client, args) => client.fetchAll("/active_account/companies", "companies", { role: args.role, name: args.name }),
     },
+    {
+        name: "get_company",
+        description: "Get one client or supplier by id, with its contact people. Requires companies:read.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/active_account/companies/${args.id}`, "company"),
+    },
+    {
+        name: "create_company",
+        description: "Create a client or supplier (a company / contact) so an invoice or quote can be addressed to it without a trip to the web app. " +
+            "It must be a client (you sell to them), a supplier (you buy from them), or both. `people` are optional; the first becomes the contact documents are addressed to. " +
+            "Check list_companies first — names are unique per account and a duplicate is refused. Nothing here emails anyone. Requires companies:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                client: { type: "boolean", description: "You sell to them." },
+                supplier: { type: "boolean", description: "You buy from them." },
+                phone: { type: "string" },
+                address: { type: "string" },
+                city: { type: "string" },
+                state: { type: "string" },
+                postcode: { type: "string" },
+                country: { type: "string" },
+                web_address: { type: "string" },
+                invoice_details: { type: "string", description: "Free text printed on documents: ABN / tax number, reference lines." },
+                default_tax_id: { type: "integer", description: "See list_taxes." },
+                people: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            first_name: { type: "string" }, last_name: { type: "string" }, email: { type: "string" },
+                            phone: { type: "string" }, mobile: { type: "string" },
+                        },
+                        required: ["first_name", "last_name", "email"],
+                    },
+                },
+            },
+            required: ["name"],
+        },
+        handler: (client, args) => client.mutate("POST", "/active_account/companies", { company: args }),
+    },
+    {
+        name: "update_company",
+        description: "Update a client or supplier. Only the fields you pass change. `people` APPENDS contacts (an existing email is left alone); removing a person stays a web-app action. " +
+            "A company must remain a client, a supplier, or both. The business's own company and system companies are refused. Requires companies:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                name: { type: "string" },
+                client: { type: "boolean" },
+                supplier: { type: "boolean" },
+                phone: { type: "string" },
+                address: { type: "string" },
+                city: { type: "string" },
+                state: { type: "string" },
+                postcode: { type: "string" },
+                country: { type: "string" },
+                web_address: { type: "string" },
+                invoice_details: { type: "string" },
+                default_tax_id: { type: ["integer", "null"] },
+                people: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            first_name: { type: "string" }, last_name: { type: "string" }, email: { type: "string" },
+                            phone: { type: "string" }, mobile: { type: "string" },
+                        },
+                        required: ["first_name", "last_name", "email"],
+                    },
+                },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => {
+            const { id, ...body } = args;
+            return client.mutate("PATCH", `/active_account/companies/${id}`, { company: body });
+        },
+    },
     // ── Quote authoring ──────────────────────────────────────────────────
     // The boundary here is deliberate: create and edit, never send. There is no
     // tool that emails a quote to a client or marks one accepted — those stay

package/package.json

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