ato-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Laverty
+
+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,38 @@
+# ato-mcp
+
+MCP server for the Australian Taxation Office corpus — cited retrieval over 29k+ ATO
+documents, ITAA 1997, and public rulings, plus personal-context and tax workflow tools
+(`deduction_discovery`, `depreciation_helper`, `bas_prep_checklist`, `audit_risk_check`).
+
+Get your token at **https://ato-mcp.com.au/onboard**, then add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "ato-mcp": {
+      "command": "npx",
+      "args": ["-y", "ato-mcp"],
+      "env": { "ATO_MCP_TOKEN": "<your-token>" }
+    }
+  }
+}
+```
+
+The client forwards every tool call to `api.ato-mcp.com.au` over TLS. There is no
+local corpus to download.
+
+## The 13 tools
+
+**Retrieval** — `search`, `get_chunks`, `get_doc`, `get_doc_anchors`, `get_definition`,
+`get_threshold`, `fetch`, `stats`.
+
+**Personal context** — `get_user_facts`: 25 facts captured once at onboarding so the
+agent never re-asks.
+
+**Workflows** — `deduction_discovery`, `depreciation_helper`, `bas_prep_checklist`,
+`audit_risk_check`.
+
+Full tool reference: https://github.com/william-laverty/ato-mcp/blob/main/docs/tools.md
+
+Not tax advice: tools return structured data + ATO citations for an agent to reason over.
+MIT © William Laverty

package/bin/ato-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/index.js");

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+function main() {
+    // Default action is to start the server, so `npx -y ato-mcp` just works.
+    const cmd = process.argv[2] ?? "mcp";
+    if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+        process.stdout.write(`ato-mcp - hosted MCP server for the Australian Taxation Office corpus
+
+Usage:
+  ato-mcp            # start the MCP stdio server (default; reads ATO_MCP_TOKEN)
+  ato-mcp mcp        # same as above, explicit
+  ato-mcp onboard    # open the browser to get your token + config snippet
+  ato-mcp help       # this message
+
+Set ATO_MCP_TOKEN in your MCP client config.
+Get a token at https://ato-mcp.com.au/onboard
+`);
+        return;
+    }
+    if (cmd === "mcp") {
+        return import("./server.js").then((m) => m.runMcp());
+    }
+    if (cmd === "onboard") {
+        return import("./lib/onboard.js").then((m) => m.runOnboard());
+    }
+    process.stderr.write(`Unknown command: ${cmd}\n`);
+    process.exit(2);
+}
+Promise.resolve(main()).catch((err) => {
+    process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,SAAS,IAAI;IACX,yEAAyE;IACzE,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;IACrC,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACvD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;;;;;;;;;CAUxB,CAAC,CAAC;QACC,OAAO;IACT,CAAC;IACD,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/onboard.d.ts

@@ -0,0 +1,6 @@
+/**
+ * runOnboard — opens the browser to the onboarding page where the user
+ * can sign in, complete the facts wizard, and copy their ATO_MCP_TOKEN.
+ */
+export declare function runOnboard(): Promise<void>;
+//# sourceMappingURL=onboard.d.ts.map

package/dist/lib/onboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboard.d.ts","sourceRoot":"","sources":["../../src/lib/onboard.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAYhD"}

package/dist/lib/onboard.js

@@ -0,0 +1,17 @@
+const BASE_URL = process.env.ATO_MCP_WEB_URL ?? "https://ato-mcp.com.au";
+/**
+ * runOnboard — opens the browser to the onboarding page where the user
+ * can sign in, complete the facts wizard, and copy their ATO_MCP_TOKEN.
+ */
+export async function runOnboard() {
+    const url = `${BASE_URL}/onboard`;
+    process.stdout.write(`\nato-mcp onboard\n`);
+    process.stdout.write(`─────────────────────────────────────────\n`);
+    process.stdout.write(`Opening browser to:\n  ${url}\n\n`);
+    process.stdout.write(`Sign in, complete the setup wizard, then copy\n`);
+    process.stdout.write(`the ATO_MCP_TOKEN into your AI client config.\n`);
+    // Dynamically import `open` (ESM-only package)
+    const { default: open } = await import("open");
+    await open(url);
+}
+//# sourceMappingURL=onboard.js.map

package/dist/lib/onboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboard.js","sourceRoot":"","sources":["../../src/lib/onboard.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,wBAAwB,CAAC;AAEzE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,GAAG,GAAG,GAAG,QAAQ,UAAU,CAAC;IAElC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACpE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,GAAG,MAAM,CAAC,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACxE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAExE,+CAA+C;IAC/C,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;AAClB,CAAC"}

package/dist/lib/remote-tools.d.ts

@@ -0,0 +1,12 @@
+export declare class RemoteToolForwarder {
+    private readonly endpoint;
+    private readonly bearerToken;
+    constructor(endpoint: string, bearerToken: string);
+    /**
+     * POST {endpoint}/{toolName} with args as JSON body.
+     * Returns the parsed JSON response.
+     * Throws on non-2xx status with a descriptive message.
+     */
+    call(toolName: string, args: unknown): Promise<unknown>;
+}
+//# sourceMappingURL=remote-tools.d.ts.map

package/dist/lib/remote-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-tools.d.ts","sourceRoot":"","sources":["../../src/lib/remote-tools.ts"],"names":[],"mappings":"AAQA,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM;IAGtC;;;;OAIG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAsC9D"}

package/dist/lib/remote-tools.js

@@ -0,0 +1,61 @@
+// Hosted-mode tool forwarder.
+//
+// When the local MCP is configured for hosted mode, every tool call goes
+// over HTTPS to api.ato-mcp.com.au. The backend runs the same shared tool
+// code we'd otherwise run locally, against Supabase Postgres + pgvector.
+//
+// One forwarder per MCP process. No local Store/Embedder needed.
+export class RemoteToolForwarder {
+    endpoint;
+    bearerToken;
+    constructor(endpoint, bearerToken) {
+        this.endpoint = endpoint;
+        this.bearerToken = bearerToken;
+    }
+    /**
+     * POST {endpoint}/{toolName} with args as JSON body.
+     * Returns the parsed JSON response.
+     * Throws on non-2xx status with a descriptive message.
+     */
+    async call(toolName, args) {
+        const url = `${this.endpoint.replace(/\/$/, "")}/${toolName}`;
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${this.bearerToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(args),
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Backend unreachable (${url}): ${msg}`);
+        }
+        const text = await resp.text();
+        if (!resp.ok) {
+            // Try to surface the structured error payload if the backend returned JSON
+            let detail = text.slice(0, 500);
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed.message)
+                    detail = parsed.message;
+            }
+            catch {
+                // not JSON, use the raw text
+            }
+            throw new Error(`Backend ${toolName}: HTTP ${resp.status} — ${detail}`);
+        }
+        if (resp.status === 204 || text.length === 0)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch (e) {
+            throw new Error(`Backend ${toolName}: invalid JSON response: ${text.slice(0, 200)}`);
+        }
+    }
+}
+//# sourceMappingURL=remote-tools.js.map

