beeswax-mcp 0.2.0 → 0.4.0

package/README.md

@@ -80,6 +80,7 @@ longer use from the same settings page.
 | `list_events`, `get_event` | `/events` (visibility-filtered) |
 | `list_milestones`, `get_milestone` | `/milestones` |
 | `get_project` | `/active_account/projects/:id` |
+| `list_task_files`, `list_task_file_versions` | `/tasks/:id/files` (+ per-file version history) |
 | `list_products_services`, `get_product_service` | `/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/index.js

@@ -14,7 +14,7 @@ if (!token) {
 }
 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.2.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "beeswax-mcp", version: "0.4.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
 }));
@@ -34,7 +34,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 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)`);
+    console.error(`beeswax-mcp ready → ${baseUrl}; ${TOOLS.length} tools (read + tax-return preparation)`);
 }
 main().catch((err) => {
     console.error("Fatal:", err);

package/dist/tools.js

@@ -160,6 +160,23 @@ export const TOOLS = [
         inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
         handler: (client, args) => client.getOne(`/active_account/projects/${args.id}`, "project"),
     },
+    // ── Task files & version history ───────────────────────────────────────
+    {
+        name: "list_task_files",
+        description: "List the files attached to a task, including version info: current_version_number and versions_count (files with versions_count > 0 have history readable via list_task_file_versions).",
+        inputSchema: { type: "object", properties: { task_id: { type: "integer" } }, required: ["task_id"] },
+        handler: (client, args) => client.getList(`/tasks/${args.task_id}/files`, "files"),
+    },
+    {
+        name: "list_task_file_versions",
+        description: "Version history of a task file (read-only). Returns { file, versions }: `file` is the current head; each `versions` entry is a replacement event — the archived file as it was BEFORE that replacement, with version_number, filename, size, the uploader, and their optional change note. History is append-only; restores appear as new versions.",
+        inputSchema: {
+            type: "object",
+            properties: { task_id: { type: "integer" }, file_id: { type: "integer" } },
+            required: ["task_id", "file_id"],
+        },
+        handler: (client, args) => client.getOne(`/tasks/${args.task_id}/files/${args.file_id}/versions`, ""),
+    },
     // ── Products & services catalogue (transaction templates) ──────────────
     {
         name: "list_products_services",
@@ -273,6 +290,189 @@ export const TOOLS = [
         },
         handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/sections/${args.section_key}/confirm`, {}),
     },
+    {
+        name: "unconfirm_tax_return_section",
+        description: "Unlock a previously-confirmed tax-return section for editing again. 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 unlock." },
+            },
+            required: ["id", "section_key"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/sections/${args.section_key}/unconfirm`, {}),
+    },
+    {
+        name: "tax_return_preflight_check",
+        description: "Run the pre-creation reconciliation checks for a financial year (BAS periods locked, bank accounts reconciled, unallocated transactions, unmapped accounts). Blockers must be fixed in Beeswax before a tax return can be created; warnings are informational.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                financial_year: { type: "integer", description: "Financial year ending, e.g. 2025 for FY2024-25." },
+            },
+            required: ["financial_year"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/preflight_check?financial_year=${args.financial_year}`, ""),
+    },
+    {
+        name: "create_tax_return",
+        description: "Create a draft tax return for a financial year and auto-populate it from the ledger. Runs the preflight reconciliation checks first and fails with the blockers if any exist. return_type defaults to the account's business structure. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                financial_year: { type: "integer", description: "Financial year ending, e.g. 2025 for FY2024-25." },
+                return_type: { type: "string", description: "Optional: sole_trader or company." },
+            },
+            required: ["financial_year"],
+        },
+        handler: (client, args) => client.mutate("POST", "/tax_returns", {
+            financial_year: args.financial_year,
+            return_type: args.return_type,
+        }),
+    },
+    {
+        name: "repopulate_tax_return",
+        description: "Refresh a draft tax return's auto-filled figures from the latest ledger data (after new transactions or mapping changes). Manual overrides are preserved. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Tax return id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/repopulate`, {}),
+    },
+    {
+        name: "request_tax_return_ai_review",
+        description: "Start an AI review of the tax return. The review runs in the background — poll get_tax_return (latest_review) or list_tax_return_findings to see the outcome. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Tax return id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/review`, {}),
+    },
+    {
+        name: "resolve_tax_return_finding",
+        description: "Resolve one pending AI review finding: accept (applies the suggested value to the field), reject, or defer. Every pending finding in a section must be resolved before that section can be confirmed. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                finding_id: { type: "integer", description: "Finding id (from list_tax_return_findings)." },
+                resolution: { type: "string", enum: ["accept", "reject", "defer"], description: "How to resolve the finding." },
+            },
+            required: ["id", "finding_id", "resolution"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/findings/${args.finding_id}/resolve`, {
+            resolution: args.resolution,
+        }),
+    },
+    {
+        name: "finalise_tax_return",
+        description: "Finalise a tax return once every section is confirmed. A finalised return is locked against edits (use unfinalise_tax_return to unlock it). This does NOT lodge the return with the ATO. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Tax return id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/finalise`, {}),
+    },
+    {
+        name: "list_tax_return_field_notes",
+        description: "The note timeline for one tax-return field, oldest first — who wrote what, when, and from where (web, api, or assistant). This is the durable record of WHY a figure is what it is; read it before changing a field that has notes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string" },
+                field_key: { type: "string" },
+            },
+            required: ["id", "section_key", "field_key"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/${args.id}/sections/${args.section_key}/fields/${args.field_key}/notes`, ""),
+    },
+    {
+        name: "add_tax_return_field_note",
+        description: "Append a dated, attributed note to a tax-return field's timeline — a decision, its reasoning, a follow-up, or context for next year. Notes are never deleted (you can correct your own with edit_tax_return_field_note). Recorded as written by the assistant. Requires tax_returns:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string" },
+                field_key: { type: "string" },
+                text: { type: "string", description: "The note (up to 4000 characters)." },
+            },
+            required: ["id", "section_key", "field_key", "text"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/sections/${args.section_key}/fields/${args.field_key}/notes`, {
+            text: args.text,
+            source: "mcp",
+        }),
+    },
+    {
+        name: "edit_tax_return_field_note",
+        description: "Correct a field note you wrote earlier (a typo, a wrong figure). The note keeps its place in the timeline and is marked as edited. You can only edit notes written under this token's user. Requires tax_returns:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                section_key: { type: "string" },
+                note_id: { type: "integer" },
+                text: { type: "string", description: "The corrected note text." },
+            },
+            required: ["id", "section_key", "note_id", "text"],
+        },
+        handler: (client, args) => client.mutate("PATCH", `/tax_returns/${args.id}/sections/${args.section_key}/notes/${args.note_id}`, { text: args.text }),
+    },
+    {
+        name: "get_tax_return_conversation",
+        description: "The discussion thread on a tax return — the same conversation the business owner, bookkeeper and accountant see in Beeswax. Read it to pick up questions, decisions and context before working on the return.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                limit: { type: "integer", description: "Most recent messages to return (default 100)." },
+            },
+            required: ["id"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/${args.id}/conversation?limit=${args.limit ?? 100}`, ""),
+    },
+    {
+        name: "post_tax_return_message",
+        description: "Post a message into the tax return's discussion thread, visible to everyone on the return in Beeswax. Use it to ask the owner or accountant a question, report what you did, or flag something for a human decision. Requires tax_returns:write.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id." },
+                body: { type: "string" },
+            },
+            required: ["id", "body"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/conversation/messages`, { body: args.body }),
+    },
+    {
+        name: "compare_tax_returns",
+        description: "Field-by-field comparison of a tax return against the same-type return for another financial year: prior value, current value, delta and % change per field. Fields blank in both years are omitted.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Tax return id (the current-year return)." },
+                financial_year: { type: "integer", description: "The other financial year to compare against, e.g. 2024." },
+            },
+            required: ["id", "financial_year"],
+        },
+        handler: (client, args) => client.getOne(`/tax_returns/${args.id}/compare?financial_year=${args.financial_year}`, ""),
+    },
+    {
+        name: "unfinalise_tax_return",
+        description: "Unlock a finalised (not lodged) tax return back to draft for further editing. Requires a token with the tax_returns:write scope.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "integer", description: "Tax return id." } },
+            required: ["id"],
+        },
+        handler: (client, args) => client.mutate("POST", `/tax_returns/${args.id}/unfinalise`, {}),
+    },
     // ── Manual / general journal entries (RawJournalEntry) ──────────────────
     {
         name: "list_manual_journals",

package/package.json

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