canpoint-ui-mcp

研学产品线的 UI 规范查询 MCP 服务。在 Claude Code / Cursor 等支持 MCP 的 AI 工具里接入后，AI 可以随时查询「研学小程序」与「研学后台」的官方设计规范， 按规范生成和自检页面，不再凭空发挥。

能帮你做什么

• 查设计 token：色彩（主色/语义色/状态色/中性色阶）、字体字号阶梯、间距、 圆角、投影、布局密度，全部来自设计稿实测值
• 查组件规格：侧边导航、表格、表单、弹窗、Tab、分页、状态标签、步骤条、 空态等组件的尺寸、颜色与状态变体
• 按页面类型取模式卡：布局骨架精确几何（每个区域块的 x/y/w/h 坐标）、 组件组合、状态清单、新画页 checklist，直接按卡施工——admin 覆盖列表页/ 详情页/表单弹窗/数据看板等 9 类页面，mini 覆盖首页/课程列表/订单表单/ 我的页等 11 类页面
• 拿生成纪律：生成页面前必须遵守的规则包（版本基准、断点事实、 设计稿未提供的状态清单等），避免虚构不存在的样式
• 取官方素材：图标/插画/Logo 等官方设计素材直接取用——list_assets 按平台/类别列清单，支持按区域/版本组过滤、按需降采样与 WebP 转换； get_asset 拿下载 URL（curl 带 key 下载），max_width 降采样、 format="webp" 转码减体积；内联仅限 SVG（≤100KB UTF-8 文本），PNG/WEBP 不内联以免 base64 撑爆上下文；模式卡标注需要素材的区域按卡取用， 不再自行绘制或找第三方替代
• 截图校验：把生成好的页面截图交给 verify_ui，逐色比对官方规范并给出 PASS/FAIL 结论，不达标精确到哪个颜色差多少

工具一览

前置条件

1. 已安装 uv（提供 uvx 命令）
2. 向服务管理员获取：服务地址 与 API key（usk_ 前缀，按人发放）

配置

两个环境变量必填：

可选：UI_SPEC_TIMEOUT（超时秒数，默认 30）、UI_SPEC_LOG_LEVEL（默认 INFO）。

Claude Code（项目 .mcp.json 或全局配置）：

{
  "mcpServers": {
    "canpoint-ui": {
      "command": "npx",
      "args": ["-y", "canpoint-ui-mcp"],
      "env": {
        "UI_SPEC_SERVER_URL": "<管理员提供的服务地址>",
        "UI_SPEC_API_KEY": "usk_<你的key>"
      }
    }
  }
}

Cursor：mcp.json 同款配置。

Windows 下若 npx 启动失败，把 command 改为 cmd、args 改为 ["/c", "npx", "-y", "canpoint-ui-mcp"]（env 不变）。

不走 npm 也可以直接用：

UI_SPEC_SERVER_URL=<服务地址> UI_SPEC_API_KEY=usk_xxx uvx canpoint-ui-mcp

推荐用法（给接入方的 AI 提示词参考）

生成研学前端页面前：先 list_platforms 确认平台 → get_generation_rules 读纪律 → list_page_patterns 看有哪些页面模式 → get_page_pattern 取目标 页面模式卡 → get_tokens / get_component_spec 补齐规格 → 按模式卡施工到 需要素材的区域（侧栏 Logo、功能图标、空态插画等）时，list_assets（可按 region/version_group/has_vector 过滤）挑选官方素材、get_asset 取下载 URL （curl 带 key 下载；SVG 可内联文本，大图可 max_width 降采样/转 webp） → 按 skeleton 几何与 checklist 生成 → 截图交给 verify_ui 自检，FAIL 则按报告 修正后重验。

常见问题

License

Apache-2.0