Metadata-Version: 2.4
Name: canpoint-ui-mcp
Version: 0.1.1
Summary: 研学产品线 UI 规范查询 MCP：查询研学小程序/研学后台的设计 token、组件规格与生成纪律，并支持对生成页面截图做色彩校验。
Author: 若清风
License-Expression: Apache-2.0
Keywords: mcp,model-context-protocol,ui,design-tokens,design-system
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.6.0
Requires-Dist: httpx>=0.27.0

# canpoint-ui-mcp

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

## 能帮你做什么

- **查设计 token**：色彩（主色/语义色/状态色/中性色阶）、字体字号阶梯、间距、
  圆角、投影、布局密度，全部来自设计稿实测值
- **查组件规格**：侧边导航、表格、表单、弹窗、Tab、分页、状态标签、步骤条、
  空态等组件的尺寸、颜色与状态变体
- **拿生成纪律**：生成页面前必须遵守的规则包（版本基准、断点事实、
  设计稿未提供的状态清单等），避免虚构不存在的样式
- **截图校验**：把生成好的页面截图交给 `verify_ui`，逐色比对官方规范并给出
  PASS/FAIL 结论，不达标精确到哪个颜色差多少

## 工具一览

| 工具 | 用途 |
|------|------|
| `list_platforms` | 列出可用平台（mini=研学小程序，admin=研学后台）与数据状态，建议会话开始先调用 |
| `get_tokens(platform, category)` | 按类别查 token：color / typography / spacing / shape / elevation / layout，category 留空返回全部 |
| `list_components(platform)` | 列出该平台全部组件规范条目 |
| `get_component_spec(platform, component)` | 查单个组件完整规格，支持中文名与模糊匹配（如"表格"→list） |
| `get_generation_rules(platform)` | 生成 UI 前必读的纪律包 |
| `verify_ui(platform, image_base64)` | 对生成页面截图做色彩校验，返回逐色偏差与 PASS/FAIL |

## 前置条件

1. 已安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)（提供 `uvx` 命令）
2. 向服务管理员获取：**服务地址** 与 **API key**（`usk_` 前缀，按人发放）

## 配置

两个环境变量必填：

| 变量 | 说明 |
|------|------|
| `UI_SPEC_SERVER_URL` | 服务地址（管理员提供，不带 `/mcp` 后缀） |
| `UI_SPEC_API_KEY` | 管理员发放的 key |

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

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

```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 也可以直接用：

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

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

> 生成研学前端页面前：先 `list_platforms` 确认平台 → `get_generation_rules`
> 读纪律 → `get_tokens` / `get_component_spec` 取规格 → 生成 →
> 截图交给 `verify_ui` 自检，FAIL 则按报告修正后重验。

## 常见问题

| 现象 | 处理 |
|------|------|
| 提示「认证或授权失败」 | key 错误/已吊销，联系管理员核对 |
| 提示「服务不可用」 | 服务地址填错或服务维护中，联系管理员 |
| 查询返回「规范数据未就绪」 | 该平台数据维护中，稍后再试或联系管理员 |
| 某状态样式查不到 | 设计稿未提供，纪律包中有清单；不要虚构，找设计师确认 |

## License

Apache-2.0
