codecks-mcp: Skill for Claude Code

codecks-mcp-extend

This skill extends the CodecksMCP server (an MCP that bridges AI assistants to the Codecks task-management API) with new capabilities. It encodes a workflow proven to work for this codebase: research → probe → implement → smoke-test → clean up.

The Codecks API is not exhaustively documented. You will not know the dispatch endpoint payload shapes from training data alone. Discovering them by probing the live API is the core of this workflow — do not skip it and do not guess.

When this skill applies

• The user wants to add a new entity, tool, or capability to this MCP (CRUD for some Codecks model, attaching one entity to another, exposing a Codecks feature, etc.)
• A working .env with CODECKS_AUTH_TOKEN and CODECKS_SUBDOMAIN must exist at the project root — the probe step depends on it. If it's missing, stop and ask the user.

Quick orientation

Read these files first, in order. They establish the patterns you must follow:

• src/codecks/client.ts — the request method. Two modes: request(query) posts a GraphQL-like body to https://api.codecks.io/ for reads; request(payload, endpoint) posts to https://api.codecks.io/dispatch/<endpoint> for actions. Auth headers: X-Account (subdomain), X-Auth-Token. Existing dispatch endpoints used: cards/create, cards/update, decks/create, milestones/create|update|delete.
• src/tools/ToolGroup.ts — the base class. registerTool(name, description, handler, zodSchema, formatter?) is what every tool uses. Errors are caught and returned as text; you do not need to wrap your handler in try/catch.
• src/tools/CardTools.ts — the most complete example. Mirror its patterns for: dynamic Zod schemas from client.context.metadata, splitting/joining card content as ${title}\n\n${description}, conditional spread for optional update fields (...(args.x !== undefined && { x: args.x })).
• src/tools/DeckTools.ts — minimal example. Good template if your entity has just create/list.
• src/tools/MilestoneTools.ts — full CRUD example with a dispatch action endpoint requiring userId, accountId, and a relation array (projectIds).
• src/codecks/entities.ts — where API and MCP-facing types live. Split: CodecksApi<X> for the raw response shape, Codecks<X> for what your tool returns. Const enums (CardStatus, MilestoneColor) are used both as TS types and Zod enums.
• src/codecks/APItypes.ts — response wrapper types per endpoint. Add a list<X>Response, a get<X>Response, and (for dispatch endpoints) an action response shape if it doesn't already exist.
• src/server.ts — register the new ToolGroup here with one new XTools(server, client).register() line.