@urovotest/urovosdk-docs-mcp 1.0.1

package/README.md

@@ -0,0 +1,176 @@
+# @urovotest/urovosdk-docs-mcp
+
+UrovoSDK 文档 MCP（stdio），知识库打进 npm 包，供 Cursor 通过 `npx` 离线使用。
+
+- **npm 包名**：`@urovotest/urovosdk-docs-mcp`
+- **覆盖范围**：Pinpad、Printer、Scanner、EMV、读卡、安装等 POS 终端 SDK 文档
+- **入口**：`src/launch.js`（`bin` 同名）
+
+## Cursor 配置
+
+### 生产（推荐）
+
+从 npm registry 拉取，每次 MCP 启动时自动检查是否有更新：
+
+```json
+{
+  "mcpServers": {
+    "urovosdk": {
+      "command": "npx",
+      "args": ["-y", "@urovotest/urovosdk-docs-mcp@latest"]
+    }
+  }
+}
+```
+
+完整示例见 [`cursor-mcp.example.json`](cursor-mcp.example.json)。
+
+### 本地开发（`file:`）
+
+直接指向仓库内 npx 包，**必须**设置 `DOCS_MCP_SKIP_UPDATE=1`，否则会尝试从 registry 拉取并覆盖本地：
+
+```json
+{
+  "mcpServers": {
+    "urovosdk": {
+      "command": "npx",
+      "args": ["-y", "file:D:/path/to/UrovoSDK/ai-kit/npx/urovosdk-docs-mcp"],
+      "env": {
+        "DOCS_MCP_SKIP_UPDATE": "1"
+      }
+    }
+  }
+}
+```
+
+完整示例见 [`cursor-mcp.local.example.json`](cursor-mcp.local.example.json)。
+
+## MCP Tools
+
+| Tool | 说明 |
+|------|------|
+| `search_urovosdk_docs` | 全文搜索 |
+| `lookup_urovosdk_api` | 按模块/方法/类路径查 API |
+| `lookup_urovosdk_emv` | EMV 域查询 |
+| `lookup_urovosdk_error_code` | Pinpad/Printer 错误码 |
+| `get_urovosdk_doc` / `list_urovosdk_docs` | 读文档 |
+
+## 版本号在哪里
+
+| 字段 | 文件 | 说明 |
+|------|------|------|
+| **npm 包版本（发版必改）** | 本目录 [`package.json`](package.json) 的 `"version"` | 发布到 registry 的版本号，也是 `check-update` 比较的「当前版本」 |
+| MCP 协议版本 | `src/lib/create-mcp-server.js` 内 `version` | MCP Server 元信息，与 npm 版本独立 |
+| 知识库索引版本 | `docs/search-index.json` 的 `"version"` | 知识库生成时写入，随 `bundle` 同步 |
+
+**发版前必须递增** `package.json` 的 `version`（semver：`major.minor.patch`）。若只改文档/代码但未升版本，`npm publish` 会被 registry 拒绝（同版本不可重复发布）。
+
+## 启动与自动更新（check-update）
+
+启动链路：
+
+```
+Cursor 执行 npx -y @urovotest/urovosdk-docs-mcp@latest
+  → launch.js
+  → ensureLatestFromRegistry()
+  → server.js（stdio MCP）
+```
+
+### `@latest` 与 check-update 的关系
+
+两层机制配合，目的都是让用户尽量跑到 registry 上的最新包：
+
+1. **npx `@latest`**：Cursor 每次启动 MCP 时，npx 会解析并下载 registry 上 `@latest` 指向的版本（若本地缓存不是最新）。
+2. **check-update（启动时二次校验）**：`launch.js` 启动后读取**当前已安装包**的 `package.json.version`，请求 registry 的 `GET /{包名}/latest`，若 registry 版本 **semver 更大**，则 `npx -y {包名}@{新版本}` 重新 exec 当前进程并退出旧进程。
+
+因此：即使用户 Cursor 配置里写死 `@1.0.0`，只要该旧包内的 `check-update` 逻辑存在且 registry 有更高版本，仍可能在启动时被拉到新版本（除非设置了 `DOCS_MCP_SKIP_UPDATE=1`）。
+
+### 判定逻辑（`src/lib/check-update.js`）
+
+1. 若 `DOCS_MCP_SKIP_UPDATE=1` → 跳过，直接启动 MCP。
+2. 读取本包 `package.json` → `current`。
+3. `fetch` `{DOCS_MCP_REGISTRY 或 https://registry.npmjs.org}/@urovotest%2Furovosdk-docs-mcp/latest`（scoped 包路径编码，超时 8s）。
+4. 网络失败 / 404 → 打日志，**不阻断**，用当前 bundled 版本继续。
+5. `isNewer(latest, current)`：按 `.` 分段比较整数（如 `1.0.1` > `1.0.0`）。
+6. 若 `latest` 更新 → stderr 输出 `>> @urovotest/urovosdk-docs-mcp: vX -> vY`，spawn `npx -y @urovotest/urovosdk-docs-mcp@Y`（子进程带 `DOCS_MCP_SKIP_UPDATE=1` 防止递归），当前进程退出。
+
+### 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `DOCS_MCP_SKIP_UPDATE` | 未设置 | 设为 `1` 跳过 registry 检查（本地 `file:` 开发必设） |
+| `DOCS_MCP_REGISTRY` | `https://registry.npmjs.org` | 自定义 npm registry（内网 mirror 等） |
+
+日志前缀均为 `>>`，便于 Cursor MCP 输出过滤。
+
+## 发版流程
+
+在 **ai-kit/scripts** 目录执行一站式发版向导（无需再 cd 到 npx 子目录）：
+
+```bat
+cd UrovoSDK\ai-kit\scripts
+run.bat deploy          :: 可选：若 docs 有变更，先生成知识库 + 索引
+bundle-npx.bat          :: 输入新版本（回车=patch+1）→ bundle → verify → npm publish
+```
+
+仅同步知识库、不升版本、不 publish：
+
+```bat
+bundle-npx.bat --bundle-only
+```
+
+手动分步（跳过向导时）：
+
+```bat
+cd ..\npx\urovosdk-docs-mcp
+:: 编辑 package.json version
+npm run bundle
+npm run verify
+npm publish
+```
+
+说明：
+
+- `npm publish` / `npm pack` 前会自动执行 `prepack` → `scripts/bundle.js`，再次同步知识库与源码。
+- `bundle.js` 来源：`../../docs/`、`../../mcp-server/src/lib/`（`create-mcp-server.js`、`docs-tools.js`）、`../_shared/check-update.js`。
+- 若 `docs/search-index.json` 不存在，bundle 会失败并提示先 `run.bat deploy`。
+
+### 发版检查清单
+
+- [ ] `run.bat deploy` 或等价步骤已更新 `ai-kit/docs/`
+- [ ] `bundle-npx.bat` 或 `npm run bundle` 成功
+- [ ] `package.json` 的 `version` 已递增
+- [ ] `npm run verify` 通过（可选）
+- [ ] `npm publish` 成功
+- [ ] 同事 Cursor 重启 MCP 后 stderr 出现 `vX (latest)` 或 `v旧 -> v新`
+
+## 常见问题
+
+**Q：改了知识库但用户 npx 没更新？**  
+A：确认已 `npm publish` 且 **version 已递增**；让用户重启 Cursor MCP。配置建议使用 `@latest`。
+
+**Q：本地 `file:` 调试时被拉成 registry 版本？**  
+A：在 mcp.json 的 `env` 中加 `"DOCS_MCP_SKIP_UPDATE": "1"`。
+
+**Q：registry 404 / 网络不通？**  
+A：check-update 会跳过，使用当前包内 bundled 文档，MCP 仍可工作。
+
+**Q：与 Tomcat / HTTP MCP（:3101）的关系？**  
+A：npx 包**不依赖** Tomcat；文档全部在包内 `docs/`。HTTP MCP 适合局域网共享（`http://<LAN_IP>:3101/mcp`），npx 适合每人本机离线。二者知识库来源相同（ai-kit `docs/`），需分别 deploy / bundle / publish。
+
+**Q：与 ScanSDK-U100 npx 包的区别？**  
+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)。
+
+## 维护者路径速查
+
+```
+UrovoSDK/ai-kit/
+  docs/                          # 知识库（deploy 生成）
+  mcp-server/src/lib/            # MCP 业务逻辑（bundle 复制源）
+  npx/_shared/check-update.js    # 自动更新（bundle 复制源）
+  npx/urovosdk-docs-mcp/         # 本 npm 包（registry 名 @urovotest/urovosdk-docs-mcp）
+    package.json                 # version 发版入口
+    src/launch.js                # bin 入口
+    src/lib/check-update.js      # bundle 产物
+    docs/                        # bundle 产物
+```

