@desktopaccountingapi/quickbooks-desktop-mcp 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+First release of `@desktopaccountingapi/quickbooks-desktop-mcp`, generated from API contract sha256 `1cc3058cecb5` (API version 1.0.0, 275 operations).
+
+- Local MCP server over stdio: `npx -y @desktopaccountingapi/quickbooks-desktop-mcp`. Node.js 20 or later on Windows, macOS and Linux; no other runtime and no runtime dependencies.
+- Tools: `list_end_users`, `list_api_endpoints`, `get_api_endpoint_schema`, `invoke_api_endpoint`, `search_docs`; optional one tool per operation with `--resources`.
+- Writes carry an `Idempotency-Key`; an unknown outcome is reported with recovery steps, never resent.
+- `--read-only` hides and refuses writes; read-only secret keys are enforced by the API.
+- Library exports (`McpServer`, `handleMcpRequest`, `Tools`) to embed the server in your own process.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Desktop Accounting API
+
+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

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+# Desktop Accounting API MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@desktopaccountingapi/quickbooks-desktop-mcp` connects Claude, Cursor, VS Code, Codex and other AI tools to QuickBooks Desktop through [Desktop Accounting API](https://www.desktopaccountingapi.com/) and the [Model Context Protocol](https://modelcontextprotocol.io). Ask in plain English for overdue invoices, a vendor's payment history or last month's profit and loss, and the agent finds the operation, calls the API and answers from the company file.
+
+- Covers all 275 operations of API 1.0.0 through five compact tools, so it does not fill the agent's context.
+- Writes carry an idempotency key and are never retried blindly. Read-only keys are enforced by the API itself.
+- Runs over stdio with Node.js 20 or later on Windows, macOS and Linux, with no runtime dependencies.
+
+The current version is **0.1.1**. [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/) · [Documentation](https://www.desktopaccountingapi.com/docs/) · [Changelog](CHANGELOG.md) · [Status](https://status.desktopaccountingapi.com)
+
+## Hosted server or local package
+
+Both expose the same tools and call the same API with your secret key:
+
+| | Hosted server | This package |
+| --- | --- | --- |
+| Address | `https://mcp.desktopaccountingapi.com/` (Streamable HTTP) | `npx -y @desktopaccountingapi/quickbooks-desktop-mcp` (stdio) |
+| Install | Nothing | Node.js 20 or later |
+| Secret key | `Authorization: Bearer sk_...` header | `DAAPI_SECRET_KEY` environment variable |
+| Use it when | Your client supports remote servers with a header | Your client runs only local servers, or you prefer a local process |
+
+## Before you start
+
+- Create a secret key in the [dashboard](https://www.desktopaccountingapi.com/dashboard) under **API keys**. Use a separate key per person or tool, so you can revoke one without affecting the rest. For tools that should only look things up, choose **Read-only** (see [Read-only access](#read-only-access)). Test projects issue `sk_test_...` keys, production projects `sk_live_...` keys.
+- Connect at least one end user's QuickBooks Desktop company file. QuickBooks must be open on that computer for data requests to succeed.
+
+Replace `sk_live_...` below with your key. Keep it in your client's configuration only, never in shared documents, chat or a repository.
+
+## Setup
+
+### Claude Desktop
+
+Open **Settings > Developer > Edit Config** (`claude_desktop_config.json`) and add:
+
+```json
+{
+  "mcpServers": {
+    "quickbooks-desktop": {
+      "command": "npx",
+      "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp@0.1.1"],
+      "env": { "DAAPI_SECRET_KEY": "sk_live_..." }
+    }
+  }
+}
+```
+
+If the file already has an `mcpServers` section, add the `quickbooks-desktop` entry inside it, then restart Claude Desktop. Drop `@0.1.1` from the package name to always run the latest version.
+
+### Claude Code
+
+```sh
+claude mcp add quickbooks-desktop --env DAAPI_SECRET_KEY=sk_live_... -- npx -y @desktopaccountingapi/quickbooks-desktop-mcp
+```
+
+Or the hosted server:
+
+```sh
+claude mcp add --transport http quickbooks-desktop https://mcp.desktopaccountingapi.com/ --header "Authorization: Bearer sk_live_..."
+```
+
+Add `--scope user` to make it available in all your projects.
+
+### Cursor
+
+In `~/.cursor/mcp.json`, or `.cursor/mcp.json` inside a project:
+
+```json
+{
+  "mcpServers": {
+    "quickbooks-desktop": {
+      "command": "npx",
+      "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp"],
+      "env": { "DAAPI_SECRET_KEY": "sk_live_..." }
+    }
+  }
+}
+```
+
+For the hosted server, replace `command`, `args` and `env` with `"url": "https://mcp.desktopaccountingapi.com/"` and `"headers": { "Authorization": "Bearer sk_live_..." }`.
+
+### VS Code
+
+Run **MCP: Open User Configuration** from the Command Palette, or use `.vscode/mcp.json` in a workspace. The top-level key is `servers`:
+
+```json
+{
+  "inputs": [{ "type": "promptString", "id": "daapi-key", "description": "Desktop Accounting API secret key", "password": true }],
+  "servers": {
+    "quickbooks-desktop": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp"],
+      "env": { "DAAPI_SECRET_KEY": "${input:daapi-key}" }
+    }
+  }
+}
+```
+
+VS Code asks for the key once and stores it securely, so it never sits in the file.
+
+### Other clients
+
+Any stdio client: run `npx -y @desktopaccountingapi/quickbooks-desktop-mcp` with `DAAPI_SECRET_KEY` set. Any client that supports remote servers with custom headers can use `https://mcp.desktopaccountingapi.com/` with `Authorization: Bearer sk_live_...`. Setup for Codex CLI and more clients is in the [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/).
+
+### Verify it works
+
+Ask the agent: "List my QuickBooks Desktop end users and show the 5 most recent invoices for the first one." If it returns real data from the company file, you are set up. The key is checked when the agent first requests data, so a "connected" indicator alone does not prove the key works.
+
+## Options
+
+| Flag | Environment | Meaning |
+| --- | --- | --- |
+| | `DAAPI_SECRET_KEY` | Secret key (`sk_live_...` or `sk_test_...`). Required. |
+| `--read-only` | `DAAPI_MCP_READ_ONLY=true` | Hide and refuse operations that change data. |
+| `--resources invoices,customers` | `DAAPI_MCP_RESOURCES` | Also expose one tool per operation for these resources (`all` for every operation). |
+| `--end-user-id eu_...` | `DAAPI_END_USER_ID` | Default end user (company file) for QuickBooks operations. A tool call's `end_user_id` overrides it. |
+| `--base-url <url>` | `DAAPI_BASE_URL` | API origin. Default `https://api.desktopaccountingapi.com`. |
+| `--version` | | Print the version. |
+| `--help` | | Print the options. |
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_end_users` | Your end users (one QuickBooks company file each), with connection status and QuickBooks company name. |
+| `list_api_endpoints` | Searches the operations by resource, name or words, for example "open invoices" or "profit and loss". |
+| `get_api_endpoint_schema` | One operation's description and the JSON Schema of its arguments. |
+| `invoke_api_endpoint` | Calls an operation and returns its JSON result. `fields` (dot paths such as `["id", "refNumber"]`) trims each record. |
+| `search_docs` | Searches the documentation, including the error codes. |
+
+With `--resources`, each operation of those resources also becomes its own tool, such as `qbd_invoices_list` and `qbd_invoices_create`.
+
+## Writes and safety
+
+- By default the agent can read and write. The server instructs agents to describe each write and get your confirmation first.
+- Every write carries an `Idempotency-Key`, and the result shows it. Repeating a call with the same key returns the original result instead of writing twice.
+- Nothing is retried automatically. When a write's outcome is unknown, the result tells the agent not to resend it and how to check the request instead.
+- Errors include the `userFacingMessage` and `fixes` from the [error catalog](https://www.desktopaccountingapi.com/docs/errors/), so the agent can tell you what to do.
+- Every call appears in the dashboard's request log, like any other API call.
+
+## Read-only access
+
+Create a **read-only** secret key in the dashboard and use it in the setup above. The API enforces it for every client: a read-only key can call every `GET` operation and passthrough requests that contain only queries, and any other call returns `403 API_KEY_READ_ONLY` before anything reaches QuickBooks. Add `--read-only` (or `DAAPI_MCP_READ_ONLY=true`) to also hide write tools from the agent; the read-only key is what guarantees writes cannot happen.
+
+## Use as a library
+
+`handleMcpRequest(request, options)` serves Streamable HTTP from any runtime with web-standard `Request` and `Response`, such as Cloudflare Workers, Deno or Bun:
+
+```ts
+import { buildCatalog, handleMcpRequest } from "@desktopaccountingapi/quickbooks-desktop-mcp";
+
+// The tool catalog comes from the API's OpenAPI document, published with the documentation.
+const spec = await (await fetch("https://www.desktopaccountingapi.com/docs/openapi.json")).json();
+const catalog = buildCatalog(spec);
+
+export default {
+  fetch: (request: Request): Promise<Response> =>
+    handleMcpRequest(request, { catalog, version: "1.0.0", apiBaseUrl: "https://api.desktopaccountingapi.com" }),
+};
+```
+
+Clients send their own secret key as `Authorization: Bearer sk_...`; the server passes it to the API unchanged. `McpServer` and `Tools` are exported for other transports.
+
+## Troubleshooting
+
+- **"No secret key reached the MCP server".** `DAAPI_SECRET_KEY` (or the `Authorization` header for the hosted server) is missing or not passed through.
+- **"The secret key ... is malformed".** The key was cut off or mistyped. Copy it again from the dashboard.
+- **`API_KEY_INVALID`.** The key is unknown or was revoked. The message shows only the key's last four characters.
+- **Requests fail with a QuickBooks error.** QuickBooks must be open on the end user's computer and the Web Connector must be running. See [troubleshooting](https://www.desktopaccountingapi.com/docs/troubleshooting/).
+
+## Versioning and changelog
+
+- The package follows [semantic versioning](https://semver.org/) and is released together with the [Node.js](https://github.com/DesktopAccountingAPI/quickbooks-desktop-node), [Python](https://github.com/DesktopAccountingAPI/quickbooks-desktop-python), [.NET](https://github.com/DesktopAccountingAPI/quickbooks-desktop-dotnet) and [Java](https://github.com/DesktopAccountingAPI/quickbooks-desktop-java) SDKs, with the same version number.
+- It is generated from the Desktop Accounting API contract (sha256 `1cc3058cecb5...` for this release) by the same pipeline as the SDKs.
+- Every release is listed in [CHANGELOG.md](CHANGELOG.md) and tagged `v<version>` on GitHub.
+
+## Support
+
+- [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/), [documentation](https://www.desktopaccountingapi.com/docs/) and [status page](https://status.desktopaccountingapi.com).
+- Bugs and feature requests for this package: [GitHub issues](https://github.com/DesktopAccountingAPI/quickbooks-desktop-mcp/issues).
+- Questions about your account, keys, billing or a connection: [contact us](https://www.desktopaccountingapi.com/contact). Never send your secret key.
+- Security reports: use **Report a vulnerability** on this repository's Security tab.
+
+## Development
+
+```sh
+mise install        # pinned Node.js
+mise run check      # install, typecheck, build, tests with the official MCP client, README samples, smoke test, package contents
+```
+
+This README is generated; `mise run check` parses its JSON configuration blocks and type-checks its TypeScript sample against the build.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+QuickBooks is a registered trademark of Intuit Inc. Desktop Accounting API is an independent product and is not affiliated with, endorsed by, or approved by Intuit Inc.

package/dist/catalog.d.ts

@@ -0,0 +1,47 @@
+export type JsonSchema = Record<string, unknown>;
+export interface CatalogParam {
+    name: string;
+    required: boolean;
+    description: string;
+    schema: JsonSchema;
+}
+export interface CatalogEndpoint {
+    /** The contract operationId, for example `qbd.invoices.create`. */
+    name: string;
+    method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+    path: string;
+    /** First contract tag, for example `Invoices`. */
+    tag: string;
+    /** x-tagGroups group of the tag, for example `Transactions`. */
+    group: string;
+    summary: string;
+    description: string;
+    /** Anything other than GET changes data (read-only keys are rejected by the API). */
+    write: boolean;
+    /** The operation requires the Daapi-End-User-Id header. */
+    endUser: boolean;
+    /** The operation accepts an Idempotency-Key header. */
+    idempotent: boolean;
+    pathParams: CatalogParam[];
+    queryParams: CatalogParam[];
+    /** JSON request body, when the operation takes one. `schema` may contain `$ref: #/$defs/<name>`. */
+    body: {
+        required: boolean;
+        schema: JsonSchema;
+    } | null;
+}
+export interface Catalog {
+    apiVersion: string;
+    servers: {
+        url: string;
+        description: string;
+    }[];
+    endpoints: CatalogEndpoint[];
+    /** Every component schema reachable from an endpoint input, keyed by component name. */
+    defs: Record<string, JsonSchema>;
+}
+type Obj = Record<string, unknown>;
+export declare function buildCatalog(doc: Obj): Catalog;
+/** The `$defs` an input schema needs, transitively. */
+export declare function defsFor(catalog: Catalog, roots: unknown[]): Record<string, JsonSchema>;
+export {};

package/dist/catalog.js

@@ -0,0 +1,140 @@
+// Code generated by packages/sdk-generator from packages/mcp/src. DO NOT EDIT.
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1cc3058cecb557ce1cc724d5236d36860df6bec39636e2d427c8a408bf5f2ca2
+// MCP endpoint catalog: a compact, input-only view of the public OpenAPI contract that the MCP
+// tools search, describe and invoke. Built from packages/api-contract/generated/openapi.json by
+// scripts/api-contract.mjs (committed as packages/mcp/generated/catalog.json, drift-checked) and
+// shipped inside the stdio package by packages/sdk-generator. Pure data; no runtime imports.
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+function deref(doc, value) {
+    let v = value;
+    for (let i = 0; i < 10 && v && typeof v.$ref === 'string'; i++) {
+        const parts = v.$ref.replace(/^#\//, '').split('/');
+        let cur = doc;
+        for (const p of parts)
+            cur = cur[p];
+        v = cur;
+    }
+    return v;
+}
+/** Rewrites component refs to `#/$defs/<name>` and records the referenced names. */
+function rewrite(value, seen) {
+    if (Array.isArray(value))
+        return value.map((v) => rewrite(v, seen));
+    if (!value || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (k === '$ref' && typeof v === 'string' && v.startsWith('#/components/schemas/')) {
+            const name = v.slice('#/components/schemas/'.length);
+            seen.add(name);
+            out.$ref = `#/$defs/${name}`;
+        }
+        else if (k === 'example' || k === 'examples') {
+            // Examples stay: they show agents the expected shape.
+            out[k] = v;
+        }
+        else
+            out[k] = rewrite(v, seen);
+    }
+    return out;
+}
+export function buildCatalog(doc) {
+    const groups = new Map();
+    for (const g of doc['x-tagGroups'] ?? [])
+        for (const t of g.tags)
+            groups.set(t, g.name);
+    const pending = new Set();
+    const endpoints = [];
+    for (const [path, item] of Object.entries(doc.paths)) {
+        for (const method of METHODS) {
+            const op = item[method];
+            if (!op)
+                continue;
+            const pathParams = [];
+            const queryParams = [];
+            let endUser = false;
+            let idempotent = false;
+            for (const raw of op.parameters ?? []) {
+                const p = deref(doc, raw);
+                if (p.in === 'header') {
+                    if (p.name === 'Daapi-End-User-Id')
+                        endUser = true;
+                    if (p.name === 'Idempotency-Key')
+                        idempotent = true;
+                    continue;
+                }
+                const schema = { ...rewrite(p.schema, pending) };
+                if (schema.description === p.description)
+                    delete schema.description;
+                const param = { name: String(p.name), required: p.required === true, description: String(p.description ?? ''), schema };
+                if (p.in === 'path')
+                    pathParams.push(param);
+                else if (p.in === 'query')
+                    queryParams.push(param);
+            }
+            const rb = op.requestBody ? deref(doc, op.requestBody) : undefined;
+            const json = rb?.content?.['application/json'];
+            const tag = String(op.tags[0]);
+            endpoints.push({
+                name: String(op.operationId),
+                method: method.toUpperCase(),
+                path,
+                tag,
+                group: groups.get(tag) ?? 'Other',
+                summary: String(op.summary ?? ''),
+                description: String(op.description ?? ''),
+                write: method !== 'get',
+                endUser,
+                idempotent,
+                pathParams,
+                queryParams,
+                body: json ? { required: rb?.required === true, schema: rewrite(json.schema, pending) } : null,
+            });
+        }
+    }
+    const schemas = (doc.components.schemas ?? {});
+    const defs = {};
+    while (pending.size) {
+        const [name] = pending;
+        pending.delete(name);
+        if (defs[name])
+            continue;
+        const found = new Set();
+        defs[name] = rewrite(schemas[name], found);
+        for (const n of found)
+            if (!defs[n])
+                pending.add(n);
+    }
+    const sortedDefs = {};
+    for (const k of Object.keys(defs).sort())
+        sortedDefs[k] = defs[k];
+    return {
+        apiVersion: String(doc.info.version),
+        servers: doc.servers ?? [],
+        endpoints,
+        defs: sortedDefs,
+    };
+}
+/** The `$defs` an input schema needs, transitively. */
+export function defsFor(catalog, roots) {
+    const out = {};
+    const visit = (v) => {
+        if (Array.isArray(v))
+            return v.forEach(visit);
+        if (!v || typeof v !== 'object')
+            return;
+        for (const [k, x] of Object.entries(v)) {
+            if (k === '$ref' && typeof x === 'string' && x.startsWith('#/$defs/')) {
+                const name = x.slice('#/$defs/'.length);
+                if (!out[name] && catalog.defs[name]) {
+                    out[name] = catalog.defs[name];
+                    visit(catalog.defs[name]);
+                }
+            }
+            else
+                visit(x);
+        }
+    };
+    roots.forEach(visit);
+    return out;
+}