canpoint-ui-mcp 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -30
- package/package.json +2 -11
package/README.md
CHANGED
|
@@ -1,40 +1,48 @@
|
|
|
1
1
|
# canpoint-ui-mcp
|
|
2
2
|
|
|
3
|
-
UI 规范查询 MCP
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
支持 MCP 的工具里用 `npx` 直接配置。
|
|
3
|
+
研学产品线的 **UI 规范查询 MCP 服务**。在 Claude Code / Cursor 等支持 MCP 的
|
|
4
|
+
AI 工具里接入后，AI 可以随时查询「研学小程序」与「研学后台」的官方设计规范，
|
|
5
|
+
按规范生成和自检页面，不再凭空发挥。
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
由远程服务做 allowlist 投影，客户端只拿到 token、组件规格、生成纪律与截图
|
|
10
|
-
色彩校验结论。
|
|
7
|
+
## 能帮你做什么
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
- **查设计 token**：色彩（主色/语义色/状态色/中性色阶）、字体字号阶梯、间距、
|
|
10
|
+
圆角、投影、布局密度，全部来自设计稿实测值
|
|
11
|
+
- **查组件规格**：侧边导航、表格、表单、弹窗、Tab、分页、状态标签、步骤条、
|
|
12
|
+
空态等组件的尺寸、颜色与状态变体
|
|
13
|
+
- **拿生成纪律**：生成页面前必须遵守的规则包（版本基准、断点事实、
|
|
14
|
+
设计稿未提供的状态清单等），避免虚构不存在的样式
|
|
15
|
+
- **截图校验**：把生成好的页面截图交给 `verify_ui`，逐色比对官方规范并给出
|
|
16
|
+
PASS/FAIL 结论，不达标精确到哪个颜色差多少
|
|
13
17
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
18
|
+
## 工具一览
|
|
19
|
+
|
|
20
|
+
| 工具 | 用途 |
|
|
21
|
+
|------|------|
|
|
22
|
+
| `list_platforms` | 列出可用平台（mini=研学小程序，admin=研学后台）与数据状态，建议会话开始先调用 |
|
|
23
|
+
| `get_tokens(platform, category)` | 按类别查 token：color / typography / spacing / shape / elevation / layout，category 留空返回全部 |
|
|
24
|
+
| `list_components(platform)` | 列出该平台全部组件规范条目 |
|
|
25
|
+
| `get_component_spec(platform, component)` | 查单个组件完整规格，支持中文名与模糊匹配（如"表格"→list） |
|
|
26
|
+
| `get_generation_rules(platform)` | 生成 UI 前必读的纪律包 |
|
|
27
|
+
| `verify_ui(platform, image_base64)` | 对生成页面截图做色彩校验，返回逐色偏差与 PASS/FAIL |
|
|
20
28
|
|
|
21
29
|
## 前置条件
|
|
22
30
|
|
|
23
|
-
|
|
24
|
-
|
|
31
|
+
1. 已安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)（提供 `uvx` 命令）
|
|
32
|
+
2. 向服务管理员获取：**服务地址** 与 **API key**（`usk_` 前缀，按人发放）
|
|
25
33
|
|
|
26
34
|
## 配置
|
|
27
35
|
|
|
28
|
-
|
|
36
|
+
两个环境变量必填：
|
|
29
37
|
|
|
30
38
|
| 变量 | 说明 |
|
|
31
39
|
|------|------|
|
|
32
|
-
| `UI_SPEC_SERVER_URL` |
|
|
33
|
-
| `UI_SPEC_API_KEY` |
|
|
40
|
+
| `UI_SPEC_SERVER_URL` | 服务地址（管理员提供，不带 `/mcp` 后缀） |
|
|
41
|
+
| `UI_SPEC_API_KEY` | 管理员发放的 key |
|
|
34
42
|
|
|
35
|
-
可选：`UI_SPEC_TIMEOUT
|
|
43
|
+
可选：`UI_SPEC_TIMEOUT`（超时秒数，默认 30）、`UI_SPEC_LOG_LEVEL`（默认 INFO）。
|
|
36
44
|
|
|
37
|
-
Claude Code
|
|
45
|
+
**Claude Code**（项目 `.mcp.json` 或全局配置）：
|
|
38
46
|
|
|
39
47
|
```json
|
|
40
48
|
{
|
|
@@ -43,7 +51,7 @@ Claude Code 配置示例（`.mcp.json`）：
|
|
|
43
51
|
"command": "npx",
|
|
44
52
|
"args": ["-y", "canpoint-ui-mcp"],
|
|
45
53
|
"env": {
|
|
46
|
-
"UI_SPEC_SERVER_URL": "
|
|
54
|
+
"UI_SPEC_SERVER_URL": "<管理员提供的服务地址>",
|
|
47
55
|
"UI_SPEC_API_KEY": "usk_<你的key>"
|
|
48
56
|
}
|
|
49
57
|
}
|
|
@@ -51,20 +59,34 @@ Claude Code 配置示例（`.mcp.json`）：
|
|
|
51
59
|
}
|
|
52
60
|
```
|
|
53
61
|
|
|
54
|
-
Cursor
|
|
55
|
-
`cmd`、`args` 改为 `["/c", "npx", "-y", "canpoint-ui-mcp"]`（env 表不变）。
|
|
62
|
+
**Cursor**：`mcp.json` 同款配置。
|
|
56
63
|
|
|
57
|
-
|
|
64
|
+
Windows 下若 `npx` 启动失败，把 `command` 改为 `cmd`、`args` 改为
|
|
65
|
+
`["/c", "npx", "-y", "canpoint-ui-mcp"]`（env 不变）。
|
|
66
|
+
|
|
67
|
+
不走 npm 也可以直接用：
|
|
58
68
|
|
|
59
69
|
```bash
|
|
60
|
-
UI_SPEC_SERVER_URL
|
|
70
|
+
UI_SPEC_SERVER_URL=<服务地址> UI_SPEC_API_KEY=usk_xxx uvx canpoint-ui-mcp
|
|
61
71
|
```
|
|
62
72
|
|
|
63
|
-
|
|
64
|
-
|
|
73
|
+
## 推荐用法（给接入方的 AI 提示词参考）
|
|
74
|
+
|
|
75
|
+
> 生成研学前端页面前：先 `list_platforms` 确认平台 → `get_generation_rules`
|
|
76
|
+
> 读纪律 → `get_tokens` / `get_component_spec` 取规格 → 生成 →
|
|
77
|
+
> 截图交给 `verify_ui` 自检，FAIL 则按报告修正后重验。
|
|
65
78
|
|
|
66
|
-
|
|
79
|
+
## 常见问题
|
|
80
|
+
|
|
81
|
+
| 现象 | 处理 |
|
|
82
|
+
|------|------|
|
|
83
|
+
| 提示「认证或授权失败」 | key 错误/已吊销，联系管理员核对 |
|
|
84
|
+
| 提示「服务不可用」 | 服务地址填错或服务维护中，联系管理员 |
|
|
85
|
+
| 查询返回「规范数据未就绪」 | 该平台数据维护中，稍后再试或联系管理员 |
|
|
86
|
+
| 某状态样式查不到 | 设计稿未提供，纪律包中有清单；不要虚构，找设计师确认 |
|
|
67
87
|
|
|
68
88
|
## License
|
|
69
89
|
|
|
70
|
-
Apache-2.0
|
|
90
|
+
Apache-2.0
|
|
91
|
+
|
|
92
|
+
© 若清风
|
package/package.json
CHANGED
|
@@ -1,18 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "canpoint-ui-mcp",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "UI spec query MCP for
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "UI spec query MCP for the StudyTour product line: fetch official design tokens, component specs and generation rules for the mini-program and admin console, and verify generated-page screenshots against the spec.",
|
|
5
5
|
"author": "若清风",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
|
-
"homepage": "https://github.com/mjwyr/ui-knowledge",
|
|
8
|
-
"repository": {
|
|
9
|
-
"type": "git",
|
|
10
|
-
"url": "git+https://github.com/mjwyr/ui-knowledge.git",
|
|
11
|
-
"directory": "mcp-server/npm"
|
|
12
|
-
},
|
|
13
|
-
"bugs": {
|
|
14
|
-
"url": "https://github.com/mjwyr/ui-knowledge/issues"
|
|
15
|
-
},
|
|
16
7
|
"keywords": [
|
|
17
8
|
"mcp",
|
|
18
9
|
"model-context-protocol",
|