spark-figma-mcp

Spark Figma MCP Server — bridges Cursor / Claude Code / Codex to the Spark Figma plugin over localhost WebSocket.

发布者：lazykids119 · 包页面：https://www.npmjs.com/package/spark-figma-mcp

完整多端说明见仓库根文档 docs/spark-figma-mcp.md。

Cursor 配置（推荐）

在 ~/.cursor/mcp.json（或项目 .cursor/mcp.json）中：外层 mcpServers 为 Cursor 固定字段；其下的 server 名与包名统一为 spark-figma-mcp（Cursor MCP 列表显示此名）：

{
  "mcpServers": {
    "spark-figma-mcp": {
      "command": "npx",
      "args": ["-y", "spark-figma-mcp"]
    }
  }
}

前提： Figma 桌面端或浏览器 Web已打开目标文件，且 Spark 插件已运行（插件 UI 连 ws://localhost:1994/ws，状态为 Mcp Bridge已启动）。不需要 Figma API Key；Web 端用账号登录 + 跑插件即可。

URL / 选中说明： 把 Figma 设计链接交给 Agent 时，URL 给的是「读哪个节点」的 ID（node-id=1812-7 → MCP 用 1812:7）；不必先在画布选中该节点。必须满足的是：该文件在本地 Figma 里打开，且插件 Bridge 已连上。详见 docs/mcp-bridge-workflow.md 第 5 节。
Web 端注意事项： 见 docs/mcp-bridge-workflow.md 第 4 节（同机 localhost、关标签即断桥、不能仅凭链接远程拉稿等）。

关掉旧版、启用 npm 最新版

lsof -tiTCP:1994 -sTCP:LISTEN 2>/dev/null | xargs kill -9 2>/dev/null
pkill -f 'spark-figma-mcp' 2>/dev/null
find ~/.npm/_npx -type d -name 'spark-figma-mcp' -prune -exec rm -rf {} + 2>/dev/null
echo "已清理。请在 Cursor Reload MCP，并重新打开 Spark 插件。"

然后 curl -sS http://127.0.0.1:1994/ping 核对 version。完整说明见 docs/mcp-bridge-workflow.md §7、docs/spark-figma-mcp.md §7。

Claude Code / Codex 配置见 docs/spark-figma-mcp.md。

本地开发

从 monorepo 根目录：

pnpm install
pnpm build:mcp
# 或
pnpm --filter spark-figma-mcp build

Cursor 指向本地构建产物：

{
  "mcpServers": {
    "spark-figma-mcp": {
      "command": "node",
      "args": [
        "/ABS/PATH/TO/spark-figma-plugin/packages/mcp-server/dist/index.js"
      ]
    }
  }
}

更多联调说明见 docs/mcp-bridge-workflow.md。

发版

在 monorepo 根目录（需已 npm login，账号 lazykids119）：

# 预览（不改文件、不发布）
cd packages/mcp-server && node scripts/release.mjs patch --dry-run

# bump patch + 写 CHANGELOG + build + npm publish
pnpm release:mcp:patch

# 只 bump，不发布
cd packages/mcp-server && node scripts/release.mjs patch --no-publish

# 带发布说明
cd packages/mcp-server && node scripts/release.mjs minor --notes "支持某某工具"

不要写成 pnpm release:mcp:patch -- --dry-run：多出来的 -- 会传给脚本并报错。

也可用：

| 命令 | 含义 | |------|------| | pnpm release:mcp:patch | patch：x.y.z → x.y.(z+1) | | pnpm release:mcp:minor | minor：x.y.z → x.(y+1).0 | | pnpm release:mcp:major | major：x.y.z → (x+1).0.0 |

变更记录见 CHANGELOG.md。

PNG compression on save

save_screenshots compresses PNG files by default (same TinyPNG-style pipeline as the plugin UI). Compression lives inside this package (src/compress-png.ts).

{
  "items": [{ "nodeId": "1623:1515", "outputPath": "./out/slice.png" }],
  "scale": 3,
  "clip": true,
  "compress": true
}

Set compress: false to keep the raw Figma PNG.