@cueai/omni-reader-mcp 1.0.0

package/dist/cli/setup.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+import { detectAgentTargets, parseAgentTarget, prepareAgentConfig, verifyPreparedAgentConfig, writePreparedAgentConfig, } from "./agent-config.js";
+import { checkHealth } from "./doctor.js";
+function parseExtraRoots(input, environment) {
+    const separator = environment.platform === "win32" ? ";" : ":";
+    const paths = environment.platform === "win32" ? path.win32 : path.posix;
+    return input.split(separator)
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)
+        .map((value) => {
+        const expanded = value === "~"
+            ? environment.homeDirectory
+            : value.startsWith(`~${paths.sep}`)
+                ? paths.join(environment.homeDirectory, value.slice(2))
+                : value;
+        if (!paths.isAbsolute(expanded)) {
+            throw new Error("Every additional allowed root must be an absolute path.");
+        }
+        return paths.normalize(expanded);
+    });
+}
+export async function runSetup(options) {
+    const labels = { cursor: "Cursor", "claude-desktop": "Claude Desktop" };
+    const detected = await detectAgentTargets(options);
+    const detectedLabel = detected.length === 0
+        ? "none"
+        : detected.map((target) => labels[target]).join(", ");
+    const selected = await options.ask(`Agent (Cursor / Claude Desktop / Other; Detected: ${detectedLabel}): `);
+    const target = parseAgentTarget(selected);
+    const extraRootInput = await options.ask("Additional allowed roots (optional): ");
+    const extraRoots = parseExtraRoots(extraRootInput, options);
+    const prepared = await prepareAgentConfig(target, extraRoots, options);
+    options.write(`Target: ${prepared.displayPath}\n`);
+    options.write("Before:\n");
+    options.write(`${JSON.stringify(prepared.before, null, 2)}\n`);
+    options.write("After:\n");
+    options.write(`${JSON.stringify(prepared.after, null, 2)}\n`);
+    const confirmation = (await options.ask("Apply this user-scope configuration? Type yes: ")).trim().toLowerCase();
+    if (confirmation !== "yes") {
+        options.write("No changes written.\n");
+        return;
+    }
+    await verifyPreparedAgentConfig(prepared);
+    const apiKey = options.env.CUE_API_KEY ?? "";
+    if (apiKey.length === 0) {
+        throw new Error("CUE_API_KEY is absent. Create one at https://cuecue.cn/hub/api-key and retry.");
+    }
+    options.write("Cue API Key: present\n");
+    await checkHealth(options.fetchImpl, apiKey);
+    if (prepared.configPath === undefined) {
+        options.write("Generic user-scope configuration:\n");
+        options.write(`${JSON.stringify({ mcpServers: { "omni-reader": prepared.entry } }, null, 2)}\n`);
+    }
+    else {
+        await writePreparedAgentConfig(prepared);
+        options.write(`Wrote ${prepared.displayPath}\n`);
+    }
+    options.write("用 Omni 解析 ./report.pdf\n");
+}

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const MAX_FILE_BYTES = 268435456;
+export declare const INLINE_RESULT_MAX_BYTES = 65536;
+export declare const ARTIFACT_TTL_MS: number;
+export declare const RESULT_CHUNK_MAX_BYTES = 65536;
+export declare const PROTOCOL_VERSION = "omni.direct_upload.v1";
+export declare const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
+export declare const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";

package/dist/constants.js

@@ -0,0 +1,7 @@
+export const MAX_FILE_BYTES = 268435456;
+export const INLINE_RESULT_MAX_BYTES = 65536;
+export const ARTIFACT_TTL_MS = 24 * 60 * 60 * 1000;
+export const RESULT_CHUNK_MAX_BYTES = 65536;
+export const PROTOCOL_VERSION = "omni.direct_upload.v1";
+export const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
+export const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";

package/dist/cube-client.d.ts

