Brickognize MCP Server

Instructions

Implementation Reference

• src/tools/predict.ts:55-66 (registration)

  The `brickognize_identify` tool is registered using `registerIdentifyTool`, which wraps the `createPredictTool` utility with the `/predict/` endpoint.

  export function registerIdentifyTool(server: McpServer): void {
    createPredictTool(
      server,
      "brickognize_identify",
      "Identify LEGO Item",
      "Identify any LEGO item (part, set, minifigure, or sticker) from a photograph. " +
        "Use this when the item type is unknown or the image may contain multiple types.\n\n" +
        "Provide imagePath — absolute path to a local image file (JPEG, PNG, or WebP).\n" +
        "Returns top matches with confidence scores, IDs, names, categories, and links to BrickLink/BrickOwl.",
      "/predict/",
    );
  }

• src/tools/predict.ts:22-51 (handler)

  The handler for the tool (within `createPredictTool`) processes the input image, calls the Brickognize API using the `predict` function, and maps the result.

  async (input) => {
    try {
      const { blob, filename } = await resolveImage(input);
      const raw = await predict(endpoint, blob, filename);
      const result = mapPredictionResult(raw, input.includeRaw ?? false);
  
      return {
        content: [
          {
            type: "text" as const,
            text: result.summary,
          },
          {
            type: "text" as const,
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        isError: true,
        content: [
          {
            type: "text" as const,
            text: formatToolError(error),
          },
        ],
      };
    }
  },

• src/brickognize/client.ts:24-50 (helper)

  The actual network request to the Brickognize API is performed by this function.

  export async function predict(
    endpoint: string,
    imageBlob: Blob,
    filename: string,
  ): Promise<RawSearchResults> {
    const form = new FormData();
    form.append("query_image", imageBlob, filename);
  
    const res = await fetch(`${BASE_URL}${endpoint}`, {
      method: "POST",
      body: form,
      signal: AbortSignal.timeout(60_000),
    });
  
    if (!res.ok) {
      const body = await res.text();
      throw apiError(res.status, body);
    }
  
    const data = await res.json();
  
    if (!data || typeof data.listing_id !== "string" || !Array.isArray(data.items)) {
      throw unexpectedResponse("missing listing_id or items array");
    }
  
    return data as RawSearchResults;
  }