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