@iflow-mcp/nazarlysyi-brickscope 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brickognize MCP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# Brickscope
+
+Identify LEGO parts, sets, and minifigures from images — as a **CLI tool** or an **MCP server** for AI assistants.
+
+Powered by the [Brickognize API](https://api.brickognize.com/docs) and [Rebrickable](https://rebrickable.com/api/).
+
+Huge thanks to [Piotr Rybak](https://brickognize.com/about) for creating the Brickognize service and making LEGO recognition accessible to everyone!
+
+## CLI
+
+```bash
+npm install -g brickscope
+
+brickscope identify photo.jpg --type part
+brickscope part 3001 --color Black
+brickscope set 75192
+brickscope minifig fig-012805
+```
+
+Or run without installing: `npx brickscope identify photo.jpg`
+
+[Full CLI documentation](./docs/cli.md)
+
+## MCP Server
+
+For AI assistants (Claude, Cursor, etc.), add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "brickscope": {
+      "command": "npx",
+      "args": ["-y", "brickscope", "mcp"],
+      "env": {
+        "REBRICKABLE_API_KEY": "your-key-here",
+        "BRICKOGNIZE_CACHE": "sqlite"
+      }
+    }
+  }
+}
+```
+
+[Full MCP documentation](./docs/mcp.md)
+
+## Configuration
+
+### Config file (CLI)
+
+```bash
+brickscope config init
+```
+
+Creates `~/.config/brickscope/config.json` with your Rebrickable API key and cache settings.
+
+### Environment variables
+
+| Variable              | Default | Description                                                                                       |
+| --------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `REBRICKABLE_API_KEY` | —       | Free API key from [rebrickable.com/api](https://rebrickable.com/api/). Required for lookup tools. |
+| `BRICKOGNIZE_CACHE`   | `none`  | Cache mode: `none`, `memory`, or `sqlite`                                                         |
+
+Environment variables take priority over the config file.
+
+## Features
+
+- **Image recognition** — identify parts, sets, minifigures, and stickers from photos
+- **Batch processing** — identify multiple images in parallel
+- **Part lookup** — colors, set appearances via Rebrickable
+- **Set inventory** — full parts list, year, theme, piece count
+- **Minifigure lookup** — details and set appearances
+- **Caching** — in-memory or SQLite cache for Rebrickable API responses
+- **Config file** — save API key and preferences once, use everywhere
+
+## Examples
+
+See the [examples](./examples) folder for prompt templates.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev           # Watch mode
+npm test              # Unit + integration tests
+npm run lint          # ESLint
+npm run format        # Prettier
+```
+
+## License
+
+MIT

package/dist/cli/commands/config.js

