拼豆 MCP 怎么用？AI Agent 生成拼豆图纸保姆级教程（MCP / 命令行 / Agent Skill 三种接法）

拼豆Pic（pindoupic.com）把和网页版同源的图纸引擎发成了 npm 包 @javascribe/pindoupic，专门给「会用 AI Agent 的人」准备：你可以把它接进支持 MCP 的客户端，也可以在终端里一行命令出图，还能给 Claude Code、Qoder、Cursor 这类宿主装一个 Agent Skill。接好之后，丢一张图给 Agent，它直接还你一张可照着拼的图纸——带色号格子、网格、行列坐标、材料清单的 PNG / PDF，外加各色号豆子用量统计。

这篇教程只讲人类需要做好的三件事：怎么接、参数怎么给、图纸出来后去哪精修。

它能干什么？先看一个真实例子

对配置好的 Agent 说一句：

把 ~/Downloads/cat.png 做成拼豆图纸，52 格，圆豆效果

Agent 会在你本机跑生成命令，几秒后回报图纸文件路径和颜色统计（比如浅粉 × 132、白色 × 47……）。图纸默认带色号标注、网格、行列编号和材料清单，--format pdf 可以直接输出打印版。

动手之前，先记住三条边界（都是实话，不是卖点）：

生成引擎跑在你自己电脑上，图片只在本机处理，不上传到任何地方；
色板与图片类型预设随包内联，出图不消耗服务器算力；
首次生成需要能访问 pindoupic.com 完成一次联网激活，网站打不开（离线、公司网络、DNS 问题）时出不了图，恢复联网后重试即可。

三种接入方式怎么选

三种方式共用同一个 npm 包，出图结果完全一致，按「你在哪里用它」来选：

方式	形态	适合谁
MCP Server	往客户端里粘一段 JSON 配置，Agent 即获得 `generate_bead_pattern` 等工具	支持 Model Context Protocol（MCP）的客户端
CLI 命令行	一行 `npx` 命令直接出图	终端、脚本、CI
Agent Skill	把一份「选参数手册」复制进宿主的技能目录，Agent 自己选参数、生成、回报	Claude Code / Qoder / Cursor 等支持 Agent Skills 的宿主

共同前提：Node.js ≥ 20；不需要预装任何东西，npx 首次调用时自动下载本包（含约 100 MB 的 sharp 原生依赖，约 1–2 分钟），之后走本地缓存。

手把手一：MCP 配置

把下面这段配置原样交给支持 MCP 的客户端即可（无需预装，首次调用时 npx 自动下载本包并启动 Server）：

{
  "mcpServers": {
    "pindoupic": {
      "command": "npx",
      "args": ["-y", "-p", "@javascribe/pindoupic", "pindoupic-mcp"]
    }
  }
}

配好之后，Agent 能获得三个工具：generate_bead_pattern（图片 → 图纸 + 各色号用量统计）、list_palettes（列出本包内置色板）、list_image_types（列出图片类型预设）；另有一个 submit_feedback，用于把使用意见回传给网站。

一次典型调用的入参长这样：

{ "image_path": "/abs/path/cat.png", "width": 52, "palette_sub": "291", "image_type": "cartoon", "mirror": false }

常见宿主注意事项：

image_path 写本机的绝对路径；
返回里有 width / height / total_beads / colors_used / color_stats，以及 png_data_url（base64，可直接落盘）和 png_file（本机临时文件路径）；
客户端里 Server 起不来时，先在终端手工跑 npx -y -p @javascribe/pindoupic pindoupic-mcp，能打印启动信息就说明包没问题，卡住的大多是网络或镜像；
不确定有哪些色板/类型时，让 Agent 直接调 list_palettes、list_image_types，或用 CLI 的 --help 查看。

手把手二：命令行一条命令出图

最小可用形态：

npx -y -p @javascribe/pindoupic pindoupic --image ./cat.png --width 52 --type cartoon --colors

完整参数示例（52 格、MARD/291 全色板、圆豆预览、带用量统计）：

npx -y -p @javascribe/pindoupic pindoupic \
  --image cat.png --width 52 --type cartoon --palette MARD/291 \
  --bead-shape circle --colors --output cat_bead.png

进度与结果写在 stderr，色号统计表写在 stdout（方便脚本解析）。参数速查表与包内 README 一致：

参数	说明
`-i, --image <path>`	输入图片路径（必填）
`-w, --width <n>`	图纸宽度/格数，默认 50，范围 10–200（超过 160 格会自动压低每格像素以适配画布）
`-p, --palette <b/s>`	色板品牌/型号，默认 `MARD/120`；`--help` 会列出全部色板与色数
`-t, --type <id>`	图片类型：`cartoon 卡通画`、`watercolor 水彩画`、`illustration 插画`、`lineart 线稿`、`photo 照片`、`pixelart 像素画`、`logo Logo图标`、`miniapp_fast 极速`
`--simplify-colors`	合并稀有色号，颜色太多想省钱时用
`--format <png\|pdf>`	输出格式，默认 png
`-o, --output <path>`	输出路径，默认 `<输入>_bead.png`
`--bead-shape <s>`	豆子形状：`square 方形`／`circle 圆形`
`--cell-size <px>`	每格像素大小，默认 50
`--mirror`	镜像翻转图纸（默认不翻转；只翻导出画面，不改颜色统计）
`--keep-bg`	保留白色背景（默认把纯白格当透明）
`--no-color-codes`	不显示「色号」
`--no-grid`	不显示「网格」
`--no-rulers`	不显示「行列坐标」
`--no-materials`	不显示「材料清单」
`-c, --colors`	打印各色号用量统计

参数经验：杯垫、钥匙扣这类小件用 32–52 格；头像、装饰画 60–100 格；大幅作品 100–200 格，拿不准就用 52。像素画配 --type pixelart，黑白线稿配 --type lineart；CLI 自身默认色板是 MARD/120，想要 291 色全色板就显式传 --palette MARD/291；嫌颜色多费豆，加 --simplify-colors。

出图之后：到官网免费编辑器精修

本包负责「图片 → 图纸」这一步，拿到初稿后，最后一公里建议回到浏览器。拼豆Pic 官方网页工具免费、无需安装，把刚生成的图纸传上去就能继续：

官方工具	能做什么
拼豆图纸编辑器	逐格改色号、擦除杂豆、色号合并与微调、批量替换、镜像翻转、行列坐标查看、导出 PNG/PDF
图层编辑器	多图层叠加编辑，复杂图案分块拼装
空画布豆板	不上传图片，直接在豆板上逐格手拼创作
色号对照表	MARD / COCO 色号与实物色对照、按色号查相近色

常见问题

能直接用文字生成拼豆图纸吗？ 本包不支持文字输入，只接受图片。输入文字做图纸请用官网免费功能文字转拼豆图纸，含字体、字高、字距行距、描边、艺术字效果与底色。

我的图片会被上传吗？ 不会。图片只在本机处理；色板与预设都打进包里。就连使用意见回传，内容也只有参数与评价文本，不含图片本身和它的路径。

网站打不开会怎样？ 首次生成需要能访问 pindoupic.com 完成一次联网激活。如果提示无法联网激活或取不到授权，通常是离线、公司网络限制或 DNS 问题——恢复联网后重试即可。长期离线的环境请自托管或联系我们。

报错「色板 X/Y 不在本包内」？ 错误信息里已经列出该版本支持的色板清单，按清单换一个型号即可；需要新色板就升级本包版本。本包不会静默替你换色板。

npx 下载失败 / sharp 装不上？ 网络或镜像问题，重试或挂代理即可。

卡住了？告诉我们

接入过程中卡住了（npx 下载失败、联网激活不通、色板不在包里、MCP 工具报参数错），或者希望补充哪个色板、哪段说明，欢迎到官网留言告诉我们。如果你的图纸是 Agent 生成的，它每出一张图也会按包内的提示来征询你的意见——你给 Agent 的回复会标着「agent 提交」进入同一个留言模块。

更多动手玩法见拼豆教程栏目，从材料清单到熨烫技巧都有。