codecks-mcp

Instructions

Implementation Reference

• src/tools/mutation.ts:18-64 (handler)

  Complete MCP tool registration for 'create_card', including Zod input schema validation (lines 25-34) and the async handler function (lines 36-62) that validates inputs and calls client.createCard()
  export function registerMutationTools(server: McpServer, client: CodecksClient): void { server.registerTool( "create_card", { title: "Create Card", description: "Create a new card. Set deck/project to place it. Use parent to nest as sub-card.", inputSchema: z.object({ title: z.string().describe("Card title (max 500 chars)"), content: z.string().optional().describe("Card body. Use '- []' for checkboxes"), deck: z.string().optional().describe("Destination deck name"), project: z.string().optional(), severity: z.enum(["critical", "high", "low", "null"]).optional(), doc: z.boolean().default(false).describe("True for doc card"), allow_duplicate: z.boolean().default(false), parent: z.string().optional().describe("Parent card UUID for sub-cards"), }), }, async (args) => { try { const title = validateInput(args.title, "title"); const content = args.content ? validateInput(args.content, "content") : undefined; const result = await client.createCard({ title, content, deck: args.deck, project: args.project, severity: args.severity, doc: args.doc, allowDuplicate: args.allow_duplicate, parent: args.parent, }); return { content: [{ type: "text", text: JSON.stringify(finalizeToolResult(result)) }], }; } catch (err) { return { content: [ { type: "text", text: JSON.stringify(finalizeToolResult(handleError(err))), }, ], }; } }, );
• src/client.ts:379-401 (handler)

  Core implementation of createCard method that constructs the payload with title/content, handles severity and doc card type, dispatches to 'cards/create' API endpoint, and returns the created card ID
  async createCard(options: { title: string; content?: string; deck?: string; project?: string; severity?: string; doc?: boolean; allowDuplicate?: boolean; parent?: string; }): Promise<Record<string, unknown>> { const payload: Record<string, unknown> = { content: `# ${options.title}${options.content ? "\n\n" + options.content : ""}`, }; if (options.severity && options.severity !== "null") { payload.severity = options.severity; } if (options.doc) payload.cardType = "doc"; const result = await dispatch("cards/create", payload); const cardId = (result.payload as Record<string, unknown>)?.id ?? result.cardId ?? "unknown"; return { ok: true, card_id: cardId, title: options.title }; }
• src/security.ts:161-171 (helper)

  Input validation helper function used by create_card handler to sanitize text and enforce maximum length limits
  export function validateInput(text: string, field: string): string { if (typeof text !== "string") { throw new CliError(`[ERROR] ${field} must be a string`); } const cleaned = text.replace(CONTROL_RE, ""); const limit = INPUT_LIMITS[field] ?? 50_000; if (cleaned.length > limit) { throw new CliError(`[ERROR] ${field} exceeds maximum length of ${limit} characters`); } return cleaned; }
• src/api.ts:194-196 (helper)

  dispatch function that routes API requests to the backend, used by createCard to send 'cards/create' commands
  export async function dispatch(path: string, data: unknown): Promise<Record<string, unknown>> { return sessionRequest(`/dispatch/${path}`, data); }
• src/contract.ts:56-75 (helper)

  finalizeToolResult helper that normalizes the tool response format, used to format create_card results before returning to MCP client
  export function finalizeToolResult(result: unknown): unknown { if (result !== null && typeof result === "object" && !Array.isArray(result)) { const dict = result as Record<string, unknown>; const normalized = ensureContractDict(dict); if (normalized.ok === false) return normalized; if (config.mcpResponseMode === "envelope") { const data = { ...normalized }; delete data.ok; delete data.schema_version; return { ok: true, schema_version: CONTRACT_SCHEMA_VERSION, data, }; } return normalized; }