@cueai/omni-reader-mcp 1.4.0 → 1.5.0

package/README.md

@@ -64,7 +64,7 @@ differ from the numbers above, report the live values.
 Always use an audited exact version, never an implicit `latest`:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.4.0 setup
+npx -y @cueai/omni-reader-mcp@1.5.0 setup
 ```
 
 The interactive setup supports Hermes, Cursor, Claude Desktop, and generic stdio
@@ -72,9 +72,9 @@ configuration. Non-interactive installation uses the same argument parsing and w
 logic:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.4.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.4.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.4.0 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.0 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
 ```
 
 When an agent or script runs under a pty (stdin is still a TTY), declare non-interactive
@@ -82,7 +82,7 @@ mode explicitly with `--headless` (alias `--non-interactive`): no `--yes` is req
 stdin is never read:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.4.0 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.5.0 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
 ## Cache and journal isolation
@@ -133,6 +133,7 @@ The public tools are fixed:
 - `read_result`
 - `read_outline`
 - `discard_result`
+- `save_result`
 
 Every tool returns `structuredContent` with a strict `outputSchema`, plus an equivalent
 fallback for clients that only read legacy MCP `content[].text`:
@@ -150,7 +151,11 @@ fallback for clients that only read legacy MCP `content[].text`:
   advancing sequentially through `next_cursor`. An empty or absent outline is reported
   explicitly, never silently — it never blocks reading the result itself with `read_result`;
 - the `discard_result` text JSON explicitly returns `discarded`; never claim deletion on
-  call success alone.
+  call success alone;
+- the `save_result` text JSON contains the written file `path` and `bytes` count; there is
+  no path argument — the file is always named from `result_id` inside the Bridge cache's
+  export directory, so it cannot be pointed at an arbitrary location; calling it again for
+  the same result overwrites the same file.
 
 This gives clients that do not render `structuredContent` the operation/result handles
 and the full body without changing the contract for structured-capable clients.
@@ -188,7 +193,11 @@ Both URL and local files use mandatory no-store semantics and enter the
   **24 hours**; this is a different class of data from the remote 10-minute delivery
   window;
 - `read_result` reads local results in chunks; `discard_result` deletes a specific result
-  immediately; `clean` removes Bridge-created local artifacts and expired records.
+  immediately; `clean` removes Bridge-created local artifacts and expired records;
+- `save_result` writes a result's complete content to a stable file under the Bridge cache's
+  export directory and returns its path; exports are independent of the 24-hour cache sweep,
+  so discarding the cached artifact or letting retention expire does not remove an export the
+  user asked to keep.
 
 Status queries, result reads, and discards never create a new parse or usage event.
 `cancel_parse` reports only the real settlement state confirmed by the server and never
@@ -212,16 +221,16 @@ satisfies the constraints.
 ## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.4.0 doctor
-npx -y @cueai/omni-reader-mcp@1.4.0 doctor --json
-npx -y @cueai/omni-reader-mcp@1.4.0 clean
-npx -y @cueai/omni-reader-mcp@1.4.0 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.0 doctor
+npx -y @cueai/omni-reader-mcp@1.5.0 doctor --json
+npx -y @cueai/omni-reader-mcp@1.5.0 clean
+npx -y @cueai/omni-reader-mcp@1.5.0 uninstall --yes --json
 ```
 
 Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.4.0
+npx -y @cueai/omni-reader-mcp@1.5.0
 ```
 
 `doctor --json` returns package/npm/client adapter, Key present/absent, allowed-root
@@ -230,12 +239,12 @@ status; it never prints the Key, private source paths, or content.
 
 ## Uninstall and rollback
 
-`uninstall --yes --json` removes only a trusted 1.3.3 or 1.4.0 Bridge entry; when a
+`uninstall --yes --json` removes only a trusted 1.4.1 or 1.5.0 Bridge entry; when a
 matching trusted backup exists, it restores the original URL-only `omni-reader` entry.
 Uninstall never deletes user source files and never silently removes unexpired local
 results.
 
