@desktopaccountingapi/quickbooks-desktop-mcp 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 0.1.0
 
-First release of `@desktopaccountingapi/quickbooks-desktop-mcp`, generated from API contract sha256 `b5774d24bc81` (API version 1.0.0, 275 operations).
+First release of `@desktopaccountingapi/quickbooks-desktop-mcp`, generated from API contract sha256 `79b06eb20083` (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`.

package/README.md

@@ -6,7 +6,7 @@
 - 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.2.1**. [MCP guide](https://www.desktopaccountingapi.com/docs/guides/mcp/) · [Documentation](https://www.desktopaccountingapi.com/docs/) · [Changelog](CHANGELOG.md) · [Status](https://status.desktopaccountingapi.com)
+The current version is **0.3.0**. [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
 
@@ -37,14 +37,14 @@ Open **Settings > Developer > Edit Config** (`claude_desktop_config.json`) and a
   "mcpServers": {
     "quickbooks-desktop": {
       "command": "npx",
-      "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp@0.2.1"],
+      "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp@0.3.0"],
       "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.2.1` from the package name to always run the latest version.
+If the file already has an `mcpServers` section, add the `quickbooks-desktop` entry inside it, then restart Claude Desktop. Drop `@0.3.0` from the package name to always run the latest version.
 
 ### Claude Code
 
@@ -173,7 +173,7 @@ Clients send their own secret key as `Authorization: Bearer sk_...`; the server
 ## 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 `b5774d24bc81...` for this release) by the same pipeline as the SDKs.
+- It is generated from the Desktop Accounting API contract (sha256 `79b06eb20083...` 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

package/dist/catalog.js

@@ -1,5 +1,5 @@
 // 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:b5774d24bc8154ccc2acb85370ae27581a072c3f5070a529111ee2dd26f103b9
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:79b06eb2008381661d24d3bd5e23643483ec1bf9b70d5f4cdff2a2a71e22fe94
 // 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

package/dist/catalog.json

@@ -11490,13 +11490,10 @@
     },
     {
      "name": "fiscalYear",
-     "required": false,
+     "required": true,
      "description": "Filter by fiscal year.",
      "schema": {
-      "type": [
-       "integer",
-       "null"
-      ]
+      "type": "integer"
      }
     },
     {
@@ -33128,14 +33125,15 @@
        "request.outcome_unknown",
        "request.outcome_resolved",
        "connection.setup_completed",
-       "connection.status_changed"
+       "connection.status_changed",
+       "connection.company_file_remarked"
       ],
-      "description": "`request.succeeded`, `request.failed`, `request.canceled`: a request reached that status. `request.outcome_unknown`: a write was sent without a confirmed result. `request.outcome_resolved`: such a write was resolved. `connection.setup_completed`: an end user finished setup and the first check passed. `connection.status_changed`: the derived connection status changed (offline is announced after it holds for 30 seconds).",
+      "description": "`request.succeeded`, `request.failed`, `request.canceled`: a request reached that status. `request.outcome_unknown`: a write was sent without a confirmed result. `request.outcome_resolved`: such a write was resolved. `connection.setup_completed`: an end user finished setup and the first check passed. `connection.status_changed`: the derived connection status changed (offline is announced after it holds for 30 seconds). `connection.company_file_remarked`: the private marker that identifies the connected company file was created, written back after the file lost it (for example a restored backup) or adopted from the file; `data.reason` is `marker_created`, `marker_restored` or `marker_adopted`.",
       "x-daapi-open-enum": true,
       "example": "request.succeeded"
      },
      "minItems": 1,
-     "maxItems": 7,
+     "maxItems": 8,
      "description": "Event types to deliver. At least one."
     },
     "description": {
@@ -33182,14 +33180,15 @@
        "request.outcome_unknown",
        "request.outcome_resolved",
        "connection.setup_completed",
-       "connection.status_changed"
+       "connection.status_changed",
+       "connection.company_file_remarked"
       ],
-      "description": "`request.succeeded`, `request.failed`, `request.canceled`: a request reached that status. `request.outcome_unknown`: a write was sent without a confirmed result. `request.outcome_resolved`: such a write was resolved. `connection.setup_completed`: an end user finished setup and the first check passed. `connection.status_changed`: the derived connection status changed (offline is announced after it holds for 30 seconds).",
+      "description": "`request.succeeded`, `request.failed`, `request.canceled`: a request reached that status. `request.outcome_unknown`: a write was sent without a confirmed result. `request.outcome_resolved`: such a write was resolved. `connection.setup_completed`: an end user finished setup and the first check passed. `connection.status_changed`: the derived connection status changed (offline is announced after it holds for 30 seconds). `connection.company_file_remarked`: the private marker that identifies the connected company file was created, written back after the file lost it (for example a restored backup) or adopted from the file; `data.reason` is `marker_created`, `marker_restored` or `marker_adopted`.",
       "x-daapi-open-enum": true,
       "example": "request.succeeded"
      },
      "minItems": 1,
