@cueai/omni-reader-mcp

Omni Bridge 是 Agent 中统一的本地 stdio facade。用户只需提供来源，Bridge 通过同一个 parse(source) 自动处理 HTTPS URL 或已授权目录中的本地文件，无需选择“本地/远程”“上传/URL”或内部服务。

用户旅程

直接告诉 Agent 来源和后续任务：

用 Omni 解析 ./report.pdf
用 Omni 解析 https://example.com/report.pdf
用 Omni 解析 ./report.pdf 并总结营收变化

URL 不要求安装 Bridge。本地文件首次使用时，Agent 应先说明最小目录授权、数据处理方式并取得确认，再安装固定版本 Bridge。解析完成后，Agent 应继续摘要、问答或字段抽取等原始任务，而不是止于“解析完成”。

要求

• Node.js 20.12 或更新版本。
• Cue API Key：https://cuecue.cn/api-key。
• 新账号有免费积分可体验；当前赠送和每日额度以服务端 onboarding policy 与 doctor 输出为准。
• 请在 Agent 的安全密钥或本机环境设置中配置 CUE_API_KEY。请勿把 API Key 粘贴到对话中。

Bridge 运行时只使用以下产品配置：

• CUE_API_KEY
• OMNI_ALLOWED_ROOTS

OMNI_ALLOWED_ROOTS 只用于用户明确授权的额外绝对目录；macOS/Linux 使用冒号分隔，Windows 使用分号分隔。当前 Agent workspace 仍是默认允许范围。

安装与配置

始终使用已审核的精确版本，不使用隐式 latest：

npx -y @cueai/[email protected] setup

交互 setup 支持 Hermes、Cursor、Claude Desktop 和通用 stdio 配置。非交互安装使用同一参数解析和写入逻辑：

npx -y @cueai/[email protected] setup --client hermes --allowed-root /absolute/minimum/root --yes --json
npx -y @cueai/[email protected] setup --client cursor --add-root /absolute/minimum/root --yes --json
npx -y @cueai/[email protected] setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json

setup 会：

1. 展示 user-scope 配置目标和变更；
2. 写入单一、精确版本的 omni-reader facade；
3. 使用私有 lock、可信备份和原子替换；
4. 验证 Omni 安全解析环境；
5. 验证失败时恢复原配置；
6. 提示对应 Agent reload 或 restart。

配置不会写入 API Key 明文。Hermes 使用原生的独立 command、args 和安全环境变量引用。

Agent 调用规则

Agent 将用户提供的来源字符串直接传给 parse(source)：

• 只有 HTTP(S) 被视为 URL；普通字符串按本地路径处理。
• Do not read, attach, base64-encode, or insert the file content into the conversation before calling Omni.
• 不使用 file://、localhost 或公共临时上传站点作为回退。
• 安装 Bridge 或扩大 allowed root 前必须确认。
• 状态恢复优先使用已有 operation_id；不得为超时重复上传或重复创建解析。

公开工具固定为：

• parse
• get_parse_status
• cancel_parse
• read_result
• discard_result

每个工具都返回 structuredContent 和严格 outputSchema。

前台、后台和进度

每次解析的前台预算固定为 15 秒：

• 15 秒内完成：直接返回完整结果。
• 超过 15 秒：返回可恢复的 processing operation。
• 客户端明确请求且支持 MCP Tasks 时，Bridge 使用 task。
• 其他客户端使用 get_parse_status 的有界轮询；不承诺客户端不支持的主动通知。

processing/task 状态只包含 operation、stage、百分比和可选权威单位进度。可用单位仅为 page、sheet、slide、frame、segment。状态中不包含结果正文、预览、Markdown、页面图片、裁剪图片或累计部分输出。

数据处理与保留

URL 和本地文件都使用强制 no-store 语义并进入 Omni 安全解析环境：

• 用户电脑上的原始本地文件保持 unchanged；URL 来源也不会被修改或删除。
• Omni 创建的处理副本和临时数据在完成后主动清理。
• 加密交付数据在 ACK 后删除；未确认 ACK 时最迟在 10 分钟交付窗口到期。
• 只有远端 ACK 和清理已确认后才返回 completed。
• 本地结果已保留但远端清理仍不确定时返回 cleanup_pending，不会提前声称已删除。
• 超过 64 KiB 的结果可以保存在用户私有 Bridge cache，最长 24 小时；这与远端 10 分钟交付窗口是两类不同数据。
• read_result 分块读取本地结果；discard_result 可立即删除指定结果；clean 清理 Bridge 创建的本地 artifact 和到期记录。

状态查询、结果读取和丢弃不会创建新的解析或 usage event。cancel_parse 只报告服务端确认的真实结算状态，不会自行造成第二次计费。

约束错误

Bridge 在 grant、上传和计费前验证本地来源：

• SOURCE_TOO_LARGE：超过当前 256 MiB 上限，并返回机器可读 constraints.max_bytes。
• UNSUPPORTED_MEDIA_TYPE：媒体类型不受支持，并返回当前权威 supported_extensions。

Agent 不应自动拆分、转码或上传公共站点；应请用户提供符合约束的新来源。

命令

npx -y @cueai/[email protected] doctor
npx -y @cueai/[email protected] doctor --json
npx -y @cueai/[email protected] clean
npx -y @cueai/[email protected] uninstall --yes --json

不带命令运行固定版本会启动 stdio MCP server：

npx -y @cueai/[email protected]

doctor --json 返回 package/npm/client adapter、Key present/absent、allowed-root 安全状态、endpoint compatibility、artifact、cache mode、onboarding 和 reload 状态；不会输出 Key、私有来源路径或内容。

卸载与回滚

uninstall --yes --json 只删除当前受信的 1.1.0 Bridge entry；存在匹配的可信备份时恢复原 URL-only omni-reader entry。卸载不会删除用户源文件，也不会静默删除未过期的本地结果。

需要回滚 1.1.0 时：

1. 停止推荐或安装该版本；
2. 运行 uninstall --yes --json 恢复可信 URL-only entry；
3. 对已经上传的 operation 继续使用状态恢复，让结算和清理完成；
4. 保留本地结果，或由用户显式运行 discard_result / clean。