-To roll back from 1.4.0:
+To roll back from 1.5.0:
 
 1. stop recommending or installing that version;
 2. run `uninstall --yes --json` to restore the trusted URL-only entry;

package/dist/cli/agent-config.js

@@ -7,7 +7,7 @@ const PACKAGE_SPEC = `@cueai/omni-reader-mcp@${BRIDGE_RELEASE_VERSION}`;
 // The release that the current version is a trusted upgrade from: uninstall and
 // rollback recognize exactly {previous, current} and nothing else. Bump this to
 // the version we just published when BRIDGE_RELEASE_VERSION advances.
-const PREVIOUS_RELEASE_VERSION = "1.3.3";
+const PREVIOUS_RELEASE_VERSION = "1.4.1";
 const PREVIOUS_PACKAGE_SPEC = `@cueai/omni-reader-mcp@${PREVIOUS_RELEASE_VERSION}`;
 const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
 const TRUSTED_EXACT_PACKAGE_SPECS = new Set([PREVIOUS_PACKAGE_SPEC, PACKAGE_SPEC]);

package/dist/constants.d.ts

@@ -6,7 +6,7 @@ export declare const CUBE_GRANT_PROTOCOL_VERSION = "omni.parse_grant.v1";
 export declare const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
 export declare const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";
 export declare const DEFAULT_IIIS_GRANTED_BASE_URL = "https://cubefile.ai.iiis.co:9443/omni/granted/";
-export declare const BRIDGE_RELEASE_VERSION = "1.4.0";
+export declare const BRIDGE_RELEASE_VERSION = "1.5.0";
 export declare const REMOTE_OMNI_MCP_URL = "https://mcp.cuecue.cn/api/omni-reader/mcp/";
 export declare const FOREGROUND_BUDGET_MS = 15000;
 export declare const STATUS_LONG_POLL_MAX_MS = 20000;

package/dist/constants.js

@@ -6,7 +6,7 @@ export const CUBE_GRANT_PROTOCOL_VERSION = "omni.parse_grant.v1";
 export const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
 export const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";
 export const DEFAULT_IIIS_GRANTED_BASE_URL = "https://cubefile.ai.iiis.co:9443/omni/granted/";
-export const BRIDGE_RELEASE_VERSION = "1.4.0";
+export const BRIDGE_RELEASE_VERSION = "1.5.0";
 export const REMOTE_OMNI_MCP_URL = "https://mcp.cuecue.cn/api/omni-reader/mcp/";
 export const FOREGROUND_BUDGET_MS = 15_000;
 export const STATUS_LONG_POLL_MAX_MS = 20_000;

package/dist/protocol.d.ts

@@ -11,16 +11,37 @@ export interface RepresentationIntent {
 }
 export declare function normalizeRepresentation(detail?: "text" | "grounded" | "layout"): RepresentationIntent;
 export declare const MACHINE_INSTRUCTIONS: string;