-     "maxItems": 7,
+     "maxItems": 8,
      "description": "Event types to deliver. At least one."
     },
     "description": {

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // 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:b5774d24bc8154ccc2acb85370ae27581a072c3f5070a529111ee2dd26f103b9
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:79b06eb2008381661d24d3bd5e23643483ec1bf9b70d5f4cdff2a2a71e22fe94
 // Local (stdio) MCP server for the Desktop Accounting API.
 //
 //   npx -y @desktopaccountingapi/quickbooks-desktop-mcp [--read-only] [--resources invoices,customers] [--end-user-id eu_...]

package/dist/http.js

@@ -1,5 +1,5 @@
 // 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:b5774d24bc8154ccc2acb85370ae27581a072c3f5070a529111ee2dd26f103b9
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:79b06eb2008381661d24d3bd5e23643483ec1bf9b70d5f4cdff2a2a71e22fe94
 // Streamable HTTP transport (MCP 2025-03-26 and later), stateless: each POST carries one JSON-RPC
 // message (or a batch, for 2025-03-26 clients) and is answered with application/json. No server
 // sessions and no server-initiated stream, so GET and DELETE return 405. Web-standard Request and

package/dist/index.js

@@ -1,5 +1,5 @@
 // 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:b5774d24bc8154ccc2acb85370ae27581a072c3f5070a529111ee2dd26f103b9
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:79b06eb2008381661d24d3bd5e23643483ec1bf9b70d5f4cdff2a2a71e22fe94
 // Runtime-agnostic MCP server core (no Node-only imports); the tool design is in tools.ts.
 export { buildCatalog, defsFor } from './catalog.js';
 export { handleMcpRequest } from './http.js';

package/dist/key.js

@@ -1,5 +1,5 @@
 // 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:b5774d24bc8154ccc2acb85370ae27581a072c3f5070a529111ee2dd26f103b9
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:79b06eb2008381661d24d3bd5e23643483ec1bf9b70d5f4cdff2a2a71e22fe94
 // Local secret-key check (same rule as the API and SDKs, docs/api-conventions.md section 2):
 // `sk_live_`/`sk_test_` + 40 base62 chars, the last 6 being the base62 CRC32 of the first 34.
 // Rejecting a mistyped key locally keeps it from counting against the API's per-IP

package/dist/server.js

@@ -1,5 +1,5 @@
 // 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:b5774d24bc8154ccc2acb85370ae27581a072c3f5070a529111ee2dd26f103b9
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:79b06eb2008381661d24d3bd5e23643483ec1bf9b70d5f4cdff2a2a71e22fe94
 // Model Context Protocol server core: JSON-RPC 2.0 message handling for the `tools` capability.
 // Transport-independent; stdio.ts and http.ts carry the messages. Implements the lifecycle
 // (initialize with version negotiation, notifications/initialized, ping) plus tools/list and

package/dist/stdio.js

@@ -1,5 +1,5 @@
 // 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:b5774d24bc8154ccc2acb85370ae27581a072c3f5070a529111ee2dd26f103b9
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:79b06eb2008381661d24d3bd5e23643483ec1bf9b70d5f4cdff2a2a71e22fe94
 // stdio transport: newline-delimited JSON-RPC on stdin/stdout (MCP specification, "stdio").
 // Only protocol messages go to stdout; diagnostics go to stderr. Pure Node.js (no Deno, no
 // POSIX-only features), so it runs the same on Windows, macOS and Linux.

package/dist/tools.js

@@ -1,5 +1,5 @@
 // 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:b5774d24bc8154ccc2acb85370ae27581a072c3f5070a529111ee2dd26f103b9
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:79b06eb2008381661d24d3bd5e23643483ec1bf9b70d5f4cdff2a2a71e22fe94
 // MCP tools over the Desktop Accounting API. Runtime-agnostic (fetch and Web Crypto only), so the
 // same code runs in the hosted Cloudflare Worker (apps/mcp) and the stdio npm package.
 //
@@ -449,26 +449,54 @@ export class Tools {
     }
     errorResult(r, e, idempotencyKey) {
         const err = r.json?.error;
-        if (!err)
-            return text(`HTTP ${r.status} from the API: ${r.raw.slice(0, 2000)}`, true);
+        if (!err) {
+            // A non-JSON error (edge or proxy page) says nothing about whether a write happened.
+            const write = e?.write && idempotencyKey ? ` It is unknown whether this write happened: do not send it with a new idempotency key; repeat this exact call with idempotency_key "${idempotencyKey}", which returns the original result instead of writing twice.` : '';
+            return text(`HTTP ${r.status} from the API: ${r.raw.slice(0, 2000)}${write}`, true);
+        }
         const guidance = [];
         const outcome = err.outcome;
+        // The request that keeps running is details.requestId (504 QBD_REQUEST_TIMEOUT, 502 outcome unknown); the
+        // error's own requestId is this HTTP call, which for a lost submit identifies nothing (Fable F-19).
+        const details = (err.details ?? {});
+        const pendingId = typeof details.requestId === 'string' ? details.requestId : null;
+        const retrieve = (id, wait) => `invoke_api_endpoint endpoint "requests.retrieve" with args {"id": "${id}"${wait ? ', "waitSeconds": 60' : ''}}`;
+        const sameKey = idempotencyKey ? ` Only ever repeat this call with idempotency_key "${idempotencyKey}"; that returns the original request instead of a second write.` : '';
         if (err.code === 'API_KEY_READ_ONLY')
             guidance.push('This secret key is read-only. Do not try other ways to make the change; tell the user it needs a full-access key.');
-        else if (outcome === 'unknown' || outcome === 'pending') {
-            guidance.push(`It is not known yet whether this write took effect. Do not send it again with a new idempotency key. Check the request with invoke_api_endpoint endpoint "requests.retrieve" and args {"id": "${String(err.requestId)}"}${idempotencyKey ? `, or repeat this exact call with idempotency_key "${idempotencyKey}" to attach to the original` : ''}.`);
+        else if (outcome === 'pending') {
+            guidance.push(`QuickBooks is still processing this write${pendingId ? ` (request ${pendingId})` : ''}. Do not send it again.${pendingId ? ` Wait for its result with ${retrieve(pendingId, true)}.` : ''}${sameKey}`);
+        }
+        else if (outcome === 'unknown') {
+            guidance.push(`It is unknown whether this write took effect, and the API will not find out on its own${pendingId ? ` (request ${pendingId})` : ''}. Do not send it again with a new idempotency key.${pendingId ? ` Check ${retrieve(pendingId, false)}, and check the record in QuickBooks${typeof details.externalId === 'string' ? ` (externalId ${details.externalId})` : ''} before doing anything else.` : ''}${sameKey}`);
+        }
+        else if (err.code === 'QBD_REQUEST_TIMEOUT' && pendingId) {
+            guidance.push(`QuickBooks is still working on this read. Get its result with ${retrieve(pendingId, true)} instead of repeating the call.`);
+        }
+        else if (err.retryable === true) {
+            const after = r.headers.get('Retry-After');
+            const wait = after ? ` Wait ${after} seconds first (Retry-After).` : '';
+            guidance.push(e?.write && idempotencyKey ? `Retryable: repeat with idempotency_key "${idempotencyKey}".${wait}` : `Retryable: try again shortly.${wait}`);
         }
-        else if (err.retryable === true)
-            guidance.push(e?.write && idempotencyKey ? `Retryable: repeat with idempotency_key "${idempotencyKey}".` : 'Retryable: try again shortly.');
         if (err.code === 'END_USER_ID_MISSING' || err.code === 'RESOURCE_MISSING')
             guidance.push('Check end_user_id and IDs with list_end_users or a list operation.');
         const keep = ['type', 'code', 'message', 'userFacingMessage', 'cause', 'fixes', 'outcome', 'retryable', 'param', 'details', 'requestId', 'docsUrl', 'integrationCode'];
         const slim = { httpStatus: r.status };
+        // `cause` and `fixes` are fixed catalog text (never caller or QuickBooks data), so they go outside
+        // the envelope whose preamble says not to follow instructions in it (Fable re-review F-19).
         for (const k of keep)
-            if (err[k] !== undefined && err[k] !== null && !(k === 'details' && Object.keys(err[k]).length === 0))
+            if (k !== 'cause' && k !== 'fixes' && err[k] !== undefined && err[k] !== null && !(k === 'details' && Object.keys(err[k]).length === 0))
                 slim[k] = err[k];
-        // Error messages can quote QuickBooks data (names, memos), so they get the same envelope.
-        return text(`${untrusted(JSON.stringify(slim))}${guidance.length ? `\n${guidance.join(' ')}` : ''}`, true);
+        const catalog = [];
+        if (typeof err.code === 'string')
+            catalog.push(`Error ${err.code}${typeof err.type === 'string' ? ` (${err.type})` : ''}.`);
+        if (typeof err.cause === 'string')
+            catalog.push(`Cause: ${err.cause}`);
+        const fixes = Array.isArray(err.fixes) ? err.fixes.filter((f) => typeof f?.action === 'string') : [];
+        if (fixes.length)
+            catalog.push(`How to fix: ${fixes.map((f) => `${f.actor === 'end_user' ? 'the end user' : f.actor === 'support' ? 'support' : 'you'}: ${String(f.action)}`).join(' ')}`);
+        // Error messages and details can quote QuickBooks data (names, memos), so they get the envelope.
+        return text(`${catalog.length ? `${catalog.join('\n')}\n` : ''}${untrusted(JSON.stringify(slim))}${guidance.length ? `\n${guidance.join(' ')}` : ''}`, true);
     }
     async searchDocs(args) {
         const query = String(args.query ?? '').trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desktopaccountingapi/quickbooks-desktop-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Model Context Protocol (MCP) server for Desktop Accounting API: QuickBooks Desktop for Claude, Cursor, VS Code, Codex and other AI tools.",
   "license": "MIT",
   "author": "Desktop Accounting API",