@@ -0,0 +1,81 @@
+import { loadConfig, saveConfig, getConfigPath } from "../../core/config.js";
+import * as readline from "node:readline/promises";
+export function registerConfigCommand(program) {
+    const config = program.command("config").description("Manage brickscope configuration");
+    config
+        .command("show")
+        .description("Show current configuration")
+        .action(() => {
+        const cfg = loadConfig();
+        const configPath = getConfigPath();
+        console.log(`Config file: ${configPath}`);
+        console.log("");
+        if (Object.keys(cfg).length === 0) {
+            console.log("No configuration set. Run 'brickscope config init' to set up.");
+            return;
+        }
+        if (cfg.rebrickableApiKey) {
+            const masked = cfg.rebrickableApiKey.slice(0, 4) + "..." + cfg.rebrickableApiKey.slice(-4);
+            console.log(`  rebrickableApiKey: ${masked}`);
+        }
+        if (cfg.cache) {
+            console.log(`  cache: ${cfg.cache}`);
+        }
+    });
+    config
+        .command("path")
+        .description("Print config file location")
+        .action(() => {
+        console.log(getConfigPath());
+    });
+    config
+        .command("set <key> <value>")
+        .description("Set a configuration value (rebrickableApiKey, cache)")
+        .action((key, value) => {
+        const cfg = loadConfig();
+        if (key === "rebrickableApiKey") {
+            cfg.rebrickableApiKey = value;
+        }
+        else if (key === "cache") {
+            if (!["none", "memory", "sqlite"].includes(value)) {
+                console.error(`Invalid cache value "${value}". Valid: none, memory, sqlite`);
+                process.exit(1);
+            }
+            cfg.cache = value;
+        }
+        else {
+            console.error(`Unknown config key "${key}". Valid keys: rebrickableApiKey, cache`);
+            process.exit(1);
+        }
+        saveConfig(cfg);
+        console.log(`Set ${key} = ${key === "rebrickableApiKey" ? "***" : value}`);
+    });
+    config
+        .command("init")
+        .description("Interactive setup wizard")
+        .action(async () => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            const cfg = loadConfig();
+            const apiKey = await rl.question(`Rebrickable API key${cfg.rebrickableApiKey ? " (press Enter to keep current)" : ""}: `);
+            if (apiKey.trim()) {
+                cfg.rebrickableApiKey = apiKey.trim();
+            }
+            const cache = await rl.question(`Cache mode (none/memory/sqlite)${cfg.cache ? ` [${cfg.cache}]` : " [none]"}: `);
+            if (cache.trim()) {
+                if (!["none", "memory", "sqlite"].includes(cache.trim())) {
+                    console.error(`Invalid cache value. Using "${cfg.cache ?? "none"}".`);
+                }
+                else {
+                    cfg.cache = cache.trim();
+                }
+            }
+            saveConfig(cfg);
+            console.log(`\nConfiguration saved to ${getConfigPath()}`);
+        }
+        finally {
+            rl.close();
+        }
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/commands/health.js

@@ -0,0 +1,27 @@
+import { checkHealth } from "../../core/brickognize/client.js";
+export function registerHealthCommand(program) {
+    program
+        .command("health")
+        .description("Check whether the Brickognize API is online")
+        .option("--json", "Output raw JSON")
+        .action(async (opts) => {
+        try {
+            const health = await checkHealth();
+            if (opts.json) {
+                console.log(JSON.stringify(health, null, 2));
+            }
+            else {
+                const status = Object.values(health).every(Boolean) ? "healthy" : "degraded";
+                console.log(`Brickognize API: ${status}`);
+                for (const [key, value] of Object.entries(health)) {
+                    console.log(`  ${key}: ${value ? "ok" : "FAIL"}`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : "Failed to check health");
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=health.js.map

package/dist/cli/commands/identify.js

@@ -0,0 +1,72 @@
+import { predict } from "../../core/brickognize/client.js";
+import { mapPredictionResult } from "../../core/brickognize/mappers.js";
+import { resolveImage, PREDICT_ENDPOINTS } from "../../core/image.js";
+import { runWithConcurrencyLimit } from "../../core/concurrency.js";
+import { formatToolError } from "../../core/utils/errors.js";
+import { formatPrediction } from "../output.js";
+const CONCURRENCY_LIMIT = 5;
+export function registerIdentifyCommand(program) {
+    program
+        .command("identify")
+        .description("Identify LEGO item(s) from photo(s)")
+        .argument("<images...>", "Path(s) to image files (JPEG, PNG, or WebP)")
+        .option("-t, --type <type>", "Item type: general, part, set, fig", "general")
+        .option("--json", "Output raw JSON")
+        .action(async (images, opts) => {
+        const type = opts.type;
+        const endpoint = PREDICT_ENDPOINTS[type];
+        if (!endpoint) {
+            console.error(`Unknown type "${opts.type}". Valid types: general, part, set, fig`);
+            process.exit(1);
+        }
+        try {
+            if (images.length === 1) {
+                const { blob, filename } = await resolveImage({ imagePath: images[0] });
+                const raw = await predict(endpoint, blob, filename);
+                const result = mapPredictionResult(raw, false);
+                if (opts.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log(formatPrediction(result));
+                }
+            }
+            else {
+                const tasks = images.map((imagePath) => async () => {
+                    try {
+                        const { blob, filename } = await resolveImage({ imagePath });
+                        const raw = await predict(endpoint, blob, filename);
+                        const result = mapPredictionResult(raw, false);
+                        return { imagePath, status: "success", result };
+                    }
+                    catch (err) {
+                        return { imagePath, status: "error", error: formatToolError(err) };
+                    }
+                });
+                const results = await runWithConcurrencyLimit(tasks, CONCURRENCY_LIMIT);
+                if (opts.json) {
+                    console.log(JSON.stringify(results, null, 2));
+                }
+                else {
+                    for (const r of results) {
+                        console.log(`\n--- ${r.imagePath} ---`);
+                        if (r.status === "success") {
+                            console.log(formatPrediction(r.result));
+                        }
+                        else {
+                            console.error(`Error: ${r.error}`);
+                        }
+                    }
+                    const succeeded = results.filter((r) => r.status === "success").length;
+                    const failed = results.length - succeeded;
+                    console.log(`\nBatch: ${succeeded}/${results.length} succeeded${failed > 0 ? `, ${failed} failed` : ""}`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : "Identification failed");
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=identify.js.map

package/dist/cli/commands/mcp.js

@@ -0,0 +1,14 @@
+export function registerMcpCommand(program) {
+    program
+        .command("mcp")
+        .description("Start MCP server (stdio transport) for AI assistant integration")
+        .action(async () => {
+        // Dynamic import to avoid loading MCP SDK unless needed
+        const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+        const { createServer } = await import("../../mcp/server.js");
+        const server = createServer();
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    });
+}
+//# sourceMappingURL=mcp.js.map

package/dist/cli/commands/minifig.js

@@ -0,0 +1,57 @@
+import { fetchMinifigDetails } from "../../core/rebrickable/minifigDetails.js";
+import { formatToolError } from "../../core/utils/errors.js";
+import { formatMinifigDetails } from "../output.js";
+export function registerMinifigCommand(program) {
+    program
+        .command("minifig")
+        .description("Get LEGO minifigure details and which sets contain it")
+        .argument("<ids...>", "Minifigure ID(s), e.g. fig-000001")
+        .option("--json", "Output raw JSON")
+        .action(async (ids, opts) => {
+        try {
+            if (ids.length === 1) {
+                const result = await fetchMinifigDetails(ids[0]);
+                if (opts.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log(formatMinifigDetails(result));
+                }
+            }
+            else {
+                const results = [];
+                for (const minifigId of ids) {
+                    try {
+                        const result = await fetchMinifigDetails(minifigId);
+                        results.push({ minifigId, status: "success", result });
+                    }
+                    catch (err) {
+                        results.push({ minifigId, status: "error", error: formatToolError(err) });
+                    }
+                }
+                if (opts.json) {
+                    console.log(JSON.stringify(results, null, 2));
+                }
+                else {
+                    for (const r of results) {
+                        console.log(`\n--- ${r.minifigId} ---`);
+                        if (r.status === "success") {
+                            console.log(formatMinifigDetails(r.result));
+                        }
+                        else {
+                            console.error(`Error: ${r.error}`);
+                        }
+                    }
+                    const succeeded = results.filter((r) => r.status === "success").length;
+                    const failed = results.length - succeeded;
+                    console.log(`\nBatch: ${succeeded}/${results.length} succeeded${failed > 0 ? `, ${failed} failed` : ""}`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : "Failed to fetch minifig details");
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=minifig.js.map

package/dist/cli/commands/part.js

@@ -0,0 +1,59 @@
+import { fetchPartDetails } from "../../core/rebrickable/partDetails.js";
+import { formatToolError } from "../../core/utils/errors.js";
+import { formatPartDetails } from "../output.js";
+export function registerPartCommand(program) {
+    program
+        .command("part")
+        .description("Get details about LEGO part(s): colors, sets containing the part")
+        .argument("<ids...>", "LEGO part number(s), e.g. 3001")
+        .option("-c, --color <name>", "Filter by color name (e.g. Black)")
+        .option("--json", "Output raw JSON")
+        .action(async (ids, opts) => {
+        try {
+            if (ids.length === 1) {
+                const result = await fetchPartDetails(ids[0], opts.color);
+                if (opts.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log(formatPartDetails(result));
+                }
+            }
+            else {
+                const results = [];
+                // Sequential due to Rebrickable rate limit
+                for (const partId of ids) {
+                    try {
+                        const result = await fetchPartDetails(partId, opts.color);
+                        results.push({ partId, status: "success", result });
+                    }
+                    catch (err) {
+                        results.push({ partId, status: "error", error: formatToolError(err) });
+                    }
+                }
+                if (opts.json) {
+                    console.log(JSON.stringify(results, null, 2));
+                }
+                else {
+                    for (const r of results) {
+                        console.log(`\n--- ${r.partId} ---`);
+                        if (r.status === "success") {
+                            console.log(formatPartDetails(r.result));
+                        }
+                        else {
+                            console.error(`Error: ${r.error}`);
+                        }
+                    }
+                    const succeeded = results.filter((r) => r.status === "success").length;
+                    const failed = results.length - succeeded;
+                    console.log(`\nBatch: ${succeeded}/${results.length} succeeded${failed > 0 ? `, ${failed} failed` : ""}`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : "Failed to fetch part details");
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=part.js.map

package/dist/cli/commands/set.js

@@ -0,0 +1,57 @@
+import { fetchSetDetails } from "../../core/rebrickable/setDetails.js";
+import { formatToolError } from "../../core/utils/errors.js";
+import { formatSetDetails } from "../output.js";
+export function registerSetCommand(program) {
+    program
+        .command("set")
+        .description("Get LEGO set details: inventory, year, theme, piece count")
+        .argument("<ids...>", 'Set number(s), e.g. 75192 (the "-1" suffix is added automatically)')
+        .option("--json", "Output raw JSON")
+        .action(async (ids, opts) => {
+        try {
+            if (ids.length === 1) {
+                const result = await fetchSetDetails(ids[0]);
+                if (opts.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log(formatSetDetails(result));
+                }
+            }
+            else {
+                const results = [];
+                for (const setId of ids) {
+                    try {
+                        const result = await fetchSetDetails(setId);
+                        results.push({ setId, status: "success", result });
+                    }
+                    catch (err) {
+                        results.push({ setId, status: "error", error: formatToolError(err) });
+                    }
+                }
+                if (opts.json) {
+                    console.log(JSON.stringify(results, null, 2));
+                }
+                else {
+                    for (const r of results) {
+                        console.log(`\n--- ${r.setId} ---`);
+                        if (r.status === "success") {
+                            console.log(formatSetDetails(r.result));
+                        }
+                        else {
+                            console.error(`Error: ${r.error}`);
+                        }
+                    }
+                    const succeeded = results.filter((r) => r.status === "success").length;
+                    const failed = results.length - succeeded;
+                    console.log(`\nBatch: ${succeeded}/${results.length} succeeded${failed > 0 ? `, ${failed} failed` : ""}`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : "Failed to fetch set details");
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=set.js.map

package/dist/cli/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { applyConfig } from "../core/config.js";
+import { initCache } from "../core/cache/index.js";
+import { setCache } from "../core/rebrickable/client.js";
+import { registerHealthCommand } from "./commands/health.js";
+import { registerIdentifyCommand } from "./commands/identify.js";
+import { registerPartCommand } from "./commands/part.js";
+import { registerSetCommand } from "./commands/set.js";
+import { registerMinifigCommand } from "./commands/minifig.js";
+import { registerMcpCommand } from "./commands/mcp.js";
+import { registerConfigCommand } from "./commands/config.js";
+// Load config file values (env vars take priority)
+applyConfig();
+// Initialize cache from resolved config
+const cache = initCache();
+setCache(cache);
+const program = new Command()
+    .name("brickscope")
+    .description("Identify LEGO parts, sets, and minifigures from images")
+    .version("0.1.0");
+registerHealthCommand(program);
+registerIdentifyCommand(program);
+registerPartCommand(program);
+registerSetCommand(program);
+registerMinifigCommand(program);
+registerMcpCommand(program);
+registerConfigCommand(program);
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/cli/output.js

@@ -0,0 +1,84 @@
+export function formatPrediction(result) {
+    const lines = [];
+    if (result.matches.length === 0) {
+        lines.push("No matches found.");
+        return lines.join("\n");
+    }
+    for (const match of result.matches) {
+        const score = (match.score * 100).toFixed(1);
+        lines.push(`  ${match.id}  ${match.name}  (${match.type}, ${score}%)`);
+        for (const site of match.externalSites) {
+            lines.push(`    ${site.name}: ${site.url}`);
+        }
+    }
+    if (result.predictedColors && result.predictedColors.length > 0) {
+        lines.push("");
+        lines.push("Predicted colors:");
+        for (const color of result.predictedColors) {
+            lines.push(`  ${color.name} (${(color.score * 100).toFixed(1)}%)`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatPartDetails(result) {
+    const lines = [];
+    lines.push(`Part ${result.part.partNum}: ${result.part.name}`);
+    lines.push(`  URL: ${result.part.url}`);
+    lines.push(`  Colors: ${result.totalColors}, Set appearances: ~${result.totalSetsAppearances}`);
+    if (result.colorFilter) {
+        if (result.colorMatched) {
+            lines.push(`  Filtered by color: "${result.colorFilter}"`);
+        }
+        else {
+            lines.push(`  Color "${result.colorFilter}" not found, showing top 5 colors`);
+        }
+    }
+    lines.push("");
+    for (const color of result.colorDetails) {
+        lines.push(`  ${color.colorName} (${color.numSets} sets):`);
+        for (const set of color.sets.slice(0, 10)) {
+            lines.push(`    ${set.setNum}  ${set.setName} (${set.year}, ${set.numParts} pcs)`);
+        }
+        if (color.sets.length > 10) {
+            lines.push(`    ... and ${color.sets.length - 10} more`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatSetDetails(result) {
+    const lines = [];
+    lines.push(`Set ${result.set.setNum}: ${result.set.name} (${result.set.year})`);
+    lines.push(`  Pieces: ${result.set.numParts}, Unique parts: ${result.parts.length}, Spare: ${result.spareParts.length}`);
+    lines.push(`  URL: ${result.set.url}`);
+    lines.push("");
+    lines.push("Parts:");
+    for (const part of result.parts) {
+        lines.push(`  ${part.quantity}x ${part.partNum}  ${part.name} [${part.color}]`);
+    }
+    if (result.spareParts.length > 0) {
+        lines.push("");
+        lines.push("Spare parts:");
+        for (const part of result.spareParts) {
+            lines.push(`  ${part.quantity}x ${part.partNum}  ${part.name} [${part.color}]`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatMinifigDetails(result) {
+    const lines = [];
+    lines.push(`Minifigure ${result.minifig.id}: ${result.minifig.name}`);
+    lines.push(`  Parts: ${result.minifig.numParts}`);
+    lines.push(`  URL: ${result.minifig.url}`);
+    lines.push("");
+    if (result.appearsInSets.length > 0) {
+        lines.push(`Appears in ${result.appearsInSets.length} set(s):`);
+        for (const set of result.appearsInSets) {
+            lines.push(`  ${set.setNum}  ${set.setName} (${set.numParts} pcs)`);
+        }
+    }
+    else {
+        lines.push("Does not appear in any sets.");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=output.js.map

package/dist/core/brickognize/client.js

@@ -0,0 +1,39 @@
+import { apiError, unexpectedResponse } from "../utils/errors.js";
+const PARTS_PREDICT_ENDPOINT = "/predict/parts/";
+const BASE_URL = "https://api.brickognize.com";
+export async function checkHealth() {
+    const res = await fetch(`${BASE_URL}/health/`, {
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        throw apiError(res.status, await res.text());
+    }
+    const data = await res.json();
+    if (typeof data !== "object" || data === null) {
+        throw unexpectedResponse("health endpoint did not return an object");
+    }
+    return data;
+}
+export async function predict(endpoint, imageBlob, filename) {
+    const form = new FormData();
+    form.append("query_image", imageBlob, filename);
+    // Always request color prediction for the parts endpoint specifically
+    const url = endpoint === PARTS_PREDICT_ENDPOINT
+        ? `${BASE_URL}${endpoint}?predict_color=true`
+        : `${BASE_URL}${endpoint}`;
+    const res = await fetch(url, {
+        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;
+}
+//# sourceMappingURL=client.js.map