@cueai/omni-reader-mcp 1.1.2 → 1.2.0

package/dist/server.d.ts

@@ -1,3 +1,20 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CAPABILITIES_PROTOCOL_VERSION, DIRECT_GROUNDING_PROFILE, URL_GROUNDING_PROFILE } from "./constants.js";
 import { type OmniToolDependencies } from "./tools.js";
+export interface ReaderCapabilitiesAdvertisement {
+    readonly protocol_version: typeof CAPABILITIES_PROTOCOL_VERSION;
+    readonly expires_at: string;
+    readonly direct_profiles: readonly [typeof DIRECT_GROUNDING_PROFILE];
+    readonly url_profiles: readonly [typeof URL_GROUNDING_PROFILE];
+}
+export declare function buildReaderCapabilitiesAdvertisement(now: Date, ttlSeconds: number): ReaderCapabilitiesAdvertisement;
+/** OMNI_CAPABILITIES_ENABLED gate, default off; a malformed value fails fast. */
+export declare function capabilitiesEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** OMNI_CAPABILITIES_TTL_SECONDS, default 300; malformed/non-positive values fall back. */
+export declare function capabilitiesTtlSeconds(env?: NodeJS.ProcessEnv): number;
+/**
+ * The advertisement to include in an initialize result, or null when the flag is off
+ * (the custom field must be absent — the server never emits a partial value).
+ */
+export declare function readerCapabilitiesAdvertisement(now?: Date): ReaderCapabilitiesAdvertisement | null;
 export declare function createOmniMcpServer(dependencies: OmniToolDependencies): McpServer;

package/dist/server.js

@@ -1,11 +1,52 @@
 import { InMemoryTaskStore } from "@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { BRIDGE_RELEASE_VERSION } from "./constants.js";
+import { BRIDGE_RELEASE_VERSION, CAPABILITIES_DEFAULT_TTL_SECONDS, CAPABILITIES_ENABLED_ENV, CAPABILITIES_PROTOCOL_VERSION, CAPABILITIES_TTL_SECONDS_ENV, DIRECT_GROUNDING_PROFILE, REMOTE_CAPABILITIES_CUSTOM_FIELD, URL_GROUNDING_PROFILE, } from "./constants.js";
 import { MACHINE_INSTRUCTIONS } from "./protocol.js";
 import { registerOmniTools } from "./tools.js";
 const SERVER_NAME = "omni-reader-mcp";
+/** RFC3339 UTC timestamp at seconds precision (matches the §D2-D example form). */
+function rfc3339Seconds(date) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function buildReaderCapabilitiesAdvertisement(now, ttlSeconds) {
+    return {
+        protocol_version: CAPABILITIES_PROTOCOL_VERSION,
+        expires_at: rfc3339Seconds(new Date(now.getTime() + ttlSeconds * 1000)),
+        direct_profiles: [DIRECT_GROUNDING_PROFILE],
+        url_profiles: [URL_GROUNDING_PROFILE],
+    };
+}
+/** OMNI_CAPABILITIES_ENABLED gate, default off; a malformed value fails fast. */
+export function capabilitiesEnabled(env = process.env) {
+    const raw = (env[CAPABILITIES_ENABLED_ENV] ?? "").trim().toLowerCase();
+    if (raw === "true")
+        return true;
+    if (raw === "" || raw === "false")
+        return false;
+    throw new Error(`${CAPABILITIES_ENABLED_ENV} must be true or false`);
+}
+/** OMNI_CAPABILITIES_TTL_SECONDS, default 300; malformed/non-positive values fall back. */
+export function capabilitiesTtlSeconds(env = process.env) {
+    const raw = env[CAPABILITIES_TTL_SECONDS_ENV];
+    if (raw === undefined || raw.trim() === "")
+        return CAPABILITIES_DEFAULT_TTL_SECONDS;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        return CAPABILITIES_DEFAULT_TTL_SECONDS;
+    return parsed;
+}
+/**
+ * The advertisement to include in an initialize result, or null when the flag is off
+ * (the custom field must be absent — the server never emits a partial value).
+ */
+export function readerCapabilitiesAdvertisement(now = new Date()) {
+    if (!capabilitiesEnabled())
+        return null;
+    return buildReaderCapabilitiesAdvertisement(now, capabilitiesTtlSeconds());
+}
 export function createOmniMcpServer(dependencies) {
     const taskStore = new InMemoryTaskStore();
+    const advertised = readerCapabilitiesAdvertisement();
     const server = new McpServer({ name: SERVER_NAME, version: BRIDGE_RELEASE_VERSION }, {
         instructions: MACHINE_INSTRUCTIONS,
         taskStore,
@@ -15,6 +56,9 @@ export function createOmniMcpServer(dependencies) {
                 cancel: {},
                 requests: { tools: { call: {} } },
             },
+            ...(advertised === null
+                ? {}
+                : { experimental: { [REMOTE_CAPABILITIES_CUSTOM_FIELD]: advertised } }),
         },
     });
     registerOmniTools(server, dependencies, taskStore);

