codecks-mcp

Instructions

Implementation Reference

• src/tools/hand.ts:72-99 (handler)

  Tool registration and handler for 'add_to_hand'. Registers the MCP tool with title, description, and zod schema (card_ids array). The handler validates UUIDs, calls client.addToHand(), formats the result, and handles errors.

  server.registerTool(
    "add_to_hand",
    {
      title: "Add to Hand",
      description: "Add cards to the user's hand.",
      inputSchema: z.object({
        card_ids: z.array(z.string()).describe("Full 36-char UUIDs"),
      }),
    },
    async (args) => {
      try {
        validateUuidList(args.card_ids);
        const result = await client.addToHand(args.card_ids);
        return {
          content: [{ type: "text", text: JSON.stringify(finalizeToolResult(result)) }],
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(finalizeToolResult(handleError(err))),
            },
          ],
        };
      }
    },
  );

• src/client.ts:359-366 (handler)

  Core implementation of addToHand in CodecksClient class. Iterates through card IDs and dispatches 'hand-cards/add' API call for each, returning success count.

  async addToHand(cardIds: string[]): Promise<Record<string, unknown>> {
    const results = [];
    for (const id of cardIds) {
      const r = await dispatch("hand-cards/add", { cardId: id });
      results.push(r);
    }
    return { ok: true, added: cardIds.length };
  }

• src/tools/hand.ts:77-79 (schema)

  Zod input schema defining the tool's expected input structure - an array of card_ids (strings) described as full 36-char UUIDs.

  inputSchema: z.object({
    card_ids: z.array(z.string()).describe("Full 36-char UUIDs"),
  }),

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

  UUID validation helpers used by the handler. validateUuid checks for 36-char string with 4 hyphens; validateUuidList applies this check to each value in an array.

  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;
  }
  
  export function validateUuidList(values: string[], field = "card_ids"): string[] {
    return values.map((v) => validateUuid(v, field));
  }

• src/tools/hand.ts:39-129 (registration)

  registerHandTools function that exports the registration of all hand-related tools (list_hand, add_to_hand, remove_from_hand) with the MCP server.

  export function registerHandTools(server: McpServer, client: CodecksClient): void {
    server.registerTool(
      "list_hand",
      {
        title: "List Hand",
        description: "List cards in the user's hand (personal work queue), sorted by hand order.",
        inputSchema: z.object({}),
      },
      async () => {
        try {
          const result = await client.listHand();
          const sanitized = result.map((c) => sanitizeCard(slimCard(c)));
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(finalizeToolResult(sanitized)),
              },
            ],
          };
        } catch (err) {
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(finalizeToolResult(handleError(err))),
              },
            ],
          };
        }
      },
    );
  
    server.registerTool(
      "add_to_hand",
      {
        title: "Add to Hand",
        description: "Add cards to the user's hand.",
        inputSchema: z.object({
          card_ids: z.array(z.string()).describe("Full 36-char UUIDs"),
        }),
      },
      async (args) => {
        try {
          validateUuidList(args.card_ids);
          const result = await client.addToHand(args.card_ids);
          return {
            content: [{ type: "text", text: JSON.stringify(finalizeToolResult(result)) }],
          };
        } catch (err) {
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(finalizeToolResult(handleError(err))),
              },
            ],
          };
        }
      },
    );
  
    server.registerTool(
      "remove_from_hand",
      {
        title: "Remove from Hand",
        description: "Remove cards from the user's hand.",
        inputSchema: z.object({
          card_ids: z.array(z.string()).describe("Full 36-char UUIDs"),
        }),
      },
      async (args) => {
        try {
          validateUuidList(args.card_ids);
          const result = await client.removeFromHand(args.card_ids);
          return {
            content: [{ type: "text", text: JSON.stringify(finalizeToolResult(result)) }],
          };
        } catch (err) {
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(finalizeToolResult(handleError(err))),
              },
            ],
          };
        }
      },
    );
  }