beeswax-mcp 1.4.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` |
@@ -141,8 +142,9 @@ 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_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/client.js

@@ -84,6 +84,28 @@ export class BeeswaxClient {
             transactions: body?.transactions ?? [],
         };
     }
+    // Paginated list whose envelope matters (balances, totals): walks every
+    // page, merges the array under rootKey, and keeps the first page's other
+    // top-level fields (minus meta).
+    async fetchAllWithEnvelope(path, rootKey, params = {}) {
+        const perPage = 100;
+        let page = 1;
+        let totalPages = 1;
+        let envelope = null;
+        const all = [];
+        do {
+            const body = await this.request(path, { ...params, page, per_page: perPage });
+            if (!envelope) {
+                envelope = { ...body };
+                delete envelope[rootKey];
+                delete envelope.meta;
+            }
+            all.push(...(body?.[rootKey] ?? []));
+            totalPages = Number(body?.meta?.total_pages ?? 1) || 1;
+            page += 1;
+        } while (page <= totalPages && all.length < 20000);
+        return { ...(envelope ?? {}), [rootKey]: all };
+    }
     // Paginated list — walks every page (via meta.total_pages) and returns the
     // merged array. Capped defensively so a malformed meta can't loop forever.
     async fetchAll(path, rootKey, params = {}) {

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",
@@ -1291,6 +1360,26 @@ export const TOOLS = [
             bank: args.bank,
         }),
     },
+    {
+        name: "list_account_transactions",
+        description: "The ledger for ONE transaction account over a period — the reconciliation query. Returns every POSTED posting to the account between from and to (inclusive, by document date), oldest first, with the opening balance at `from`, a running balance on each line, the period's debit and credit totals and the closing balance. " +
+            "Drafts, payroll templates, quotes and voided entries never appear, so these figures can be compared directly with a trial balance or a tax-return field. " +
+            "Balances follow the account's classification: asset/expense accounts grow with debits, income/loan/equity accounts with credits. Accrual basis only. " +
+            "Use list_transaction_accounts to find the account id. Requires transaction_accounts:read AND transactions:read.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                transaction_account_id: { type: "integer" },
+                from: { type: "string", description: "Start date (inclusive), e.g. '2025-07-01'. Omit for the beginning of time." },
+                to: { type: "string", description: "End date (inclusive), e.g. '2026-06-30'." },
+            },
+            required: ["transaction_account_id"],
+        },
+        handler: (client, args) => client.fetchAllWithEnvelope(`/active_account/transaction_accounts/${args.transaction_account_id}/transactions`, "transactions", {
+            from: normalizeDate(args.from),
+            to: normalizeDate(args.to),
+        }),
+    },
     {
         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. " +
@@ -1322,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.4.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",