@jiujiang/jishi-mcp-server
v1.2.0
Published
MCP Server for JiShi Design
Maintainers
tone-lyleReadme
即时 MCP - 即时设计 MCP 桥接插件
即时 MCP 是连接「即时设计」与 MCP (Model Context Protocol) 的桥接插件，让 AI 助手（如 Claude、Cursor）能够直接读取与操作即时设计画布中的设计稿。
功能特性
- 获取设计数据：读取当前页面节点、选中元素、节点层级结构
- 导出图片：支持 PNG、JPG、SVG、PDF 格式，可指定缩放比例，保存到本地或触发下载
- 批量下载图标：批量导出选中节点为 SVG
- 执行脚本：在插件环境中执行自定义 JavaScript（
jsDesignAPI） - 多客户端并行：多个 AI 工具可同时连接同一画布；多个设计文档可被分别识别与寻址
- 稳定连接：内置心跳保活、断线快速重连、请求唯一标识，避免数据错配与丢失
系统要求
- Node.js 18+
- 即时设计桌面版或网页版
- MCP 客户端（如 Claude Desktop、Cursor）
快速开始
1. 安装全局 MCP 服务包
npm i -g @jiujiang/jishi-mcp-server2. 配置 MCP 客户端
在 MCP 客户端配置文件中添加（如 claude_desktop_config.json）：
{
"mcpServers": {
"jishi-design": {
"command": "npx",
"args": ["-y", "@jiujiang/jishi-mcp-server"]
}
}
}3. 启动插件
- 打开即时设计
- 打开
九匠即时MCP插件 - 等待面板状态指示灯变为绿色 「已连接」
插件面板
面板会实时展示连接诊断信息，便于排查多客户端问题：
- 状态指示灯：绿色（已连接）/ 琥珀色（连接中）/ 灰色（未连接）
- 客户端：本会话的客户端 ID（每个标签页/文档唯一）
- 文档：当前设计文档名
- 端口：已连接的服务端口
- 运行日志：按类型着色，可折叠、可清空
提示：默认端口为
19999，可在端口输入框中填写多个端口（逗号分隔）。
架构说明
┌─────────────────┐ stdio ┌─────────────────┐
│ MCP Client │ ◄─────────────────► │ MCP Server │
│ (Claude 等) │ │ (Node.js) │
└─────────────────┘ └────────┬────────┘
│
WebSocket:19999
│
┌────────▼────────┐
│ Plugin UI │
│ (ui.html) │
└────────┬────────┘
│
postMessage
│
┌────────▼────────┐
│ Plugin Code │
│ (code.js) │
└────────┬────────┘
│
jsDesign API
│
┌────────▼────────┐
│ 即时设计 │
└─────────────────┘多个 MCP 客户端进程会共享同一个 WebSocket 端口：第一个启动的进程成为 主进程（leader） 并监听端口，其余进程以 代理模式（broker） 通过主进程转发请求。整个过程对用户透明，主进程退出后其余进程会自动接管。
安装 Skill（Claude / Codex）
仓库内置 jishi-mcp Skill，封装了本插件的标准工作流与完整工具参数，帮助 AI 更准确地调用。
通过 npx 一键安装（推荐）：
# 同时安装到 Claude Code 和 Codex CLI
npx "git+ssh://[email protected]/next-lyle/jsdesign-mcp.git"
# 仅安装到 Claude Code → ~/.claude/skills/jishi-mcp/SKILL.md
npx "git+ssh://[email protected]/next-lyle/jsdesign-mcp.git" claude
# 仅安装到 Codex CLI → ~/.codex/prompts/jishi-mcp.md（用 /jishi-mcp 调用）
npx "git+ssh://[email protected]/next-lyle/jsdesign-mcp.git" codex无 SSH 密钥时可改用 HTTPS：
npx "git+https://gitcode.com/next-lyle/jsdesign-mcp.git"
已克隆仓库时，也可直接运行本地脚本：
node scripts/install-skill.mjs # 全部
node scripts/install-skill.mjs claude # 仅 Claude Code
node scripts/install-skill.mjs codex # 仅 Codex CLI- Claude Code：安装后自动按场景触发，无需手动调用。
- Codex CLI：安装为自定义提示词，在会话中输入
/jishi-mcp调用。
可用工具
| 工具名称 | 说明 |
|---------|------|
| get_page_nodes | 获取当前页面所有顶层节点（画板/Frame）列表 |
| get_selection | 获取当前选中节点的详细信息（含子节点） |
| get_node_children | 获取指定节点（按 ID 或名称）的子节点 |
| save_image | 导出节点为图片并保存到指定路径或触发下载 |
| download_icons | 批量导出选中节点为 SVG |
| execute_script | 在插件环境执行自定义 JavaScript |
| list_plugin_clients | 列出当前已连接的插件客户端（用于多客户端寻址） |
详细参数与示例见 USAGE.md。
多客户端寻址
当多个设计文档同时连接时，先用 list_plugin_clients 获取客户端列表，再在任意工具调用中传入可选参数 clientId 指定目标文档。不传 clientId 时默认操作首个在线客户端。
大型设计稿的数据完整性
get_selection 与 get_node_children 返回结构为：
{
"nodes": [ /* 节点数组 */ ],
"summary": {
"totalSerialized": 1200,
"truncated": true,
"limits": { "maxDepth": 12, "maxNodes": 2000 },
"hint": "提高 maxDepth/maxNodes 或按节点分批读取以获取完整数据"
}
}当 summary.truncated 为 true 时，说明内容超出上限被截断，可调高 maxDepth/maxNodes，或对子节点分批读取。
高级配置
可通过环境变量或命令行参数调整服务行为：
| 环境变量 | 命令行参数 | 默认值 | 说明 |
|---------|-----------|--------|------|
| JISHI_MCP_WSS_PORT | --ws-port= / --port= | 19999 | WebSocket 监听端口 |
| JISHI_MCP_BROKER | --broker / --broker-mode | 关闭 | 强制以代理模式启动 |
| JISHI_MCP_BROKER_PORT | --broker-port= | 同 WS 端口 | 代理模式连接的主进程端口 |
| JISHI_MCP_HEARTBEAT_MS | — | 15000 | 心跳间隔（毫秒） |
文件结构
即时MCP/
├── manifest.json # 插件清单文件
├── code.js # 插件主代码（jsDesign 命令处理）
├── ui.html # 插件面板（WebSocket 桥接 + 诊断界面）
├── server/ # MCP Server
│ ├── src/index.ts # Server 源码
│ ├── dist/ # 编译产物
│ ├── package.json
│ └── README.md # 本文档
├── USAGE.md # 工具详细使用说明
└── 即时设计插件API参考文档.md故障排除
| 现象 | 排查 |
|------|------|
| 状态显示「未连接」 | 确认 MCP Server 正在运行，端口 19999 未被占用；尝试重启 MCP 客户端与插件 |
| 提示「插件未连接」 | 确认即时设计中已打开本插件且面板为绿色「已连接」 |
| 多文档操作错乱 | 用 list_plugin_clients 确认目标 clientId，并在调用中显式传入 |
| 数据看起来不完整 | 检查返回的 summary.truncated，调高 maxDepth/maxNodes 或分批读取 |
许可证
MIT License