Skip to main content
Glama
Sign In
beads

beads

by InfernoPC
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

🫘 豆豆工作室 Bead Studio

AI 協作的拼豆（Perler／MARD）設計工具。在 Claude Code 裡請 AI 設計圖案，網頁上會即時看到 AI 畫的每一筆；你也可以在網頁上自己微調，AI 馬上讀得到。

豆豆工作室網頁介面

特色

  • AI 設計：透過 MCP 提供 19 個工具，AI 可以建立作品、批次畫圖、匯入圖片、檢查結構與預覽成品。專案內附設計知識（.claude/skills/bead-design），涵蓋配色、描邊、明暗、掛孔與尺寸。

  • 即時同步：AI 的修改會即時出現在網頁上，不用重新整理，被改到的豆子會跳一下。網頁上的修改也走同一套工具。

  • 網頁編輯器：提供畫筆、橡皮擦、油漆桶、吸管、直線、圓形、全域換色、掛孔等工具，支援復原／重做、快照、鏡像檢視、亮暗模式，也能預覽 3D 成品。編輯區上方可以切換燙前／燙後、有／無釘板，3D 預覽會一起切換；燙後會把豆子畫成連成一片的方塊，看到整片圓孔會不舒服的人可以改用這個模式。

  • 庫存管理：勾選擁有的顏色、填顆數（也能秤重換算）。用量面板會顯示每色需要多少、還缺多少；拼完作品後，按「做完了，扣庫存」會依用量扣掉庫存。

  • 檢查器：檢查留邊、浮豆、易斷的細線、掛孔位置、缺料，以及相鄰顏色太接近的地方。

  • 圖片匯入：適合卡通和線稿圖。支援去背（可指定多種背景色）、每格取主要顏色、加粗細線、清雜點、裁切與排除區塊。

  • 匯出：可匯出成品圖、施工圖、3D 預覽的 PNG。PNG 內含作品資料，拖回網頁就能還原。

Related MCP server: Shared Craft Room

快速開始

需要 Node.js ≥ 24 與 pnpm。

pnpm install
pnpm build:web
pnpm start          # http://localhost:5174

或用 Docker：

mkdir -p ~/BeadStudio        # 匯入／匯出圖片的交換資料夾
docker compose up -d --build # http://localhost:5174
docker compose logs -f       # 看 log
docker compose down          # 停止

  • 埠只開在本機（127.0.0.1:5174）。

  • data/、config/ 掛進容器，作品與庫存都留在這個資料夾裡。AI 改了 config/checks.json 後，執行 docker compose restart 生效。

  • ~/BeadStudio 以相同的絕對路徑掛進容器。import_image／export_png 只能使用這個資料夾裡的檔案。

  • 更新程式碼後，重新執行 docker compose up -d --build。

  • 若把主機埠改成 5174 以外，記得在 BEADS_ALLOWED_HOSTS 加上 localhost:新埠。

連接 Claude Code

claude mcp add --transport http beads http://localhost:5174/mcp

在這個資料夾裡啟動 Claude Code，就會自動載入 .claude/skills/bead-design 的設計知識。網頁右上角的「連接 AI」也會顯示這行指令。

開始設計前，AI 會先問你兩件事：

  1. 只用有的顏色嗎？

  2. 只用有的數量嗎？

畫完後，它會依檢查器的缺料提醒自己修正，直到符合你的要求。

MCP 工具

類別

工具

作品

list_designs、open_design、new_design、set_board

讀取與預覽

get_design、describe_design、render_preview、run_checks

修改

apply_ops（一次送一整批指令，整批算一步復原）、undo、redo、snapshot、restore_snapshot

顏色與庫存

get_palette、calibrate_color、set_inventory、deduct_inventory

圖片

import_image、export_png

apply_ops 的指令有：

  • 繪製：paste（用字元畫圖）、rect、ellipse、line、polygon、fill

  • 換色與清除：replace_color、clear

  • 搬移變形：move、mirror、rotate

  • 效果：outline、gradient、shade

  • 掛孔：set_hole

匯入圖片的選項

選項

說明

removeBg

去掉從圖片外圍連進來的背景，被外框圍住的同色區塊（例如白色身體）會保留

bgColors、bgTolerance

另外指定背景色（例如白底外的淡藍天空），以及去背的色差容許值

colors

只用這些色號轉換

crop、exclude

只取原圖某一塊；把原圖上的區塊（例如文字）當背景略過

sampling: "dominant"

每格取最多像素對到的顏色，不會平均出灰邊

lineBoost

一格裡深色佔這個比例以上就整格用深色，細線不會斷（卡通建議 0.3）

cleanup

把小於 N 顆、而且和周圍顏色相近的雜點併掉（建議 3）

dither

抖色，用相近的顏色交錯排列來模擬漸層（適合照片）

開發

pnpm dev        # 同時啟動伺服器與 Vite，開 http://localhost:5173
pnpm test       # 單元測試（vitest）
pnpm e2e        # 網頁測試（Playwright；先 pnpm build:web）
pnpm typecheck

技術：TypeScript、Fastify、MCP SDK（Streamable HTTP）、React、Vite、@napi-rs/canvas。

環境變數

變數

預設

說明

PORT

5174

伺服器埠

BEADS_VISION

auto

off：render_preview 改回傳文字描述（給不能看圖的模型）

BEADS_DATA_DIR

data

設計、色表、庫存

BEADS_CONFIG_DIR

config

檢查器門檻 checks.json

BEADS_HOST

127.0.0.1

監聽位址；Docker 映像內為 0.0.0.0

BEADS_FILES_DIR

（不限制）

設定後 import_image／export_png 只能使用此資料夾（絕對路徑）

BEADS_HOME_DIR

系統家目錄

展開 ~ 用的家目錄（絕對路徑）；Docker 內設為主機的家目錄

BEADS_ALLOWED_HOSTS

（空）

額外允許的 Host（host:port，逗號分隔）；預設只接受 localhost:PORT 與 127.0.0.1:PORT，其他 Host／Origin 一律 403

使用者資料

以下資料都存在 data/ 底下，不會被 commit：

  • 作品：data/designs/

  • 目前開啟的作品：data/state.json

  • 庫存：data/inventory.json

只有色表 data/palette.json 納入版本控制，色號來源見 data/PALETTE_SOURCES.md。

授權

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers