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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,71 @@
+#!/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:1cc3058cecb557ce1cc724d5236d36860df6bec39636e2d427c8a408bf5f2ca2
+// Local (stdio) MCP server for the Desktop Accounting API.
+//
+//   npx -y @desktopaccountingapi/quickbooks-desktop-mcp [--read-only] [--resources invoices,customers] [--end-user-id eu_...]
+//
+// Environment: DAAPI_SECRET_KEY (required for API calls), DAAPI_BASE_URL (default
+// https://api.desktopaccountingapi.com), DAAPI_END_USER_ID, DAAPI_MCP_READ_ONLY=true,
+// DAAPI_MCP_RESOURCES, DAAPI_DOCS_URL.
+import { existsSync, readFileSync } from 'node:fs';
+import { McpServer } from './server.js';
+import { serveStdio } from './stdio.js';
+const HELP = `Desktop Accounting API MCP server (stdio)
+
+Usage: quickbooks-desktop-mcp [options]
+
+Options:
+  --read-only             Hide and refuse operations that change data. For a limit
+                          the API enforces, use a read-only secret key.
+  --resources <list>      Also expose one tool per operation for these resources
+                          (for example invoices,customers or all).
+  --end-user-id <eu_...>  Default end user for QuickBooks operations.
+  --base-url <url>        API origin (default https://api.desktopaccountingapi.com).
+  --version               Print the version.
+  --help                  Print this help.
+
+Environment: DAAPI_SECRET_KEY (secret key), DAAPI_BASE_URL, DAAPI_END_USER_ID,
+DAAPI_MCP_READ_ONLY, DAAPI_MCP_RESOURCES.
+Docs: https://www.desktopaccountingapi.com/docs/guides/mcp/
+`;
+function readJson(candidates) {
+    for (const rel of candidates) {
+        const url = new URL(rel, import.meta.url);
+        if (existsSync(url))
+            return JSON.parse(readFileSync(url, 'utf8'));
+    }
+    throw new Error(`missing ${candidates[0]}`);
+}
+const argv = process.argv.slice(2);
+const opt = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : argv.find((a) => a.startsWith(`--${name}=`))?.slice(name.length + 3);
+};
+const flag = (name) => argv.includes(`--${name}`);
+const truthy = (v) => !!v && /^(1|true|yes|on)$/i.test(v);
+const pkg = readJson(['../package.json']);
+if (flag('help') || flag('h')) {
+    process.stdout.write(HELP);
+    process.exit(0);
+}
+if (flag('version')) {
+    process.stdout.write(`${pkg.version}\n`);
+    process.exit(0);
+}
+const catalog = readJson(['./catalog.json', '../generated/catalog.json']);
+const env = process.env;
+const server = new McpServer({
+    catalog,
+    version: pkg.version,
+    apiKey: env.DAAPI_SECRET_KEY?.trim() || undefined,
+    baseUrl: opt('base-url') ?? env.DAAPI_BASE_URL ?? 'https://api.desktopaccountingapi.com',
+    endUserId: opt('end-user-id') ?? (env.DAAPI_END_USER_ID || undefined),
+    readOnly: flag('read-only') || truthy(env.DAAPI_MCP_READ_ONLY),
+    resources: (opt('resources') ?? env.DAAPI_MCP_RESOURCES ?? '').split(',').map((s) => s.trim()).filter(Boolean),
+    docsUrl: env.DAAPI_DOCS_URL || undefined,
+    userAgent: `desktopaccountingapi-mcp/${pkg.version} (stdio; node ${process.version}; ${process.platform})`,
+});
+if (!env.DAAPI_SECRET_KEY)
+    process.stderr.write('desktopaccountingapi-mcp: DAAPI_SECRET_KEY is not set; tools will report the missing key.\n');
+await serveStdio(server);

package/dist/http.d.ts

