beeswax-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryanchow Pty Ltd (beeswaxapp.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# beeswax-mcp
+
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for
+[Beeswax](https://www.beeswaxapp.com) — projects, tasks, time tracking and accounting
+for creative businesses. It lets Claude and other MCP clients query your invoices,
+quotes, expenses, payments, journals, time entries, milestones and tax returns.
+
+It is **read-mostly**: writes are limited to manual journals and tax-return fields,
+and each write is gated behind its own token scope — everything else is strictly
+read-only.
+
+## Quick start
+
+You need **Node.js ≥ 18** and a Beeswax API token (see below).
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "beeswax": {
+      "command": "npx",
+      "args": ["-y", "beeswax-mcp"],
+      "env": {
+        "BEESWAX_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add beeswax --env BEESWAX_API_TOKEN=your-token -- npx -y beeswax-mcp
+```
+
+### Any other MCP client
+
+Run `npx -y beeswax-mcp` as a stdio server with `BEESWAX_API_TOKEN` set in the
+environment.
+
+## Getting an API token
+
+Create a token in Beeswax under **Account Settings → API Tokens** (Owner or
+Super Admin only; requires the accounting add-on). The token is bound to one
+account.
+
+**Grant only the scopes you need.** Tick individual read scopes
+(`invoices:read`, `payments:read`, `transactions:read`, `journal_entries:read`,
+`tax_returns:read`, `events:read`, `milestones:read`, `projects:read`,
+`time_entries:read`, …) rather than `all` — `all` grants read **and** write. Add
+`journal_entries:write` / `tax_returns:write` only if the agent should be able to
+use the write tools.
+
+**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.
+
+## Configuration
+
+| Environment variable | Required | Default |
+|---|---|---|
+| `BEESWAX_API_TOKEN` | yes | — |
+| `BEESWAX_BASE_URL`  | no  | `https://app.beeswaxapp.com/new_api/v1` |
+
+## Tools
+
+| Tool | Endpoint |
+|---|---|
+| `list_invoices`, `get_invoice`, `list_invoice_transactions` | `/invoices` |
+| `list_quotes`, `get_quote`, `list_quote_transactions` | `/quotes` |
+| `list_expenses`, `get_expense`, `list_expense_transactions` | `/expenses` |
+| `query_payments`, `get_payment`, `list_payment_transactions` | `/payments` |
+| `query_journal_entries`, `get_journal_entry`, `list_journal_entry_transactions` | `/journal_entries` |
+| `list_time_entries`, `get_time_entry` | `/time_entries` |
+| `list_events`, `get_event` | `/events` (visibility-filtered) |
+| `list_milestones`, `get_milestone` | `/milestones` |
+| `get_project` | `/active_account/projects/:id` |
+| `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` |
+
+### Notes
+
+- **Scopes.** `query_journal_entries` / `get_journal_entry` need an `all`-scoped
+  token for a bare listing, a show, or a long-tail type (credits, bank_transfers,
+  payrolls); a typed listing (`type: "invoices"`) accepts that type's read scope.
+- **Transactions filter.** `system: "true"` returns only system postings (Trade
+  Debtors / Tax); omitted / `"false"` returns only the non-system line items.
+- **Overdue / outstanding (invoices & expenses only).** `overdue: true` returns
+  just the entries past their due date and not fully paid — those rows also carry
+  `due_on` and `overdue`, so "what's overdue?" is one call, not a list + N detail
+  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.
+- **Manual journals.** Balanced double-entry enforced by the API (≥ 2 lines, one of
+  debit/credit per line, debits = credits). Created finalised by default; pass
+  `status: "draft"` and use `finalise_manual_journal` for a review step. Needs
+  `journal_entries:read` / `journal_entries:write`.
+- **Tax returns.** Australian accounts only (feature-gated server-side). Reads need
+  `tax_returns:read`; `update_tax_return_field` / `confirm_tax_return_section` need
+  `tax_returns:write` and refuse calculated fields and finalised/lodged returns.
+
+## Development
+
+Building from source (in the Beeswax repo, `mcp/` folder):
+
+```bash
+cd mcp
+npm install
+npm run build      # tsc → dist/
+```
+
+The repo's default `node` may be older than 18 — use nvm/Homebrew (e.g. `nvm use 20`).
+Point your MCP client at `node /absolute/path/to/mcp/dist/index.js` instead of `npx`
+to run a local build. The underlying HTTP API is documented in `docs/openapi.yaml`
+in the main repo.
+
+## Support
+
+Setup guide: <https://www.beeswaxapp.com/support/mcp-setup>

package/dist/client.js

@@ -0,0 +1,116 @@
+// Thin HTTP client for the Beeswax new_api/v1 REST API.
+//
+// Responsibilities the MCP tools delegate here:
+//   - Bearer-token auth (from BEESWAX_API_TOKEN)
+//   - collapsing pagination into "fetch every page"
+//   - turning non-2xx responses into clear Error messages
+export class BeeswaxClient {
+    token;
+    baseUrl;
+    constructor(baseUrl, token) {
+        this.token = token;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+    }
+    async request(path, params = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null && value !== "") {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                headers: { Authorization: `Bearer ${this.token}`, Accept: "application/json" },
+            });
+        }
+        catch (err) {
+            throw new Error(`Could not reach Beeswax at ${url.origin}: ${err.message}`);
+        }
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            body = text;
+        }
+        if (!res.ok) {
+            const message = body && typeof body === "object" && body.error ? body.error : res.statusText;
+            throw new Error(`Beeswax API ${res.status} on GET ${path}: ${message}`);
+        }
+        return body;
+    }
+    // Single resource — returns the value nested under `rootKey` (e.g. "invoice").
+    async getOne(path, rootKey) {
+        const body = await this.request(path);
+        return rootKey ? body?.[rootKey] : body;
+    }
+    // Non-paginated array (e.g. an entry's transactions).
+    async getList(path, rootKey, params = {}) {
+        const body = await this.request(path, params);
+        return body?.[rootKey] ?? [];
+    }
+    // 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 = {}) {
+        const perPage = 100;
+        const all = [];
+        let page = 1;
+        let totalPages = 1;
+        do {
+            const body = await this.request(path, { ...params, page, per_page: perPage });
+            const items = body?.[rootKey] ?? [];
+            all.push(...items);
+            totalPages = Number(body?.meta?.total_pages ?? 1) || 1;
+            page += 1;
+        } while (page <= totalPages && all.length < 20000);
+        return all;
+    }
+    // Write request (POST / PATCH / DELETE) with a JSON body. Returns the parsed
+    // response body, or throws with the API's error message on a non-2xx.
+    async mutate(method, path, body = {}) {
+        const url = new URL(this.baseUrl + path);
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new Error(`Could not reach Beeswax at ${url.origin}: ${err.message}`);
+        }
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            parsed = text;
+        }
+        if (!res.ok) {
+            const message = parsed && typeof parsed === "object" && parsed.error ? parsed.error : res.statusText;
+            throw new Error(`Beeswax API ${res.status} on ${method} ${path}: ${message}`);
+        }
+        return parsed;
+    }
+}
+// Normalize a natural-ish date string to YYYY-MM-DD (what the API filters expect).
+// Already-ISO and unparseable strings pass through untouched.
+export function normalizeDate(input) {
+    if (!input)
+        return undefined;
+    const s = String(input).trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(s))
+        return s;
+    const parsed = new Date(s);
+    if (Number.isNaN(parsed.getTime()))
+        return s;
+    return parsed.toISOString().slice(0, 10);
+}

