@iflow-mcp/nazarlysyi-brickscope 0.1.0

package/dist/mcp/tools/batchPredict.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { predict } from "../../core/brickognize/client.js";
+import { mapPredictionResult } from "../../core/brickognize/mappers.js";
+import { formatToolError } from "../../core/utils/errors.js";
+import { runWithConcurrencyLimit } from "../../core/concurrency.js";
+import { PREDICT_ENDPOINTS, resolveImage, TOOL_ANNOTATIONS, toolSuccess } from "./shared.js";
+const CONCURRENCY_LIMIT = 5;
+const MAX_BATCH_SIZE = 20;
+async function processSingleImage(imagePath, endpoint, includeRaw) {
+    try {
+        const { blob, filename } = await resolveImage({ imagePath });
+        const raw = await predict(endpoint, blob, filename);
+        const result = mapPredictionResult(raw, includeRaw);
+        return { imagePath, status: "success", result };
+    }
+    catch (err) {
+        return { imagePath, status: "error", error: formatToolError(err) };
+    }
+}
+export function registerBatchIdentifyTool(server) {
+    server.registerTool("brickognize_batch_identify", {
+        title: "Batch Identify LEGO Items",
+        description: "Identify multiple LEGO items from local image files in a single call. " +
+            "Processes all images in parallel and returns an array of results. " +
+            "Use this when the user provides a folder of photos or multiple image paths. " +
+            "Accepts 1–20 image paths per call.\n\n" +
+            "When type='part', color prediction is included automatically in each result's predictedColors field.",
+        inputSchema: {
+            imagePaths: z
+                .array(z.string())
+                .min(1)
+                .max(MAX_BATCH_SIZE)
+                .describe(`Array of absolute paths to local image files (JPEG, PNG, or WebP). Max ${MAX_BATCH_SIZE} images per call.`),
+            type: z
+                .enum(["general", "part", "set", "fig"])
+                .default("part")
+                .describe("Type of identification: 'part' for single bricks/elements, 'set' for assembled sets or boxes, 'fig' for minifigures, 'general' when unknown."),
+            includeRaw: z
+                .boolean()
+                .default(false)
+                .describe("When true, includes the raw Brickognize API response in each result."),
+        },
+        annotations: TOOL_ANNOTATIONS,
+    }, async ({ imagePaths, type, includeRaw }) => {
+        const endpoint = PREDICT_ENDPOINTS[type];
+        const tasks = imagePaths.map((imagePath) => () => processSingleImage(imagePath, endpoint, includeRaw));
+        const results = await runWithConcurrencyLimit(tasks, CONCURRENCY_LIMIT);
+        const succeeded = results.filter((r) => r.status === "success").length;
+        const failed = results.length - succeeded;
+        const summary = `Batch complete: ${succeeded}/${results.length} succeeded` +
+            (failed > 0 ? `, ${failed} failed.` : ".");
+        return toolSuccess(summary, JSON.stringify(results, null, 2));
+    });
+}
+//# sourceMappingURL=batchPredict.js.map

package/dist/mcp/tools/cacheTools.js

