@cueai/omni-reader-mcp 1.0.2 → 1.1.0

package/README.md

@@ -1,49 +1,138 @@
 # @cueai/omni-reader-mcp
 
-Local stdio MCP Bridge for parsing files from an Agent workspace through Omni Reader. Source bytes upload directly from the local Bridge to IIIS; they do not pass through Cube-MCP or the model conversation before `parse_document` is called.
+Omni Bridge 是 Agent 中统一的本地 stdio facade。用户只需提供来源，Bridge 通过同一个 `parse(source)` 自动处理 HTTPS URL 或已授权目录中的本地文件，无需选择“本地/远程”“上传/URL”或内部服务。
 
-## Requirements
+## 用户旅程
 
-- Node.js 20.12 or newer
-- A Cue API Key from <https://cuecue.cn/hub/api-key>
+直接告诉 Agent 来源和后续任务：
 
-## Setup
+```text
+用 Omni 解析 ./report.pdf
+用 Omni 解析 https://example.com/report.pdf
+用 Omni 解析 ./report.pdf 并总结营收变化
+```
 
-Set the existing general Cue API Key, then run the interactive user-scope setup:
+URL 不要求安装 Bridge。本地文件首次使用时，Agent 应先说明最小目录授权、数据处理方式并取得确认，再安装固定版本 Bridge。解析完成后，Agent 应继续摘要、问答或字段抽取等原始任务，而不是止于“解析完成”。
 
-```sh
-export CUE_API_KEY="YOUR_CUE_API_KEY"
-npx -y @cueai/omni-reader-mcp setup
-```
+## 要求
 
-Setup supports Cursor, Claude Desktop, and a generic MCP configuration for other Agents. The current working directory is allowed by default. To allow additional directories, provide them during setup or configure absolute paths in `OMNI_ALLOWED_ROOTS` (colon-separated on macOS/Linux and semicolon-separated on Windows).
+- Node.js 20.12 或更新版本。
+- Cue API Key：<https://cuecue.cn/api-key>。
+- 新账号有免费积分可体验；当前赠送和每日额度以服务端 onboarding policy 与 `doctor` 输出为准。
+- 请在 Agent 的安全密钥或本机环境设置中配置 `CUE_API_KEY`。**请勿把 API Key 粘贴到对话中。**
 
-The Bridge reads only these production environment variables:
+Bridge 运行时只使用以下产品配置：
 
 - `CUE_API_KEY`
 - `OMNI_ALLOWED_ROOTS`
 
-## Daily use
+`OMNI_ALLOWED_ROOTS` 只用于用户明确授权的额外绝对目录；macOS/Linux 使用冒号分隔，Windows 使用分号分隔。当前 Agent workspace 仍是默认允许范围。
 
-Tell the Agent the local path as ordinary text:
+## 安装与配置
 
-```text
-用 Omni 解析 ./report.pdf
+始终使用已审核的精确版本，不使用隐式 `latest`：
+
+```sh
+npx -y @cueai/omni-reader-mcp@1.1.0 setup
+```
+
+交互 setup 支持 Hermes、Cursor、Claude Desktop 和通用 stdio 配置。非交互安装使用同一参数解析和写入逻辑：
+
+```sh
+npx -y @cueai/omni-reader-mcp@1.1.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.1.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.1.0 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
 ```
 
-For local documents, pass the exact user-provided path to parse_document.
-Do not read, attach, base64-encode, or insert the file content into the
-conversation before calling this tool. Do not use @file as a prerequisite.
-Use parse_url for HTTP(S) URLs.
+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`
 
-Local parsing defaults to `no_store=true`. Files are restricted to configured roots, one regular file per invocation, with a maximum size of 256 MiB.
+每个工具都返回 `structuredContent` 和严格 `outputSchema`。
 
-## Commands
+## 前台、后台和进度
+
+每次解析的前台预算固定为 **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 不应自动拆分、转码或上传公共站点；应请用户提供符合约束的新来源。
+
+## 命令
+
+```sh
+npx -y @cueai/omni-reader-mcp@1.1.0 doctor
+npx -y @cueai/omni-reader-mcp@1.1.0 doctor --json
+npx -y @cueai/omni-reader-mcp@1.1.0 clean
+npx -y @cueai/omni-reader-mcp@1.1.0 uninstall --yes --json
+```
+
+不带命令运行固定版本会启动 stdio MCP server：
 
 ```sh
-npx -y @cueai/omni-reader-mcp setup
-npx -y @cueai/omni-reader-mcp doctor
-npx -y @cueai/omni-reader-mcp clean
+npx -y @cueai/omni-reader-mcp@1.1.0
 ```
 
