@reglow/review-mcp 0.1.0

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.
Files changed (15) hide show
  1. package/README.md +238 -0
  2. package/catalog.mjs +537 -0
  3. package/cli-utils.mjs +29 -0
  4. package/index.mjs +192 -0
  5. package/integrations.mjs +270 -0
  6. package/knowledge.mjs +1130 -0
  7. package/package.json +48 -0
  8. package/server.mjs +742 -0
  9. package/setup.mjs +404 -0
  10. package/site.mjs +255 -0
  11. package/skills/review-components/BEST_PRACTICES.md +132 -0
  12. package/skills/review-components/COMPONENTS.md +216 -0
  13. package/skills/review-components/SKILL.md +138 -0
  14. package/skills/review-components/WORKFLOWS.md +435 -0
  15. package/skills.mjs +194 -0
package/README.md ADDED
@@ -0,0 +1,238 @@
1
+ # @reglow/review-mcp
2
+
3
+ ReView 组件库的 **MCP 服务器** 与 **Skills 知识包**，形态对齐同仓库的
4
+ [`@reglow/reui-mcp`](../../reui/mcp/README.md)：
5
+ MCP 负责「查得到」（组件文档 / 示例 / 源码 / 函数实现 / 检索 / 指南），
6
+ Skills 负责「怎么用」（uni_modules 安装、easycom、平台差异、主题、i18n 与常见陷阱）。
7
+
8
+ > ReView 是**基于 uni-app x（uts/uvue）的移动端组件库**，参考 TDesign 设计风格，
9
+ > 组件以 `uni_modules/reglow-review/` 安装，模板里用 `re-*` easycom 标签（如 `<re-button />`）。
10
+
11
+ ## 什么是 MCP？
12
+
13
+ Model Context Protocol（MCP）是一种标准化协议，用于连接 AI 助手与外部数据源和工具。通过 MCP，AI 助手可以动态发现和调用各种能力，而无需为每个工具单独集成。
14
+ MCP 的核心价值：
15
+
16
+ - 统一接口：提供标准化的方式让 AI 与外部系统交互
17
+ - 动态发现：AI 可以自动发现可用的工具和资源
18
+ - 易于扩展：新增工具只需实现 MCP 协议即可被 AI 使用
19
+
20
+ ## 什么是 Skills？
21
+
22
+ Skills（技能）是一种模块化的能力扩展方式，允许 AI 助手通过添加预定义的指令和工具来增强其功能。每个 Skill 包含详细的说明文档和相关的代码资源，使 AI 能够在特定任务中表现得更加专业和高效。
23
+ Skills 的核心价值：
24
+
25
+ - 领域专长：为 AI 添加特定领域的专业知识和最佳实践
26
+ - 标准化：统一团队的开发流程和规范
27
+ - 可复用：快速复用成功经验和解决方案
28
+
29
+ ## ⚠️ 前置说明：`@reglow/review` 未发布到 npm
30
+
31
+ 组件库**没有发到 npm**（`npm view @reglow/review` 返回 404），所以本 MCP **不做 npm 版本知识源**，
32
+ 知识只有两级来源：
33
+
34
+ | 来源 | 触发条件 | 内容 |
35
+ | -------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
36
+ | 本地 ReView 仓库 | `--root <review 仓库路径>`，或直接在仓库内运行（`mcp/` 的上一级即仓库根） | `docs/components/*.md`、`docs/guide/*.md`、`README.md`、`CHANGELOG.md`、组件源码、演示页 |
37
+ | 项目内安装包 | 当前工作目录含 `uni_modules/reglow-review`（自动识别） | 组件源码（无 `docs/` 与演示页，文档回退官网） |
38
+ | 官方文档站点（兜底） | 本地缺文档 / 未找到本地来源时 | 抓取 <https://reglow.huoli.tech/components-library/review> 并转 Markdown |
39
+
40
+ - 版本号从 `CHANGELOG.md` 顶部解析（当前 `1.0.6（2026-09-22）`），每次响应都会标注「知识源 + 组件库版本」。
41
+ - `version` 参数与 `--version` 保留（与 reui-mcp 的签名一致），但传值只会得到「未发布到 npm，请用 `--root`」的提示。
42
+
43
+ ## 快速开始
44
+
45
+ ### 0. 一键配置（推荐，Trae / CodeBuddy / Qoder / Cursor / Claude）
46
+
47
+ 一条命令同时写好 MCP 配置并安装 Skills：
48
+
49
+ ```bash
50
+ npx -y -p @reglow/review-mcp review-setup # 默认 trae,codebuddy,qoder
51
+ npx -y -p @reglow/review-mcp review-setup --tools trae,qoder # 指定工具
52
+ npx -y -p @reglow/review-mcp review-setup --tools all --scope user # 全部工具 / 用户级
53
+ npx -y -p @reglow/review-mcp review-setup --dry-run # 先预览再执行
54
+ ```
55
+
56
+ 等价写法：`npx -y @reglow/review-mcp --setup trae,codebuddy,qoder`。
57
+
58
+ 各工具的项目级落地位置与仍需手动完成的步骤：
59
+
60
+ | 工具 | Skills 目录 | MCP 配置文件 | 仍需手动完成 |
61
+ | ---------------------- | ------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
62
+ | **Trae** | `.trae/skills/<skill>/` | `.trae/mcp.json` | 设置 → MCP 打开「启用项目级 MCP」；用户级为 `%APPDATA%/Trae/User/mcp.json`（macOS/Linux 见 `--list-tools`） |
63
+ | **CodeBuddy** | `.codebuddy/skills/<skill>/` | `.mcp.json`（JSONC） | IDE 需在对话面板 CodeBuddy Settings → MCP → Add MCP 粘贴同一条目；CLI 直接生效；用户级 `~/.codebuddy/.mcp.json` |
64
+ | **Qoder** | `.qoder/skills/<skill>/` | `.mcp.json`（或 `.qoder/settings.json`） | 项目级 MCP 默认需批准（或 `mcp.enableAllProjectMcpServers: true`）；CLI 可 `qoder mcp add review-mcp -s project -- npx -y @reglow/review-mcp`；`/mcp reload` |
65
+ | Cursor / Claude / 通用 | `.cursor/skills/`、`.claude/skills/`、`.skills/` | `.cursor/mcp.json`、`.mcp.json` | 见 `review-setup --list-tools` 输出 |
66
+
67
+ - 写入是**幂等合并**：只增改 `mcpServers["review-mcp"]`，其它服务器与顶层字段保持不变；
68
+ 配置文件为非法 JSON 时默认报错不改动，`--force` 会先备份为 `*.bak` 再重写。
69
+ - 查看支持的工具与路径：`npx -y @reglow/review-mcp --list-tools`。
70
+ - 若工具里读不到完整文档，把 npx 参数补上仓库路径：
71
+ `{"command":"npx","args":["-y","@reglow/review-mcp","--root","D:/path/to/review"]}`。
72
+
73
+ ### 1. 手动配置 MCP（任意客户端）
74
+
75
+ 在 Trae / CodeBuddy / Qoder / Cursor / Claude Desktop 等客户端的 `mcpServers` 中加入：
76
+
77
+ ```json
78
+ {
79
+ "mcpServers": {
80
+ "review-mcp": {
81
+ "command": "npx",
82
+ "args": ["-y", "@reglow/review-mcp"]
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ 要读完整文档（含 `docs/` 与演示页）时，追加 `--root`：
89
+
90
+ ```json
91
+ {
92
+ "mcpServers": {
93
+ "review-mcp": {
94
+ "command": "npx",
95
+ "args": ["-y", "@reglow/review-mcp", "--root", "D:/path/to/review"]
96
+ }
97
+ }
98
+ }
99
+ ```
100
+
101
+ 命令行方式（Claude Code / Qoder CLI 等）：
102
+
103
+ ```bash
104
+ claude mcp add review-mcp -- npx -y @reglow/review-mcp
105
+ qoder mcp add review-mcp -s project -- npx -y @reglow/review-mcp
106
+ ```
107
+
108
+ ### 2. 仅安装 Skills 知识包
109
+
110
+ ```bash
111
+ npx -y -p @reglow/review-mcp review-skills # 默认写入 .trae/skills
112
+ npx -y -p @reglow/review-mcp review-skills --target qoder # .qoder/skills
113
+ npx -y -p @reglow/review-mcp review-skills --target codebuddy # .codebuddy/skills
114
+ npx -y -p @reglow/review-mcp review-skills --all # 全部已知工具目录
115
+ npx -y -p @reglow/review-mcp review-skills --list # 查看可用目标
116
+ ```
117
+
118
+ 也可通过主命令安装：`npx -y @reglow/review-mcp --install-skills --target trae`。
119
+
120
+ 安装后在项目中的位置：
121
+
122
+ ```
123
+ <project>/.trae/skills/review-components/
124
+ ├── SKILL.md 技能入口（何时使用 + 组件库关键事实 + 硬性规则 + 文件导航）
125
+ ├── WORKFLOWS.md MCP 工具工作流与 6 个完整任务示例
126
+ ├── BEST_PRACTICES.md 安装、easycom、平台差异、主题、i18n、性能与常见陷阱
127
+ └── COMPONENTS.md 按分类的组件选型清单（tag + 用途 + 文档路径）
128
+ ```
129
+
130
+ ## 工具（Tools）
131
+
132
+ | 工具 | 参数 | 用途 |
133
+ | -------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
134
+ | `get_review_document` | `component?` `category?` `version?` `source?` | 不传 `component` 返回按分类的组件总览（含 easycom 标签、演示页可用性、官网链接）；传则返回完整文档与 API 表格 |
135
+ | `get_review_code_examples` | `component` `index?` `lang?` `version?` | 从官方演示页提取可复制的 uvue 片段（按 `<!-- 小节标题 -->` 切分），保留小节标题 |
136
+ | `list_component_files` | `component` `version?` | 组件源码文件清单（路径 / 行数 / 字节） |
137
+ | `get_file_code` | `component` `file` `startLine?` `endLine?` `version?` | 读取组件目录内文件内容（带路径穿越防护），读 `type Props` / `withDefaults` 用 |
138
+ | `get_function_code` | `component` `name` `file?` `version?` | 提取函数 / 常量 / 类 / `type` 定义的完整实现；未命中时返回相近与可用符号 |
139
+ | `search_review_docs` | `query?` `keywords?` `component?` `category?` `limit?` `version?` | 跨组件文档、演示页、源码与库级文档检索（多关键词「全部命中」），返回 `文件:行号 + 上下文 + 文档链接` |
140
+ | `get_review_guide` | `topic?` `version?` | 库级指南章节：`overview` / `install` / `easycom` / `theme` / `i18n` / `platform` / `changelog` / `conventions` |
141
+
142
+ - 组件名用 kebab-case 且**不带** `re-` 前缀（`button`、`search-history`），也接受 easycom 标签写法（`re-button`）。
143
+ - `version` 参数保留以对齐 reui-mcp，但本库未发布 npm，传值只会得到提示。
144
+ - 所有返回都以「知识源 + 组件库版本 + 版本来源」开头（如 `知识源：本地 ReView 仓库｜组件库版本：1.0.5（2026-09-14）`），
145
+ 当内容来自官方文档站点兜底时会额外标注 ⚠️，避免 AI 误判文档版本。
146
+
147
+ ## 知识来源
148
+
149
+ | 来源 | 触发条件 | 内容 |
150
+ | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
151
+ | 本地 ReView 仓库 | `--root <dir>` / `REVIEW_ROOT` / 在仓库内运行（默认） | 组件文档 + 全部源码 + 演示页 + `README.md` / `CHANGELOG.md` / `docs/guide/*.md` |
152
+ | 项目内 uni_modules | 工作目录含 `uni_modules/reglow-review` | 仅组件源码（文档与官方链接回退官网） |
153
+ | 官方文档站点 | 本地缺文档、或未找到本地来源 | <https://reglow.huoli.tech/components-library/review> 组件页 / 指南页 / 版本记录页 |
154
+
155
+ - 组件分类以 `docs/.vitepress/sidebar.ts` 为权威（9 个分类，与官网 `components/<category>/<name>` 路由段一致）。
156
+ - `uni_modules/reglow-review/components/*/readme.md` 是脚本生成的**二次编码文本（中文乱码）**，
157
+ 因此不作为文档正文，也不参与检索；读文件时会标注 `⚠️ 该文件是脚本生成的二次编码文本`。
158
+ - `--no-site` 可完全离线（仅本地仓库）。
159
+
160
+ ## CLI 选项
161
+
162
+ | 选项 | 说明 |
163
+ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
164
+ | `--root <dir>` | 指定 ReView 仓库工作区（未指定时自动识别仓库 / 项目内的 `uni_modules/reglow-review`） |
165
+ | `--version <ver>` | 指定知识版本；因未发布 npm，只会给出提示（不带值时打印本包版本号，等价 `-v`） |
166
+ | `--no-site` | 禁用官方文档站点兜底（完全离线） |
167
+ | `--check` | 自检：打印知识源、版本、分类与组件数量后退出 |
168
+ | `--setup [tools]` | 一键配置 AI 工具（MCP 配置 + Skills），默认 `trae,codebuddy,qoder`；支持 `--scope user`、`--dry-run`、`--force`、`--skills-only`、`--mcp-only` |
169
+ | `--list-tools` | 列出支持的工具、MCP 配置路径（项目级 / 用户级）与 Skills 目录 |
170
+ | `--install-skills` | 安装 Skills 知识包（可配合 `--target` / `--all` / `--force`） |
171
+ | `--print-config` | 打印 MCP 客户端配置片段 |
172
+ | `-v` / `-h, --help` | 版本 / 帮助 |
173
+
174
+ 三个可执行入口（bin）：
175
+
176
+ | 命令 | 作用 |
177
+ | --------------- | ------------------------------------------------------------------------------------------------ |
178
+ | `review-mcp` | MCP stdio 服务器（默认行为）；另提供 `--check` / `--setup` / `--install-skills` / `--list-tools` |
179
+ | `review-setup` | 为 Trae / CodeBuddy / Qoder 等一键写 MCP 配置 + 安装 Skills |
180
+ | `review-skills` | 仅把 Skills 知识包装到指定工具目录 |
181
+
182
+ ```bash
183
+ # 自检示例
184
+ npx -y @reglow/review-mcp --check
185
+ # 查看各工具路径
186
+ npx -y @reglow/review-mcp --list-tools
187
+ ```
188
+
189
+ ## 开发与测试
190
+
191
+ ```bash
192
+ # 安装依赖（SDK 与测试工具只在本子包内，ReView 消费方不受影响）
193
+ cd mcp && npm install
194
+
195
+ # 单测（含用官方 SDK Client 连接真实 stdio 服务器的端到端用例）
196
+ npm test # 在 mcp/ 目录，vitest 由本子包 devDependencies 提供
197
+ ```
198
+
199
+ 仓库根也提供了同名脚本（`npm run mcp` / `mcp:check` / `setup` / `skills` / `test:mcp`）；
200
+ 其中 `test:mcp` 直接调用 `vitest`，需根目录能解析到 vitest（如在根目录安装过该依赖）。
201
+
202
+ 目录结构：
203
+
204
+ ```
205
+ mcp/
206
+ ├── index.mjs bin：review-mcp（stdio 服务器入口 / --check / --setup / --install-skills）
207
+ ├── server.mjs MCP 服务器与 7 个工具的实现
208
+ ├── knowledge.mjs 知识源：本地仓库 / 安装包 / 官网兜底 + 符号提取、演示页示例与检索
209
+ ├── catalog.mjs 组件目录（解析 sidebar.ts 分类 + 扫描 docs / uni_modules / pages）
210
+ ├── site.mjs 官网 HTML → Markdown 兜底抓取（组件页 / 指南页 / 版本记录页）
211
+ ├── integrations.mjs AI 工具集成规格（Trae / CodeBuddy / Qoder / Cursor / Claude 的 MCP 配置与 Skills 目录）
212
+ ├── setup.mjs bin：review-setup（一键写 MCP 配置 + 装 Skills，含 JSONC 解析与幂等合并）
213
+ ├── skills.mjs bin：review-skills（仅安装 Skills 知识包）
214
+ ├── skills/ 内置 Skills 知识包（随包发布）
215
+ └── __tests__/ 单测（knowledge / site / skills / setup / server 端到端）
216
+ ```
217
+
218
+ > ⚠️ stdio 模式下 **stdout 仅供协议通信**，日志一律走 stderr。
219
+
220
+ ## 发布
221
+
222
+ `@reglow/review-mcp` 与 `@reglow/review` 是两个独立包（同仓库、可分别发布，互不拖累依赖）：
223
+
224
+ ```bash
225
+ cd mcp
226
+ npm version patch # 按需
227
+ npm publish # 需要 npm 登录且有 @reglow 权限
228
+ ```
229
+
230
+ `files` 已包含 `skills/`，因此 Skills 知识包随 MCP 包一起发布，版本一致。
231
+
232
+ ## 相关资源
233
+
234
+ - 官方文档站点：<https://reglow.huoli.tech/components-library/review>
235
+ - ReView 仓库：<https://gitee.com/reglow-ai/review>
236
+ - 同构实现（Vue 3 后台组件库）：<https://gitee.com/reglow-ai/reui>
237
+ - Model Context Protocol：<https://modelcontextprotocol.io/>
238
+ - Agent Skills：<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview>