@desktopaccountingapi/quickbooks-desktop-mcp 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- `list_api_endpoints` finds the searches its description suggests: "profit and loss" and "open invoices" now return the report operation and name the matching `reportType` (for example `profit_and_loss_standard`, `open_invoices`). Words match as tokens against the operation name, resource, summary, description, path, parameter names and report types; case, plurals and stop words do not matter, common synonyms count (P&L, A/R, supplier for vendor), and results come best match first. An exact operation or tool name (`qbd.salesOrders.list`, `qbd_sales_orders_list`, `generalSummary`) is found and listed first.
+
 ## 0.1.0
 
-First release of `@desktopaccountingapi/quickbooks-desktop-mcp`, generated from API contract sha256 `68a0d76d6b51` (API version 1.0.0, 275 operations).
+First release of `@desktopaccountingapi/quickbooks-desktop-mcp`, generated from API contract sha256 `1fc5496cc47b` (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.4.0**. [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.5.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.4.0"],
+      "args": ["-y", "@desktopaccountingapi/quickbooks-desktop-mcp@0.5.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.4.0` 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.5.0` from the package name to always run the latest version.
 
 ### Claude Code
 
@@ -125,7 +125,7 @@ We recommend a **read-only** secret key for AI tools. The API rejects every writ
 | 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". |
+| `list_api_endpoints` | Searches the operations by resource, name, words or report type, for example "open invoices" or "profit and loss", and names the matching report types. |
 | `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. |
@@ -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 `68a0d76d6b51...` for this release) by the same pipeline as the SDKs.
+- It is generated from the Desktop Accounting API contract (sha256 `1fc5496cc47b...` 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:68a0d76d6b51187adfc66d768eae8e30675b5093f4ae538b0d9c32c905b9bb2d
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
 // 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/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:68a0d76d6b51187adfc66d768eae8e30675b5093f4ae538b0d9c32c905b9bb2d
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
 // 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:68a0d76d6b51187adfc66d768eae8e30675b5093f4ae538b0d9c32c905b9bb2d
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
 // 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:68a0d76d6b51187adfc66d768eae8e30675b5093f4ae538b0d9c32c905b9bb2d
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
 // 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:68a0d76d6b51187adfc66d768eae8e30675b5093f4ae538b0d9c32c905b9bb2d
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
 // 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/search.d.ts

@@ -0,0 +1,32 @@
+import type { Catalog, CatalogEndpoint } from './catalog.ts';
+/** Lowercase stemmed tokens; splits camelCase, snake_case, kebab-case, dots and slashes. */
+export declare function tokens(text: string): string[];
+/** The words of a search query, without stop words, each with the words it also matches. */
+export declare function queryWords(search: string): string[][];
+interface Field {
+    weight: number;
+    tokens: Set<string>;
+}
+export interface SearchEntry {
+    endpoint: CatalogEndpoint;
+    fields: Field[];
+    /** Values of required enum query parameters, for example reportType values. */
+    selectors: {
+        param: string;
+        value: string;
+        tokens: Set<string>;
+    }[];
+}
+export declare function searchEntry(catalog: Catalog, e: CatalogEndpoint): SearchEntry;
+export interface SearchHit {
+    endpoint: CatalogEndpoint;
+    score: number;
+    /** Selector values (for example reportType `open_invoices`) that contain every query word, by parameter. */
+    selectors: {
+        param: string;
+        values: string[];
+    }[];
+}
+/** Scores one operation against the query words; null when a word matches nothing. */
+export declare function scoreEntry(entry: SearchEntry, words: string[][]): SearchHit | null;
+export {};

package/dist/search.js

@@ -0,0 +1,112 @@
+// 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:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
+// Operation search for list_api_endpoints. Words are matched as tokens (case, plurals and
+// camelCase/snake_case ignored, a word of 5+ letters also matches the start of a longer one)
+// against an operation's name, tag, summary, description, path, query parameter names and the
+// values of its required selector parameters (for example the report families' `reportType`:
+// `profit_and_loss_standard`, `open_invoices`). Every word must match; common accounting synonyms
+// count as the same word. Each result names the selector values that matched, so "profit and
+// loss" leads straight to qbd.reports.generalSummary with reportType profit_and_loss_standard.
+const STOP_WORDS = new Set(['a', 'an', 'and', 'the', 'of', 'for', 'by', 'to', 'in', 'on', 'with', 'or', 'from', 'my', 'our', 'all']);
+/** Phrases rewritten before tokenizing. */
+const PHRASES = [
+    [/\bp\s*&\s*l\b|\bpnl\b|\bincome statement\b/gi, 'profit loss'],
+    [/\ba\s*\/\s*r\b/gi, 'ar'],
+    [/\ba\s*\/\s*p\b/gi, 'ap'],
+];
+/** A query word also matches these words (already stemmed). */
+const SYNONYMS = {
+    receivable: ['ar'],
+    ar: ['receivable'],
+    payable: ['ap'],
+    ap: ['payable'],
+    unpaid: ['open'],
+    outstanding: ['open'],
+    overdue: ['aging', 'open'],
+    supplier: ['vendor'],
+    client: ['customer'],
+    product: ['item'],
+    service: ['item'],
+    staff: ['employee'],
+};
+function stem(word) {
+    if (word.length > 4 && word.endsWith('ies'))
+        return word.slice(0, -3) + 'y';
+    if (word.length > 3 && word.endsWith('s') && !word.endsWith('ss'))
+        return word.slice(0, -1);
+    return word;
+}
+/** Lowercase stemmed tokens; splits camelCase, snake_case, kebab-case, dots and slashes. */
+export function tokens(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean)
+        .map(stem);
+}
+/** The words of a search query, without stop words, each with the words it also matches. */
+export function queryWords(search) {
+    // Phrases are rewritten case-insensitively, but the query keeps its case until tokens() so a
+    // camelCase name (qbd.salesOrders.list, generalSummary) splits exactly like the index does.
+    let q = search;
+    for (const [re, to] of PHRASES)
+        q = q.replace(re, to);
+    return tokens(q)
+        .filter((w) => !STOP_WORDS.has(w))
+        .map((w) => [w, ...(SYNONYMS[w] ?? [])]);
+}
+function enumOf(catalog, schema) {
+    const ref = typeof schema.$ref === 'string' ? schema.$ref.split('/').pop() : undefined;
+    const target = ref ? catalog.defs[ref] : schema;
+    return Array.isArray(target?.enum) ? target.enum.filter((v) => typeof v === 'string') : [];
+}
+export function searchEntry(catalog, e) {
+    const field = (weight, ...texts) => ({ weight, tokens: new Set(texts.flatMap(tokens)) });
+    const selectors = e.queryParams
+        .filter((p) => p.required)
+        .flatMap((p) => enumOf(catalog, p.schema).map((value) => ({ param: p.name, value, tokens: new Set(tokens(value)) })));
+    return {
+        endpoint: e,
+        fields: [
+            field(3, e.name, e.tag),
+            field(2, e.summary),
+            { weight: 2, tokens: new Set(selectors.flatMap((s) => [...s.tokens])) },
+            field(1, e.group, e.path, e.description, ...e.queryParams.map((p) => p.name)),
+        ],
+        selectors,
+    };
+}
+const matches = (have, word) => {
+    if (have.has(word))
+        return true;
+    if (word.length < 5)
+        return false;
+    for (const t of have)
+        if (t.startsWith(word))
+            return true;
+    return false;
+};
+const matchesAny = (have, alternatives) => alternatives.some((w) => matches(have, w));
+/** Scores one operation against the query words; null when a word matches nothing. */
+export function scoreEntry(entry, words) {
+    let score = 0;
+    for (const alternatives of words) {
+        let best = 0;
+        for (const f of entry.fields)
+            if (f.weight > best && matchesAny(f.tokens, alternatives))
+                best = f.weight;
+        if (!best)
+            return null;
+        score += best;
+    }
+    const full = words.length ? entry.selectors.filter((s) => words.every((alts) => matchesAny(s.tokens, alts))) : [];
+    // A selector value holding the whole multi-word query ("profit and loss") outranks scattered
+    // matches, but not an operation whose name holds every word ("sales orders": qbd.salesOrders.*).
+    if (full.length && words.length > 1)
+        score += 1;
+    const byParam = new Map();
+    for (const s of full)
+        byParam.set(s.param, [...(byParam.get(s.param) ?? []), s.value]);
+    return { endpoint: entry.endpoint, score, selectors: [...byParam].map(([param, values]) => ({ param, values })) };
+}

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:68a0d76d6b51187adfc66d768eae8e30675b5093f4ae538b0d9c32c905b9bb2d
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
 // 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:68a0d76d6b51187adfc66d768eae8e30675b5093f4ae538b0d9c32c905b9bb2d
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
 // 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.d.ts

@@ -64,6 +64,7 @@ export declare class Tools {
     opts: ToolOptions;
     private readonly byName;
     private readonly perEndpoint;
+    private readonly searchIndex;
     private docsCache;
     private prepared;
     constructor(opts: ToolOptions);
@@ -81,6 +82,7 @@ export declare class Tools {
     call(name: string, args?: Record<string, unknown>): Promise<ToolResult>;
     private resolve;
     private listEndpoints;
+    private searchEntry;
     private endpointSchema;
     private headers;
     private keyProblem;

package/dist/tools.js

@@ -1,11 +1,11 @@
 // 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:68a0d76d6b51187adfc66d768eae8e30675b5093f4ae538b0d9c32c905b9bb2d
+// Contract: packages/api-contract/generated/openapi.json (OpenAPI 3.1.0) sha256:1fc5496cc47b442606ea78c818f94a29798b32785dc14c59e7986e24f10bf332
 // 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.
 //
 // Default tool set (dynamic, so 275 operations do not flood the client's context):
 //   list_end_users          the project's end users and their connection status
-//   list_api_endpoints      search the operations by name, resource or text
+//   list_api_endpoints      search the operations by name, resource, text or report type (search.ts)
 //   get_api_endpoint_schema one operation's description and input schema
 //   invoke_api_endpoint     call one operation
 //   search_docs             search the documentation (llms-full.txt)
@@ -20,6 +20,7 @@
 // found in it (prompt-injection boundary).
 import { defsFor } from './catalog.js';
 import { isValidSecretKey, maskKey } from './key.js';
+import { queryWords, scoreEntry, searchEntry } from './search.js';
 export const SERVER_NAME = 'desktopaccountingapi-quickbooks-desktop';
 const END_USER_ID = { type: 'string', pattern: '^eu_[0-9a-hjkmnp-tv-z]{26}$', description: 'The end user (eu_...) whose QuickBooks company file to use. Get it from list_end_users. Overrides the connection default.' };
 const IDEMPOTENCY_KEY = { type: 'string', minLength: 1, maxLength: 255, description: 'Writes only. Leave empty to get a fresh key. To retry a write whose outcome is unknown, send the key from the earlier attempt: the API then attaches to or replays the original instead of writing twice.' };
@@ -93,6 +94,7 @@ export class Tools {
     opts;
     byName = new Map();
     perEndpoint = new Map();
+    searchIndex = new Map();
     docsCache;
     prepared;
     constructor(opts) {
@@ -163,7 +165,7 @@ export class Tools {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        search: { type: 'string', description: 'Words to match in the operation name, resource, summary or path, for example "invoice", "open invoices", "profit and loss".' },
+                        search: { type: 'string', description: 'Words that must all match the operation name, resource, summary, description, path, parameter names or report type, for example "invoice", "open invoices", "profit and loss", "ar aging". Case and plurals do not matter, and common synonyms (supplier for vendor, P&L for profit and loss) count as the same word. Results come best match first and name the matching reportType.' },
                         group: { type: 'string', description: `Only this group: ${groups}.` },
                         kind: { type: 'string', enum: ['read', 'write', 'all'], description: 'Only reads (GET), only writes, or all (default).' },
                     },
@@ -254,7 +256,8 @@ export class Tools {
         return `Unknown endpoint "${endpoint}".${close.length ? ` Did you mean: ${close.join(', ')}?` : ' Use list_api_endpoints to find it.'}`;
     }
     listEndpoints(args) {
-        const words = String(args.search ?? '').toLowerCase().split(/\s+/).filter(Boolean).map((w) => w.replace(/s$/, ''));
+        const words = queryWords(String(args.search ?? ''));
+        const exact = String(args.search ?? '').trim().toLowerCase();
         const group = args.group ? slug(String(args.group)) : '';
         const kind = args.kind === 'read' || args.kind === 'write' ? args.kind : 'all';
         const rows = [];
@@ -265,23 +268,32 @@ export class Tools {
                 continue;
             if (kind === 'write' && !e.write)
                 continue;
-            const hay = `${e.name} ${e.tag} ${e.summary} ${e.path}`.toLowerCase();
-            let score = 0;
-            for (const w of words) {
-                if (!hay.includes(w)) {
-                    score = -1;
-                    break;
-                }
-                score += e.name.toLowerCase().includes(w) || e.tag.toLowerCase().includes(w) ? 2 : 1;
-            }
-            if (score >= 0)
-                rows.push({ e, score });
+            const hit = scoreEntry(this.searchEntry(e), words);
+            if (!hit)
+                continue;
+            // The exact operation or tool name always comes first.
+            if (exact && (exact === e.name.toLowerCase() || exact === toolName(e.name)))
+                hit.score += 100;
+            rows.push(hit);
         }
-        rows.sort((a, b) => b.score - a.score);
+        // Best score first; on a tie the operation name with fewer words (qbd.customers.* before qbd.customerTypes.*).
+        const size = (h) => h.endpoint.name.split(/\.|(?=[A-Z])/).length;
+        rows.sort((a, b) => b.score - a.score || size(a) - size(b));
         if (!rows.length)
             return text(`No operation matches${words.length ? ` "${String(args.search)}"` : ''}. Try fewer or broader words, or omit search to list every operation.`);
-        const lines = rows.map(({ e }) => `${e.name}  ${e.method} ${e.path}  ${e.summary}${e.write ? ' [write]' : ''}${e.endUser ? '' : ' [no end user]'}`);
-        return text(`${rows.length} operation${rows.length === 1 ? '' : 's'} (name, method, path, summary). QuickBooks operations need end_user_id unless marked [no end user].\n${lines.join('\n')}`);
+        const lines = rows.map(({ endpoint: e, selectors }) => {
+            const shown = selectors.map(({ param, values }) => `${param} ${values.slice(0, 6).join(', ')}${values.length > 6 ? ` and ${values.length - 6} more` : ''}`).join('; ');
+            return `${e.name}  ${e.method} ${e.path}  ${e.summary}${e.write ? ' [write]' : ''}${e.endUser ? '' : ' [no end user]'}${shown ? ` (matching ${shown})` : ''}`;
+        });
+        return text(`${rows.length} operation${rows.length === 1 ? '' : 's'} (name, method, path, summary), best match first. QuickBooks operations need end_user_id unless marked [no end user].\n${lines.join('\n')}`);
+    }
+    searchEntry(e) {
+        let entry = this.searchIndex.get(e.name);
+        if (!entry) {
+            entry = searchEntry(this.opts.catalog, e);
+            this.searchIndex.set(e.name, entry);
+        }
+        return entry;
     }
     endpointSchema(args) {
         const e = this.resolve(args.endpoint);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desktopaccountingapi/quickbooks-desktop-mcp",
-  "version": "0.4.0",
+  "version": "0.5.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",