-Running `npx -y @cueai/omni-reader-mcp` without a command starts the stdio MCP server.
+`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`。

package/dist/artifact-store.d.ts

@@ -11,8 +11,18 @@ export interface DefaultArtifactRootOptions {
     readonly homeDirectory?: string;
     readonly env?: Readonly<Record<string, string | undefined>>;
 }
+export interface SelectArtifactRootOptions extends DefaultArtifactRootOptions {
+    readonly projectDirectory: string;
+    readonly temporaryDirectory: string;
+}
+export interface SelectedArtifactRoot {
+    readonly mode: "default" | "fallback";
+    readonly rootDirectory: string;
+}
 export interface InlineResult extends ReleasedMetadata {
     readonly kind: "inline";
+    readonly resultId: string;
+    readonly expiresAt: string;
     readonly text: string;
 }
 export interface ArtifactResult extends ReleasedMetadata {
@@ -35,6 +45,7 @@ interface ArtifactFinalizeInput extends ReleasedMetadata {
     readonly resultId: string;
 }
 export declare function defaultArtifactRoot(options?: DefaultArtifactRootOptions): string;
+export declare function selectArtifactRoot(options: SelectArtifactRootOptions): Promise<SelectedArtifactRoot>;
 export declare class ArtifactStore {
     #private;
     private constructor();

package/dist/artifact-store.js

@@ -15,7 +15,9 @@ function artifactError(code, message, retryable = false) {
     return new OmniBridgeError({
         code,
         message,
+        operationCreated: true,
         fileUploaded: true,
+        parserStarted: true,
         billed: true,
         contentReleased: true,
         retryable,
@@ -25,7 +27,9 @@ function cacheError(code, message) {
     return new OmniBridgeError({
         code,
         message,
+        operationCreated: false,
         fileUploaded: false,
+        parserStarted: false,
         billed: false,
         contentReleased: false,
         retryable: false,
@@ -174,14 +178,6 @@ async function loadOrCreateKey(rootDirectory) {
     }
     return winner;
 }
-function decodeUtf8(bytes) {
-    try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-    }
-    catch {
-        throw artifactError("RESULT_ENCODING_INVALID", "The released result is not valid UTF-8.");
-    }
-}
 async function readUtf8Slice(handle, offset, maximumBytes, totalBytes) {
     const requested = Math.min(maximumBytes, totalBytes - offset);
     if (requested <= 0)
@@ -218,7 +214,7 @@ function parseMetadata(value, expectedResultId) {
         || record.resultId !== expectedResultId
         || typeof record.resultBytes !== "number"
         || !Number.isSafeInteger(record.resultBytes)
-        || record.resultBytes <= INLINE_RESULT_MAX_BYTES
+        || record.resultBytes < 0
         || typeof record.mediaType !== "string"
         || record.mediaType.length === 0
         || typeof record.resultDigest !== "string"
@@ -252,6 +248,61 @@ export function defaultArtifactRoot(options = {}) {
         : path.posix.join(homeDirectory, ".cache");
     return path.posix.join(cacheHome, "cue", "omni-reader-mcp");
 }
+async function selectionPathIdentity(candidate, platform) {
+    const paths = platform === "win32" ? path.win32 : path.posix;
+    const resolved = paths.resolve(candidate);
+    if (platform !== process.platform)
+        return resolved;
+    const suffix = [];
+    let current = resolved;
+    while (true) {
+        try {
+            return paths.join(await realpath(current), ...suffix);
+        }
+        catch (error) {
+            if (!errno(error, "ENOENT")) {
+                throw cacheError("ARTIFACT_CACHE_UNSAFE", "The automatic local artifact cache path could not be resolved safely.");
+            }
+            const parent = paths.dirname(current);
+            if (parent === current)
+                return resolved;
+            suffix.unshift(paths.basename(current));
+            current = parent;
+        }
+    }
+}
+function selectionPathsOverlap(left, right, platform) {
+    const paths = platform === "win32" ? path.win32 : path.posix;
+    const normalizedLeft = paths.resolve(left);
+    const normalizedRight = paths.resolve(right);
+    const contains = (parent, child) => {
+        const relative = paths.relative(parent, child);
+        return relative === "" || (relative !== ".." &&
+            !relative.startsWith(`..${paths.sep}`) &&
+            !paths.isAbsolute(relative));
+    };
+    return contains(normalizedLeft, normalizedRight) ||
+        contains(normalizedRight, normalizedLeft);
+}
+export async function selectArtifactRoot(options) {
+    const platform = options.platform ?? process.platform;
+    const rootDirectory = defaultArtifactRoot(options);
+    const [rootIdentity, projectIdentity, homeIdentity] = await Promise.all([
+        selectionPathIdentity(rootDirectory, platform),
+        selectionPathIdentity(options.projectDirectory, platform),
+        selectionPathIdentity(options.homeDirectory ?? os.homedir(), platform),
+    ]);
+    if (!selectionPathsOverlap(rootIdentity, projectIdentity, platform)) {
+        return { mode: "default", rootDirectory };
+    }
+    const paths = platform === "win32" ? path.win32 : path.posix;
+    const fallback = paths.join(options.temporaryDirectory, `cue-omni-reader-${createHash("sha256").update(homeIdentity, "utf8").digest("hex").slice(0, 16)}`);
+    const fallbackIdentity = await selectionPathIdentity(fallback, platform);
+    if (selectionPathsOverlap(fallbackIdentity, projectIdentity, platform)) {
+        throw cacheError("ARTIFACT_CACHE_UNSAFE", "The automatic local artifact cache fallback overlaps the project directory.");
+    }
+    return { mode: "fallback", rootDirectory: fallback };
+}
 export class ArtifactStore {
     #rootDirectory;
     #resultsDirectory;
@@ -563,7 +614,6 @@ export class LocalResultRetention {
     #decoder;
     #encodingInvalid = false;
     #received = 0;
-    #inlineChunks = [];
     #artifact;
     #result;
     constructor(store) {
@@ -584,16 +634,13 @@ export class LocalResultRetention {
             || metadata.mediaType.length === 0) {
             throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The released result metadata is invalid.");
         }
+        const temporary = await this.#store._newTemporaryArtifact();
         this.#start = metadata;
         this.#hash = createHash("sha256");
         this.#decoder = new TextDecoder("utf-8", { fatal: true });
         this.#encodingInvalid = false;
         this.#received = 0;
-        this.#inlineChunks = [];
-        if (metadata.resultBytes > INLINE_RESULT_MAX_BYTES) {
-            const temporary = await this.#store._newTemporaryArtifact();
-            this.#artifact = temporary;
-        }
+        this.#artifact = temporary;
     }
     async write(chunk) {
         if (this.#start === undefined || this.#hash === undefined || this.#decoder === undefined) {
@@ -614,23 +661,18 @@ export class LocalResultRetention {
                 this.#encodingInvalid = true;
             }
         }
-        if (this.#artifact === undefined) {
-            this.#inlineChunks.push(Buffer.from(chunk));
+        const handle = this.#artifact?.handle;
+        if (handle === undefined) {
+            throw artifactError("LOCAL_RESULT_STATE_INVALID", "The local artifact is not writable.");
         }
-        else {
-            const handle = this.#artifact.handle;
-            if (handle === undefined) {
-                throw artifactError("LOCAL_RESULT_STATE_INVALID", "The local artifact is not writable.");
-            }
-            let written = 0;
-            while (written < chunk.byteLength) {
-                const result = await handle.write(chunk, written, chunk.byteLength - written, null);
-                if (result.bytesWritten === 0) {
-                    await this.abort();
-                    throw artifactError("LOCAL_ARTIFACT_FAILED", "The local result artifact write stalled.", true);
-                }
-                written += result.bytesWritten;
+        let written = 0;
+        while (written < chunk.byteLength) {
+            const result = await handle.write(chunk, written, chunk.byteLength - written, null);
+            if (result.bytesWritten === 0) {
+                await this.abort();
+                throw artifactError("LOCAL_ARTIFACT_FAILED", "The local result artifact write stalled.", true);
             }
+            written += result.bytesWritten;
         }
         this.#received += chunk.byteLength;
     }
@@ -665,26 +707,33 @@ export class LocalResultRetention {
             if (computedDigest !== metadata.resultDigest) {
                 throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained result digest did not match.");
             }
-            if (this.#artifact === undefined) {
-                const bytes = Buffer.concat(this.#inlineChunks);
+            const artifact = this.#artifact;
+            const handle = artifact?.handle;
+            if (artifact === undefined || handle === undefined) {
+                throw artifactError("LOCAL_RESULT_STATE_INVALID", "The local artifact is not writable.");
+            }
+            await handle.sync();
+            await handle.close();
+            artifact.handle = undefined;
+            const stored = await this.#store._finalizeArtifact(artifact.temporaryPath, {
+                ...metadata,
+                resultId: artifact.resultId,
+            });
+            if (metadata.resultBytes <= INLINE_RESULT_MAX_BYTES) {
+                const recovered = await this.#store.read(stored.resultId, undefined, INLINE_RESULT_MAX_BYTES);
+                if (recovered.nextCursor !== undefined) {
+                    throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained inline result was not fully readable.");
+                }
                 this.#result = {
                     kind: "inline",
                     ...metadata,
-                    text: decodeUtf8(bytes),
+                    resultId: stored.resultId,
+                    expiresAt: stored.expiresAt,
+                    text: recovered.text,
                 };
             }
             else {
-                const handle = this.#artifact.handle;
-                if (handle === undefined) {
-                    throw artifactError("LOCAL_RESULT_STATE_INVALID", "The local artifact is not writable.");
-                }
-                await handle.sync();
-                await handle.close();
-                this.#artifact.handle = undefined;
-                this.#result = await this.#store._finalizeArtifact(this.#artifact.temporaryPath, {
-                    ...metadata,
-                    resultId: this.#artifact.resultId,
-                });
+                this.#result = stored;
             }
         }
         catch (error) {
@@ -706,12 +755,9 @@ export class LocalResultRetention {
         }
         if (artifact !== undefined) {
             await removeIfPresent(artifact.temporaryPath);
-            if (this.#result?.kind === "artifact") {
-                await this.#store.discard(this.#result.resultId);
-            }
+            await this.#store.discard(artifact.resultId);
         }
         this.#artifact = undefined;
-        this.#inlineChunks = [];
         this.#hash = undefined;
         this.#decoder = undefined;
         this.#received = 0;

package/dist/cli/agent-config.d.ts

@@ -1,10 +1,21 @@
-export type AgentTarget = "cursor" | "claude-desktop" | "generic";
+export type AgentTarget = "hermes" | "cursor" | "claude-desktop" | "generic";
+type NativeAgentTarget = Exclude<AgentTarget, "generic">;
+type AgentConfigFormat = "json" | "hermes-yaml";
 export interface AgentConfigEnvironment {
     readonly homeDirectory: string;
     readonly platform: NodeJS.Platform;
     readonly env?: Readonly<Record<string, string | undefined>>;
 }
 export type AgentConfigStatus = "configured" | "not configured" | "invalid or unreadable";
+interface JsonPreviousEntry {
+    readonly format: "json";
+    readonly value: unknown;
+}
+interface HermesPreviousEntry {
+    readonly format: "hermes-yaml";
+    readonly serialized: string;
+}
+type PreviousEntry = JsonPreviousEntry | HermesPreviousEntry;
 export interface PreparedAgentConfig {
     readonly target: AgentTarget;
     readonly configPath?: string;
@@ -15,14 +26,28 @@ export interface PreparedAgentConfig {
     readonly entry: Record<string, unknown>;
     readonly sourceFingerprint?: string;
     readonly environment?: AgentConfigEnvironment;
+    readonly reload: string;
+    readonly format?: AgentConfigFormat;
+    readonly serializedBefore?: string;
+    readonly serializedAfter?: string;
+    readonly previousEntry?: PreviousEntry | null;
 }
 export declare function parseAgentTarget(value: string): AgentTarget;
 export declare function agentConfigPath(target: AgentTarget, environment: AgentConfigEnvironment): string | undefined;
+export declare function agentBackupPath(configPath: string): string;
 export declare function displayConfigPath(configPath: string, environment: AgentConfigEnvironment): string;
-export declare function buildAgentEntry(extraRoots: readonly string[], platform: NodeJS.Platform): Record<string, unknown>;
+export declare function buildAgentEntry(target: AgentTarget, extraRoots: readonly string[], platform: NodeJS.Platform): Record<string, unknown>;
 export declare function prepareAgentConfig(target: AgentTarget, extraRoots: readonly string[], environment: AgentConfigEnvironment): Promise<PreparedAgentConfig>;
 export declare function verifyPreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;
 export declare function writePreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;
-export declare function inspectAgentConfig(configPath: string, environment?: AgentConfigEnvironment): Promise<AgentConfigStatus>;
-export declare function detectAgentTargets(environment: AgentConfigEnvironment): Promise<Array<Exclude<AgentTarget, "generic">>>;
+export declare function inspectAgentConfig(configPath: string, environment?: AgentConfigEnvironment, target?: NativeAgentTarget): Promise<AgentConfigStatus>;
+export declare function detectAgentTargets(environment: AgentConfigEnvironment): Promise<NativeAgentTarget[]>;
 export declare function configContainsOmni(configPath: string): Promise<boolean>;
+export declare function configuredAllowedRoots(target: AgentTarget, environment: AgentConfigEnvironment): Promise<string[]>;
+export declare function rollbackPreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;
+export interface UninstallAgentResult {
+    readonly target: NativeAgentTarget;
+    readonly restoredRemote: boolean;
+}
+export declare function uninstallAgentConfig(target: NativeAgentTarget, environment: AgentConfigEnvironment): Promise<UninstallAgentResult | undefined>;
+export {};