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

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,78 @@
-# 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` is the local [Model Context Protocol](https://modelcontextprotocol.io) server for [Desktop Accounting API](https://www.desktopaccountingapi.com/docs/), the REST API for QuickBooks Desktop. It lets Claude, Cursor, VS Code, Codex and other AI tools look up and change QuickBooks Desktop data in plain English: overdue invoices, a vendor's payment history, last month's profit and loss.
+
+It runs over stdio with Node.js 20 or later on Windows, macOS and Linux, and has no runtime dependencies. It covers all 275 operations of API version 1.0.0.
+
+If your client supports remote servers with a header, you can skip the install and use the hosted server at `https://mcp.desktopaccountingapi.com/`. Setup for every client: [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/).
+
+## Setup
+
+You need a secret key from the dashboard (**API keys**) and at least one connected QuickBooks Desktop company file.
+
+Claude Desktop (`claude_desktop_config.json`, **Settings > Developer > Edit Config**):
+
+```json
+{
+  "mcpServers": {
+    "quickbooks-desktop": {
+      "command": "npx",
+      "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp"],
+      "env": { "DAAPI_SECRET_KEY": "sk_live_..." }
+    }
+  }
+}
+```
+
+Claude Code:
+
+```sh
+claude mcp add quickbooks-desktop --env DAAPI_SECRET_KEY=sk_live_... -- npx -y @desktopaccountingapi/quickbooks-desktop-mcp
+```
+
+Any other stdio client: run `npx -y @desktopaccountingapi/quickbooks-desktop-mcp` with `DAAPI_SECRET_KEY` set.
+
+## Options
+
+| Flag | Environment | Meaning |
+| --- | --- | --- |
+| | `DAAPI_SECRET_KEY` | Secret key (`sk_live_...` or `sk_test_...`). |
+| `--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. |
+| `--base-url <url>` | `DAAPI_BASE_URL` | API origin. Default `https://api.desktopaccountingapi.com`. |
+
+For a limit the API itself enforces, create a **read-only** secret key in the dashboard. The API rejects every write made with it (`403 API_KEY_READ_ONLY`), whatever the client does.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_end_users` | Your end users (one QuickBooks company file each) and their connection status. |
+| `list_api_endpoints` | Search the operations by resource, name or words. |
+| `get_api_endpoint_schema` | One operation's description and input schema. |
+| `invoke_api_endpoint` | Call an operation. Writes carry an `Idempotency-Key`; an unknown outcome is reported with recovery steps, never resent. |
+| `search_docs` | Search the documentation. |
+
+## Use as a library
+
+```ts
+import { McpServer, handleMcpRequest } from "@desktopaccountingapi/quickbooks-desktop-mcp";
+```
+
+`handleMcpRequest(request, options)` serves Streamable HTTP from any runtime with web-standard `Request` and `Response`.
+
+## Versioning
+
+Generated from the Desktop Accounting API contract (sha256 `1cc3058cecb5`) by the same pipeline as the SDKs, and released in lockstep with them. See [CHANGELOG.md](CHANGELOG.md).
+
+## Development
+
+```sh
+mise install        # pinned Node.js
+mise run check      # install, typecheck, build, tests with the official MCP client, smoke test, package contents
+```
+
+## License
+
+MIT

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;
+}