@urovotest/urovosdk-docs-mcp 1.0.1 → 1.0.2
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 +24 -146
- package/docs/api-registry.json +1 -1
- package/docs/search-index.json +1 -1
- package/package.json +1 -1
- package/src/lib/create-mcp-server.js +14 -3
package/README.md
CHANGED
|
@@ -1,16 +1,13 @@
|
|
|
1
1
|
# @urovotest/urovosdk-docs-mcp
|
|
2
2
|
|
|
3
|
-
UrovoSDK 文档 MCP
|
|
3
|
+
UrovoSDK 文档 MCP 服务。知识库内置在 npm 包中，通过 `npx` 在 Cursor 等 AI 编辑器中离线查阅 SDK 文档。
|
|
4
4
|
|
|
5
|
-
-
|
|
6
|
-
-
|
|
7
|
-
- **入口**：`src/launch.js`（`bin` 同名）
|
|
5
|
+
- **覆盖范围**：Pinpad、Printer、Scanner、EMV、读卡、安装等 POS 终端 SDK
|
|
6
|
+
- **Node.js**：>= 18
|
|
8
7
|
|
|
9
|
-
## Cursor
|
|
8
|
+
## 在 Cursor 中使用
|
|
10
9
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
从 npm registry 拉取，每次 MCP 启动时自动检查是否有更新：
|
|
10
|
+
在 **Cursor Settings → MCP** 中添加：
|
|
14
11
|
|
|
15
12
|
```json
|
|
16
13
|
{
|
|
@@ -23,154 +20,35 @@ UrovoSDK 文档 MCP（stdio），知识库打进 npm 包，供 Cursor 通过 `np
|
|
|
23
20
|
}
|
|
24
21
|
```
|
|
25
22
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
### 本地开发（`file:`）
|
|
29
|
-
|
|
30
|
-
直接指向仓库内 npx 包，**必须**设置 `DOCS_MCP_SKIP_UPDATE=1`，否则会尝试从 registry 拉取并覆盖本地：
|
|
31
|
-
|
|
32
|
-
```json
|
|
33
|
-
{
|
|
34
|
-
"mcpServers": {
|
|
35
|
-
"urovosdk": {
|
|
36
|
-
"command": "npx",
|
|
37
|
-
"args": ["-y", "file:D:/path/to/UrovoSDK/ai-kit/npx/urovosdk-docs-mcp"],
|
|
38
|
-
"env": {
|
|
39
|
-
"DOCS_MCP_SKIP_UPDATE": "1"
|
|
40
|
-
}
|
|
41
|
-
}
|
|
42
|
-
}
|
|
43
|
-
}
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
完整示例见 [`cursor-mcp.local.example.json`](cursor-mcp.local.example.json)。
|
|
23
|
+
保存后重启 Cursor，或刷新 MCP 连接。
|
|
47
24
|
|
|
48
25
|
## MCP Tools
|
|
49
26
|
|
|
50
27
|
| Tool | 说明 |
|
|
51
28
|
|------|------|
|
|
52
|
-
| `search_urovosdk_docs` |
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
|
|
58
|
-
## 版本号在哪里
|
|
59
|
-
|
|
60
|
-
| 字段 | 文件 | 说明 |
|
|
61
|
-
|------|------|------|
|
|
62
|
-
| **npm 包版本（发版必改）** | 本目录 [`package.json`](package.json) 的 `"version"` | 发布到 registry 的版本号，也是 `check-update` 比较的「当前版本」 |
|
|
63
|
-
| MCP 协议版本 | `src/lib/create-mcp-server.js` 内 `version` | MCP Server 元信息，与 npm 版本独立 |
|
|
64
|
-
| 知识库索引版本 | `docs/search-index.json` 的 `"version"` | 知识库生成时写入，随 `bundle` 同步 |
|
|
65
|
-
|
|
66
|
-
**发版前必须递增** `package.json` 的 `version`（semver：`major.minor.patch`）。若只改文档/代码但未升版本，`npm publish` 会被 registry 拒绝（同版本不可重复发布）。
|
|
67
|
-
|
|
68
|
-
## 启动与自动更新（check-update）
|
|
69
|
-
|
|
70
|
-
启动链路：
|
|
71
|
-
|
|
72
|
-
```
|
|
73
|
-
Cursor 执行 npx -y @urovotest/urovosdk-docs-mcp@latest
|
|
74
|
-
→ launch.js
|
|
75
|
-
→ ensureLatestFromRegistry()
|
|
76
|
-
→ server.js（stdio MCP）
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
### `@latest` 与 check-update 的关系
|
|
80
|
-
|
|
81
|
-
两层机制配合，目的都是让用户尽量跑到 registry 上的最新包：
|
|
29
|
+
| `search_urovosdk_docs` | 全文搜索文档 |
|
|
30
|
+
| `list_urovosdk_docs` | 列出全部文档路径 |
|
|
31
|
+
| `get_urovosdk_doc` | 按路径读取完整文档 |
|
|
32
|
+
| `lookup_urovosdk_api` | 按模块 / 方法 / 类路径查 API |
|
|
33
|
+
| `lookup_urovosdk_emv` | 查询 EMV 内核 API、回调、枚举 |
|
|
34
|
+
| `lookup_urovosdk_error_code` | 查询 Pinpad / Printer 错误码 |
|
|
82
35
|
|
|
83
|
-
|
|
84
|
-
2. **check-update（启动时二次校验）**：`launch.js` 启动后读取**当前已安装包**的 `package.json.version`，请求 registry 的 `GET /{包名}/latest`，若 registry 版本 **semver 更大**，则 `npx -y {包名}@{新版本}` 重新 exec 当前进程并退出旧进程。
|
|
36
|
+
## 自动更新
|
|
85
37
|
|
|
86
|
-
|
|
38
|
+
每次 MCP 启动时会检查 npm registry 是否有更新版本；若有则自动拉取并重启。无需手动升级。
|
|
87
39
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
3. `fetch` `{DOCS_MCP_REGISTRY 或 https://registry.npmjs.org}/@urovotest%2Furovosdk-docs-mcp/latest`（scoped 包路径编码，超时 8s）。
|
|
93
|
-
4. 网络失败 / 404 → 打日志，**不阻断**，用当前 bundled 版本继续。
|
|
94
|
-
5. `isNewer(latest, current)`：按 `.` 分段比较整数（如 `1.0.1` > `1.0.0`）。
|
|
95
|
-
6. 若 `latest` 更新 → stderr 输出 `>> @urovotest/urovosdk-docs-mcp: vX -> vY`，spawn `npx -y @urovotest/urovosdk-docs-mcp@Y`（子进程带 `DOCS_MCP_SKIP_UPDATE=1` 防止递归），当前进程退出。
|
|
96
|
-
|
|
97
|
-
### 环境变量
|
|
98
|
-
|
|
99
|
-
| 变量 | 默认值 | 说明 |
|
|
100
|
-
|------|--------|------|
|
|
101
|
-
| `DOCS_MCP_SKIP_UPDATE` | 未设置 | 设为 `1` 跳过 registry 检查（本地 `file:` 开发必设） |
|
|
102
|
-
| `DOCS_MCP_REGISTRY` | `https://registry.npmjs.org` | 自定义 npm registry（内网 mirror 等） |
|
|
103
|
-
|
|
104
|
-
日志前缀均为 `>>`，便于 Cursor MCP 输出过滤。
|
|
105
|
-
|
|
106
|
-
## 发版流程
|
|
107
|
-
|
|
108
|
-
在 **ai-kit/scripts** 目录执行一站式发版向导（无需再 cd 到 npx 子目录）：
|
|
109
|
-
|
|
110
|
-
```bat
|
|
111
|
-
cd UrovoSDK\ai-kit\scripts
|
|
112
|
-
run.bat deploy :: 可选：若 docs 有变更，先生成知识库 + 索引
|
|
113
|
-
bundle-npx.bat :: 输入新版本（回车=patch+1）→ bundle → verify → npm publish
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
仅同步知识库、不升版本、不 publish：
|
|
117
|
-
|
|
118
|
-
```bat
|
|
119
|
-
bundle-npx.bat --bundle-only
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
手动分步（跳过向导时）：
|
|
123
|
-
|
|
124
|
-
```bat
|
|
125
|
-
cd ..\npx\urovosdk-docs-mcp
|
|
126
|
-
:: 编辑 package.json version
|
|
127
|
-
npm run bundle
|
|
128
|
-
npm run verify
|
|
129
|
-
npm publish
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
说明：
|
|
133
|
-
|
|
134
|
-
- `npm publish` / `npm pack` 前会自动执行 `prepack` → `scripts/bundle.js`，再次同步知识库与源码。
|
|
135
|
-
- `bundle.js` 来源：`../../docs/`、`../../mcp-server/src/lib/`（`create-mcp-server.js`、`docs-tools.js`）、`../_shared/check-update.js`。
|
|
136
|
-
- 若 `docs/search-index.json` 不存在，bundle 会失败并提示先 `run.bat deploy`。
|
|
137
|
-
|
|
138
|
-
### 发版检查清单
|
|
139
|
-
|
|
140
|
-
- [ ] `run.bat deploy` 或等价步骤已更新 `ai-kit/docs/`
|
|
141
|
-
- [ ] `bundle-npx.bat` 或 `npm run bundle` 成功
|
|
142
|
-
- [ ] `package.json` 的 `version` 已递增
|
|
143
|
-
- [ ] `npm run verify` 通过（可选）
|
|
144
|
-
- [ ] `npm publish` 成功
|
|
145
|
-
- [ ] 同事 Cursor 重启 MCP 后 stderr 出现 `vX (latest)` 或 `v旧 -> v新`
|
|
40
|
+
| 环境变量 | 说明 |
|
|
41
|
+
|----------|------|
|
|
42
|
+
| `DOCS_MCP_SKIP_UPDATE=1` | 跳过更新检查 |
|
|
43
|
+
| `DOCS_MCP_REGISTRY` | 自定义 npm registry（默认 `https://registry.npmjs.org`） |
|
|
146
44
|
|
|
147
45
|
## 常见问题
|
|
148
46
|
|
|
149
|
-
|
|
150
|
-
|
|
47
|
+
**文档没更新？**
|
|
48
|
+
确认维护方已发布新版本，然后重启 Cursor MCP。配置建议使用 `@latest`。
|
|
151
49
|
|
|
152
|
-
**
|
|
153
|
-
|
|
50
|
+
**registry 无法访问？**
|
|
51
|
+
自动更新会跳过，使用当前包内文档，MCP 仍可正常工作。
|
|
154
52
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
**Q：与 Tomcat / HTTP MCP（:3101）的关系？**
|
|
159
|
-
A：npx 包**不依赖** Tomcat；文档全部在包内 `docs/`。HTTP MCP 适合局域网共享（`http://<LAN_IP>:3101/mcp`），npx 适合每人本机离线。二者知识库来源相同（ai-kit `docs/`），需分别 deploy / bundle / publish。
|
|
160
|
-
|
|
161
|
-
**Q：与 ScanSDK-U100 npx 包的区别？**
|
|
162
|
-
A：独立 npm 包、独立知识库与 Tool 前缀（`urovosdk_*` vs `scansdk_u100_*`）。check-update 与环境变量机制相同，详见 [`ScanSDK/ai-kit/npx/scansdk-u100-docs-mcp/README.md`](../../../../ScanSDK/ai-kit/npx/scansdk-u100-docs-mcp/README.md)。
|
|
163
|
-
|
|
164
|
-
## 维护者路径速查
|
|
165
|
-
|
|
166
|
-
```
|
|
167
|
-
UrovoSDK/ai-kit/
|
|
168
|
-
docs/ # 知识库（deploy 生成）
|
|
169
|
-
mcp-server/src/lib/ # MCP 业务逻辑（bundle 复制源）
|
|
170
|
-
npx/_shared/check-update.js # 自动更新（bundle 复制源）
|
|
171
|
-
npx/urovosdk-docs-mcp/ # 本 npm 包（registry 名 @urovotest/urovosdk-docs-mcp）
|
|
172
|
-
package.json # version 发版入口
|
|
173
|
-
src/launch.js # bin 入口
|
|
174
|
-
src/lib/check-update.js # bundle 产物
|
|
175
|
-
docs/ # bundle 产物
|
|
176
|
-
```
|
|
53
|
+
**与 ScanSDK-U100 npx 包的区别？**
|
|
54
|
+
独立 npm 包、独立知识库。UrovoSDK 工具名带 `urovosdk_` 前缀；ScanSDK-U100 为 `@urovotest/scansdk-u100-docs-mcp`。
|
package/docs/api-registry.json
CHANGED
package/docs/search-index.json
CHANGED
package/package.json
CHANGED
|
@@ -2,19 +2,30 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
|
|
2
2
|
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
|
3
3
|
import { createDocsTools, callTool } from "./docs-tools.js";
|
|
4
4
|
|
|
5
|
+
const UROVO_MCP_INSTRUCTIONS =
|
|
6
|
+
"UrovoSDK POS terminal SDK docs: Pinpad, Printer, EMV, read card, install, and general POS modules. " +
|
|
7
|
+
"Do NOT use Scanner module here when user mentions U100, 69PC, SK100, ScanSDK-U100, ScannerSDK, 码制, 串口扫码, or dedicated hardware scanner config — " +
|
|
8
|
+
"use @urovotest/scansdk-u100-docs-mcp (scansdk_u100_* tools) instead. " +
|
|
9
|
+
"UrovoSDK Scanner (InnerScannerImpl) is camera-based scan UI for general POS; it is NOT ScanSDK-U100 hardware documentation.";
|
|
10
|
+
|
|
11
|
+
const SCANSDK_U100_KEYWORDS = "U100, 69PC, SK100, ScanSDK, ScannerSDK, 码制, 串口扫码";
|
|
12
|
+
|
|
5
13
|
export function createUrovoSdkMcpServer(options = {}) {
|
|
6
14
|
const tools = createDocsTools(options);
|
|
7
15
|
|
|
8
16
|
const server = new Server(
|
|
9
17
|
{ name: "urovosdk-docs", version: "1.0.0" },
|
|
10
|
-
{ capabilities: { tools: {} } }
|
|
18
|
+
{ capabilities: { tools: {} }, instructions: UROVO_MCP_INSTRUCTIONS }
|
|
11
19
|
);
|
|
12
20
|
|
|
13
21
|
server.setRequestHandler(ListToolsRequestSchema, async () => ({
|
|
14
22
|
tools: [
|
|
15
23
|
{
|
|
16
24
|
name: "search_urovosdk_docs",
|
|
17
|
-
description:
|
|
25
|
+
description:
|
|
26
|
+
"Search UrovoSDK docs (Pinpad, Printer, EMV, read card, install). " +
|
|
27
|
+
`NOT for ${SCANSDK_U100_KEYWORDS} hardware scanner — use scansdk-u100 MCP instead. ` +
|
|
28
|
+
"Use for POS integration excluding ScanSDK-U100 dedicated scanner.",
|
|
18
29
|
inputSchema: {
|
|
19
30
|
type: "object",
|
|
20
31
|
properties: { query: { type: "string" }, limit: { type: "number" } },
|
|
@@ -42,7 +53,7 @@ export function createUrovoSdkMcpServer(options = {}) {
|
|
|
42
53
|
type: "object",
|
|
43
54
|
properties: {
|
|
44
55
|
domain: { type: "string", description: "general | emv | undocumented" },
|
|
45
|
-
module: { type: "string", description:
|
|
56
|
+
module: { type: "string", description: `e.g. Pinpad, Printer, EMV API. For Scanner on ${SCANSDK_U100_KEYWORDS}, use scansdk-u100 MCP, not module=Scanner here.` },
|
|
46
57
|
method: { type: "string" },
|
|
47
58
|
classPath: { type: "string" },
|
|
48
59
|
keyword: { type: "string" },
|