让OpenIntelligentUI设计系统被任意AI客户端调用:MCP服务器接入Claude Desktop与Cursor完全指南

原创2026-10-11 01:12:051,929 阅读

让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。

一键安装步骤:准备工作 ⚡

  1. 获取仓库代码:
git clone https://gitcode.com/gh_mirrors/op/OpenIntelligentUI
  1. 环境要求: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 传输,两步即可:

  1. 启动 MCP 服务器:
cd apps/mcp
pnpm dev        # 监听 http://localhost:3100/mcp
  1. 在项目根目录创建 .mcp.json:
{
  "mcpServers": {
    "openGenerativeUI": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

重启 Cursor 后,在 AI 对话面板的 MCP 设置中即可看到 openGenerativeUI 已连接,assemble_document 工具会出现在可用工具列表里。

💡 两个客户端的完整配置对照,参考 apps/mcp/README.md 的 "Usage" 章节。

验证接入是否成功:3 个实测用例 ✅

配置完成后,试试这些提示,检验 MCP 能力是否就绪:

  1. 测试工具:"用 assemble_document 工具生成一个交互式快速排序可视化页面" → AI 应调用工具并返回完整 HTML 文档,可直接保存为 .html 打开查看
  2. 测试资源:"读取 skills://master-agent-playbook,告诉我它讲什么"
  3. 测试模板:"使用 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 设计系统吧!

登录后查看全文
OpenIntelligentUI