让OpenIntelligentUI设计系统被任意AI客户端调用:MCP服务器接入Claude Desktop与Cursor完全指南
让OpenIntelligentUI设计系统被任意AI客户端调用:MCP服务器接入Claude Desktop与Cursor完全指南
OpenIntelligentUI 是一个开源的 Generative UI 框架,它内置了一个独立部署的 MCP(Model Context Protocol)服务器。通过这份完全指南,你将学会如何在 10 分钟内把它的设计系统、技能文档和 HTML 文档组装工具接入 Claude Desktop 与 Cursor,让任意支持 MCP 的 AI 客户端都能直接调用它生成带完整主题的交互界面。
为什么你的 AI 客户端需要一个 MCP 服务器 🤝
MCP 服务器相当于给 AI 客户端装上"外接工具箱":
| 概念 | 作用 | 类比 |
|---|---|---|
| Tools(工具) | 让 AI 执行具体操作 | 函数调用 |
| Resources(资源) | 让 AI 读取上下文文档 | 参考手册 |
| Prompts(提示模板) | 预置的任务指令 | 快捷提示词 |
OpenIntelligentUI 的 MCP 服务器(位于 apps/mcp/)同时支持两种传输方式,正好覆盖两类主流客户端:
- stdio 传输:客户端直接拉起子进程通信,适合 Claude Desktop
- HTTP 传输:服务器常驻运行,适合 Cursor、Claude Code 等
服务器代码结构一目了然,核心实现在 apps/mcp/src/server.ts、HTTP 入口 apps/mcp/src/index.ts、stdio 入口 apps/mcp/src/stdio.ts。
MCP 服务器提供什么:3 类能力速览 🔍
1. assemble_document 工具(核心)
接收一段自包含的 HTML 片段,自动包裹上 OpenGenerativeUI 的完整设计系统——主题 CSS 变量、SVG 样式类、表单样式和 iframe 通信桥接 JS,返回一份可直接放进 <iframe> 渲染的完整 HTML 文档。设计系统 CSS 单一来源自 packages/design-system/src/index.ts,保证与主站视觉一致。
2. Skills 技能资源
通过 skills://list 和 skills://{name} 两个资源 URI 浏览和读取 3 份技能文档:
| 资源名 | 内容 |
|---|---|
master-agent-playbook |
何时、如何创建交互式 HTML 组件 |
svg-diagram-skill |
SVG 图表模板与模式 |
agent-skills-vol2 |
高级可视化、仪表盘、模拟 |
3. Prompt 模板
create_widget、create_svg_diagram、create_visualization 三个预置提示模板,AI 客户端可一键调取对应技能作为指令。
完整说明见官方文档 docs/mcp-integration.md 与 apps/mcp/README.md。
一键安装步骤:准备工作 ⚡
- 获取仓库代码:
git clone https://gitcode.com/gh_mirrors/op/OpenIntelligentUI
- 环境要求:Node.js ≥ 18 + pnpm
cd OpenIntelligentUI
pnpm install
cd apps/mcp
pnpm build # 构建产物输出到 dist/,stdio 模式必须
构建成功后,你可以通过健康检查确认 HTTP 模式可用:
pnpm dev # 启动 http://localhost:3100/mcp
curl http://localhost:3100/health # → {"status":"ok"}
最快配置方法:Claude Desktop 接入(stdio 传输)🖥️
Claude Desktop 使用 stdio 传输,只需编辑配置文件 claude_desktop_config.json(macOS 位于 ~/Library/Application Support/Claude/,Windows 位于 %APPDATA%\Claude\):
{
"mcpServers": {
"open-generative-ui": {
"command": "node",
"args": ["dist/stdio.js"],
"cwd": "/你的绝对路径/apps/mcp"
}
}
}
关键点:
cwd必须指向apps/mcp的绝对路径,dist/stdio.js是相对它的路径- 开发期不想每次构建,可改用
tsx直跑源码:"command": "npx", "args": ["tsx", "src/stdio.ts"]
保存配置后完全退出并重启 Claude Desktop,在输入框附近出现 MCP 工具图标,即接入成功。
最快配置方法:Cursor 接入(HTTP 传输)⚡
Cursor 走 HTTP 传输,两步即可:
- 启动 MCP 服务器:
cd apps/mcp
pnpm dev # 监听 http://localhost:3100/mcp
- 在项目根目录创建
.mcp.json:
{
"mcpServers": {
"openGenerativeUI": {
"url": "http://localhost:3100/mcp"
}
}
}
重启 Cursor 后,在 AI 对话面板的 MCP 设置中即可看到 openGenerativeUI 已连接,assemble_document 工具会出现在可用工具列表里。
💡 两个客户端的完整配置对照,参考 apps/mcp/README.md 的 "Usage" 章节。
验证接入是否成功:3 个实测用例 ✅
配置完成后,试试这些提示,检验 MCP 能力是否就绪:
- 测试工具:"用 assemble_document 工具生成一个交互式快速排序可视化页面"
→ AI 应调用工具并返回完整 HTML 文档,可直接保存为
.html打开查看 - 测试资源:"读取 skills://master-agent-playbook,告诉我它讲什么"
- 测试模板:"使用 create_svg_diagram 提示模板,画一个二叉搜索树结构图"
常见问题排查:4 个典型报错 ⚠️
| 症状 | 原因 | 解决方法 |
|---|---|---|
| Claude Desktop 无反应 / 图标灰色 | 未执行 pnpm build 或路径错误 |
先构建,确认 apps/mcp/dist/stdio.js 存在,cwd 用绝对路径 |
{"status":"ok"} 返回 404 |
端口被占用 | 修改 .env 中 MCP_PORT,同步更新客户端 URL |
| Cursor 连接超时 | 服务器未启动 | 先运行 pnpm dev 保持常驻 |
| 修改技能不生效 | 技能目录指向错误 | 检查环境变量 SKILLS_DIR,默认为 ./skills |
环境变量配置模板(apps/mcp/.env):
MCP_PORT=3100 # 服务器端口
ALLOWED_ORIGINS=* # CORS 允许来源
SKILLS_DIR=./skills # 技能文档目录
LOG_LEVEL=info # 日志级别
进阶:部署到服务器供团队共享 🚀
服务器是标准 Node.js 应用,仓库自带多阶段 apps/mcp/Dockerfile(非 root 用户 + 健康检查):
cd apps/mcp
docker build -t open-generative-ui-mcp .
docker run -p 3100:3100 open-generative-ui-mcp
部署到云端后,把客户端配置中的 URL 换成公网地址即可。也可以直接把新的 .txt 技能文件放进 skills/ 目录,它们会自动作为资源暴露给 AI 客户端——这是扩展设计系统能力的"零代码"方式。
总结
- OpenIntelligentUI 的 MCP 服务器位于 apps/mcp/,支持 stdio + HTTP 双传输
- Claude Desktop:
pnpm build后配置node dist/stdio.js - Cursor:
pnpm dev后配置http://localhost:3100/mcp - 核心能力:
assemble_document工具 +skills://资源 + 3 个 Prompt 模板
更多细节可查阅 docs/mcp-integration.md、docs/deployment.md 和 docs/architecture.md。现在,让你的 AI 客户端拥有完整的生成式 UI 设计系统吧!