{
  "markdown": "# BMBrick Photo-to-LEGO-Mosaic Skill\n\n[![npm version](https://img.shields.io/npm/v/@bmbrick/photo-to-lego-mosaic-skill)](https://www.npmjs.com/package/@bmbrick/photo-to-lego-mosaic-skill)\n[![License](https://img.shields.io/badge/license-MIT%20%2B%20Restricted-blue)](#license)\n\nConvert any local photo into a LEGO-style brick mosaic preview — directly from your AI agent.\n\n`@bmbrick/photo-to-lego-mosaic-skill` is an MCP server that lets Claude, Cursor, Windsurf, and other AI agents transform local images into high-fidelity 3D brick mosaics using the same canonical engine as [bmbrick.com](https://bmbrick.com).\n\n> **Renamed from `@bmbrick/agent-mosaic-skill`** (the old name still works but is deprecated — please migrate to the new name for future updates).\n\n## Visual Previews\n\nGenerated with the `generate_lego_mosaic` tool (3D render mode):\n\n**Square Tiles (`square_1x1`)**\n\n| Original Photo | 48x48 Preview | 64x64 Preview |\n| :--- | :--- | :--- |\n| ![Original](https://raw.githubusercontent.com/Able-rip/agent-mosaic-skill/main/assets/cat_original_photo.png) | ![48x48](https://raw.githubusercontent.com/Able-rip/agent-mosaic-skill/main/assets/cat_mosaic_preview.png) | ![64x64](https://raw.githubusercontent.com/Able-rip/agent-mosaic-skill/main/assets/cat_mosaic_64x64.png) |\n\n**Round Tiles (`round_1x1`)**\n\n| Original Photo | 48x48 Preview | 64x64 Preview |\n| :--- | :--- | :--- |\n| ![Original](https://raw.githubusercontent.com/Able-rip/agent-mosaic-skill/main/assets/cat_original_photo.png) | ![48x48 Round](https://raw.githubusercontent.com/Able-rip/agent-mosaic-skill/main/assets/cat_mosaic_round_48x48.png) | ![64x64 Round](https://raw.githubusercontent.com/Able-rip/agent-mosaic-skill/main/assets/cat_mosaic_round_64x64.png) |\n\nFor more case studies and mosaic examples, check out our [Pinterest Showcase](https://www.pinterest.com/BMBrickTeam/diy-lego-mosaic-art-pixel-art-ideas/).\n\n## Quick Start\n\n```bash\nnpx -y @bmbrick/photo-to-lego-mosaic-skill\n```\n\n### MCP Client Configuration\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"lego-mosaic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bmbrick/photo-to-lego-mosaic-skill\"]\n    }\n  }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"lego-mosaic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bmbrick/photo-to-lego-mosaic-skill\"]\n    }\n  }\n}\n```\n\n## Tool: `generate_lego_mosaic`\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `imagePath` | string | Yes | — | Absolute path to a local image |\n| `columns` | number | No | 48 | Preview width in studs (max 64) |\n| `rows` | number | No | 48 | Preview height in studs (max 64) |\n| `materialMode` | string | No | `square_1x1` | `square_1x1` or `round_1x1` |\n| `renderMode` | string | No | `3D` | Render style |\n| `removeBackground` | boolean | No | false | Clean up white/transparent backgrounds |\n\nReturns: a local watermarked PNG preview + a link to unlock the full project at [bmbrick.com](https://bmbrick.com).\n\n## Unlock Full Project\n\nThe preview is watermarked and intended for creative exploration. To get the complete deliverables — HD unwatermarked mosaic, brick-by-brick PDF instructions, parts list with ordering links, and CSV/XML placement matrices — visit [bmbrick.com](https://bmbrick.com).\n\n## Features\n\n- **Same Engine as bmbrick.com** — canonical color science, quantization, and 3D rendering pipeline\n- **Local & Private** — all processing happens on your machine via Node.js\n- **Agent-Ready** — ships with a `SKILL.md` for seamless agent workflow integration\n- **3D Render Mode** — InstancedMesh PBR rendering with realistic brick studs\n\n## Engineering Docs\n\nDeep technical reference for the color quantization pipeline that powers this skill and [bmbrick.com](https://www.bmbrick.com):\n\n- **Color quantization pipeline: principles, history, and lessons** — current architecture, architectural decisions, verified principles, failed experiments from 25+ versions of iteration, and parameter sensitivity reference.\n  - 🇬🇧 [English](./docs/color-pipeline.md)\n  - 🇨🇳 [中文](./docs/color-pipeline.zh-CN.md)\n\n## Migrating from `@bmbrick/agent-mosaic-skill`\n\nIf you were using the old name, the migration is one search/replace:\n\n1. **Package name:** `@bmbrick/agent-mosaic-skill` → `@bmbrick/photo-to-lego-mosaic-skill`\n2. **MCP tool name** (in your agent's tool list): `generate_bmbrick_mosaic` → `generate_lego_mosaic`\n3. **Binary name** (rare): `agent-mosaic-skill` → `photo-to-lego-mosaic-skill`\n\nThe tool parameters (imagePath, columns, rows, etc.) and return shape are unchanged.\n\n## Development\n\n## License\n\nDual-licensed:\n\n- **MIT** — MCP wrapper, `skill/` directory, agent integration surface\n- **Restricted** — `dist/` engine files: free to use and distribute as-is, but no de-obfuscation, reverse engineering, or redistribution of modified versions\n\nSee [LICENSE](LICENSE) for full terms.\n",
  "bytes": 4970,
  "sha": "875806e711e4a0f5d02f87ab0e2978a2caae643fde1866fff31e22d9143ea53f",
  "repo_slug": "able-rip/agent-mosaic-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_able_rip_agent_mosaic_skill_6a5ebc69/readme"
}