package/dist/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { BeeswaxClient } from "./client.js";
+import { TOOLS } from "./tools.js";
+const token = process.env.BEESWAX_API_TOKEN;
+const baseUrl = process.env.BEESWAX_BASE_URL ?? "https://app.beeswaxapp.com/new_api/v1";
+if (!token) {
+    console.error("BEESWAX_API_TOKEN is required. Create an API token in Beeswax " +
+        "(Account Settings → API Tokens) with the scopes you need — add tax_returns:write " +
+        "to edit tax-return figures — and set it in the environment.");
+    process.exit(1);
+}
+const client = new BeeswaxClient(baseUrl, token);
+const toolsByName = new Map(TOOLS.map((tool) => [tool.name, tool]));
+const server = new Server({ name: "beeswax-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = toolsByName.get(request.params.name);
+    if (!tool) {
+        return { content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }], isError: true };
+    }
+    try {
+        const result = await tool.handler(client, request.params.arguments ?? {});
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+    }
+});
+async function main() {
+    await server.connect(new StdioServerTransport());
+    // stderr only — stdout is the MCP protocol channel.
+    console.error(`beeswax-mcp ready → ${baseUrl}; ${TOOLS.length} tools (read + tax-return write)`);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,308 @@
+import { normalizeDate } from "./client.js";
+const SYSTEM_PROP = {
+    system: {
+        type: "string",
+        enum: ["true", "false"],
+        description: "true = only system postings (Trade Debtors/Tax); false or omitted = only non-system line items.",
+    },
+};
+const DATE_PROPS = {
+    from: {
+        type: "string",
+        description: "Earliest document date (sent_on). Accepts natural strings, e.g. '2026-01-01' or 'Jan 1 2026'.",
+    },
+    to: { type: "string", description: "Latest document date (sent_on). Same format as `from`." },
+};
+const ACCOUNTING_LIST_PROPS = {
+    state: { type: "string", description: "Filter by state (draft, finalised, pdf_sent, partial_paid, paid, …)." },
+    project_id: { type: "integer", description: "Filter to a single project." },
+    ...DATE_PROPS,
+};
+// Only the payable types (invoices / expenses) carry a due date, so the
+// overdue / outstanding filters are exposed for those tools only.
+const PAYABLE_LIST_PROPS = {
+    overdue: {
+        type: "boolean",
+        description: "true = only entries past their due date and not fully paid (state ≠ paid/draft, sent_on older than the account payment term). The list rows then include `due_on` and `overdue`.",
+    },
+    outstanding: {
+        type: "boolean",
+        description: "true = only entries not fully settled (any state except paid/draft), regardless of due date.",
+    },
+};
+// invoices / quotes / expenses / payments all share list + show + transactions.
+// `payable` adds the overdue/outstanding filters + due_on/overdue list fields.
+function accountingTools(resource, singular, label, listName, opts = {}) {
+    const payable = opts.payable ?? false;
+    const listProps = payable ? { ...ACCOUNTING_LIST_PROPS, ...PAYABLE_LIST_PROPS } : { ...ACCOUNTING_LIST_PROPS };
+    return [
+        {
+            name: listName,
+            description: `List all ${label} for the configured account. Fetches every page and returns the merged array.` +
+                (payable ? " Pass overdue:true to get just the overdue ones (with due dates) in a single call." : ""),
+            inputSchema: { type: "object", properties: { ...listProps } },
+            handler: (client, args) => client.fetchAll(`/${resource}`, resource, {
+                state: args.state,
+                project_id: args.project_id,
+                from: normalizeDate(args.from),
+                to: normalizeDate(args.to),
+                ...(payable ? { overdue: args.overdue, outstanding: args.outstanding } : {}),
+            }),
+        },
+        {
+            name: `get_${singular}`,
+            description: `Get a single ${singular} by id (full detail incl. totals and, where applicable, payment status).`,
+            inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+            handler: (client, args) => client.getOne(`/${resource}/${args.id}`, singular),
+        },
+        {
+            name: `list_${singular}_transactions`,
+            description: `List the ledger postings (debit/credit lines) beneath a ${singular}.`,
+            inputSchema: { type: "object", properties: { id: { type: "integer" }, ...SYSTEM_PROP }, required: ["id"] },
+            handler: (client, args) => client.getList(`/${resource}/${args.id}/transactions`, "transactions", { system: args.system }),
+        },
+    ];
+}
+export const TOOLS = [
+    ...accountingTools("invoices", "invoice", "invoices", "list_invoices", { payable: true }),
+    ...accountingTools("quotes", "quote", "quotes", "list_quotes"),
+    ...accountingTools("expenses", "expense", "expense documents", "list_expenses", { payable: true }),
+    ...accountingTools("payments", "payment", "payments (income / expense / payroll)", "query_payments"),
+    // Generic journal-entries reader for the long tail.
+    {
+        name: "query_journal_entries",
+        description: "List journal entries of any type. `type` accepts a URL segment (invoices) or class name (Invoice). " +
+            "Long-tail types (credits, bank_transfers, payrolls) and bare listings require an `all`-scoped token.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                type: { type: "string", description: "STI type filter, e.g. invoices, payments, payrolls, credits, bank_transfers." },
+                state: { type: "string", description: "Filter by state." },
+            },
+        },
+        handler: (client, args) => client.fetchAll("/journal_entries", "journal_entries", { type: args.type, state: args.state }),
+    },
+    {
+        name: "get_journal_entry",
+        description: "Get a single journal entry by id (any type). Requires an `all`-scoped token.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/journal_entries/${args.id}`, "journal_entry"),
+    },
+    {
+        name: "list_journal_entry_transactions",
+        description: "List the ledger postings beneath any journal entry by id.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" }, ...SYSTEM_PROP }, required: ["id"] },
+        handler: (client, args) => client.getList(`/journal_entries/${args.id}/transactions`, "transactions", { system: args.system }),
+    },
+    // Project / work cluster.
+    {
+        name: "list_time_entries",
+        description: "List all time entries for the configured account (every page).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "integer", description: "Filter to a single project." },
+                billable: { type: "boolean", description: "Filter by billable flag." },
+            },
+        },
+        handler: (client, args) => client.fetchAll("/time_entries", "time_entries", { project_id: args.project_id, billable: args.billable }),
+    },
+    {
+        name: "get_time_entry",
+        description: "Get a single time entry by id.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/time_entries/${args.id}`, "time_entry"),
+    },
+    {
+        name: "list_events",
+        description: "List calendar events visible to the token's user (private events the user is not invited to are excluded).",
+        inputSchema: {
+            type: "object",
+            properties: { project_id: { type: "integer", description: "Filter to a single project." }, ...DATE_PROPS },
+        },
+        handler: (client, args) => client.fetchAll("/events", "events", {
+            project_id: args.project_id,
+            from: normalizeDate(args.from),
+            to: normalizeDate(args.to),
+        }),
+    },
+    {
+        name: "get_event",
+        description: "Get a single event by id (returns not-found if it is not visible to the token's user).",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/events/${args.id}`, "event"),
+    },
+    {
+        name: "list_milestones",
+        description: "List all milestones (project TaskLists) for the configured account.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "integer", description: "Filter to a single project." },
+                complete: { type: "boolean", description: "Filter by completion." },
+            },
+        },
+        handler: (client, args) => client.fetchAll("/milestones", "milestones", { project_id: args.project_id, complete: args.complete }),
+    },
+    {
+        name: "get_milestone",
+        description: "Get a single milestone by id.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/milestones/${args.id}`, "milestone"),
+    },
+    {
+        name: "get_project",
+        description: "Get a single project by id.",
+        inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
+        handler: (client, args) => client.getOne(`/active_account/projects/${args.id}`, "project"),
+    },
+    // ── Tax returns (Australian company / sole-trader) ──────────────────
+    {
+        name: "list_tax_returns",
+        description: "List the account's tax returns (most recent financial year first) with status, completion %, and pending-findings count. Australian accounts only.",
+        inputSchema: { type: "object", properties: {} },
+        handler: (client) => client.getList("/tax_returns", "tax_returns"),
+    },
+    {
+        name: "get_tax_return",
+        description: "Get one tax return in full: every section with its fields, current values, the source of each value (auto / manual / calculated), whether each field is editable, and the calculated taxable income and tax. Read this before updating a field.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Tax return id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/${args.id}`, "tax_return"),
+    },
+    {
+        name: "get_tax_return_field_transactions",
+        description: "Show the chart-of-accounts transactions behind a single tax-return figure (the drill-down for an income or expense field), grouped by account, each with its journal entry number. Returns drillable:false for calculated or manually-entered fields.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string", description: "e.g. item_6_income, item_6_expenses." },
+                field_key: { type: "string", description: "e.g. other_sales_goods_services, motor_vehicle." },
+            },
+            required: ["id", "section_key", "field_key"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/${args.id}/sections/${args.section_key}/fields/${args.field_key}/transactions`, ""),
+    },
+    {
+        name: "list_tax_return_findings",
+        description: "List the AI review findings for a tax return. Optionally filter by status (pending, accepted, rejected, deferred, stale).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                status: { type: "string", description: "Optional status filter." },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => client.getList(`/tax_returns/${args.id}/findings`, "findings", { status: args.status }),
+    },
+    {
+        name: "update_tax_return_field",
+        description: "Set a manual override on one tax-return field — the same as a person editing it in the web form. Recomputes the totals and marks any now-stale AI findings. Pass an empty value to clear an override and revert to the auto-filled figure. Fails on calculated/read-only fields and on finalised or lodged returns. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string", description: "Section key, e.g. item_6_expenses." },
+                field_key: { type: "string", description: "Field key, e.g. motor_vehicle." },
+                value: {
+                    type: "string",
+                    description: "New value (numbers as strings, e.g. '15154'). An empty string clears the override.",
+                },
+            },
+            required: ["id", "section_key", "field_key", "value"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/tax_returns/${args.id}/field`, {
+            section_key: args.section_key,
+            field_key: args.field_key,
+            value: args.value,
+        }),
+    },
+    {
+        name: "confirm_tax_return_section",
+        description: "Mark a tax-return section as confirmed (reviewed). Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string", description: "Section key to confirm." },
+            },
+            required: ["id", "section_key"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/sections/${args.section_key}/confirm`, {}),
+    },
+    // ── Manual / general journal entries (RawJournalEntry) ──────────────────
+    {
+        name: "list_manual_journals",
+        description: "List manual (general) journal entries for the account, newest first. Optional state filter ('draft' or 'finalised'). Requires journal_entries:read (write implies read).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                state: { type: "string", enum: ["draft", "finalised"], description: "Optional state filter." },
+            },
+        },
+        handler: (client, args) => client.fetchAll("/raw_journal_entries", "raw_journal_entries", { state: args.state }),
+    },
+    {
+        name: "get_manual_journal",
+        description: "Get a single manual journal entry by id, including its debit/credit lines. Requires journal_entries:read.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Manual journal entry id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.getOne(`/raw_journal_entries/${args.id}`, "raw_journal_entry"),
+    },
+    {
+        name: "create_manual_journal",
+        description: "Create a manual (general) journal entry — the double-entry primitive behind every accounting adjustment that is not an invoice or expense (depreciation, accruals, asset disposals, reclassifications, opening balances, tax provisions, dividends). " +
+            "Finalised (posted to the ledger) on create by default, like every other Beeswax journal. Pass status: \"draft\" to stage it for review instead (then finalise_manual_journal). " +
+            "Rules enforced by the API: two or more lines; each line has account_id (a chart-of-accounts transaction_account id) and exactly one of debit or credit as a positive number; total debits MUST equal total credits; every account must belong to this account. " +
+            "Requires a token with the journal_entries:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                date: { type: "string", description: "Entry date, e.g. '2024-04-01'." },
+                narration: { type: "string", description: "What the journal is for, e.g. 'BMW write-off'." },
+                status: { type: "string", enum: ["finalised", "draft"], description: "Optional. Default 'finalised' posts to the ledger immediately; 'draft' stages it for review." },
+                lines: {
+                    type: "array",
+                    description: "Two or more balanced lines; total debits must equal total credits.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            account_id: { type: "integer", description: "Chart-of-accounts transaction_account id (the account to debit or credit)." },
+                            debit: { type: "number", description: "Positive debit amount. Omit or 0 on a credit line." },
+                            credit: { type: "number", description: "Positive credit amount. Omit or 0 on a debit line." },
+                            description: { type: "string", description: "Line narration." },
+                        },
+                        required: ["account_id"],
+                    },
+                },
+            },
+            required: ["date", "narration", "lines"],
+        },
+        handler: (client, args) => client.mutate("POST", "/raw_journal_entries", {
+            manual_journal: {
+                date: normalizeDate(args.date),
+                narration: args.narration,
+                status: args.status,
+                lines: args.lines,
+            },
+        }),
+    },
+    {
+        name: "finalise_manual_journal",
+        description: "Post a DRAFT manual journal to the ledger (draft -> finalised) and allocate its number. This is the deliberate, human-in-the-loop step that makes the entry real — only call it once the draft has been reviewed and confirmed. Requires journal_entries:write.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Manual journal entry id (must be a draft)." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/raw_journal_entries/${args.id}/finalise`, {}),
+    },
+];

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "beeswax-mcp",
+  "version": "0.1.0",
+  "description": "Official MCP server for Beeswax (beeswaxapp.com) — query invoices, quotes, expenses, payments, journals, time entries, projects and tax returns from Claude and other MCP clients.",
+  "license": "MIT",
+  "homepage": "https://www.beeswaxapp.com/support/mcp-setup",
+  "bugs": {
+    "url": "https://www.beeswaxapp.com/support"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "beeswax",
+    "accounting",
+    "bookkeeping",
+    "invoices",
+    "claude"
+  ],
+  "type": "module",
+  "bin": {
+    "beeswax-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  }
+}