@@ -0,0 +1,48 @@
+import { OperationJournal } from "./operation-journal.js";
+declare const BRIDGE_PACKAGE = "@cue/omni-reader-mcp";
+declare const BRIDGE_VERSION = "1.0.0";
+export interface GrantRequestInput {
+    readonly contentLength: number;
+    readonly contentType: string;
+    readonly fileExtension: string;
+    readonly noStore: boolean;
+    readonly output: "markdown";
+}
+export interface GrantedOperation {
+    readonly clientRequestId: string;
+    readonly requestHash: string;
+    readonly grantId: string;
+    readonly operationId: string;
+    readonly parseGrant: string;
+    readonly operationToken: string;
+    readonly uploadUrl: string;
+    readonly expiresAt: string;
+    readonly maxBytes: number;
+    readonly protocolVersion: string;
+}
+export interface CubeGrantClientOptions {
+    readonly journal: OperationJournal;
+    readonly apiKey?: string;
+    readonly environment?: Pick<NodeJS.ProcessEnv, "CUE_API_KEY">;
+    readonly baseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+interface GrantRequestBody {
+    readonly content_length: number;
+    readonly content_type: string;
+    readonly file_extension: string;
+    readonly no_store: boolean;
+    readonly output: "markdown";
+    readonly bridge: {
+        readonly package: typeof BRIDGE_PACKAGE;
+        readonly version: typeof BRIDGE_VERSION;
+    };
+}
+export declare function grantRequestHash(body: GrantRequestBody): string;
+export declare function createClientRequestId(): string;
+export declare class CubeGrantClient {
+    #private;
+    constructor(options: CubeGrantClientOptions);
+    createGrant(input: GrantRequestInput, clientRequestId: string, signal?: AbortSignal): Promise<GrantedOperation>;
+}
+export {};

package/dist/cube-client.js

@@ -0,0 +1,161 @@
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import { DEFAULT_CUBE_BASE_URL, MAX_FILE_BYTES, PROTOCOL_VERSION, } from "./constants.js";
+import { OmniBridgeError } from "./errors.js";
+const GRANT_PATH = "/api/omni-reader/direct-upload/v1/parse-grants";
+const BRIDGE_PACKAGE = "@cue/omni-reader-mcp";
+const BRIDGE_VERSION = "1.0.0";
+const grantResponseSchema = z
+    .object({
+    grant_id: z.string().min(1),
+    operation_id: z.string().min(1),
+    parse_grant: z.string().min(1),
+    operation_token: z.string().min(1),
+    upload_url: z
+        .string()
+        .url()
+        .refine((value) => new URL(value).protocol === "https:"),
+    expires_at: z.string().datetime({ offset: true }),
+    max_bytes: z.literal(MAX_FILE_BYTES),
+    protocol_version: z.literal(PROTOCOL_VERSION),
+})
+    .strict();
+function bridgeError(code, message, retryable) {
+    return new OmniBridgeError({
+        code,
+        message,
+        fileUploaded: false,
+        billed: false,
+        contentReleased: false,
+        retryable,
+    });
+}
+function grantRequestBody(input) {
+    if (!Number.isSafeInteger(input.contentLength) ||
+        input.contentLength < 0 ||
+        input.contentLength > MAX_FILE_BYTES ||
+        !/^[^\s;/]+\/[^\s;]+$/u.test(input.contentType) ||
+        !/^\.[a-z0-9]{1,10}$/u.test(input.fileExtension) ||
+        typeof input.noStore !== "boolean" ||
+        input.output !== "markdown") {
+        throw bridgeError("INVALID_GRANT_REQUEST", "The local file metadata is invalid for a parse grant.", false);
+    }
+    return {
+        content_length: input.contentLength,
+        content_type: input.contentType,
+        file_extension: input.fileExtension,
+        no_store: input.noStore,
+        output: input.output,
+        bridge: {
+            package: BRIDGE_PACKAGE,
+            version: BRIDGE_VERSION,
+        },
+    };
+}
+export function grantRequestHash(body) {
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify(body), "utf8")
+        .digest("hex")}`;
+}
+export function createClientRequestId() {
+    return randomUUID();
+}
+function responseError(status) {
+    if (status === 401) {
+        return bridgeError("INVALID_CUE_API_KEY", "The Cue API Key is invalid or expired.", false);
+    }
+    if (status === 403) {
+        return bridgeError("OMNI_NOT_ENTITLED", "This Cue account is not entitled to use Omni Reader.", false);
+    }
+    if (status === 402) {
+        return bridgeError("INSUFFICIENT_BALANCE", "The Cue account does not have enough balance to start this parse.", false);
+    }
+    if (status === 409) {
+        return bridgeError("IDEMPOTENCY_COLLISION", "This grant request identifier is already bound to different metadata.", false);
+    }
+    if (status === 404) {
+        return bridgeError("DIRECT_UPLOAD_DISABLED", "Direct local-file parsing is not enabled on this Omni service.", false);
+    }
+    if (status === 429) {
+        return bridgeError("CUBE_BUSY", "Cube is temporarily busy. Retry this same grant request later.", true);
+    }
+    return bridgeError("CUBE_UNAVAILABLE", "Cube could not create the parse grant. Retry this same grant request later.", status >= 500);
+}
+export class CubeGrantClient {
+    #journal;
+    #apiKey;
+    #grantUrl;
+    #fetch;
+    constructor(options) {
+        this.#journal = options.journal;
+        this.#apiKey =
+            options.apiKey ??
+                options.environment?.CUE_API_KEY ??
+                process.env.CUE_API_KEY ??
+                "";
+        const baseUrl = new URL(options.baseUrl ?? DEFAULT_CUBE_BASE_URL);
+        if (baseUrl.protocol !== "https:" ||
+            baseUrl.username.length > 0 ||
+            baseUrl.password.length > 0) {
+            throw bridgeError("INSECURE_CUBE_BASE_URL", "The Cube control endpoint must use HTTPS without embedded credentials.", false);
+        }
+        this.#grantUrl = new URL(GRANT_PATH, baseUrl).toString();
+        this.#fetch = options.fetchImpl ?? fetch;
+    }
+    async createGrant(input, clientRequestId, signal) {
+        if (this.#apiKey.length === 0) {
+            throw bridgeError("MISSING_CUE_API_KEY", "Set CUE_API_KEY before using local Omni document parsing.", false);
+        }
+        const body = grantRequestBody(input);
+        const serializedBody = JSON.stringify(body);
+        const requestHash = grantRequestHash(body);
+        await this.#journal.begin(clientRequestId, requestHash);
+        let response;
+        try {
+            response = await this.#fetch(this.#grantUrl, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${this.#apiKey}`,
+                    "content-type": "application/json",
+                    "idempotency-key": clientRequestId,
+                },
+                body: serializedBody,
+                signal,
+            });
+        }
+        catch {
+            if (signal?.aborted) {
+                throw bridgeError("GRANT_REQUEST_CANCELED", "The parse grant request was canceled.", false);
+            }
+            throw bridgeError("CUBE_UNAVAILABLE", "Cube could not create the parse grant. Retry this same grant request later.", true);
+        }
+        if (!response.ok) {
+            throw responseError(response.status);
+        }
+        let parsed;
+        try {
+            parsed = grantResponseSchema.parse(await response.json());
+        }
+        catch {
+            throw bridgeError("CUBE_PROTOCOL_ERROR", "Cube returned an invalid parse grant response.", false);
+        }
+        await this.#journal.markGrantIssued(clientRequestId, {
+            operationId: parsed.operation_id,
+            operationToken: parsed.operation_token,
+            uploadUrl: parsed.upload_url,
+            expiresAt: parsed.expires_at,
+        });
+        return {
+            clientRequestId,
+            requestHash,
+            grantId: parsed.grant_id,
+            operationId: parsed.operation_id,
+            parseGrant: parsed.parse_grant,
+            operationToken: parsed.operation_token,
+            uploadUrl: parsed.upload_url,
+            expiresAt: parsed.expires_at,
+            maxBytes: parsed.max_bytes,
+            protocolVersion: parsed.protocol_version,
+        };
+    }
+}