package/docs/00-overview.md

@@ -0,0 +1,37 @@
+---
+title: UrovoSDK 总览
+module: urovosdk
+version: 1.0.24.10
+tags: ["overview"]
+---
+# UrovoSDK 知识库总览
+
+POS 终端 SDK 知识库：**不依赖 UrovoSDK/Code 工程**，权威源为 `docs/source/*.md` + 结构化模块文档。
+
+## 统计
+
+- General API：**157** 条（17 模块）
+- EMV API：**79** 条（4 模块）
+- api-registry 条目：**238**
+
+## 文档结构
+
+| 路径 | 说明 |
+|------|------|
+| [docs/source/](../source/) | 原始规范 Markdown（唯一维护入口） |
+| [module-index.md](02-reference/module-index.md) | 模块索引 |
+| [02-reference/general/](02-reference/general/) | 蜂鸣器/密码键盘/打印/扫码/读卡等 |
+| [02-reference/emv/](02-reference/emv/) | EMV 内核 API/回调/枚举 |
+| [02-reference/undocumented/](02-reference/undocumented/) | Demo 发现、官方未收录 API |
+| [error-codes.md](02-reference/error-codes.md) | Pinpad / Printer 错误码 |
+| [api-registry.json](api-registry.json) | MCP 精确查询注册表 |
+| [01-integration/quickstart-zh.md](01-integration/quickstart-zh.md) | AAR 接入 |
+| [01-integration/android-permissions.md](01-integration/android-permissions.md) | 权限参考 |
+
+## MCP Tools
+
+- `search_urovosdk_docs` — 全文搜索
+- `lookup_urovosdk_api` — 按模块/方法/类路径查 API
+- `lookup_urovosdk_emv` — EMV 域精确查询
+- `lookup_urovosdk_error_code` — Pinpad/Printer 错误码
+- `get_urovosdk_doc` / `list_urovosdk_docs`

