@countfinancial/cli 0.1.6 → 0.2.1

package/dist/commands/setup.command.d.ts

@@ -0,0 +1,11 @@
+interface RunSetupCommandParams {
+    profileName?: string;
+    skipLogin?: boolean;
+    skipInstall?: boolean;
+    nonInteractive?: boolean;
+    clientId?: string;
+    clientSecret?: string;
+    apiBaseUrl?: string;
+}
+export declare function runSetupCommand(params?: RunSetupCommandParams): Promise<number>;
+export {};

package/dist/commands/setup.command.js

@@ -0,0 +1,85 @@
+import { DEFAULT_API_BASE_URL, DEFAULT_CALLBACK_HOST, DEFAULT_CALLBACK_PATH, DEFAULT_CALLBACK_PORT, PARTNERS_PORTAL_URL, } from '../constants.js';
+import { runDoctorCommand } from './doctor.command.js';
+import { runInitCommand } from './init.command.js';
+import { runLoginCommand } from './login.command.js';
+import { runMcpInstallCommand } from './mcpInstall.command.js';
+import { getConfigFilePath, loadCredentials } from '../services/credentialStore.service.js';
+import { DEFAULT_PROFILE_NAME, ensureProfileDirectory, setActiveProfileName, } from '../services/profileStore.service.js';
+import { createPromptInterface, promptChoice, promptLine, promptYesNo, } from '../services/setupPrompt.service.js';
+export async function runSetupCommand(params = {}) {
+    const readlineInterface = createPromptInterface();
+    try {
+        process.stdout.write('COUNT CLI setup\n');
+        process.stdout.write('This wizard saves partner credentials, signs you in, installs MCP config, and runs health checks.\n\n');
+        const profileName = params.profileName ??
+            (params.nonInteractive
+                ? DEFAULT_PROFILE_NAME
+                : await promptLine({
+                    readlineInterface,
+                    question: 'Profile name',
+                    defaultValue: DEFAULT_PROFILE_NAME,
+                }));
+        await ensureProfileDirectory({ profileName });
+        await setActiveProfileName({ profileName });
+        const existingCredentials = await loadCredentials({ profileName });
+        let clientId = params.clientId ?? existingCredentials?.clientId;
+        let clientSecret = params.clientSecret ?? existingCredentials?.clientSecret;
+        let apiBaseUrl = params.apiBaseUrl ?? existingCredentials?.apiBaseUrl ?? DEFAULT_API_BASE_URL;
+        if (!clientId || !clientSecret) {
+            if (params.nonInteractive) {
+                throw new Error('Partner credentials are required. Pass --client-id and --client-secret for non-interactive setup.');
+            }
+            process.stdout.write(`Create a partner app at ${PARTNERS_PORTAL_URL} if you have not already.\n\n`);
+            clientId = await promptLine({ readlineInterface, question: 'Partner client ID' });
+            clientSecret = await promptLine({ readlineInterface, question: 'Partner client secret' });
+            apiBaseUrl = await promptLine({
+                readlineInterface,
+                question: 'API base URL',
+                defaultValue: apiBaseUrl,
+            });
+        }
+        if (!clientId || !clientSecret) {
+            throw new Error('Partner client ID and client secret are required.');
+        }
+        await runInitCommand({
+            clientId,
+            clientSecret,
+            apiBaseUrl,
+            profileName,
+        });
+        const redirectUri = `http://${DEFAULT_CALLBACK_HOST}:${DEFAULT_CALLBACK_PORT}${DEFAULT_CALLBACK_PATH}`;
+        process.stdout.write(`\nEnsure this redirect URI is registered on your partner app:\n  ${redirectUri}\n\n`);
+        const shouldLogin = !params.skipLogin &&
+            (params.nonInteractive
+                ? !(await loadCredentials({ profileName }))?.accessToken
+                : await promptYesNo({
+                    readlineInterface,
+                    question: 'Sign in to COUNT now?',
+                    defaultYes: true,
+                }));
+        if (shouldLogin) {
+            await runLoginCommand({ profileName });
+        }
+        if (!params.skipInstall && !params.nonInteractive) {
+            const installChoice = await promptChoice({
+                readlineInterface,
+                question: 'Install MCP config for',
+                choices: ['skip', 'cursor', 'claude-code', 'claude-desktop', 'all'],
+                defaultChoice: 'cursor',
+            });
+            if (installChoice !== 'skip') {
+                await runMcpInstallCommand({ target: installChoice });
+            }
+        }
+        process.stdout.write('\nRunning health checks...\n\n');
+        const doctorExitCode = await runDoctorCommand({ profileName });
+        process.stdout.write(`\nSetup complete for profile "${profileName}".\n`);
+        process.stdout.write(`Credentials: ${getConfigFilePath({ profileName })}\n`);
+        process.stdout.write('Run `count mcp` to start the local MCP server.\n');
+        return doctorExitCode;
+    }
+    finally {
+        readlineInterface.close();
+    }
+}
+//# sourceMappingURL=setup.command.js.map

