Metadata-Version: 2.4
Name: canpoint-ui-mcp
Version: 0.5.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**：色彩语义、字体字号、间距、圆角、投影与布局密度。
- **查小程序完整规范**：31 个规范主题，覆盖视觉风格、组件、页面、交互、素材及验收；可查询 53 个规则条目，含课程详情的专用组件。
- **查组件规格**：侧边导航、表格、表单、弹窗、Tab、分页、状态标签、步骤条、
  空态等组件的尺寸、颜色与状态变体
- **按页面类型取模式卡**：布局结构与已定义的区域尺寸、
  组件组合、状态清单、新画页 checklist，直接按卡施工——admin 覆盖列表页/
  详情页/表单弹窗/数据看板等 9 类页面，mini 覆盖首页/课程列表/订单表单/
  我的页等 14 类页面
- **拿生成纪律**：生成页面前必须遵守的规则包（版本基准、断点事实、
  设计稿未提供的状态清单等），避免虚构不存在的样式
- **取官方素材**：图标/插画/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`（详细组件与规则条目） |
| `get_component_spec(platform, component)` | 查单个组件完整规格，支持中文名与模糊匹配（如"表格"→list）；均命中时同时返回 `spec`（摘要）与 `standard_spec`（详细规则） |
| `get_generation_rules(platform)` | 生成 UI 前必读的纪律包；若有规范层，另返回 `standard`（风格、信息层级、素材、交互、交付物、验收与待补页面） |
| `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 |

## 小程序规范查询

小程序的摘要、页面模式和详细规则采用同一套设计师规范：

| 内容 | 字段 |
|---|---|
| 视觉变量和组件摘要 | `tokens`、`components`、`spec` |
| 详细变量、组件属性和适用范围 | `standard_tokens`、`standard_components`、`standard_spec` |
| 页面结构、尺寸、状态与验收 | `pattern`、`standard_constraints` |
| 生成与交付规则 | `standard.discipline` |

按组件和页面范围应用专用值。未指定的区域尺寸为 `null`，由内容和设备宽度决定，不能当作零尺寸。admin 按其返回的 token、组件与模式卡使用。

## 前置条件

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` 读规则 →
> `list_page_patterns` / `get_page_pattern` 选择页面结构 → `get_tokens` / `get_component_spec`
> 查组件与专用值 → `list_assets` / `get_asset` 取官方素材 → 按模式与验收清单实现 →
> 截图交给 `verify_ui` 辅助检查颜色，同时人工或浏览器核对布局、文字、状态与交互。

## 常见问题

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

## License

Apache-2.0