package/dist/lib/remote-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-tools.js","sourceRoot":"","sources":["../../src/lib/remote-tools.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,yEAAyE;AACzE,EAAE;AACF,iEAAiE;AAEjE,MAAM,OAAO,mBAAmB;IAEX;IACA;IAFnB,YACmB,QAAgB,EAChB,WAAmB;QADnB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,gBAAW,GAAX,WAAW,CAAQ;IACnC,CAAC;IAEJ;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,QAAgB,EAAE,IAAa;QACxC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC9D,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBACtB,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,eAAe,EAAE,UAAU,IAAI,CAAC,WAAW,EAAE;oBAC7C,cAAc,EAAE,kBAAkB;iBACnC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;aAC3B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAE/B,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,2EAA2E;YAC3E,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YAChC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAC;gBACxD,IAAI,MAAM,CAAC,OAAO;oBAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;YAC9C,CAAC;YAAC,MAAM,CAAC;gBACP,6BAA6B;YAC/B,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,WAAW,QAAQ,UAAU,IAAI,CAAC,MAAM,MAAM,MAAM,EAAE,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1D,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;QACrC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,WAAW,QAAQ,4BAA4B,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;CACF"}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+interface Forwarder {
+    call(toolName: string, args: unknown): Promise<unknown>;
+}
+/** Test seam: inject a fake forwarder to exercise listing + dispatch. */
+export declare function buildServerForTesting(deps: {
+    forwarder: Forwarder;
+}): {
+    listToolNames(): string[];
+    callTool(name: string, args: unknown): Promise<any>;
+};
+export declare function runMcp(): Promise<void>;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAyIA,UAAU,SAAS;IACjB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,SAAS,CAAA;CAAE;qBAE/C,MAAM,EAAE;mBAGJ,MAAM,QAAQ,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;EAI5D;AAED,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CA4C5C"}

package/dist/server.js