package/dist/cursor.d.ts

@@ -0,0 +1,14 @@
+export interface CursorPayload {
+    readonly resultId: string;
+    readonly offset: number;
+    readonly expiresAt: string;
+}
+export interface CursorCodecOptions {
+    readonly now?: () => Date;
+}
+export declare class CursorCodec {
+    #private;
+    constructor(key: Uint8Array, options?: CursorCodecOptions);
+    encode(payload: CursorPayload): string;
+    decode(cursor: string): CursorPayload;
+}

package/dist/cursor.js

@@ -0,0 +1,101 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { OmniBridgeError } from "./errors.js";
+const CURSOR_VERSION = 1;
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+const RESULT_ID_PATTERN = /^result_[A-Za-z0-9_-]{16,64}$/;
+function cursorError(code, message) {
+    return new OmniBridgeError({
+        code,
+        message,
+        fileUploaded: true,
+        billed: true,
+        contentReleased: true,
+        retryable: false,
+    });
+}
+function decodeBase64Url(value) {
+    if (!BASE64URL_PATTERN.test(value)) {
+        throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+    }
+    const decoded = Buffer.from(value, "base64url");
+    if (decoded.toString("base64url") !== value) {
+        throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+    }
+    return decoded;
+}
+export class CursorCodec {
+    #key;
+    #now;
+    constructor(key, options = {}) {
+        if (key.byteLength !== 32)
+            throw new Error("cursor key must contain exactly 32 bytes");
+        this.#key = Buffer.from(key);
+        this.#now = options.now ?? (() => new Date());
+    }
+    encode(payload) {
+        this.#validatePayload(payload);
+        const encoded = Buffer.from(JSON.stringify({
+            version: CURSOR_VERSION,
+            resultId: payload.resultId,
+            offset: payload.offset,
+            expiresAt: payload.expiresAt,
+        }), "utf8").toString("base64url");
+        const signature = createHmac("sha256", this.#key).update(encoded).digest("base64url");
+        return `cursor_${encoded}.${signature}`;
+    }
+    decode(cursor) {
+        if (typeof cursor !== "string" || cursor.length > 2048 || !cursor.startsWith("cursor_")) {
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        const components = cursor.slice("cursor_".length).split(".");
+        if (components.length !== 2) {
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        const [encoded, encodedSignature] = components;
+        const signature = decodeBase64Url(encodedSignature);
+        const expected = createHmac("sha256", this.#key).update(encoded).digest();
+        if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) {
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        let value;
+        try {
+            value = JSON.parse(decodeBase64Url(encoded).toString("utf8"));
+        }
+        catch (error) {
+            if (error instanceof OmniBridgeError)
+                throw error;
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        const record = value;
+        if (Object.keys(record).sort().join(",") !== "expiresAt,offset,resultId,version"
+            || record.version !== CURSOR_VERSION
+            || typeof record.resultId !== "string"
+            || !RESULT_ID_PATTERN.test(record.resultId)
+            || typeof record.offset !== "number"
+            || !Number.isSafeInteger(record.offset)
+            || record.offset < 0
+            || typeof record.expiresAt !== "string"
+            || !Number.isFinite(Date.parse(record.expiresAt))) {
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        if (Date.parse(record.expiresAt) <= this.#now().getTime()) {
+            throw cursorError("RESULT_CURSOR_EXPIRED", "The result cursor has expired.");
+        }
+        return {
+            resultId: record.resultId,
+            offset: record.offset,
+            expiresAt: record.expiresAt,
+        };
+    }
+    #validatePayload(payload) {
+        if (!RESULT_ID_PATTERN.test(payload.resultId)
+            || !Number.isSafeInteger(payload.offset)
+            || payload.offset < 0
+            || !Number.isFinite(Date.parse(payload.expiresAt))) {
+            throw new Error("cursor payload is invalid");
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+export interface OmniBridgeErrorInit {
+    code: string;
+    message: string;
+    fileUploaded: boolean;
+    billed: boolean;
+    contentReleased: boolean;
+    retryable: boolean;
+}
+export interface OmniBridgeErrorPayload {
+    code: string;
+    message: string;
+    file_uploaded: boolean;
+    billed: boolean;
+    content_released: boolean;
+    retryable: boolean;
+}
+export declare class OmniBridgeError extends Error {
+    readonly code: string;
+    readonly fileUploaded: boolean;
+    readonly billed: boolean;
+    readonly contentReleased: boolean;
+    readonly retryable: boolean;
+    constructor(init: OmniBridgeErrorInit);
+    toJSON(): OmniBridgeErrorPayload;
+}

package/dist/errors.js

@@ -0,0 +1,26 @@
+export class OmniBridgeError extends Error {
+    code;
+    fileUploaded;
+    billed;
+    contentReleased;
+    retryable;
+    constructor(init) {
+        super(init.message);
+        this.name = "OmniBridgeError";
+        this.code = init.code;
+        this.fileUploaded = init.fileUploaded;
+        this.billed = init.billed;
+        this.contentReleased = init.contentReleased;
+        this.retryable = init.retryable;
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            file_uploaded: this.fileUploaded,
+            billed: this.billed,
+            content_released: this.contentReleased,
+            retryable: this.retryable,
+        };
+    }
+}

package/dist/iiis-client.d.ts

@@ -0,0 +1,43 @@
+import type { OpenedAllowedFile } from "./path-security.js";
+import { type ProgressSink } from "./progress.js";
+export interface ResultRetentionStart {
+    readonly operationId: string;
+    readonly resultBytes: number;
+    readonly mediaType: string;
+    readonly source: "sse" | "recovery";
+}
+export interface ReleasedMetadata extends ResultRetentionStart {
+    readonly resultDigest: string;
+}
+export interface ResultRetentionSink {
+    reset(): Promise<void>;
+    begin(metadata: ResultRetentionStart): Promise<void>;
+    write(chunk: Uint8Array): Promise<void>;
+    complete(metadata: ReleasedMetadata): Promise<void>;
+    abort(): Promise<void>;
+}
+export interface IiisOperationInput {
+    readonly parseGrant: string;
+    readonly operationId: string;
+    readonly operationToken: string;
+    readonly uploadUrl: string;
+    readonly expiresAt: string;
+    readonly openedFile: OpenedAllowedFile;
+    readonly retention: ResultRetentionSink;
+    readonly progress?: ProgressSink;
+    readonly signal?: AbortSignal;
+}
+export interface ReleasedResult extends ReleasedMetadata {
+}
+export interface IiisClientOptions {
+    readonly fetchImpl?: typeof fetch;
+    readonly pollIntervalMs?: number;
+    readonly maxPolls?: number;
+}
+export declare class IiisClient {
+    #private;
+    constructor(options?: IiisClientOptions);
+    uploadAndWait(input: IiisOperationInput): Promise<ReleasedResult>;
+    downloadResult(input: IiisOperationInput): Promise<ReleasedResult>;
+    ack(input: IiisOperationInput): Promise<void>;
+}