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

package/dist/tools.js

@@ -0,0 +1,520 @@
+// 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 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
+//   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)
+// Optionally one tool per operation for chosen resources (`resources`), with exact input schemas.
+//
+// Safety: the API enforces read-only keys server-side (403 API_KEY_READ_ONLY). `readOnly` here
+// also hides and refuses writes before they reach the API. Writes always carry an Idempotency-Key;
+// nothing is retried automatically, and an unknown outcome is reported, never resent.
+import { defsFor } from './catalog.js';
+import { isValidSecretKey, maskKey } from './key.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.' };
+const FIELDS = { type: 'array', items: { type: 'string' }, description: 'Optional: keep only these fields (dot paths such as "id", "customer.fullName", "lines.amount") of the returned object, or of each item of a list. Use it to keep large results small.' };
+const RESERVED = new Set(['end_user_id', 'idempotency_key', 'fields', 'body']);
+const text = (t, isError = false) => ({ content: [{ type: 'text', text: t }], ...(isError ? { isError: true } : {}) });
+export function toolName(endpoint) {
+    return endpoint.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/\./g, '_').toLowerCase();
+}
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+/** Flattened arguments for one operation: path and query parameters at the top, the JSON body under `body`. */
+export function endpointArgsSchema(catalog, e, withDefs = true) {
+    const properties = {};
+    const required = [];
+    for (const p of [...e.pathParams, ...e.queryParams]) {
+        if (RESERVED.has(p.name))
+            throw new Error(`${e.name}: parameter ${p.name} collides with a reserved MCP argument`);
+        properties[p.name] = { ...p.schema, ...(p.description ? { description: p.description } : {}) };
+        if (p.required)
+            required.push(p.name);
+    }
+    if (e.body) {
+        properties.body = { ...e.body.schema, description: `JSON request body.${e.body.schema.description ? ` ${String(e.body.schema.description)}` : ''}` };
+        if (e.body.required)
+            required.push('body');
+    }
+    const schema = { type: 'object', properties, ...(required.length ? { required } : {}), additionalProperties: false };
+    if (withDefs) {
+        const defs = defsFor(catalog, [properties]);
+        if (Object.keys(defs).length)
+            schema.$defs = defs;
+    }
+    return schema;
+}
+function endpointTool(catalog, e) {
+    const args = endpointArgsSchema(catalog, e);
+    const props = { ...args.properties };
+    const required = [...(args.required ?? [])];
+    if (e.endUser)
+        props.end_user_id = END_USER_ID;
+    if (e.idempotent)
+        props.idempotency_key = IDEMPOTENCY_KEY;
+    props.fields = FIELDS;
+    return {
+        name: toolName(e.name),
+        title: e.summary,
+        description: `${e.summary} (${e.method} ${e.path}).${e.write ? ' Changes QuickBooks or account data: confirm with the user first.' : ''}\n\n${e.description}`,
+        inputSchema: { type: 'object', properties: props, ...(required.length ? { required } : {}), additionalProperties: false, ...(args.$defs ? { $defs: args.$defs } : {}) },
+        annotations: { title: e.summary, readOnlyHint: !e.write, destructiveHint: e.method === 'DELETE' || /\.(void|delete)$/.test(e.name), idempotentHint: !e.write, openWorldHint: true },
+    };
+}
+export class Tools {
+    opts;
+    byName = new Map();
+    perEndpoint = new Map();
+    docsCache;
+    constructor(opts) {
+        this.opts = opts;
+        const wanted = (opts.resources ?? []).map(slug).filter(Boolean);
+        for (const e of opts.catalog.endpoints) {
+            if (opts.readOnly && e.write)
+                continue;
+            this.byName.set(e.name, e);
+            if (wanted.includes('all') || wanted.includes(slug(e.tag)) || wanted.includes(slug(e.group)))
+                this.perEndpoint.set(toolName(e.name), e);
+        }
+    }
+    list() {
+        const groups = [...new Set(this.opts.catalog.endpoints.map((e) => e.group))].join(', ');
+        const tools = [
+            {
+                name: 'list_end_users',
+                title: 'List end users',
+                description: 'Lists the end users (your customers, each with one QuickBooks Desktop company file) in the project this secret key belongs to, with their connection status and company name. QuickBooks operations need an end user ID (eu_...): call this first, then pass `end_user_id`.',
+                inputSchema: { type: 'object', properties: { search: { type: 'string', description: 'Case-insensitive filter on company name, source ID, email or QuickBooks company name.' } }, additionalProperties: false },
+                annotations: { title: 'List end users', readOnlyHint: true, openWorldHint: true },
+            },
+            {
+                name: 'list_api_endpoints',
+                title: 'List API endpoints',
+                description: `Searches the ${this.byName.size} Desktop Accounting API operations (QuickBooks Desktop customers, invoices, bills, items, reports and more, plus end users, requests and webhooks). Returns each operation's name, method, path and summary. Groups: ${groups}. Then call get_api_endpoint_schema for the input schema and invoke_api_endpoint to run it.${this.opts.readOnly ? ' This connection is read-only: operations that change data are hidden.' : ''}`,
+                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".' },
+                        group: { type: 'string', description: `Only this group: ${groups}.` },
+                        kind: { type: 'string', enum: ['read', 'write', 'all'], description: 'Only reads (GET), only writes, or all (default).' },
+                    },
+                    additionalProperties: false,
+                },
+                annotations: { title: 'List API endpoints', readOnlyHint: true, openWorldHint: false },
+            },
+            {
+                name: 'get_api_endpoint_schema',
+                title: 'Get API endpoint schema',
+                description: 'Returns one operation\'s description, whether it changes data, whether it needs an end user, and the JSON Schema of its `args` for invoke_api_endpoint (path and query parameters at the top level, the request body under `body`).',
+                inputSchema: { type: 'object', properties: { endpoint: { type: 'string', description: 'Operation name from list_api_endpoints, for example qbd.invoices.list.' } }, required: ['endpoint'], additionalProperties: false },
+                annotations: { title: 'Get API endpoint schema', readOnlyHint: true, openWorldHint: false },
+            },
+            {
+                name: 'invoke_api_endpoint',
+                title: 'Invoke API endpoint',
+                description: 'Calls one Desktop Accounting API operation and returns its JSON result. Operations under /v1/quickbooks-desktop/ run against the end user\'s live QuickBooks Desktop company file through the Web Connector, so QuickBooks must be open on that computer. Writes create, change, delete or void real accounting records: confirm with the user before every write. Lists return one page; pass `cursor` from `nextCursor` for the next. Never repeat a write whose outcome is unknown with a new idempotency key.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        endpoint: { type: 'string', description: 'Operation name, for example qbd.invoices.list.' },
+                        args: { type: 'object', description: 'Arguments as described by get_api_endpoint_schema: path and query parameters at the top level, the JSON body under `body`.', additionalProperties: true },
+                        end_user_id: END_USER_ID,
+                        idempotency_key: IDEMPOTENCY_KEY,
+                        fields: FIELDS,
+                    },
+                    required: ['endpoint'],
+                    additionalProperties: false,
+                },
+                annotations: { title: 'Invoke API endpoint', readOnlyHint: false, destructiveHint: !this.opts.readOnly, idempotentHint: false, openWorldHint: true },
+            },
+            {
+                name: 'search_docs',
+                title: 'Search the documentation',
+                description: 'Searches the Desktop Accounting API documentation (guides, concepts, error codes, QuickBooks Desktop behavior, end-user help) and returns the best matching sections with their URLs.',
+                inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'What to look for, for example "idempotency", "QBD_MODAL_DIALOG_OPEN", "sales tax".' }, limit: { type: 'integer', minimum: 1, maximum: 10, description: 'Sections to return (default 4).' } }, required: ['query'], additionalProperties: false },
+                annotations: { title: 'Search the documentation', readOnlyHint: true, openWorldHint: true },
+            },
+        ];
+        for (const e of this.perEndpoint.values())
+            tools.push(endpointTool(this.opts.catalog, e));
+        return tools;
+    }
+    async call(name, args = {}) {
+        try {
+            switch (name) {
+                case 'list_end_users':
+                    return await this.listEndUsers(args);
+                case 'list_api_endpoints':
+                    return this.listEndpoints(args);
+                case 'get_api_endpoint_schema':
+                    return this.endpointSchema(args);
+                case 'invoke_api_endpoint': {
+                    const e = this.resolve(args.endpoint);
+                    if (typeof e === 'string')
+                        return text(e, true);
+                    const callArgs = args.args === undefined ? {} : args.args;
+                    if (!callArgs || typeof callArgs !== 'object' || Array.isArray(callArgs))
+                        return text('`args` must be an object.', true);
+                    return await this.invoke(e, callArgs, args);
+                }
+                case 'search_docs':
+                    return await this.searchDocs(args);
+                default: {
+                    const e = this.perEndpoint.get(name);
+                    if (!e)
+                        return text(`Unknown tool ${name}.`, true);
+                    const { end_user_id, idempotency_key, fields, ...rest } = args;
+                    return await this.invoke(e, rest, { end_user_id, idempotency_key, fields });
+                }
+            }
+        }
+        catch (err) {
+            return text(`Tool ${name} failed: ${err instanceof Error ? err.message : String(err)}`, true);
+        }
+    }
+    resolve(endpoint) {
+        if (typeof endpoint !== 'string' || !endpoint)
+            return '`endpoint` is required: an operation name from list_api_endpoints.';
+        const e = this.byName.get(endpoint) ?? this.byName.get(endpoint.replace(/_/g, '.')) ?? [...this.byName.values()].find((x) => toolName(x.name) === endpoint);
+        if (e)
+            return e;
+        const hidden = this.opts.catalog.endpoints.find((x) => x.name === endpoint);
+        if (hidden)
+            return `${endpoint} changes data, and this MCP connection is read-only. Ask the user to make this change themselves, or to connect with a full-access key and without read_only.`;
+        const close = [...this.byName.keys()].filter((n) => n.includes(endpoint.split('.').pop() ?? endpoint)).slice(0, 8);
+        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 group = args.group ? slug(String(args.group)) : '';
+        const kind = args.kind === 'read' || args.kind === 'write' ? args.kind : 'all';
+        const rows = [];
+        for (const e of this.byName.values()) {
+            if (group && slug(e.group) !== group && slug(e.tag) !== group)
+                continue;
+            if (kind === 'read' && e.write)
+                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 });
+        }
+        rows.sort((a, b) => b.score - a.score);
+        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')}`);
+    }
+    endpointSchema(args) {
+        const e = this.resolve(args.endpoint);
+        if (typeof e === 'string')
+            return text(e, true);
+        const out = {
+            endpoint: e.name,
+            method: e.method,
+            path: e.path,
+            resource: e.tag,
+            summary: e.summary,
+            description: e.description,
+            changesData: e.write,
+            requiresEndUser: e.endUser,
+            acceptsIdempotencyKey: e.idempotent,
+            args: endpointArgsSchema(this.opts.catalog, e),
+        };
+        return text(JSON.stringify(out));
+    }
+    headers() {
+        const h = { Accept: 'application/json', ...(this.opts.apiHeaders ?? {}) };
+        if (this.opts.apiKey)
+            h.Authorization = `Bearer ${this.opts.apiKey}`;
+        if (this.opts.userAgent)
+            h['User-Agent'] = this.opts.userAgent;
+        return h;
+    }
+    keyProblem() {
+        const k = this.opts.apiKey;
+        if (!k)
+            return 'No secret key reached the MCP server. Send `Authorization: Bearer sk_...` (hosted server) or set DAAPI_SECRET_KEY (local server). Create keys in the dashboard under API keys.';
+        if (!isValidSecretKey(k))
+            return `The secret key ${maskKey(k)} is malformed (wrong prefix, length or checksum). Copy it again from the dashboard; secret keys look like sk_live_ or sk_test_ followed by 40 letters and digits.`;
+        return null;
+    }
+    async request(method, path, query, body, extra) {
+        const url = `${this.opts.baseUrl.replace(/\/$/, '')}${path}${query && [...query].length ? `?${query}` : ''}`;
+        const headers = { ...this.headers(), ...extra };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const res = await (this.opts.fetch ?? fetch)(url, { method, headers, ...(body !== undefined ? { body: JSON.stringify(body) } : {}), signal: AbortSignal.timeout(130_000) });
+        const raw = await res.text();
+        let json = undefined;
+        try {
+            json = raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            json = undefined;
+        }
+        return { status: res.status, headers: res.headers, json, raw };
+    }
+    async listEndUsers(args) {
+        const problem = this.keyProblem();
+        if (problem)
+            return text(problem, true);
+        const search = String(args.search ?? '').toLowerCase();
+        const rows = [];
+        let cursor = null;
+        for (let page = 0; page < 10; page++) {
+            const q = new URLSearchParams({ limit: '100' });
+            if (cursor)
+                q.set('cursor', cursor);
+            const r = await this.request('GET', '/v1/end-users', q, undefined, {});
+            if (r.status !== 200)
+                return this.errorResult(r, null, null);
+            const body = r.json;
+            for (const eu of body.data) {
+                const conn = eu.integrationConnections?.[0];
+                const file = conn?.companyFile;
+                const row = {
+                    id: eu.id,
+                    companyName: eu.companyName,
+                    sourceId: eu.sourceId,
+                    connection: conn ? { status: conn.status, statusReason: conn.statusReason, lastHeartbeatAt: conn.lastHeartbeatAt, quickbooksCompany: file?.companyName ?? null, product: file?.product ?? null } : null,
+                };
+                if (search && !JSON.stringify([eu.companyName, eu.sourceId, eu.email, file?.companyName]).toLowerCase().includes(search))
+                    continue;
+                rows.push(row);
+            }
+            cursor = body.nextCursor;
+            if (!cursor)
+                break;
+        }
+        const note = this.opts.endUserId ? ` Default end user for this connection: ${this.opts.endUserId}.` : '';
+        return text(`${rows.length} end user${rows.length === 1 ? '' : 's'}. Connection status "online" means QuickBooks requests can run now.${note}\n${JSON.stringify(rows)}`);
+    }
+    async invoke(e, args, control) {
+        if (this.opts.readOnly && e.write)
+            return text(`${e.name} changes data, and this MCP connection is read-only.`, true);
+        const problem = this.keyProblem();
+        if (problem)
+            return text(problem, true);
+        let path = e.path;
+        for (const p of e.pathParams) {
+            const v = args[p.name];
+            if (v === undefined || v === null || v === '')
+                return text(`Missing required path parameter "${p.name}" for ${e.name}.`, true);
+            path = path.replace(`{${p.name}}`, encodeURIComponent(String(v)));
+        }
+        const query = new URLSearchParams();
+        const known = new Set([...e.pathParams.map((p) => p.name), ...e.queryParams.map((p) => p.name), ...(e.body ? ['body'] : [])]);
+        const unknown = Object.keys(args).filter((k) => !known.has(k));
+        if (unknown.length)
+            return text(`Unknown argument${unknown.length > 1 ? 's' : ''} for ${e.name}: ${unknown.join(', ')}. ${e.body && unknown.length ? 'Put request body fields under `body`. ' : ''}Call get_api_endpoint_schema for the accepted arguments.`, true);
+        for (const p of e.queryParams) {
+            const v = args[p.name];
+            if (v === undefined || v === null)
+                continue;
+            for (const item of Array.isArray(v) ? v : [v])
+                query.append(p.name, typeof item === 'object' ? JSON.stringify(item) : String(item));
+        }
+        const extra = {};
+        const endUser = typeof control.end_user_id === 'string' && control.end_user_id ? control.end_user_id : this.opts.endUserId;
+        if (e.endUser) {
+            if (!endUser)
+                return text(`${e.name} runs against an end user's QuickBooks company file. Pass end_user_id (call list_end_users to find it).`, true);
+            extra['Daapi-End-User-Id'] = endUser;
+        }
+        let idempotencyKey = null;
+        if (e.idempotent) {
+            idempotencyKey = typeof control.idempotency_key === 'string' && control.idempotency_key ? control.idempotency_key : crypto.randomUUID();
+            extra['Idempotency-Key'] = idempotencyKey;
+        }
+        const body = e.body ? args.body : undefined;
+        if (e.body?.required && body === undefined)
+            return text(`${e.name} needs a JSON \`body\`. Call get_api_endpoint_schema for its fields.`, true);
+        let r;
+        try {
+            r = await this.request(e.method, path, query, body, extra);
+        }
+        catch (err) {
+            const why = err instanceof Error ? err.message : String(err);
+            if (!e.write)
+                return text(`The request to ${e.name} failed before a response arrived (${why}). It is safe to try again.`, true);
+            return text(`The connection to the API failed while sending ${e.name} (${why}), so it is unknown whether the write happened. Do not send it with a new idempotency key. To find out, repeat this exact call with idempotency_key "${idempotencyKey}": the API then returns the original result instead of writing twice.`, true);
+        }
+        if (r.status >= 200 && r.status < 300) {
+            const requestId = r.headers.get('Daapi-Request-Id');
+            let result = r.json === undefined ? r.raw : r.json;
+            if (Array.isArray(control.fields) && control.fields.length)
+                result = project(result, control.fields.map(String));
+            const meta = [`${e.method} ${e.path} -> ${r.status}`, requestId ? `requestId ${requestId}` : '', idempotencyKey ? `idempotency_key ${idempotencyKey}` : '', r.headers.get('Daapi-Idempotent-Replayed') === 'true' ? 'replayed the original result (no second write)' : ''].filter(Boolean).join('; ');
+            return text(`${meta}\n${this.fit(result)}`);
+        }
+        return this.errorResult(r, e, idempotencyKey);
+    }
+    /** Serializes a result within maxResultChars, cutting list pages rather than JSON text. */
+    fit(result) {
+        const max = this.opts.maxResultChars ?? 80_000;
+        const s = typeof result === 'string' ? result : JSON.stringify(result);
+        if (s.length <= max)
+            return s;
+        const list = result;
+        if (list && typeof list === 'object' && Array.isArray(list.data)) {
+            let n = list.data.length;
+            let out = s;
+            while (n > 1 && out.length > max) {
+                n = Math.max(1, Math.floor(n * (max / out.length) * 0.95));
+                out = JSON.stringify({ ...list, data: list.data.slice(0, n) });
+            }
+            return `${out}\n[Result cut: showing ${n} of ${list.data.length} items on this page. Ask for a smaller \`limit\`, or pass \`fields\` to return only the fields you need.]`;
+        }
+        return `${s.slice(0, max)}\n[Result cut at ${max} characters. Pass \`fields\` to return only the fields you need.]`;
+    }
+    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);
+        const guidance = [];
+        const outcome = err.outcome;
+        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 (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 };
+        for (const k of keep)
+            if (err[k] !== undefined && err[k] !== null && !(k === 'details' && Object.keys(err[k]).length === 0))
+                slim[k] = err[k];
+        return text(`${JSON.stringify(slim)}${guidance.length ? `\n${guidance.join(' ')}` : ''}`, true);
+    }
+    async searchDocs(args) {
+        const query = String(args.query ?? '').trim();
+        if (!query)
+            return text('`query` is required.', true);
+        const limit = Math.min(10, Math.max(1, Number(args.limit ?? 4) || 4));
+        const pages = await this.docs();
+        const words = query.toLowerCase().split(/[^a-z0-9_]+/).filter((w) => w.length > 1);
+        const scored = pages
+            .map((p) => {
+            const title = p.title.toLowerCase();
+            const body = p.text.toLowerCase();
+            let score = 0;
+            for (const w of words) {
+                if (title.includes(w))
+                    score += 5;
+                let i = body.indexOf(w);
+                let n = 0;
+                while (i >= 0 && n < 20) {
+                    n++;
+                    i = body.indexOf(w, i + w.length);
+                }
+                score += n;
+            }
+            if (body.includes(query.toLowerCase()))
+                score += 10;
+            return { p, score };
+        })
+            .filter((x) => x.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        if (!scored.length)
+            return text(`No documentation section matches "${query}".`);
+        return text(scored.map(({ p }) => `# ${p.title}\nSource: ${p.url}\n\n${excerpt(p.text, words)}`).join('\n\n---\n\n'));
+    }
+    async docs() {
+        if (this.docsCache && Date.now() - this.docsCache.at < 3_600_000)
+            return this.docsCache.pages;
+        const url = this.opts.docsUrl ?? 'https://www.desktopaccountingapi.com/docs/llms-full.txt';
+        const res = await (this.opts.docsFetch ?? fetch)(url, { headers: { Accept: 'text/plain' }, signal: AbortSignal.timeout(20_000) });
+        if (!res.ok)
+            throw new Error(`could not load the documentation (${res.status})`);
+        const pages = splitDocs(await res.text());
+        this.docsCache = { at: Date.now(), pages };
+        return pages;
+    }
+}
+/**
+ * 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 function splitDocs(full) {
+    const pages = [];
+    const lines = full.split('\n');
+    let cur = null;
+    for (let i = 0; i < lines.length; i++) {
+        const h = /^# (.+)$/.exec(lines[i]);
+        const src = h ? /^Source:\s*(https?:\/\/\S+)\s*$/.exec(lines[i + 1] ?? '') : null;
+        if (h && src) {
+            if (cur)
+                pages.push(cur);
+            cur = { title: h[1].trim(), url: src[1], text: '' };
+            i++;
+            continue;
+        }
+        if (cur)
+            cur.text += `${lines[i]}\n`;
+    }
+    if (cur)
+        pages.push(cur);
+    return pages.map((p) => ({ ...p, text: p.text.trim() }));
+}
+function excerpt(body, words, max = 2500) {
+    if (body.length <= max)
+        return body;
+    const lower = body.toLowerCase();
+    const hit = words.map((w) => lower.indexOf(w)).filter((i) => i >= 0).sort((a, b) => a - b)[0] ?? 0;
+    const start = Math.max(0, body.lastIndexOf('\n', Math.max(0, hit - 400)));
+    return `${start > 0 ? '...\n' : ''}${body.slice(start, start + max).trim()}\n...`;
+}
+/** Keeps only the given dot paths of an object, or of each item of a list (`data`). */
+export function project(value, paths) {
+    const pick = (v, segs) => {
+        if (Array.isArray(v))
+            return v.map((x) => pick(x, segs));
+        if (!v || typeof v !== 'object' || !segs.length)
+            return v;
+        const [head, ...rest] = segs;
+        const o = v;
+        if (!(head in o))
+            return undefined;
+        return { [head]: rest.length ? pick(o[head], rest) : o[head] };
+    };
+    const merge = (a, b) => {
+        if (a === undefined)
+            return b;
+        if (b === undefined)
+            return a;
+        if (Array.isArray(a) && Array.isArray(b))
+            return a.map((x, i) => merge(x, b[i]));
+        if (a && b && typeof a === 'object' && typeof b === 'object') {
+            const out = { ...a };
+            for (const [k, v] of Object.entries(b))
+                out[k] = merge(out[k], v);
+            return out;
+        }
+        return b;
+    };
+    const one = (item) => paths.reduce((acc, p) => merge(acc, pick(item, p.split('.'))), undefined) ?? {};
+    const list = value;
+    if (list && typeof list === 'object' && list.objectType === 'list' && Array.isArray(list.data))
+        return { ...list, data: list.data.map(one) };
+    return one(value);
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@desktopaccountingapi/quickbooks-desktop-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "homepage": "https://www.desktopaccountingapi.com/docs/guides/mcp/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DesktopAccountingAPI/quickbooks-desktop-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DesktopAccountingAPI/quickbooks-desktop-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "quickbooks",
+    "quickbooks-desktop",
+    "accounting",
+    "ai",
+    "claude",
+    "desktop-accounting-api"
+  ],
+  "type": "module",
+  "bin": {
+    "quickbooks-desktop-mcp": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepare": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"test/*.test.ts\"",
+    "smoke": "node scripts/smoke.mjs",
+    "pack:check": "node scripts/check-pack.mjs"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@types/node": "24.19.1",
+    "typescript": "7.0.2"
+  }
+}