@withpica/mcp-server/dist/resources/agent-guide.d.ts

MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog

/**
 * ADR-214 — workflow narrative for agents.
 *
 * Two markdown BUILDERS. ResourceRegistry serves buildAgentGuideLobby() when
 * config.lobbyMode || !pica, buildAgentGuideAuthenticated() otherwise.
 *
 * Nothing here is a literal, because a literal rots: this file claimed
 * "~232 tools" on 2026-08-24 while ToolRegistry.listTools() returned 329, and
 * the lobby half said "three tools are available" and listed all three by name
 * while the HTTP lobby exposes exactly ONE (the sign-in pair is
 * `audiences: ["stdio"]`). Counts AND names are parameters, supplied by the
 * transport that knows what its own caller can reach. Enforced by
 * src/__tests__/resources/agent-guide.test.ts.
 *
 * Tool sequences are verbatim from ADR-214 Decision section "Top
 * workflows" — audit-verified 2026-04-30 against the live ToolRegistry.
 *
 * Edits to this file are linted by scripts/lint-agent-guide.ts: every
 * `pica_*` token must resolve to a real tool in ToolRegistry.
 */
/**
 * The signed-in agent guide.
 *
 * @param toolCount MUST be **the number of catalogue tools THIS caller can
 *   reach, excluding deprecated aliases**. The two transports compute that
 *   differently and both are correct:
 *
 *   - **stdio / any flat surface** — `ToolRegistry.listTools().length`, which
 *     already drops aliases. This is the definition `MCP_TOOL_COUNT` in
 *     `lib/constants/mcp-surface.ts` uses.
 *   - **layered HTTP (`/api/mcp`, the connector default)** — the
 *     scope-filtered allowed set, alias names removed
 *     (`app/api/mcp/route.ts`, `catalogueToolCount`). `listTools()` is the
 *     wrong source there: under layered discovery it returns only the
 *     meta-tools, and the guide would announce that handful while the whole
 *     catalogue is reachable by name and through `pica_execute`.
 *
 *   Do NOT pass a literal, a frozen constant, or a raw
 *   `allDefinitions().length` — the last one counts deprecated aliases, which
 *   are hidden from every listing the caller can see, so the guide would
 *   promise tools the agent cannot find. `route.test.ts` ("agent guide")
 *   asserts the route passes a computed, alias-free count.
 */
export declare function buildAgentGuideAuthenticated(toolCount: number): string;
/**
 * The lobby guide, served when there is no authenticated client.
 *
 * @param lobbyToolNames The tools THIS caller can actually call right now, in
 *   the order they should be read. Names, not a count: the two transports
 *   expose different sets. stdio lists all three registered lobby tools;
 *   the HTTP lobby (`app/api/mcp/route.ts`, `lobbyToolNames`) filters to
 *   `audiences ∋ "lobby"` and only `pica_signup_start` declares it, so the
 *   sign-in pair is not callable there. The guide previously hardcoded
 *   "three tools" plus all three names, so two thirds of the HTTP lobby's
 *   instructions named tools that would be refused.
 * @param unlockedToolCount The count of catalogue tools an AUTHENTICATED
 *   client would reach — the sentence it lands in is "what unlocks after
 *   sign-in", so it is deliberately NOT `lobbyToolNames.length`.
 */
export declare function buildAgentGuideLobby(lobbyToolNames: string[], unlockedToolCount: number): string;
//# sourceMappingURL=agent-guide.d.ts.map