package/docs/01-integration/android-permissions.md

@@ -0,0 +1,22 @@
+---
+title: Android 权限
+module: integration
+tags: ["permissions"]
+---
+# Android 权限参考
+
+UrovoSDK Demo 曾使用的权限清单（接入时按实际模块裁剪）：
+
+| 权限 | 典型用途 |
+|------|----------|
+| `CAMERA` | 扫码 |
+| `NFC` / `CLOUDPOS_CONTACTLESS_CARD` | 非接读卡 |
+| `INTERNET` / `ACCESS_NETWORK_STATE` | 网络 |
+| `READ/WRITE_EXTERNAL_STORAGE` / `MANAGE_EXTERNAL_STORAGE` | 日志、固件 |
+| `READ_PHONE_STATE` 等 | 设备信息 |
+| `BLUETOOTH_*` | 蓝牙外设 |
+| `WRITE_SETTINGS` / `WRITE_SECURE_SETTINGS` | 系统设置（需系统签名或特权） |
+| `SYSTEM_ALERT_WINDOW` | 悬浮窗 |
+| `VIBRATE` / `FLASHLIGHT` | 提示 |
+
+完整列表以目标设备系统要求为准。

package/docs/01-integration/quickstart-zh.md

@@ -0,0 +1,54 @@
+---
+title: 快速接入
+module: integration
+tags: ["quickstart"]
+---
+# UrovoSDK 快速接入
+
+## 产物
+
+- **AAR：** `urovoSdkLibs_New_v1.0.24.10_{debug|release}.aar`
+- **版本：** 1.0.24.10（versionCode 24）
+- **NDK ABI：** armeabi-v7a、arm64-v8a
+- **minSdk：** 21 · **compileSdk：** 33
+
+## 依赖 JAR（放入 app libs/）
+
+| 文件 | 用途 |
+|------|------|
+| `pminstall.jar` | 静默安装 |
+| `DecoderLibrary-release.jar` | 扫码解码 |
+| `SerialPortSdk-v2.0.8.jar` | 串口 |
+| `urovosdkEmvLibs-v1.0.14.jar` | EMV 内核 |
+| `platform_sdk_20260519_01.jar` | 平台 DeviceManager |
+
+## Gradle 示例
+
+```gradle
+dependencies {
+    implementation files('libs/urovoSdkLibs_New_v1.0.24.10_release.aar')
+    implementation files('libs/pminstall.jar')
+    implementation files('libs/DecoderLibrary-release.jar')
+    implementation files('libs/SerialPortSdk-v2.0.8.jar')
+    implementation files('libs/urovosdkEmvLibs-v1.0.14.jar')
+    implementation files('libs/platform_sdk_20260519_01.jar')
+}
+```
+
+## 最小示例
+
+```java
+BeeperImpl.getInstance().startBeep(1, 100);
+InnerScannerImpl.getInstance().startScan(context, listener);
+EmvNfcKernelApi.getInstance().startKernel(params);
+```
+
+## 权限
+
+详见 [android-permissions.md](./android-permissions.md)。
+
+## 知识库
+
+- API：`02-reference/general/`、`02-reference/emv/`
+- 源规范：`docs/source/`（可独立维护，不依赖工程源码）
+- MCP：`search_urovosdk_docs`、`lookup_urovosdk_api`