@@ -0,0 +1,24 @@
+import { toolError, toolSuccess } from "./shared.js";
+export function registerCacheClearTool(server, cache) {
+    server.registerTool("brickognize_cache_clear", {
+        title: "Clear Rebrickable Cache",
+        description: "Clear the local cache of Rebrickable API responses (part details, set inventories, etc.). " +
+            "Use when you want to force fresh data from Rebrickable, e.g. after a long time or if data looks stale. " +
+            "Returns the number of entries removed.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        try {
+            const count = cache.clear();
+            return toolSuccess(`Cache cleared. ${count} entr${count === 1 ? "y" : "ies"} removed.`);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}
+//# sourceMappingURL=cacheTools.js.map

package/dist/mcp/tools/health.js

@@ -0,0 +1,19 @@
+import { checkHealth } from "../../core/brickognize/client.js";
+import { TOOL_ANNOTATIONS, toolError, toolSuccess } from "./shared.js";
+export function registerHealthTool(server) {
+    server.registerTool("brickognize_health", {
+        title: "Brickognize Health Check",
+        description: "Check whether the Brickognize image recognition API is online and responsive. " +
+            "Call this before recognition if you suspect the service might be down. Takes no parameters.",
+        annotations: TOOL_ANNOTATIONS,
+    }, async () => {
+        try {
+            const health = await checkHealth();
+            return toolSuccess(JSON.stringify(health, null, 2));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}
+//# sourceMappingURL=health.js.map

package/dist/mcp/tools/minifigDetails.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { fetchMinifigDetails, buildMinifigSummary } from "../../core/rebrickable/minifigDetails.js";
+import { TOOL_ANNOTATIONS, toolError, toolSuccess } from "./shared.js";
+export function registerMinifigDetailsTool(server) {
+    server.registerTool("brickognize_minifig_details", {
+        title: "LEGO Minifigure Details",
+        description: "Get detailed information about a LEGO minifigure by its ID: name, parts count, " +
+            "and which sets contain this minifigure. " +
+            "Use after brickognize_identify_fig to enrich results, or directly with a known minifigure ID.\n\n" +
+            'Accepts minifigure IDs like "fig-000001" or set-style IDs.',
+        inputSchema: {
+            minifigId: z.string().describe('LEGO minifigure ID, e.g. "fig-000001".'),
+        },
+        annotations: TOOL_ANNOTATIONS,
+    }, async (input) => {
+        try {
+            const result = await fetchMinifigDetails(input.minifigId);
+            const summary = buildMinifigSummary(result);
+            return toolSuccess(summary, JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}
+//# sourceMappingURL=minifigDetails.js.map

package/dist/mcp/tools/partDetails.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { fetchPartDetails, buildPartSummary, normalizeColorName, matchColorByName, } from "../../core/rebrickable/partDetails.js";
+import { formatToolError } from "../../core/utils/errors.js";
+import { TOOL_ANNOTATIONS, toolError, toolSuccess } from "./shared.js";
+// Re-export for tests
+export { normalizeColorName, matchColorByName, buildPartSummary as buildSingleSummary };
+export function registerPartDetailsTool(server) {
+    server.registerTool("brickognize_part_details", {
+        title: "LEGO Part Details",
+        description: "Get detailed information about a LEGO part by its ID: available colors, " +
+            "and which sets contain this part (appears in). " +
+            "Use after brickognize_identify_part to enrich results, or directly with a known part number.\n\n" +
+            "When colorName is provided (e.g. from predictedColors in identify results), " +
+            "returns sets only for that specific color — much faster and more precise.\n" +
+            "Without colorName, returns sets for the top 5 most popular colors.\n\n" +
+            "For multiple parts at once, use brickognize_batch_part_details instead.",
+        inputSchema: {
+            partId: z.string().describe('LEGO part number, e.g. "3001" for Brick 2x4.'),
+            colorName: z
+                .string()
+                .describe('Optional color name to filter by (e.g. "Black"). ' +
+                "Pass the predicted color name from brickognize_identify_part to get sets for that exact color.")
+                .optional(),
+        },
+        annotations: TOOL_ANNOTATIONS,
+    }, async (input) => {
+        try {
+            const result = await fetchPartDetails(input.partId, input.colorName);
+            const summary = buildPartSummary(result);
+            return toolSuccess(summary, JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}
+export function registerBatchPartDetailsTool(server) {
+    server.registerTool("brickognize_batch_part_details", {
+        title: "Batch LEGO Part Details",
+        description: "Get details for multiple LEGO parts in a single call: colors, and which sets contain each part.\n\n" +
+            "Ideal workflow: call brickognize_batch_identify first, then pass all identified parts " +
+            "with their predicted colors to this tool in one call.\n\n" +
+            "Each entry needs a partId and optional colorName for targeted color lookup. " +
+            "Results are returned in the same order as the input.",
+        inputSchema: {
+            parts: z
+                .array(z.object({
+                partId: z.string().describe("LEGO part number"),
+                colorName: z
+                    .string()
+                    .describe('Color name from predictedColors (e.g. "Black")')
+                    .optional(),
+            }))
+                .min(1)
+                .max(20)
+                .describe("Array of parts to look up. Max 20 per call."),
+        },
+        annotations: TOOL_ANNOTATIONS,
+    }, async ({ parts }) => {
+        try {
+            const results = [];
+            // Process sequentially due to Rebrickable rate limiting (1 req/sec)
+            for (const entry of parts) {
+                try {
+                    const result = await fetchPartDetails(entry.partId, entry.colorName);
+                    results.push({ partId: entry.partId, status: "success", result });
+                }
+                catch (err) {
+                    results.push({ partId: entry.partId, status: "error", error: formatToolError(err) });
+                }
+            }
+            const succeeded = results.filter((r) => r.status === "success").length;
+            const failed = results.length - succeeded;
+            const summary = `Batch part details: ${succeeded}/${results.length} succeeded` +
+                (failed > 0 ? `, ${failed} failed.` : ".");
+            return toolSuccess(summary, JSON.stringify(results, null, 2));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}
+//# sourceMappingURL=partDetails.js.map

package/dist/mcp/tools/predict.js

@@ -0,0 +1,36 @@
+import { predict } from "../../core/brickognize/client.js";
+import { mapPredictionResult } from "../../core/brickognize/mappers.js";
+import { imageInputSchema, PREDICT_ENDPOINTS, resolveImage, TOOL_ANNOTATIONS, toolError, toolSuccess, } from "./shared.js";
+function createPredictTool(server, name, title, description, endpoint) {
+    server.registerTool(name, { title, description, inputSchema: imageInputSchema, annotations: TOOL_ANNOTATIONS }, async (input) => {
+        try {
+            const { blob, filename } = await resolveImage(input);
+            const raw = await predict(endpoint, blob, filename);
+            const result = mapPredictionResult(raw, input.includeRaw);
+            return toolSuccess(result.summary, JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}
+export function registerPredictTools(server) {
+    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_ENDPOINTS.general);
+    createPredictTool(server, "brickognize_identify_part", "Identify LEGO Part", "Identify a specific LEGO part/brick/element from a photograph. " +
+        "Use instead of brickognize_identify when you know the image shows a single LEGO piece for more accurate results.\n\n" +
+        "Provide imagePath — absolute path to a local image file (JPEG, PNG, or WebP).\n" +
+        "Automatically detects the part's color (returned in predictedColors).\n" +
+        "Returns matched parts with IDs, names, confidence scores, predicted colors, and links.", PREDICT_ENDPOINTS.part);
+    createPredictTool(server, "brickognize_identify_set", "Identify LEGO Set", "Identify a LEGO set from a photograph of its box, assembled model, or instructions. " +
+        "Use instead of brickognize_identify when you know the image shows a LEGO set.\n\n" +
+        "Provide imagePath — absolute path to a local image file (JPEG, PNG, or WebP).\n" +
+        "Returns matched sets with set numbers, names, confidence scores, and links.", PREDICT_ENDPOINTS.set);
+    createPredictTool(server, "brickognize_identify_fig", "Identify LEGO Minifigure", "Identify a LEGO minifigure from a photograph. " +
+        "Use instead of brickognize_identify when you know the image shows a minifigure.\n\n" +
+        "Provide imagePath — absolute path to a local image file (JPEG, PNG, or WebP).\n" +
+        "Returns matched minifigures with IDs, names, confidence scores, and links.", PREDICT_ENDPOINTS.fig);
+}
+//# sourceMappingURL=predict.js.map

package/dist/mcp/tools/setDetails.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { fetchSetDetails, buildSetSummary, normalizeSetNum, } from "../../core/rebrickable/setDetails.js";
+import { TOOL_ANNOTATIONS, toolError, toolSuccess } from "./shared.js";
+// Re-export for tests
+export { normalizeSetNum };
+export function registerSetDetailsTool(server) {
+    server.registerTool("brickognize_set_details", {
+        title: "LEGO Set Details",
+        description: "Get detailed information about a LEGO set by its number: year, theme, piece count, " +
+            "and full parts inventory. " +
+            "Use after brickognize_identify_set to enrich results, or directly with a known set number.\n\n" +
+            'The "-1" suffix is added automatically if missing (e.g. "75192" → "75192-1").',
+        inputSchema: {
+            setId: z
+                .string()
+                .describe('LEGO set number, e.g. "75192-1" or "75192". The "-1" suffix is added automatically.'),
+        },
+        annotations: TOOL_ANNOTATIONS,
+    }, async (input) => {
+        try {
+            const result = await fetchSetDetails(input.setId);
+            const summary = buildSetSummary(result);
+            return toolSuccess(summary, JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+}
+//# sourceMappingURL=setDetails.js.map

package/dist/mcp/tools/shared.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { formatToolError } from "../../core/utils/errors.js";
+export { PREDICT_ENDPOINTS, resolveImage } from "../../core/image.js";
+/** Build a successful tool response with one or more text content blocks. */
+export function toolSuccess(...texts) {
+    return { content: texts.map((text) => ({ type: "text", text })) };
+}
+/** Build an error tool response from a caught exception. */
+export function toolError(error) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: formatToolError(error) }],
+    };
+}
+export const TOOL_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export const imageInputSchema = {
+    imagePath: z.string().describe("Absolute path to a local image file (JPEG, PNG, or WebP)."),
+    includeRaw: z
+        .boolean()
+        .describe("When true, includes the raw Brickognize API response alongside formatted results. Useful for debugging.")
+        .default(false),
+};
+//# sourceMappingURL=shared.js.map

package/package.json

@@ -0,0 +1 @@
+{"name": "@iflow-mcp/nazarlysyi-brickscope", "version": "0.1.0", "description": "CLI and MCP server for LEGO recognition — identify parts, sets, and minifigures from images", "type": "module", "main": "dist/mcp/index.js", "bin": {"iflow-mcp-nazarlysyi-brickscope": "dist/cli/index.js"}, "files": ["dist/**/*.js", "README.md", "LICENSE"], "scripts": {"build": "tsc", "start": "node dist/cli/index.js", "start:mcp": "node dist/mcp/index.js", "dev": "tsc --watch", "test": "vitest run", "test:watch": "vitest", "lint": "eslint src/", "lint:fix": "eslint src/ --fix", "format": "prettier --write .", "format:check": "prettier --check ."}, "keywords": ["mcp", "lego", "brickscope", "brickognize", "image-recognition", "cli", "brick", "rebrickable"], "license": "MIT", "dependencies": {"@modelcontextprotocol/sdk": "^1.27.1", "better-sqlite3": "^9.6.0", "commander": "^14.0.3", "zod": "^3.24.0"}, "devDependencies": {"@eslint/js": "^10.0.1", "@types/better-sqlite3": "^7.6.13", "@types/node": "^22.0.0", "eslint": "^10.0.3", "eslint-config-prettier": "^10.1.8", "prettier": "^3.8.1", "typescript": "^5.7.0", "typescript-eslint": "^8.57.1", "vitest": "^4.1.1"}, "engines": {"node": ">=18.0.0"}}