codecks-mcp

Instructions

Implementation Reference

• src/tools/mutation.ts:240-268 (registration)

  Tool registration: Registers 'delete_card' MCP tool with title, description, input schema (card_id UUID), and handler that validates the UUID and calls client.deleteCard().

  server.registerTool(
    "delete_card",
    {
      title: "Delete Card",
      description:
        "Permanently delete a card. Cannot be undone — use archive_card if reversibility needed.",
      inputSchema: z.object({
        card_id: z.string().describe("Full 36-char UUID"),
      }),
    },
    async (args) => {
      try {
        validateUuid(args.card_id);
        const result = await client.deleteCard(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:474-477 (handler)

  Client method implementation: deleteCard() dispatches 'cards/remove' action with the cardId to the Codecks API.

  async deleteCard(cardId: string): Promise<Record<string, unknown>> {
    const result = await dispatch("cards/remove", { cardId });
    return { ok: true, card_id: cardId, result };
  }

• src/api.ts:194-196 (helper)

  Dispatch function: Routes API requests to /dispatch/{path} endpoint with POST method.

  export async function dispatch(path: string, data: unknown): Promise<Record<string, unknown>> {
    return sessionRequest(`/dispatch/${path}`, data);
  }

• src/security.ts:173-180 (schema)

  UUID validation helper: Validates that card_id is a 36-character UUID string with exactly 4 hyphens.

  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;
  }