package/dist/tools.d.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TaskStore } from "@modelcontextprotocol/sdk/experimental/tasks/interfaces.js";
-import type { ArtifactReadResult, LocalResult } from "./artifact-store.js";
+import type { ArtifactReadResult, BundlePartReadChunk, LocalResult } from "./artifact-store.js";
+import type { ReaderCapabilitiesV1 } from "./capabilities.js";
 import { type CubeGrantClient } from "./cube-client.js";
 import type { IiisClient, ResultRetentionSink } from "./iiis-client.js";
 import { type OpenAllowedFileOptions, type OpenedAllowedFile } from "./path-security.js";
@@ -12,6 +13,7 @@ interface ToolRetention extends ResultRetentionSink {
 interface ToolArtifactStore {
     createRetention(): ToolRetention;
     read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
+    readBundlePart?(resultId: string, cursor: string, maxBytes?: number): Promise<BundlePartReadChunk>;
     discard(resultId: string): Promise<boolean>;
 }
 export interface ParseOperationController {
@@ -28,11 +30,13 @@ export interface ParseOperationController {
 export interface OmniToolDependencies {
     readonly workspace: string;
     readonly extraRoots?: readonly string[];
-    readonly cubeClient: Pick<CubeGrantClient, "createGrant">;
+    readonly cubeClient: Pick<CubeGrantClient, "createGrant" | "getCapabilities">;
     readonly iiisClient: Pick<IiisClient, "uploadAndWait" | "ack">;
     readonly artifactStore: ToolArtifactStore;
     readonly createClientRequestId?: () => string;
-    readonly remoteClient?: RemoteOmniClient;
+    readonly remoteClient?: RemoteOmniClient & {
+        initializeCapabilities(signal: AbortSignal): Promise<ReaderCapabilitiesV1>;
+    };
     readonly operationManager?: ParseOperationController;
     readonly openFile?: (localPath: string, options: OpenAllowedFileOptions) => Promise<OpenedAllowedFile>;
     readonly statusOperation?: (operationId: string, waitMs: number | undefined, signal: AbortSignal) => Promise<ParseResult>;

package/dist/tools.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
 import { CallToolRequestSchema, CancelTaskRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { selectDirectProfile, selectUrlProfile, } from "./capabilities.js";
 import { createClientRequestId as newClientRequestId, } from "./cube-client.js";
 import { OmniBridgeError } from "./errors.js";
 import { openAllowedFile, } from "./path-security.js";
 import { NOOP_PROGRESS } from "./progress.js";
-import { MACHINE_INSTRUCTIONS, cancelParseSchema, discardResultSchema, getParseStatusSchema, parseSchema, readResultSchema, } from "./protocol.js";
+import { MACHINE_INSTRUCTIONS, cancelParseSchema, discardResultSchema, getParseStatusSchema, normalizeRepresentation, parseSchema, readResultSchema, } from "./protocol.js";
 import { discardResultOutputSchema, discardResultToolOutputSchema, parseResultSchema, parseToolOutputSchema, readResultOutputSchema, readResultToolOutputSchema, structuredResult, } from "./result-contract.js";
 import { classifySource } from "./source.js";
 import { TaskRuntime } from "./task-runtime.js";
@@ -137,9 +138,48 @@ async function parseLocal(args, clientRequestId, signal, progress, dependencies)
         }
     }
 }
+// D2-D items 4-5: capability preflight for any explicit non-text request.
+// The capability source must be available BEFORE any non-text grant/tool
+// request is constructed: Cube requests use the authenticated
+// `GET /api/omni-reader/capabilities/v1` preflight, remote MCP requests use
+// the initialize result's exact `capabilities.experimental["cue.omni-reader"]`
+// custom field. Without one exact compatible profile for the requested
+// path/detail the request fails closed with UNSUPPORTED_DETAIL — no unknown
+// fields are sent and there is never a silent text fallback.
+async function preflightNonTextRepresentation(detail, sourceKind, signal, dependencies) {
+    if (sourceKind === "local") {
+        const capabilities = await dependencies.cubeClient.getCapabilities(signal);
+        selectDirectProfile(capabilities, detail);
+    }
+    else {
+        if (dependencies.remoteClient === undefined) {
+            throw bridgeError("REMOTE_PARSE_UNAVAILABLE", "Remote URL parsing is not available in this Bridge build.", { retryable: true });
+        }
+        const capabilities = await dependencies.remoteClient.initializeCapabilities(signal);
+        selectUrlProfile(capabilities, detail);
+    }
+    if (dependencies.operationManager === undefined) {
+        throw new OmniBridgeError({
+            code: "UNSUPPORTED_DETAIL",
+            message: "This Bridge build cannot deliver the requested output detail.",
+            failureScope: "bridge",
+            userAction: "Use plain Markdown output for this source.",
+            operationCreated: false,
+            fileUploaded: false,
+            parserStarted: false,
+            billed: false,
+            contentReleased: false,
+            retryable: false,
+        });
+    }
+}
 async function parseValue(args, signal, progress, dependencies) {
     try {
         const source = classifySource(args.source);
+        const representation = normalizeRepresentation(args.detail);
+        if (representation.detail !== "text") {
+            await preflightNonTextRepresentation(representation.detail, source.kind, signal, dependencies);
+        }
         const clientRequestId = (dependencies.createClientRequestId ?? newClientRequestId)();
         if (dependencies.operationManager !== undefined) {
             const sourceHash = `sha256:${createHash("sha256")
@@ -171,6 +211,12 @@ async function parseValue(args, signal, progress, dependencies) {
                 sourceFacts: {
                     sourceHash,
                     ...(sourceFingerprint === undefined ? {} : { sourceFingerprint }),
+                    // D2-D item 3: the exact normalized representation fields enter
+                    // SubmitOperationInput.sourceFacts BEFORE operationRequestHash so
+                    // grounded/layout serialize to distinct identities. omitted/text
+                    // must serialize byte-for-byte as legacy source facts so legacy
+                    // journal identities stay reconstructable on upgrade.
+                    ...(representation.detail === "text" ? {} : representation),
                 },
                 clientRequestId,
                 signal,
@@ -263,6 +309,36 @@ async function callReadResult(resultId, cursor, maxBytes, dependencies) {
         });
     }
     catch (error) {
+        // D2-D Task 14: a retained logical bundle is only readable through a
+        // part-selecting v2 cursor, which the plain artifact read refuses with
+        // INVALID_RESULT_CURSOR. When the store exposes a named part reader, route
+        // the cursor there so clients can reassemble content and grounding
+        // independently from offset 0.
+        if (cursor !== undefined &&
+            error instanceof OmniBridgeError &&
+            error.code === "INVALID_RESULT_CURSOR" &&
+            dependencies.artifactStore.readBundlePart !== undefined) {
+            try {
+                const part = await dependencies.artifactStore.readBundlePart(resultId, cursor, maxBytes);
+                return structuredResult(readResultOutputSchema, {
+                    status: "completed",
+                    result: {
+                        result_id: part.resultId,
+                        part: part.part,
+                        media_type: part.mediaType,
+                        result_bytes: part.resultBytes,
+                        offset: part.offset,
+                        decoded_bytes: part.decodedBytes,
+                        text: part.text,
+                        expires_at: part.expiresAt,
+                        ...(part.nextCursor === undefined ? {} : { next_cursor: part.nextCursor }),
+                    },
+                });
+            }
+            catch (partError) {
+                return structuredResult(readResultOutputSchema, failed(partError));
+            }
+        }
         return structuredResult(readResultOutputSchema, failed(error));
     }
 }

package/package.json

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