@@ -0,0 +1,14 @@
+import type { Catalog } from './catalog.ts';
+export interface HttpOptions {
+    catalog: Catalog;
+    version: string;
+    apiBaseUrl: string;
+    fetch?: typeof fetch;
+    docsFetch?: typeof fetch;
+    docsUrl?: string;
+    /** Extra headers for API requests (for example the caller's IP for per-IP limits). */
+    apiHeaders?: Record<string, string>;
+    /** Where GET from a browser goes (the setup guide). */
+    guideUrl?: string;
+}
+export declare function handleMcpRequest(request: Request, o: HttpOptions): Promise<Response>;

package/dist/http.js

@@ -0,0 +1,80 @@
+// 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
+// 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
+// Response only (Cloudflare Workers, Node 18+).
+//
+// Connection configuration (all optional):
+//   Authorization: Bearer sk_...          secret key, passed to the API unchanged
+//   Daapi-End-User-Id header / ?end_user_id=   default end user
+//   ?read_only=true                        hide and refuse writes (a read-only key is the server-enforced control)
+//   ?resources=invoices,customers          also expose one tool per operation for these resources ("all" for every one)
+import { McpServer, PROTOCOL_VERSIONS } from './server.js';
+const MAX_BODY = 1_000_000;
+const CORS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'POST, GET, DELETE, OPTIONS',
+    'Access-Control-Allow-Headers': 'Authorization, Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID, Daapi-End-User-Id',
+    'Access-Control-Expose-Headers': 'Mcp-Session-Id, Mcp-Protocol-Version',
+    'Access-Control-Max-Age': '86400',
+};
+function json(body, status = 200, extra = {}) {
+    return new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', ...CORS, ...extra } });
+}
+const rpcError = (status, code, message) => json({ jsonrpc: '2.0', id: null, error: { code, message } }, status);
+const truthy = (v) => !!v && /^(1|true|yes|on)$/i.test(v);
+export async function handleMcpRequest(request, o) {
+    const url = new URL(request.url);
+    if (request.method === 'OPTIONS')
+        return new Response(null, { status: 204, headers: CORS });
+    if (request.method === 'GET' && !(request.headers.get('Accept') ?? '').includes('text/event-stream') && o.guideUrl) {
+        return new Response(null, { status: 302, headers: { Location: o.guideUrl, 'Cache-Control': 'no-store' } });
+    }
+    if (request.method !== 'POST')
+        return json({ jsonrpc: '2.0', id: null, error: { code: -32000, message: 'Method not allowed. This server is stateless: send JSON-RPC messages with POST.' } }, 405, { Allow: 'POST, OPTIONS' });
+    const version = request.headers.get('Mcp-Protocol-Version');
+    if (version && !PROTOCOL_VERSIONS.includes(version))
+        return rpcError(400, -32000, `Unsupported MCP protocol version ${version}. Supported: ${PROTOCOL_VERSIONS.join(', ')}.`);
+    const type = request.headers.get('Content-Type') ?? '';
+    if (!type.includes('application/json'))
+        return rpcError(415, -32000, 'Send Content-Type: application/json.');
+    const length = Number(request.headers.get('Content-Length') ?? '0');
+    if (length > MAX_BODY)
+        return rpcError(413, -32000, 'Request body too large.');
+    const raw = await request.text();
+    if (raw.length > MAX_BODY)
+        return rpcError(413, -32000, 'Request body too large.');
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return rpcError(400, -32700, 'Parse error');
+    }
+    const auth = request.headers.get('Authorization') ?? '';
+    const apiKey = /^Bearer\s+(\S+)\s*$/i.exec(auth)?.[1];
+    const resources = (url.searchParams.get('resources') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    const server = new McpServer({
+        catalog: o.catalog,
+        version: o.version,
+        apiKey,
+        baseUrl: o.apiBaseUrl,
+        endUserId: request.headers.get('Daapi-End-User-Id') ?? url.searchParams.get('end_user_id') ?? undefined,
+        readOnly: truthy(url.searchParams.get('read_only')),
+        resources,
+        docsUrl: o.docsUrl,
+        fetch: o.fetch,
+        docsFetch: o.docsFetch,
+        apiHeaders: o.apiHeaders,
+        userAgent: `desktopaccountingapi-mcp/${o.version} (hosted)`,
+    });
+    if (Array.isArray(body)) {
+        if (!body.length)
+            return rpcError(400, -32600, 'Invalid Request: empty batch');
+        const out = (await Promise.all(body.map((m) => server.handle(m)))).filter((r) => r !== null);
+        return out.length ? json(out) : new Response(null, { status: 202, headers: CORS });
+    }
+    const res = await server.handle(body);
+    return res ? json(res) : new Response(null, { status: 202, headers: CORS });
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { buildCatalog, defsFor, type Catalog, type CatalogEndpoint, type CatalogParam, type JsonSchema } from './catalog.ts';
+export { handleMcpRequest, type HttpOptions } from './http.ts';
+export { isValidSecretKey, maskKey } from './key.ts';
+export { McpServer, PROTOCOL_VERSIONS, type JsonRpcMessage } from './server.ts';
+export { endpointArgsSchema, project, SERVER_NAME, splitDocs, toolName, Tools, type Tool, type ToolOptions, type ToolResult } from './tools.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+// 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
+// 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';
+export { isValidSecretKey, maskKey } from './key.js';
+export { McpServer, PROTOCOL_VERSIONS } from './server.js';
+export { endpointArgsSchema, project, SERVER_NAME, splitDocs, toolName, Tools } from './tools.js';

package/dist/key.d.ts

@@ -0,0 +1,3 @@
+export declare function isValidSecretKey(key: string): boolean;
+/** `sk_live_...` + last 4, safe for messages. */
+export declare function maskKey(key: string): string;

package/dist/key.js

@@ -0,0 +1,41 @@
+// 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
+// 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
+// failed-authentication limit.
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+let table;
+function crc32(input) {
+    if (!table) {
+        table = new Uint32Array(256);
+        for (let n = 0; n < 256; n++) {
+            let c = n;
+            for (let k = 0; k < 8; k++)
+                c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            table[n] = c >>> 0;
+        }
+    }
+    let crc = 0xffffffff;
+    for (const byte of new TextEncoder().encode(input))
+        crc = table[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function base62(value, width) {
+    let out = '';
+    let v = value;
+    while (v > 0) {
+        out = BASE62[v % 62] + out;
+        v = Math.floor(v / 62);
+    }
+    return out.padStart(width, '0');
+}
+export function isValidSecretKey(key) {
+    const m = /^sk_(live|test)_([0-9A-Za-z]{40})$/.exec(key);
+    return !!m && base62(crc32(m[2].slice(0, 34)), 6) === m[2].slice(34);
+}
+/** `sk_live_...` + last 4, safe for messages. */
+export function maskKey(key) {
+    const prefix = key.startsWith('sk_live_') ? 'sk_live_' : key.startsWith('sk_test_') ? 'sk_test_' : '';
+    return prefix ? `${prefix}...${key.slice(-4)}` : 'the provided key';
+}

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+import { Tools, type ToolOptions } from './tools.ts';
+/** Newest first. The client's version is used when supported, otherwise the newest. */
+export declare const PROTOCOL_VERSIONS: string[];
+export interface JsonRpcMessage {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method?: string;
+    params?: Record<string, unknown>;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export declare class McpServer {
+    readonly tools: Tools;
+    private readonly version;
+    constructor(opts: ToolOptions & {
+        version: string;
+    });
+    /** Handles one message. Returns the response, or null for notifications and responses. */
+    handle(msg: unknown): Promise<JsonRpcMessage | null>;
+}

package/dist/server.js

@@ -0,0 +1,73 @@
+// 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
+// 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
+// tools/call. Stateless: every HTTP request is answered on its own.
+import { SERVER_NAME, Tools } from './tools.js';
+/** Newest first. The client's version is used when supported, otherwise the newest. */
+export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const INSTRUCTIONS = `Desktop Accounting API: read and write QuickBooks Desktop company files (customers, vendors, invoices, bills, payments, items, accounts, reports and more) through the QuickBooks Web Connector.
+
+How to work:
+1. Call list_end_users to find the end user (eu_...) whose company file to use. Each end user is one QuickBooks company file. Connection status "online" means requests can run now.
+2. Find the operation with list_api_endpoints (search "invoice", "profit and loss", ...), read its input with get_api_endpoint_schema, then run it with invoke_api_endpoint and end_user_id.
+3. Lists return one page (default limit). Use filters (for example updatedAfter, customerIds, transactionDateFrom) and the fields argument to keep results small; pass nextCursor as cursor for more.
+4. Writes change the user's real accounting records. Describe the change and get the user's confirmation before each write. Never repeat a write whose outcome is unknown with a new idempotency key; follow the guidance in the error.
+5. QuickBooks must be open on the end user's computer. Error results include a userFacingMessage and fixes; relay them instead of guessing.
+6. For concepts and error codes, use search_docs.`;
+export class McpServer {
+    tools;
+    version;
+    constructor(opts) {
+        this.tools = new Tools(opts);
+        this.version = opts.version;
+    }
+    /** Handles one message. Returns the response, or null for notifications and responses. */
+    async handle(msg) {
+        if (!msg || typeof msg !== 'object' || Array.isArray(msg) || msg.jsonrpc !== '2.0') {
+            return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid Request' } };
+        }
+        const m = msg;
+        if (m.method === undefined)
+            return null; // a response to a server request (none are sent)
+        const isNotification = m.id === undefined;
+        const reply = (result) => (isNotification ? null : { jsonrpc: '2.0', id: m.id, result });
+        const fail = (code, message) => (isNotification ? null : { jsonrpc: '2.0', id: m.id, error: { code, message } });
+        const params = (m.params ?? {});
+        switch (m.method) {
+            case 'initialize': {
+                const requested = String(params.protocolVersion ?? '');
+                return reply({
+                    protocolVersion: PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0],
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: SERVER_NAME, title: 'Desktop Accounting API (QuickBooks Desktop)', version: this.version, websiteUrl: 'https://www.desktopaccountingapi.com/docs/guides/mcp/' },
+                    instructions: INSTRUCTIONS + (this.tools.opts.readOnly ? '\n\nThis connection is read-only: operations that change data are hidden and refused.' : ''),
+                });
+            }
+            case 'ping':
+                return reply({});
+            case 'tools/list':
+                return reply({ tools: this.tools.list() });
+            case 'tools/call': {
+                const name = params.name;
+                if (typeof name !== 'string')
+                    return fail(-32602, 'tools/call needs a tool name');
+                const args = params.arguments;
+                if (args !== undefined && (typeof args !== 'object' || args === null || Array.isArray(args)))
+                    return fail(-32602, 'arguments must be an object');
+                if (!this.tools.list().some((t) => t.name === name))
+                    return fail(-32602, `Unknown tool: ${name}`);
+                return reply(await this.tools.call(name, (args ?? {})));
+            }
+            case 'resources/list':
+                return reply({ resources: [] });
+            case 'prompts/list':
+                return reply({ prompts: [] });
+            default:
+                if (m.method.startsWith('notifications/'))
+                    return null;
+                return fail(-32601, `Method not found: ${m.method}`);
+        }
+    }
+}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from './server.ts';
+export declare function serveStdio(server: McpServer, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<void>;

package/dist/stdio.js

@@ -0,0 +1,40 @@
+// 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
+// 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.
+import { createInterface } from 'node:readline';
+export function serveStdio(server, input = process.stdin, output = process.stdout) {
+    const rl = createInterface({ input, crlfDelay: Infinity });
+    const write = (msg) => output.write(`${JSON.stringify(msg)}\n`);
+    const pending = new Set();
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+            return;
+        }
+        // Requests run concurrently; each response carries its id.
+        const work = (async () => {
+            if (Array.isArray(msg)) {
+                const out = (await Promise.all(msg.map((m) => server.handle(m)))).filter((r) => r !== null);
+                if (out.length)
+                    void write(out);
+            }
+            else {
+                const res = await server.handle(msg);
+                if (res)
+                    void write(res);
+            }
+        })().catch((err) => void process.stderr.write(`desktopaccountingapi-mcp: ${err instanceof Error ? err.message : String(err)}\n`));
+        pending.add(work);
+        void work.finally(() => pending.delete(work));
+    });
+    return new Promise((resolve) => rl.on('close', () => void Promise.all(pending).then(() => resolve())));
+}