-export declare const parseSchema: z.ZodObject<{
-    source: z.ZodEffects<z.ZodString, string, string>;
+export declare const parseSchemaShape: {
+    source: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    detail: z.ZodOptional<z.ZodEnum<["text", "grounded", "layout"]>>;
+};
+export declare const parseSchema: z.ZodEffects<z.ZodObject<{
+    source: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     detail: z.ZodOptional<z.ZodEnum<["text", "grounded", "layout"]>>;
 }, "strict", z.ZodTypeAny, {
-    source: string;
+    source?: string | undefined;
+    url?: string | undefined;
     detail?: "grounded" | "layout" | "text" | undefined;
 }, {
-    source: string;
+    source?: string | undefined;
+    url?: string | undefined;
+    detail?: "grounded" | "layout" | "text" | undefined;
+}>, {
+    source?: string | undefined;
+    url?: string | undefined;
+    detail?: "grounded" | "layout" | "text" | undefined;
+}, {
+    source?: string | undefined;
+    url?: string | undefined;
     detail?: "grounded" | "layout" | "text" | undefined;
 }>;
+export interface NormalizedParseArguments {
+    readonly source: string;
+    readonly detail?: "text" | "grounded" | "layout";
+}
+export declare function normalizeParseArguments(args: ParseArguments): NormalizedParseArguments;
 export declare const getParseStatusSchema: z.ZodObject<{
     operation_id: z.ZodString;
     wait_ms: z.ZodOptional<z.ZodNumber>;

package/dist/protocol.js

@@ -40,16 +40,39 @@ export const MACHINE_INSTRUCTIONS = [
 ].join("\n");
 const operationIdSchema = z.string().regex(/^op_[A-Za-z0-9_-]{16,64}$/u);
 const resultIdSchema = z.string().regex(/^result_[A-Za-z0-9_-]{16,64}$/u);
-export const parseSchema = z
+// I1 parameter unification: the remote omni-reader MCP surface accepts the
+// legacy `url` alias (plus `output`/`wait`), and agents hold that schema.  The
+// Bridge accepts exactly one of `source` or `url` with identical constraints,
+// so either surface's parse call passes validation here; `url` is normalized
+// to `source` before any handler runs (see normalizeParseArguments).
+const parseSchemaObject = z
     .object({
     source: z
         .string()
         .min(1)
         .max(8192)
-        .refine((value) => !value.includes("\0")),
+        .refine((value) => !value.includes("\0"))
+        .optional(),
+    url: z
+        .string()
+        .min(1)
+        .max(8192)
+        .refine((value) => !value.includes("\0"))
+        .optional(),
     detail: z.enum(["text", "grounded", "layout"]).optional(),
 })
     .strict();
+export const parseSchemaShape = parseSchemaObject.shape;
+export const parseSchema = parseSchemaObject.refine((value) => (value.source === undefined) !== (value.url === undefined), { message: "provide exactly one of source or url" });
+export function normalizeParseArguments(args) {
+    const source = args.source ?? args.url;
+    if (source === undefined) {
+        // The schema refine enforces exactly-one; this branch is unreachable for
+        // schema-validated input and guards misuse of the exported helper.
+        throw new Error("parse arguments require exactly one of source or url");
+    }
+    return { source, detail: args.detail };
+}
 export const getParseStatusSchema = z
     .object({
     operation_id: operationIdSchema,

package/dist/tools.js

@@ -6,7 +6,7 @@ import { OmniBridgeError } from "./errors.js";
 import { hydrateInlineUrlResultSafely } from "./operation-manager.js";
 import { openAllowedFile, } from "./path-security.js";
 import { NOOP_PROGRESS } from "./progress.js";
-import { MACHINE_INSTRUCTIONS, cancelParseSchema, discardResultSchema, getParseStatusSchema, normalizeRepresentation, parseSchema, readOutlineSchema, readResultSchema, saveResultSchema, } from "./protocol.js";
+import { MACHINE_INSTRUCTIONS, cancelParseSchema, discardResultSchema, getParseStatusSchema, normalizeParseArguments, normalizeRepresentation, parseSchema, parseSchemaShape, readOutlineSchema, readResultSchema, saveResultSchema, } from "./protocol.js";
 import { discardResultOutputSchema, discardResultToolOutputSchema, localResultToResultField, parseResultSchema, parseToolOutputSchema, readOutlineOutputSchema, readOutlineToolOutputSchema, readResultOutputSchema, readResultToolOutputSchema, saveResultOutputSchema, saveResultToolOutputSchema, structuredResult, } from "./result-contract.js";
 import { classifySource } from "./source.js";
 import { TaskRuntime } from "./task-runtime.js";
@@ -412,7 +412,7 @@ async function dispatchTool(name, rawArguments, extra, dependencies) {
     if (name === "parse") {
         const parsed = parseSchema.safeParse(rawArguments ?? {});
         return parsed.success
-            ? callParse(parsed.data, extra, dependencies)
+            ? callParse(normalizeParseArguments(parsed.data), extra, dependencies)
             : invalidArgumentsResult(name);
     }
     if (name === "get_parse_status") {
@@ -460,16 +460,17 @@ export function registerOmniTools(server, dependencies, taskStore) {
         cancel: (operationId, signal) => cancelValue(operationId, signal, dependencies),
     });
     const createParseTask = async (args, extra) => {
+        const normalized = normalizeParseArguments(args);
         const requestedTtl = extra.taskRequestedTtl ?? 600_000;
         const task = await extra.taskStore.createTask({
             ttl: Math.min(600_000, Math.max(1_000, requestedTtl)),
             pollInterval: 1_000,
         });
-        void taskRuntime.start(task.taskId, args.source, extra.taskStore)
+        void taskRuntime.start(task.taskId, normalized.source, extra.taskStore)
             .catch(() => undefined);
         return { task };
     };
-    const parseInputShape = parseSchema.shape;
+    const parseInputShape = parseSchemaShape;
     const parseTaskHandler = {
         createTask: createParseTask,
         getTask: async (_args, extra) => extra.taskStore.getTask(extra.taskId),
@@ -510,7 +511,7 @@ export function registerOmniTools(server, dependencies, taskStore) {
         },
     }, (args, extra) => callCancel(args.operation_id, extra, dependencies));
     server.registerTool("read_result", {
-        description: "Read one UTF-8 chunk from a Bridge-created local result artifact. Pass each returned next_cursor as cursor in the next call until it is absent.",
+        description: "Read one UTF-8 chunk from a Bridge-created local result artifact. Pass each returned next_cursor as cursor in the next call until it is absent. Bridge-local artifact capability: the remote omni-reader MCP surface does not expose this tool.",
         inputSchema: readResultSchema,
         outputSchema: readResultToolOutputSchema,
         annotations: {
@@ -521,7 +522,7 @@ export function registerOmniTools(server, dependencies, taskStore) {
         },
     }, (args) => callReadResult(args.result_id, args.cursor, args.max_bytes, dependencies));
     server.registerTool("discard_result", {
-        description: "Immediately delete one Bridge-created local result artifact.",
+        description: "Immediately delete one Bridge-created local result artifact. Bridge-local artifact capability: the remote omni-reader MCP surface does not expose this tool.",
         inputSchema: discardResultSchema,
         outputSchema: discardResultToolOutputSchema,
         annotations: {
@@ -532,7 +533,7 @@ export function registerOmniTools(server, dependencies, taskStore) {
         },
     }, (args) => callDiscardResult(args.result_id, dependencies));
     server.registerTool("read_outline", {
-        description: "Return a local result's heading outline. Pass node_id from a returned node's id to mint a read_result-compatible cursor that jumps straight to that section, instead of reading sequentially from the start.",
+        description: "Return a local result's heading outline. Pass node_id from a returned node's id to mint a read_result-compatible cursor that jumps straight to that section, instead of reading sequentially from the start. Bridge-local artifact capability: the remote omni-reader MCP surface does not expose this tool.",
         inputSchema: readOutlineSchema,
         outputSchema: readOutlineToolOutputSchema,
         annotations: {
@@ -543,7 +544,7 @@ export function registerOmniTools(server, dependencies, taskStore) {
         },
     }, (args) => callReadOutline(args.result_id, args.node_id, dependencies));
     server.registerTool("save_result", {
-        description: "Write a local result's complete content to a stable file on disk and return its path. There is no path argument: the file is always named from result_id inside the Bridge cache directory, so this cannot be pointed at an arbitrary location. Calling it again for the same result overwrites the same file.",
+        description: "Write a local result's complete content to a stable file on disk and return its path. There is no path argument: the file is always named from result_id inside the Bridge cache directory, so this cannot be pointed at an arbitrary location. Calling it again for the same result overwrites the same file. Bridge-local artifact capability: the remote omni-reader MCP surface does not expose this tool.",
         inputSchema: saveResultSchema,
         outputSchema: saveResultToolOutputSchema,
         annotations: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueai/omni-reader-mcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Local stdio MCP bridge for direct Omni document parsing",
   "type": "module",
   "license": "UNLICENSED",