Metadata-Version: 2.4
Name: canpoint-ui-mcp
Version: 0.5.0
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**：色彩（主色/语义色/状态色/中性色阶）、字体字号阶梯、间距、
  圆角、投影、布局密度，全部来自设计稿实测值
- **查目标态规范（mini）**：设计师已拍板的《UI 设计标准 v2.0》——字号与间距
  **白名单**、品牌红单屏配额、视觉禁区、22 类组件库规格、39 条规范×实测冲突的
  **裁决结论**、16 条缺口的正式给值、无障碍与验收 checklist。**新画或重构页面
  以这一层为准**（详见下方「两层数据怎么选」）
- **查组件规格**：侧边导航、表格、表单、弹窗、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 结论，不达标精确到哪个颜色差多少

## 工具一览

| 工具 | 用途 |
|------|------|
| `list_platforms` | 列出可用平台（mini=研学小程序，admin=研学后台）与数据状态，建议会话开始先调用；`standard_ready` 表示该平台是否有目标态规范层 |
| `get_tokens(platform, category)` | 按类别查 token：color / typography / spacing / shape / elevation / layout，category 留空返回全部；若有规范层，另返回 `standard_tokens`（目标态 token，含字号/间距白名单与豁免清单） |
| `list_components(platform)` | 列出该平台全部组件规范条目；若有规范层，另返回 `standard_components`（22 类目标态组件库，粒度更细） |
| `get_component_spec(platform, component)` | 查单个组件完整规格，支持中文名与模糊匹配（如"表格"→list）；两层都命中时同时返回 `spec`（实测）与 `standard_spec`（目标态） |
| `get_generation_rules(platform)` | 生成 UI 前必读的纪律包；若有规范层，另返回 `standard`（视觉公式/品牌红配额/层次纪律/视觉禁区/版本规则/交付物/验收 checklist/无障碍 + 39 条裁决结论 + 16 条缺口结论 + 未闭环项） |
| `list_page_patterns(platform)` | 列出该平台全部页面模式卡摘要（id/中文名/适用场景/区域数/清单数），挑选目标页面类型 |
| `get_page_pattern(platform, page_type)` | 取单个页面模式完整卡：布局骨架精确几何、组件组合、token 用法、状态清单、版本变体与施工 checklist；若有规范层，另返回 `standard_constraints`（该页型的目标态约束）；page_type 支持模式 id、中文名与模糊匹配 |
| `list_assets(platform, category, limit, offset, region, version_group, has_vector)` | 列出该平台官方素材（图标/插画/Logo）清单摘要：id/名称/类别/置信度/尺寸/格式与字节数/用途建议/display_size/svg_kind/pattern_region/version_group，支持类别、区域（pattern_region 前缀，如 `mine-page`）、版本组（如 `v1.1`）、矢量形态（`full`/`any`）过滤与分页 |
| `get_asset(asset_id, want, format, max_width)` | 取单个素材：`want="url"` 返回带鉴权的下载链接 + sha256 校验值；`format` 支持 png/svg/webp，`max_width`（16~4096）按需降采样，派生时下载链接追加 `?w=&fmt=`（bytes/sha256 为原图值）；`want="inline"` 仅限 SVG（≤100KB 文本内联），PNG/WEBP 返回错误 + download_url |
| `verify_ui(platform, image_base64)` | 对生成页面截图做色彩校验，返回逐色偏差与 PASS/FAIL |

## 两层数据怎么选（mini）

mini 平台同时返回两层数据，**并列不覆盖**，按任务选：

| 你在做什么 | 用哪一层 | 字段 |
|---|---|---|
| **新画页面 / 重构存量页面** | **规范层**（设计师已拍板的目标态标准） | `standard_tokens`、`standard_components`、`standard_spec`、`standard`（纪律包）、`standard_constraints` |
| 复现 / 校对已有页面，或要看设计稿当前长什么样 | 实测层（设计稿现状） | `tokens`、`components`、`spec`、`pattern` |
| 两层数值不一致 | 看 `standard.adjudication_conclusions`（39 条裁决结论，已写明哪层生效）；仍不确定时看响应里的 `standard_note` | — |

> admin 平台目前只有实测层（无规范层），响应里会附一句中文 `standard_note` 说明，
> 不影响其余字段使用。

## 前置条件

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` 确认平台（看 `standard_ready`）→
> `get_generation_rules` 读纪律（**新画页面重点读 `standard.discipline` 与
> `standard.adjudication_conclusions`**）→ `list_page_patterns` 看有哪些页面模式 →
> `get_page_pattern` 取目标页面模式卡（骨架几何）+ `standard_constraints`（目标态
> 约束）→ `get_tokens` / `get_component_spec` 补齐规格（新画用 `standard_*`）→ **按模式卡施工到
> 需要素材的区域（侧栏 Logo、功能图标、空态插画等）时，`list_assets`（可按
> region/version_group/has_vector 过滤）挑选官方素材、`get_asset` 取下载 URL
> （curl 带 key 下载；SVG 可内联文本，大图可 max_width 降采样/转 webp）** → 按
> skeleton 几何与 checklist 生成 → 截图交给 `verify_ui` 自检，FAIL 则按报告
> 修正后重验。

## 常见问题

| 现象 | 处理 |
|------|------|
| 提示「认证或授权失败」 | key 错误/已吊销，联系管理员核对 |
| 提示「服务不可用」 | 服务地址填错或服务维护中，联系管理员 |
| 查询返回「规范数据未就绪」或「模式库未就绪」 | 该平台 DNA 或页面模式库维护中，稍后再试或联系管理员 |
| 查询返回「素材库未就绪」 | 素材库尚未采集完成（增值能力，不影响 token/组件/模式卡查询），稍后再试或联系管理员 |
| `get_asset` inline 提示「PNG/WEBP 不支持内联返回」或超过内联上限 | 内联仅限 SVG（≤100KB 文本）：错误响应里带 `download_url`，直接改用 `want="url"` 拿链接后 curl 下载；大图可加 `max_width` 降采样或 `format="webp"` 减体积 |
| 某状态样式查不到 | 设计稿未提供，纪律包中有清单；不要虚构，找设计师确认 |
| 响应里只有 `standard_note`、没有 `standard_*` 数据 | 该平台暂无规范层（如 admin），或规范层维护中；实测层字段不受影响，可照常使用 |
| 规范层与实测层数值对不上 | 正常现象（规范层是目标态、实测层是设计稿现状）：新画页面按规范层，复现存量按实测层；具体看 `standard.adjudication_conclusions` |

## License

Apache-2.0
