codecks-mcp

Instructions

Implementation Reference

• src/tools/mutation.ts:182-209 (handler)

  Tool registration and handler for 'archive_card'. Defines input schema (card_id as 36-char UUID), validates the UUID using validateUuid(), calls client.archiveCard(args.card_id), and returns the result formatted with finalizeToolResult().
  server.registerTool( "archive_card", { title: "Archive Card", description: "Archive a card (reversible).", inputSchema: z.object({ card_id: z.string().describe("Full 36-char UUID"), }), }, async (args) => { try { validateUuid(args.card_id); const result = await client.archiveCard(args.card_id); return { content: [{ type: "text", text: JSON.stringify(finalizeToolResult(result)) }], }; } catch (err) { return { content: [ { type: "text", text: JSON.stringify(finalizeToolResult(handleError(err))), }, ], }; } }, );
• src/client.ts:458-464 (handler)

  Client method that implements the archive logic. Calls the Codecks API via dispatch('cards/update') with visibility set to 'archived' to archive the card.
  async archiveCard(cardId: string): Promise<Record<string, unknown>> { const result = await dispatch("cards/update", { cardId, update: { visibility: "archived" }, }); return { ok: true, card_id: cardId, result }; }
• src/tools/mutation.ts:187-189 (schema)

  Input schema definition using zod. Requires card_id as a string (full 36-char UUID).
  inputSchema: z.object({ card_id: z.string().describe("Full 36-char UUID"), }),
• src/security.ts:173-180 (helper)

  UUID validation function used by the handler. Ensures the card_id is a valid 36-character UUID with exactly 4 dashes.
  export function validateUuid(value: string, field = "card_id"): string { if (typeof value !== "string" || value.length !== 36 || (value.match(/-/g) ?? []).length !== 4) { throw new CliError( `[ERROR] ${field} must be a full 36-char UUID, got: ${JSON.stringify(value)}`, ); } return value; }
• src/api.ts:194-196 (helper)

  API dispatch function that makes authenticated POST requests to the Codecks API. Used by archiveCard to send the update command.
  export async function dispatch(path: string, data: unknown): Promise<Record<string, unknown>> { return sessionRequest(`/dispatch/${path}`, data); }