add_to_hand
Add project cards to your hand for immediate management by providing their UUIDs. This tool helps organize workflow items for active processing within the Codecks project management system.
Instructions
Add cards to the user's hand.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| card_ids | Yes | Full 36-char UUIDs |
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))), }, ], }; } }, ); }