package/dist/tools.d.ts

@@ -0,0 +1,89 @@
+import { type Catalog, type CatalogEndpoint, type JsonSchema } from './catalog.ts';
+export declare const SERVER_NAME = "desktopaccountingapi-quickbooks-desktop";
+export interface ToolOptions {
+    catalog: Catalog;
+    /** Secret key (`sk_live_...` or `sk_test_...`). */
+    apiKey: string | undefined;
+    /** API origin, for example https://api.desktopaccountingapi.com. */
+    baseUrl: string;
+    /** Default end user for operations that need one; a tool call's `end_user_id` overrides it. */
+    endUserId?: string | undefined;
+    /** Hide and refuse every operation that changes data. */
+    readOnly?: boolean | undefined;
+    /** Also expose one tool per operation for these resources (tag or group names, or `all`). */
+    resources?: string[] | undefined;
+    /** URL of llms-full.txt for search_docs. */
+    docsUrl?: string | undefined;
+    /** fetch for API requests (the hosted server passes its service binding). */
+    fetch?: typeof fetch | undefined;
+    /** fetch for the documentation (default: global fetch). */
+    docsFetch?: typeof fetch | undefined;
+    /** Headers added to every API request (for example the client IP for the hosted server). */
+    apiHeaders?: Record<string, string> | undefined;
+    /** Largest tool result in characters before lists are cut. */
+    maxResultChars?: number | undefined;
+    userAgent?: string | undefined;
+}
+export interface Tool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: JsonSchema;
+    annotations?: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+}
+export interface ToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+}
+export declare function toolName(endpoint: string): string;
+/** Flattened arguments for one operation: path and query parameters at the top, the JSON body under `body`. */
+export declare function endpointArgsSchema(catalog: Catalog, e: CatalogEndpoint, withDefs?: boolean): JsonSchema;
+export declare class Tools {
+    readonly opts: ToolOptions;
+    private readonly byName;
+    private readonly perEndpoint;
+    private docsCache;
+    constructor(opts: ToolOptions);
+    list(): Tool[];
+    call(name: string, args?: Record<string, unknown>): Promise<ToolResult>;
+    private resolve;
+    private listEndpoints;
+    private endpointSchema;
+    private headers;
+    private keyProblem;
+    private request;
+    private listEndUsers;
+    invoke(e: CatalogEndpoint, args: Record<string, unknown>, control: {
+        end_user_id?: unknown;
+        idempotency_key?: unknown;
+        fields?: unknown;
+    }): Promise<ToolResult>;
+    /** Serializes a result within maxResultChars, cutting list pages rather than JSON text. */
+    private fit;
+    private errorResult;
+    private searchDocs;
+    private docs;
+}
+interface DocPage {
+    title: string;
+    url: string;
+    text: string;
+}
+/**
+ * llms-full.txt: each page starts with `# Title` immediately followed by `Source: <url>`. Only that
+ * pair marks a page boundary (a `# ` line inside a code block is never followed by `Source:`).
+ */
+export declare function splitDocs(full: string): DocPage[];
+/** Keeps only the given dot paths of an object, or of each item of a list (`data`). */
+export declare function project(value: unknown, paths: string[]): unknown;
+export {};