The Game Crafter

Instructions

Implementation Reference

• src/tools/components.ts:5-58 (handler)

  The handler function `handleAddComponentToGame` manages the addition of components to a game, supporting both printable catalog products (via API path) and generic stock parts.

  export function handleAddComponentToGame(client: TgcClient) {
    return async (args: {
      game_id: string;
      part_id: string;
      quantity: number;
      name?: string;
    }): Promise<CallToolResult> => {
      // Check if part_id is a catalog product identity (printable component)
      const products = await client.getProducts();
      const catalogProduct = products.find((p) => p.identity === args.part_id);
  
      if (catalogProduct && catalogProduct.create_api) {
        // Strip leading /api prefix — the client's base URL already includes it
        const apiPath = catalogProduct.create_api.replace(/^\/api/, "");
        if (apiPath.includes("..") || apiPath.includes("//")) {
          throw new TgcError(
            `Invalid create_api path from catalog: "${catalogProduct.create_api}"`,
            "validation",
          );
        }
        const component = await client.createPrintableComponent(
          apiPath,
          catalogProduct.identity,
          args.game_id,
          args.name,
          args.quantity,
        );
        return {
          content: [
            {
              type: "text",
              text: `Printable component "${catalogProduct.name}" added to game successfully.\n\n${JSON.stringify(component, null, 2)}`,
            },
          ],
        };
      }
  
      // Fall back to stock part via /gamepart
      const part = await client.addGamePart(
        args.game_id,
        args.part_id,
        args.quantity,
        args.name,
      );
      return {
        content: [
          {
            type: "text",
            text: `Component added to game successfully.\n\n${JSON.stringify(part, null, 2)}`,
          },
        ],
      };
    };
  }

• src/schemas/tool-inputs.ts:59-77 (schema)

  Input schema definition for `add_component_to_game`, including validation for game ID, part ID, quantity, and name.

  export const addComponentToGameInput = {
    game_id: safeId.describe("The game ID to add the component to."),
    part_id: safeId.describe(
      "The component identity from the catalog (e.g., 'BridgeDeck', 'SmallTuckBox') or a stock part UUID.",
    ),
    quantity: z
      .number()
      .int()
      .positive()
      .describe(
        "Number of this component to include (e.g., 52 for a deck of cards).",
      ),
    name: z
      .string()
      .trim()
      .max(255)
      .optional()
      .describe("Optional display name for this component within the game (max 255 chars)."),
  };

• src/index.ts:113-119 (registration)

  Tool registration for `add_component_to_game` in the main server entry point, binding the schema and the handler.

  server.registerTool("add_component_to_game", {
    description:
      "Add a printable component (card deck, board, box, etc.) or stock part to a game. Use a catalog identity (e.g., 'BridgeDeck') for printable components, or a stock part UUID. Requires authentication.",
    inputSchema: schemas.addComponentToGameInput,
    annotations: { readOnlyHint: false },
  }, withErrorHandling(handleAddComponentToGame(client)));