@@ -0,0 +1,176 @@
+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 { RemoteToolForwarder } from "./lib/remote-tools.js";
+const DEFAULT_API = "https://api.ato-mcp.com.au";
+const TOOLS = {
+    stats: {
+        description: "Report corpus installation status, version, and counts.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    search: {
+        description: "Hybrid BM25 + vector search over the ATO corpus. Returns top-k chunks with [doc:X] citations.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", minLength: 1 },
+                k: { type: "integer", minimum: 1, maximum: 50, default: 10 },
+                mode: { type: "string", enum: ["hybrid", "vector", "keyword"], default: "hybrid" },
+                include_old: { type: "boolean", default: false },
+                pit: { type: "string" },
+            },
+            required: ["query"],
+            additionalProperties: true,
+        },
+    },
+    get_chunks: {
+        description: "Fetch chunk bodies by chunk_id with optional neighbour context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                chunk_ids: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 50 },
+                neighbours: { type: "integer", minimum: 0, maximum: 5, default: 0 },
+                pit: { type: "string" },
+            },
+            required: ["chunk_ids"],
+            additionalProperties: false,
+        },
+    },
+    fetch: {
+        description: "Live-fetch a document by URI. Supports `ato:`, `ato-law:`, `legis:`, and `staterev-<juris>:` schemes.",
+        inputSchema: {
+            type: "object",
+            properties: { uri: { type: "string", minLength: 1 } },
+            required: ["uri"],
+            additionalProperties: false,
+        },
+    },
+    get_definition: {
+        description: "Statutory definition with optional point-in-time. Falls back to labelled ordinary-meaning (WordNet) when no statutory match. Caller MUST respect kind:'ordinary' vs kind:'statutory'.",
+        inputSchema: { type: "object", properties: { term: { type: "string", minLength: 1 }, pit: { type: "string" }, jurisdiction: { type: "string", default: "AU" } }, required: ["term"], additionalProperties: false },
+    },
+    get_doc: {
+        description: "Fetch full document by doc_id with cleaned HTML and anchor list.",
+        inputSchema: { type: "object", properties: { doc_id: { type: "string", minLength: 1 }, pit: { type: "string" } }, required: ["doc_id"], additionalProperties: false },
+    },
+    get_doc_anchors: {
+        description: "List in-document anchors and the citation graph (inbound + outbound) for a doc.",
+        inputSchema: { type: "object", properties: { doc_id: { type: "string", minLength: 1 } }, required: ["doc_id"], additionalProperties: false },
+    },
+    get_threshold: {
+        description: "Time-keyed scalar tax fact lookup (e.g. gst_registration_threshold, instant_asset_write_off, super_concessional_cap). PIT-aware.",
+        inputSchema: { type: "object", properties: { name: { type: "string", minLength: 1 }, pit: { type: "string" } }, required: ["name"], additionalProperties: false },
+    },
+    get_user_facts: {
+        description: "Return the authenticated user's personal tax facts (state, ABN, business structure, GST, dependants, etc.). Call once on initialise and reason from the result throughout the session.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    deduction_discovery: {
+        description: "Surface every deduction-related category that plausibly applies to the authenticated user's tax profile, with corpus citations, thresholds, and a confidence rating. Branches across all taxpayer structures (individual, sole trader, partnership, company, trust, SMSF member). Optionally pass `activity` to focus on a specific spend.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                activity: { type: "string" },
+                fy: { type: "string" },
+                k_citations: { type: "integer", minimum: 1, maximum: 5, default: 3 },
+                include_low_confidence: { type: "boolean", default: true },
+            },
+            additionalProperties: false,
+        },
+    },
+    depreciation_helper: {
+        description: "Compute depreciation for an asset across all applicable methods (prime cost, diminishing value, instant asset write-off, $300 immediate, small business pool, Division 43 capital works), branched by the user's taxpayer structure. Returns year-by-year schedules, the live instant-asset-write-off threshold, and corpus citations. Inputs: asset_cost, acquisition_date (YYYY-MM-DD), and optionally business_use_pct, effective_life_years, is_small_business_entity, is_capital_works, asset_type, fy.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                asset_cost: { type: "number", exclusiveMinimum: 0 },
+                acquisition_date: { type: "string" },
+                business_use_pct: { type: "number", minimum: 0, maximum: 100, default: 100 },
+                asset_type: { type: "string" },
+                effective_life_years: { type: "number", exclusiveMinimum: 0 },
+                is_small_business_entity: { type: "boolean" },
+                is_capital_works: { type: "boolean", default: false },
+                method: { type: "string", enum: ["prime_cost", "diminishing_value", "both"], default: "both" },
+                fy: { type: "string" },
+                years: { type: "integer", minimum: 1, maximum: 40 },
+            },
+            required: ["asset_cost", "acquisition_date"],
+            additionalProperties: false,
+        },
+    },
+    bas_prep_checklist: {
+        description: "Produce a tiered, cited BAS preparation checklist for the user's GST reporting period: which labels apply (GST G1/1A/1B, PAYG-W, PAYG-I, FBT instalment, fuel tax credits, WET, LCT), what evidence to gather, and common gotchas. Does not calculate amounts. Optional inputs: period_type (monthly/quarterly/annual), quarter (1-4), fy, full_gst_method.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                period_type: { type: "string", enum: ["monthly", "quarterly", "annual"] },
+                quarter: { type: "integer", minimum: 1, maximum: 4 },
+                fy: { type: "string" },
+                full_gst_method: { type: "boolean", default: false },
+            },
+            additionalProperties: false,
+        },
+    },
+    audit_risk_check: {
+        description: "Flag patterns the ATO is known to scrutinise, given the user's facts + a draft return summary (income, deductions, rental). Returns qualitative red-flag findings with a risk band, why-flagged, what-to-do and ATO guidance citations. A heuristic indicator, NOT an audit prediction and NOT numeric benchmarking. Optional inputs: income, deductions [{category, amount}], rental {income, interest, repairs, capital_works}, business_income, fy.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                income: { type: "number", minimum: 0 },
+                deductions: { type: "array", items: { type: "object", properties: { category: { type: "string" }, amount: { type: "number", minimum: 0 } }, required: ["category", "amount"], additionalProperties: false } },
+                rental: { type: "object", properties: { income: { type: "number", minimum: 0 }, interest: { type: "number", minimum: 0 }, repairs: { type: "number", minimum: 0 }, capital_works: { type: "number", minimum: 0 } }, additionalProperties: false },
+                business_income: { type: "number" },
+                fy: { type: "string" },
+            },
+            additionalProperties: false,
+        },
+    },
+};
+/** Test seam: inject a fake forwarder to exercise listing + dispatch. */
+export function buildServerForTesting(deps) {
+    return {
+        listToolNames() {
+            return Object.keys(TOOLS);
+        },
+        async callTool(name, args) {
+            return deps.forwarder.call(name, args ?? {});
+        },
+    };
+}
+export async function runMcp() {
+    const token = process.env.ATO_MCP_TOKEN;
+    if (!token) {
+        process.stderr.write("ato-mcp: ATO_MCP_TOKEN is not set.\n" +
+            "Get your token and config snippet at https://ato-mcp.com.au/onboard\n");
+        process.exit(1);
+    }
+    const endpoint = process.env.ATO_MCP_API ?? DEFAULT_API;
+    const forwarder = new RemoteToolForwarder(endpoint, token);
+    const server = new Server({ name: "ato-mcp", version: "1.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: Object.entries(TOOLS).map(([name, def]) => ({
+            name,
+            description: def.description,
+            inputSchema: def.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        try {
+            const result = await forwarder.call(name, args ?? {});
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: JSON.stringify({ kind: "error", message }, null, 2) }],
+            };
+        }
+    });
+    // Fire-and-forget connection ping so the web onboarding page can show "connected". Failures (network or transient backend) are intentionally ignored.
+    void forwarder.call("usage_event", { event_type: "mcp_started" }).catch(() => { });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "ato-mcp",
+  "version": "1.1.0",
+  "description": "Hosted MCP server for the Australian Taxation Office corpus — cited tax retrieval, personal context, and workflow tools for AI agents.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ato",
+    "australian-tax",
+    "tax",
+    "australia",
+    "claude",
+    "ai-agent",
+    "rag",
+    "itaa-1997"
+  ],
+  "license": "MIT",
+  "author": "William Laverty",
+  "homepage": "https://ato-mcp.com.au",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/william-laverty/ato-mcp.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/william-laverty/ato-mcp/issues"
+  },
+  "type": "module",
+  "bin": {
+    "ato-mcp": "./bin/ato-mcp.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.0.4",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "7.6.12",
+    "@types/node": "22.9.0",
+    "better-sqlite3": "11.5.0",
+    "sqlite-vec": "0.1.6",
+    "tsx": "4.19.2",
+    "typescript": "5.6.3",
+    "vitest": "2.1.5",
+    "@ato-mcp/shared": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}