creator-research-mcp: Skill for Claude Code

Adding an MCP tool to creator-research-mcp

Read AGENTS.md first — this is the step-by-step recipe for its "MCP tool design conventions" section and its non-negotiable principles (client-reasoning only, no shared infra, lightweight, never fabricate, English only). Don't build anything here that contradicts that file; if it seems like it might, stop and ask the user.

This applies regardless of which AI tool or agent you're using — Claude Code, Cursor, Codex, Copilot, or a human contributor reading it directly.

1. Decide where the logic lives

• Pure, testable transformation (stats, clustering, text parsing) → a new file in packages/core/src/domain/, exported from packages/core/src/index.ts. No I/O in this layer.
• Fetching from a platform → packages/providers/src/, implementing (a subset of) the ContentProvider interface from packages/core/src/ports/provider.ts.
• The MCP tool itself → apps/mcp-server/src/tools/<name>.ts, registered in apps/mcp-server/src/server.ts.

Look at apps/mcp-server/src/tools/retention.ts (joins two existing data sources deterministically) and apps/mcp-server/src/tools/content-ideas.ts (fetches + reuses a cached repository + calls into a packages/core pure function) as the two reference shapes for a new tool — most new tools look like one of these two.

2. Write the tool

• server.registerTool("tool_name", { title, description, inputSchema }, handler).
• Name: snake_case, verb_noun, under 64 chars.
• inputSchema: Zod object, every non-obvious field gets .describe(...).
• description: state the data source, what the tool does NOT do, and any usage hint the model needs at decision time (see get_transcript's note about grounding scripts in the creator's real voice for the pattern).
• Set annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true } unless the tool genuinely isn't read-only (nothing in this repo currently isn't).
• Errors: return { error: "<code>", message: "<human-readable reason>" } as the JSON payload for expected failures (unsupported source, missing data, provider failure) instead of throwing. Reserve throwing/rejecting for genuine programming errors.
• Never compute a metric you can't be sure of — return null for that field and push a plain-English reason onto a limitations: string[] array in the payload instead.
• If a repository/cache already holds the data (check content.findIdByHash + the relevant *Repository.getForItem/get* method in packages/db/src/repositories.ts), reuse it instead of refetching.