package/dist/commands/setup.command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.command.js","sourceRoot":"","sources":["../../src/commands/setup.command.ts"],"names":[],"mappings":"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"}

package/dist/commands/status.command.d.ts

@@ -1 +1,6 @@
-export declare function runStatusCommand(): Promise<void>;
+interface RunStatusCommandParams {
+    profileName?: string;
+    json?: boolean;
+}
+export declare function runStatusCommand(params?: RunStatusCommandParams): Promise<void>;
+export {};

package/dist/commands/status.command.js

@@ -1,13 +1,16 @@
 import { getConfigFilePath, loadCredentials } from '../services/credentialStore.service.js';
-export async function runStatusCommand() {
-    const credentials = await loadCredentials();
-    const configFilePath = getConfigFilePath();
+import { getActiveProfileName } from '../services/profileStore.service.js';
+export async function runStatusCommand(params = {}) {
+    const credentials = await loadCredentials({ profileName: params.profileName });
+    const configFilePath = getConfigFilePath({ profileName: params.profileName });
+    const activeProfileName = await getActiveProfileName();
     if (!credentials) {
         process.stdout.write(`No credentials file at ${configFilePath}\n`);
-        process.stdout.write('Run `count init` then `count login`.\n');
+        process.stdout.write('Run `count init` then `count login`, or run `count setup`.\n');
         return;
     }
     const status = {
+        activeProfile: params.profileName ?? activeProfileName,
         configFilePath,
         apiBaseUrl: credentials.apiBaseUrl,
         hasClientId: Boolean(credentials.clientId),

package/dist/commands/status.command.js.map

@@ -1 +1 @@
-{"version":3,"file":"status.command.js","sourceRoot":"","sources":["../../src/commands/status.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAE5F,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,WAAW,GAAG,MAAM,eAAe,EAAE,CAAC;IAC5C,MAAM,cAAc,GAAG,iBAAiB,EAAE,CAAC;IAE3C,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,cAAc,IAAI,CAAC,CAAC;QACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC/D,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG;QACb,cAAc;QACd,UAAU,EAAE,WAAW,CAAC,UAAU;QAClC,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC;QAC1C,eAAe,EAAE,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC;QAClD,cAAc,EAAE,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC;QAChD,eAAe,EAAE,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC;QAClD,WAAW,EAAE,WAAW,CAAC,WAAW,IAAI,IAAI;QAC5C,aAAa,EAAE,WAAW,CAAC,aAAa,IAAI,IAAI;KACjD,CAAC;IAEF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"status.command.js","sourceRoot":"","sources":["../../src/commands/status.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAO3E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,SAAiC,EAAE;IACxE,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/E,MAAM,cAAc,GAAG,iBAAiB,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9E,MAAM,iBAAiB,GAAG,MAAM,oBAAoB,EAAE,CAAC;IAEvD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,cAAc,IAAI,CAAC,CAAC;QACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8DAA8D,CAAC,CAAC;QACrF,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG;QACb,aAAa,EAAE,MAAM,CAAC,WAAW,IAAI,iBAAiB;QACtD,cAAc;QACd,UAAU,EAAE,WAAW,CAAC,UAAU;QAClC,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC;QAC1C,eAAe,EAAE,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC;QAClD,cAAc,EAAE,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC;QAChD,eAAe,EAAE,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC;QAClD,WAAW,EAAE,WAAW,CAAC,WAAW,IAAI,IAAI;QAC5C,aAAa,EAAE,WAAW,CAAC,aAAa,IAAI,IAAI;KACjD,CAAC;IAEF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/dist/partner-mcp/config.js

@@ -6,7 +6,7 @@ const environmentSchema = z.object({
     COUNT_CLIENT_SECRET: z.string().trim().min(1),
     COUNT_ACCESS_TOKEN: optionalNonEmptyString,
     COUNT_REFRESH_TOKEN: optionalNonEmptyString,
-    COUNT_REQUEST_TIMEOUT_MS: z.coerce.number().int().positive().default(30000),
+    COUNT_REQUEST_TIMEOUT_MS: z.coerce.number().int().positive().default(60000),
     COUNT_CREDENTIALS_FILE: optionalNonEmptyString,
 });
 export function loadConfig(params = {}) {

package/dist/partner-mcp/helpers/mcpKnowledge.helper.d.ts

@@ -0,0 +1,19 @@
+export interface McpKnowledgeTopic {
+    id: string;
+    title: string;
+    summary: string;
+    content: string;
+    relatedTopicIds: string[];
+    keywords: string[];
+}
+export declare const MCP_KNOWLEDGE_TOPICS: McpKnowledgeTopic[];
+interface LookupMcpKnowledgeParams {
+    topic?: string;
+    search?: string;
+}
+interface LookupMcpKnowledgeResult {
+    topics: McpKnowledgeTopic[];
+    availableTopicIds: string[];
+}
+export declare function lookupMcpKnowledge(params: LookupMcpKnowledgeParams): LookupMcpKnowledgeResult;
+export {};

package/dist/partner-mcp/helpers/mcpKnowledge.helper.js

@@ -0,0 +1,293 @@
+export const MCP_KNOWLEDGE_TOPICS = [
+    {
+        id: 'authorize_additional_workspaces',
+        title: 'Can I authorize additional workspaces?',
+        summary: 'Authorized workspaces are fixed at connect time. Disconnect the COUNT connector and reconnect to pick a wider workspace set on the consent screen.',
+        relatedTopicIds: ['reconnect_count_connector', 'multiple_workspaces', 'auth_status_vs_count_app'],
+        keywords: [
+            'workspace',
+            'authorize',
+            'additional',
+            'reconnect',
+            'consent',
+            'scope',
+            'client',
+            'firm',
+            'access',
+        ],
+        content: [
+            'Yes — but only by reconnecting the COUNT MCP connector and completing the consent flow again.',
+            '',
+            'How it works:',
+            '- The workspaces this connection can use are captured when you first connect (OAuth consent).',
+            '- They do NOT update automatically when you later gain access to more client workspaces in the COUNT web app.',
+            '- Refreshing tokens does NOT add workspaces. Call COUNT_auth_status or COUNT_list_workspaces to see the current authorized set for this connection only.',
+            '',
+            'To authorize more workspaces:',
+            '1. Disconnect the COUNT connector in your AI client (see topic reconnect_count_connector).',
+            '2. Connect COUNT again and sign in with your COUNT account.',
+            '3. On the workspace selection step, choose every client workspace you want this connection to access (multiple selections or “all accessible workspaces” when offered).',
+            '4. Finish consent, then call COUNT_list_workspaces to confirm the new authorized list.',
+            '',
+            'Firm staff: you can only authorize workspaces you already have access to in COUNT at reconnect time — the consent screen never grants access beyond your firm membership.',
+        ].join('\n'),
+    },
+    {
+        id: 'reconnect_count_connector',
+        title: 'How do I disconnect and reconnect the COUNT MCP connector?',
+        summary: 'Remove the COUNT connector in your AI app settings, then add it again to run through sign-in and workspace selection.',
+        relatedTopicIds: ['authorize_additional_workspaces', 'multiple_workspaces'],
+        keywords: ['disconnect', 'reconnect', 'connector', 'claude', 'chatgpt', 'oauth', 'integration'],
+        content: [
+            'Claude (claude.ai or Claude Desktop):',
+            '1. Open Settings → Connectors (wording may be “Integrations”).',
+            '2. Find COUNT in the list and disconnect or remove it.',
+            '3. Add / connect COUNT again and complete sign-in when redirected to COUNT.',
+            '4. Select the workspace(s) to authorize, then approve access.',
+            '',
+            'ChatGPT:',
+            '1. Open Settings → Connectors / Apps.',
+            '2. Remove the COUNT connector.',
+            '3. Re-add COUNT and complete the OAuth sign-in and workspace selection flow.',
+            '',
+            'After reconnecting, call COUNT_auth_status and COUNT_list_workspaces before other tools so you know which workspace UUIDs are in scope.',
+            '',
+            'Standalone COUNT CLI MCP (developer token): workspace scope is configured in your environment — reconnecting the hosted connector does not apply.',
+        ].join('\n'),
+    },
+    {
+        id: 'multiple_workspaces',
+        title: 'How do I work with multiple authorized workspaces?',
+        summary: 'Call COUNT_list_workspaces, pass workspace_id on every read/write tool when more than one workspace is authorized, and optionally COUNT_set_active_workspace for session context.',
+        relatedTopicIds: ['authorize_additional_workspaces', 'external_uuids'],
+        keywords: ['workspace_id', 'list_workspaces', 'set_active_workspace', 'multi', 'switch'],
+        content: [
+            'When this connection has more than one authorized workspace:',
+            '- COUNT_list_workspaces — lists every workspace UUID, name, currency, and (for firm connections) whether it is a firm client workspace.',
+            '- COUNT_auth_status — shows authorizedWorkspaces and which workspace is active for echo/context.',
+            '- Pass workspace_id (external COUNT workspace UUID) on every partner read/write tool when multiple workspaces are authorized.',
+            '- COUNT_set_active_workspace — updates the session default for auth_status and the “Workspace:” echo line only; it does NOT replace workspace_id on API calls.',
+            '',
+            'When only one workspace is authorized, workspace_id is optional on partner tools.',
+        ].join('\n'),
+    },
+    {
+        id: 'auth_status_vs_count_app',
+        title: 'Why does auth_status show fewer workspaces than I see in COUNT?',
+        summary: 'auth_status lists workspaces authorized for this MCP connection at consent time, not every workspace visible in the COUNT web app.',
+        relatedTopicIds: ['authorize_additional_workspaces', 'reconnect_count_connector'],
+        keywords: ['auth_status', 'missing', 'workspace', 'token', 'scope'],
+        content: [
+            'COUNT_auth_status and COUNT_list_workspaces reflect this connector’s authorized workspace set, not your full COUNT account access.',
+            '',
+            'Common reasons for a mismatch:',
+            '- You connected before gaining access to additional firm client workspaces → reconnect to expand the set.',
+            '- You selected only a subset on the consent screen → reconnect and select the missing workspaces.',
+            '- You are comparing to workspaces visible in the COUNT web app that were never included in this connection’s consent.',
+            '',
+            'The scope field on auth_status may be null; rely on authorizedWorkspaces / COUNT_list_workspaces as the source of truth for this connection.',
+        ].join('\n'),
+    },
+    {
+        id: 'create_chart_of_accounts_account',
+        title: 'How do I create a new chart-of-accounts account (e.g. credit card)?',
+        summary: 'Call COUNT_list_account_sub_types first, pick the matching sub-type id, then COUNT_create_account. Never guess subTypeId values.',
+        relatedTopicIds: ['external_uuids', 'describe_endpoint'],
+        keywords: [
+            'create account',
+            'chart of accounts',
+            'subTypeId',
+            'sub type',
+            'credit card',
+            'liability',
+            'list_account_sub_types',
+        ],
+        content: [
+            'To create a new account (bank, credit card, expense category, etc.):',
+            '1. COUNT_list_account_sub_types — optional query.type filter (e.g. "Liabilities" for a credit card). Pick the row whose name matches what you need and copy its integer id.',
+            '2. COUNT_create_account — body.name plus body.subTypeId set to that id.',
+            '3. If a similar account already exists, you may instead COUNT_list_accounts with query.type and reuse subType.id from an existing row.',
+            '',
+            'Never guess or sequentially probe subTypeId numbers — they are sparse global ids, not a predictable sequence.',
+            'If create_account fails, tell the user COUNT could not create the account and share requestId when present. Do not quote stack traces, file paths, or internal database fields.',
+        ].join('\n'),
+    },
+    {
+        id: 'partner_error_hygiene',
+        title: 'What should I tell the user when a COUNT tool fails?',
+        summary: 'Use plain business language plus requestId when available. Never expose stack traces, source files, or internal implementation details.',
+        relatedTopicIds: ['describe_endpoint'],
+        keywords: ['error', '500', 'stack', 'internal', 'requestId', 'failure'],
+        content: [
+            'When a COUNT partner or MCP tool returns an error:',
+            '- Tell the user what you were trying to do and that COUNT could not complete it.',
+            '- Include requestId from the error payload when present so support can trace the call.',
+            '- Read _mcpRecoveryHint for suggested next tools (list_account_sub_types, validate_payload, knowledge topics).',
+            '',
+            'Never include in user-visible text:',
+            '- Stack traces or line numbers (e.g. accounts.service.js:141)',
+            '- Source file paths, function names, or ORM/SQL internals',
+            '- Internal database column names (accountTypeId, subTypeId probing commentary, etc.)',
+            '- Narration of your debugging process ("let me probe subtype 14")',
+        ].join('\n'),
+    },
+    {
+        id: 'external_uuids',
+        title: 'Which IDs should I pass to COUNT tools?',
+        summary: 'Always use external COUNT UUIDs from list/get tool results. Never pass internal numeric database ids.',
+        relatedTopicIds: ['report_category_filters', 'describe_endpoint'],
+        keywords: ['uuid', 'id', 'numeric', 'list_accounts', 'partner'],
+        content: [
+            'Partner and MCP tools expose external UUIDs as id in responses.',
+            '- Get UUIDs from the matching COUNT_list_* or COUNT_get_* tool (accounts, customers, vendors, bills, etc.).',
+            '- Pass that UUID as id in path parameters and as vendorUuid, customerUuid, categoryAccountUuid, and similar UUID fields in bodies/queries.',
+            '- Internal numeric ids are workspace-local and are rejected or silently ignored on many partner endpoints.',
+            '',
+            'Before an unfamiliar create/update call, use COUNT_describe_endpoint with the tool name for field-level guidance.',
+        ].join('\n'),
+    },
+    {
+        id: 'report_category_filters',
+        title: 'How do I filter a P&L or report to one expense category?',
+        summary: 'Pass the account UUID from COUNT_list_accounts as categoryAccount or categoryAccountUuid in the report query.',
+        relatedTopicIds: ['external_uuids'],
+        keywords: ['pnl', 'profit', 'loss', 'category', 'shipping', 'freight', 'report', 'filter'],
+        content: [
+            'Use COUNT_generate_profit_and_loss with query filters, not a numeric account id.',
+            '',
+            'Example — spending on “Freight & Courier” for calendar 2025:',
+            '1. COUNT_list_accounts — find the expense account (e.g. Freight & Courier) and copy its id UUID.',
+            '2. COUNT_generate_profit_and_loss with query: { startDate: "2025-01-01", endDate: "2025-12-31", categoryAccount: "<account-uuid>" }.',
+            '',
+            'Aliases accepted: categoryAccount, categoryAccountUuid, categoryAccountUuids (comma-separated).',
+            'Trial balance / balance sheet: use accounts or accountUuids the same way.',
+            'Report filters belong under the top-level query key, not body.',
+        ].join('\n'),
+    },
+    {
+        id: 'bulk_operations',
+        title: 'How should I run bulk imports (transactions, customers, etc.)?',
+        summary: 'Use bulk MCP tools with partial-success envelopes; recommended ~25 rows per call for large historical imports.',
+        relatedTopicIds: ['external_uuids'],
+        keywords: ['bulk', 'batch', 'import', 'migration', 'partial', 'success'],
+        content: [
+            'Bulk tools (COUNT_bulk_create_transactions, COUNT_bulk_create_customers, COUNT_bulk_update_customers, COUNT_bulk_update_budget_cells, etc.) return:',
+            '{ successCount, errorCount, results: [{ index, success, ... | error }] } with HTTP 201 when the batch is accepted.',
+            '',
+            'Best practices:',
+            '- Read errorCount first; retry only rows where success is false.',
+            '- Hard cap: 100 rows per call.',
+            '- Recommended batch size: ~25 rows for large backfills (billing-system migrations) to reduce timeout risk.',
+            '- Each row is isolated — one failure does not roll back other rows in the same batch.',
+            '- Call COUNT_validate_payload before each bulk batch and COUNT_playbooks (migration_import or budget_import) for the full workflow.',
+        ].join('\n'),
+    },
+    {
+        id: 'budget_export_import',
+        title: 'How do I export or import budgets for Excel editing?',
+        summary: 'Use get_budget_grid to export JSON, edit offline, then bulk_update_budget_cells in ~25-row batches on a draft version.',
+        relatedTopicIds: ['bulk_operations', 'external_uuids'],
+        keywords: ['budget', 'excel', 'export', 'import', 'grid', 'forecast'],
+        content: [
+            'Partner budget tools are JSON-only (no CSV upload). Typical Excel round-trip:',
+            '1. COUNT_get_budget_grid with includeActuals=false for budget amounts only.',
+            '2. Edit amounts in Excel externally — keep accountUuid + periodStart + amount columns aligned with the grid.',
+            '3. COUNT_bulk_update_budget_cells on a draft versionNumber (~25 rows per call; hard cap 100).',
+            '4. Optional COUNT_publish_budget when ready.',
+            '',
+            'Rows require accountUuid (from list_accounts / resolve_references) and periodStart (YYYY-MM-DD from grid columns).',
+            'See COUNT_playbooks playbook budget_import for the ordered workflow.',
+        ].join('\n'),
+    },
+    {
+        id: 'legacy_numeric_fields_rejected',
+        title: 'Why were numeric vendorId, tags, or vendors query params rejected?',
+        summary: 'Partner bill and list endpoints require UUID fields (vendorUuid, tagUuids, vendorUuids). Numeric legacy fields return 400, not silent ignore.',
+        relatedTopicIds: ['external_uuids', 'describe_endpoint'],
+        keywords: ['numeric', 'vendorId', 'tags', 'vendors', 'rejected', '400', 'legacy'],
+        content: [
+            'Partner MCP tools expose external UUIDs only. Numeric internal database ids are rejected on many endpoints.',
+            '',
+            'Common 400 cases:',
+            '- Bill list: use query.vendorUuids (comma-separated), not query.vendors.',
+            '- Bill create/update: use vendorUuid, tagUuids, projectUuid — not vendorId, tags, projectId.',
+            '- Line items: use categoryAccountUuid — not categoryAccountId.',
+            '',
+            'Use COUNT_resolve_references to map names to UUIDs, or COUNT_list_* tools to copy id values from responses.',
+            'Call COUNT_validate_payload before bulk imports to catch these issues early.',
+        ].join('\n'),
+    },
+    {
+        id: 'partner_warnings',
+        title: 'What does _partnerWarnings mean on a successful response?',
+        summary: 'Some fields you sent were ignored. Read _partnerWarnings before assuming the update applied every field.',
+        relatedTopicIds: ['describe_endpoint', 'external_uuids'],
+        keywords: ['warnings', 'ignored', 'internal_only', 'unknown_field', 'partnerWarnings'],
+        content: [
+            'Create/update responses may include _partnerWarnings: [{ field, reason, message }].',
+            '',
+            'reason values:',
+            '- internal_only — field is managed by COUNT internally (e.g. billId on transaction update). Use the dedicated tool instead.',
+            '- unknown_field — typo or field not on the model. Call COUNT_describe_endpoint for the tool you used.',
+            '',
+            'HTTP 200 with warnings does NOT mean every field you sent was applied. Always read _partnerWarnings.',
+        ].join('\n'),
+    },
+    {
+        id: 'describe_endpoint',
+        title: 'How do I learn the request shape for a COUNT tool?',
+        summary: 'Call COUNT_describe_endpoint with the exact tool name before unfamiliar create/update operations.',
+        relatedTopicIds: ['external_uuids'],
+        keywords: ['describe', 'documentation', 'schema', 'fields', 'body', 'query'],
+        content: [
+            'COUNT_describe_endpoint returns:',
+            '- Partner API path the tool calls',
+            '- Tool description and readOnly/destructive flags',
+            '- Tips for body vs query placement',
+            '- Link to https://developers.getcount.com/ for canonical field names',
+            '',
+            'COUNT_knowledge (this tool) answers connector and workflow FAQs; COUNT_describe_endpoint answers per-tool API shape questions.',
+            'COUNT_playbooks provides ordered multi-step workflows (bill pay, migration import, month-end review).',
+        ].join('\n'),
+    },
+];
+export function lookupMcpKnowledge(params) {
+    const { topic, search } = params;
+    const availableTopicIds = MCP_KNOWLEDGE_TOPICS.map((_entry) => _entry.id);
+    if (topic && topic.trim() !== '') {
+        const normalizedTopic = topic.trim().toLowerCase();
+        const matchedTopic = MCP_KNOWLEDGE_TOPICS.find((_entry) => _entry.id.toLowerCase() === normalizedTopic || _entry.id.toLowerCase().replace(/_/g, ' ') === normalizedTopic);
+        return {
+            topics: matchedTopic ? [matchedTopic] : [],
+            availableTopicIds,
+        };
+    }
+    if (search && search.trim() !== '') {
+        const normalizedSearch = search.trim().toLowerCase();
+        const matchedTopics = MCP_KNOWLEDGE_TOPICS.filter((_entry) => {
+            const haystack = [
+                _entry.id,
+                _entry.title,
+                _entry.summary,
+                _entry.content,
+                ..._entry.keywords,
+            ]
+                .join(' ')
+                .toLowerCase();
+            return haystack.includes(normalizedSearch);
+        });
+        return { topics: matchedTopics, availableTopicIds };
+    }
+    return {
+        topics: MCP_KNOWLEDGE_TOPICS.map((_entry) => ({
+            id: _entry.id,
+            title: _entry.title,
+            summary: _entry.summary,
+            content: _entry.content,
+            relatedTopicIds: _entry.relatedTopicIds,
+            keywords: _entry.keywords,
+        })),
+        availableTopicIds,
+    };
+}
+//# sourceMappingURL=mcpKnowledge.helper.js.map

package/dist/partner-mcp/helpers/mcpKnowledge.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpKnowledge.helper.js","sourceRoot":"","sources":["../../../src/partner-mcp/helpers/mcpKnowledge.helper.ts"],"names":[],"mappings":"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"}

package/dist/partner-mcp/helpers/mcpPayloadValidation.helper.d.ts

@@ -0,0 +1,42 @@
+import { buildMcpRecoveryHint } from './mcpRecoveryHint.helper.js';
+import type { McpReferenceResolutionPartnerClient } from './mcpReferenceResolution.helper.js';
+export interface McpPayloadValidationIssue {
+    path: string;
+    code: 'missing_required' | 'legacy_numeric_field' | 'invalid_tool' | 'bulk_envelope' | 'reference_not_found';
+    message: string;
+}
+export interface ValidateMcpPayloadParams {
+    toolName: string;
+    body?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    verifyReferences?: boolean;
+    client?: McpReferenceResolutionPartnerClient;
+}
+export interface ValidateMcpPayloadResult {
+    valid: boolean;
+    toolName: string;
+    issueCount: number;
+    issues: McpPayloadValidationIssue[];
+    suggestedPlaybook?: string;
+    _mcpRecoveryHint?: ReturnType<typeof buildMcpRecoveryHint>;
+}
+export declare function validateMcpPayload(params: ValidateMcpPayloadParams): ValidateMcpPayloadResult;
+/** Walk a payload tree and collect string values on UUID-shaped field names for optional existence checks. */
+export declare function collectUuidReferencesFromPayload(params: {
+    body?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+}): Array<{
+    path: string;
+    uuid: string;
+}>;
+interface VerifyUuidReferencesExistParams {
+    client: McpReferenceResolutionPartnerClient;
+    references: Array<{
+        path: string;
+        uuid: string;
+    }>;
+}
+/** Path-aware UUID existence checks using partner routes that actually exist. */
+export declare function verifyUuidReferencesExist(params: VerifyUuidReferencesExistParams): Promise<McpPayloadValidationIssue[]>;
+export declare function validateMcpPayloadAsync(params: ValidateMcpPayloadParams): Promise<ValidateMcpPayloadResult>;
+export {};