# 知一 MML解析工具本地 MCP Server

- MCP Server 版本：`1.3.8`
- Skill/集成版本：`1.3.8`
- 技术 ID：`mml-parser-zhiyisoft`
- 最低 MML解析工具 EXE：`1.3.8`
- 传输：本地 `stdio`，不监听网络端口
- 协议：`2025-11-25`，兼容 `2025-06-18`、`2025-03-26`、`2024-11-05`

## 安装

在本目录打开 PowerShell，执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

默认安装并配置 Codex、WorkBuddy、Cursor 和 Claude Desktop。只配置指定客户端：

```powershell
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Client Codex,WorkBuddy,VSCode
```

完全退出并重启客户端后，应看到 9 个工具：`mml_status`、`mml_get_release`、`mml_download_latest`、
`mml_start_trial`、`mml_preflight`、`mml_confirm_overage`、`mml_scan_start`、`mml_parse_start`、`mml_job_status`。

标准顺序为：身份验证 → 文件规模与权益预检 → 必要时由用户确认兑换 → 扫描报表 → 用户选择报表 →
采用用户设置或安全推荐默认值开始解析 → 从 0% 开始，每 5 秒查询、至少每 30 秒向用户汇报真实进度 → 报告完成结果。
推荐默认值为 CSV、部分拆分、不压缩；报表清单必须由用户显式选择或明确选择全部。

并发解析按所有输入文件的实际已读取字节聚合，占总进度 0%–95%；导出占 95%–99.5%；只有全部最终输出文件成功发布后才返回 100%。

单次仅解析 1 个 TXT 时不适用批次总大小、批次文件数和每日批次数限制，但仍检查单文件上限及每日累计 TXT 数量/大小；2 个及以上 TXT 才计为一个批次。正式解析授权后，后台调用记录显示“解析中”；成功结果上传后更新为“已完成”并扣减每日 TXT 数量/大小，失败则更新为“失败”且不扣额度。断网时签名结果保存在本地队列，恢复网络后补报。

## 手工配置位置

- Codex/ChatGPT 桌面版：`%USERPROFILE%\.codex\config.toml`，使用 `configs\codex.config.toml`。
- WorkBuddy：`%USERPROFILE%\.workbuddy\mcp.json`，使用 `configs\mcpServers.json`。
- Cursor：`%USERPROFILE%\.cursor\mcp.json`，使用 `configs\mcpServers.json`。
- Claude Desktop：`%APPDATA%\Claude\claude_desktop_config.json`，使用 `configs\mcpServers.json`。
- VS Code：用户 MCP 配置或项目 `.vscode\mcp.json`，使用 `configs\vscode.mcp.json`。
- 其他支持本地 stdio MCP 的客户端：命令填完整 EXE 路径，参数填 `--stdio`。

## 安全边界

TXT 正文只由本机 MML解析工具读取，不经 MCP 上传云端。下载软件、进入试用、消耗激活期扩展 AI 权益均会弹出
Windows 本机确认框；模型输出或客户端参数不能代替用户点击确认。服务只接受本机绝对路径，默认拒绝 UNC/网络路径。
主 EXE只接受当前官方 MCP/Bridge EXE 作为直接父进程；它计算父进程 SHA-256 和请求摘要，由云端与当前发布文件核对后签发
90 秒、单次使用、绑定设备公钥和请求摘要的授权。普通脚本、被修改的 Bridge、复制的旧请求和令牌重放都会被拒绝。
云端仍负责签名设备身份、试用/激活有效期、AI 权益限额和统计元数据。

AI响应经过 EXE 与 MCP 双层过滤，不返回激活码、许可证令牌、设备凭证、公私钥、原始设备指纹、硬件标识、
客户/订单信息、异常堆栈或本地解析日志。云端保存遥测前会把本地路径缩减为文件名。

当完整批次超过限制时，云端按所有超限维度计算满足本批目标所需的最少权益单位，并可在一次本机确认中兑换多天。
例如基础单批 20 个、每单位增加 10 个，解析 50 个文件会报价 3 个单位；仍受后台每日/用户累计天数上限和最低剩余有效期限制。

纯网页 AI、移动端 AI 或不支持本地 stdio MCP 的客户端不能直接使用本服务；它们无法启动本机 EXE。
- 安装脚本支持 Codex、CodeBuddy、WorkBuddy、Cursor、Claude Desktop 与 VS Code；修改 JSON/TOML 前会保留原配置并合并 `mml-parser-zhiyisoft`，不会覆盖其他 MCP。
- WorkBuddy 5.2.6 首次安装后，还需在“专家·技能·连接器 → 连接器 → 自定义连接器 → 配置 MCP”中保存一次配置，返回列表后只对 `mml-parser-zhiyisoft` 点击“信任”；显示“9/9 个工具已启用”才表示加载完成。该信任步骤必须由本机用户在 WorkBuddy 中完成，安装脚本不会绕过。
- CodeBuddy 配置文件为 `%USERPROFILE%\.codebuddy\mcp.json`。安装后必须重启客户端并确认出现九个 `mml_*` 工具。
- EXE 旧版直接解析 CLI 和旧 `--skill-request` 接口均已关闭；MCP/Skill 只能经云端哈希授权的官方 Bridge 调用 EXE。
- MCP 启动时必须通过 `--official-skill-root` 指向已安装的官方 Skill；每次调用会重新计算关键文件内容摘要，并由云端与当前发布 ZIP 比对。任何关键文件被修改、缺失或版本不一致都会返回 `official_skill_verification_failed` 并停止。
