@mcp-index/sdk 0.18.0 → 0.19.0

package/dist/src/lock/rawList.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Lock mode for the official MCP TypeScript client, at the transport.
+ *
+ * `Client.listTools()` returns tools after its zod schema has stripped unknown
+ * members, so a digest over that result is not a digest over what the server
+ * sent. LockedTransport sits between the Client and its real Transport and
+ * works on the parsed JSON-RPC message instead. The transports parse each
+ * message with JSON.parse and check only the envelope, so every member inside
+ * `result.tools`, `__proto__` included, is still there as sent.
+ *
+ * For a `tools/list` request from the client it:
+ *   - starts a listing (section 9.2.1) when it sends the request. Until the
+ *     listing is decided or fails, every `tools/call` is refused with
+ *     `no-listing`. A second cursorless `tools/list` abandons the first, whose
+ *     request is answered with an error;
+ *   - classifies every frame from the server as section 9.2.2 says
+ *     (classifyFrame): only the response to an unanswered `tools/list`,
+ *     matched by id with exact JSON type and value, can carry tools, and only
+ *     that or the `initialize` or `server/discover` response can carry
+ *     instructions. Anything else that carries them, or has both a method and
+ *     a result or error, is dropped and reported to onerror. A client request
+ *     whose id it matches is answered with an error under that id and is no
+ *     longer pending; when that request is the listing's, or one of its page
+ *     requests, the listing fails. A response whose id matches no request is
+ *     dropped too;
+ *   - follows `nextCursor` itself, sending its own page requests under private
+ *     ids, so one listing is every page (section 9.2). The client gets one
+ *     response with every shown tool and no cursor. A client request that
+ *     carries a cursor is answered with an error, since there is no partial
+ *     listing in lock mode;
+ *   - loads a lock snapshot, runs checkListing on the raw tools, installs the
+ *     decision in the CallGate, emits a listing event, and passes on only the
+ *     shown raw entries, without a top-level `_meta` that the decision removes
+ *     (section 9.2.3). The client then parses exactly those.
+ *
+ * Every outgoing `tools/call` goes through the CallGate first. A refused call
+ * is never sent; the client gets a -32011 error with data.reason. This covers
+ * callTool, request, requestStream and the task helpers alike, because they
+ * all end in Transport.send. A call on a snapshot older than maxStalenessMs
+ * (default 60 s) reloads it first; the reload can only shrink the allow-list,
+ * and if it fails the call gets `lock-stale` and the next call tries again.
+ *
+ * `notifications/tools/list_changed` is passed on and marks a listing as due.
+ * It does not change the allow-list, and this adapter does not start a
+ * listing on its own (the spec's SHOULD); the client asks for one. A listing
+ * that fails (an error response, a result with no tools array, a page that
+ * cannot be requested or gets no response, a page or tool limit exceeded)
+ * refuses every call with `unreachable` until a listing completes (section
+ * 9.5). Server instructions arrive in the initialize or server/discover
+ * result; they are checked there and stripped when the check says so.
+ *
+ * Unanswered requests are tracked in bounded maps. An entry leaves on its
+ * response, on the client's notifications/cancelled, after REQUEST_TTL_MS, or,
+ * when the map is full, oldest first. If that entry is the listing in
+ * progress, the listing fails.
+ *
+ * Lock mode has no auto-accept, first-use pin or re-pin, and this adapter
+ * takes no option that would add one.
+ */
+import type { JSONRPCMessage, MessageExtraInfo } from "@modelcontextprotocol/sdk/types.js";
+import type { Transport, TransportSendOptions } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { CallGate, DEFAULT_MAX_STALENESS_MS } from "./check.js";
+import type { Decision } from "./check.js";
+import type { LockEventSink } from "./events.js";
+import type { Identity, Posture } from "./lock.js";
+import type { LockStore } from "./store.js";
+/** Pages and tools one listing may span before the server is treated as unreachable. */
+export declare const MAX_LIST_PAGES = 100;
+export declare const MAX_LIST_TOOLS = 10000;
+/** Unanswered requests tracked at once; past this the oldest is forgotten. */
+export declare const MAX_OUTSTANDING = 4096;
+/** Age after which an unanswered request is forgotten (its late response is dropped). */
+export declare const REQUEST_TTL_MS = 600000;
+export { DEFAULT_MAX_STALENESS_MS };
+export interface LockOptions {
+    readonly store: LockStore;
+    /** This server's identity (section 3), from host configuration. */
+    readonly identity: Identity;
+    readonly posture: Posture;
+    /** The host name written into events. */
+    readonly host?: string;
+    readonly sink?: LockEventSink;
+    /**
+     * Age after which a call reloads the snapshot, so a revoke reaches a live
+     * connection; if the reload fails the call gets lock-stale. Default 60 s.
+     */
+    readonly maxStalenessMs?: number;
+    readonly now?: () => number;
+}
+/** Section 9.2.2: `id` equals one of `ids` in JSON type and value. Null matches nothing. */
+export declare function idMatches(id: unknown, ids: readonly unknown[]): boolean;
+/** Requests whose response may carry instructions (section 9.2.2). */
+export declare const HANDSHAKE_METHODS: readonly string[];
+export type FrameKind = "listing" | "handshake" | "drop" | "relay";
+/**
+ * What the host does with one frame from the server (section 9.2.2):
+ * `listing` (a page of the listing whose request it answers), `handshake`
+ * (the initialize or server/discover response; its instructions are
+ * checked), `drop`, or `relay`. `isInflight` and `isHandshake` say whether an
+ * id matches an unanswered tools/list or handshake request; unanswered
+ * tools/list requests are matched first.
+ */
+export declare function classifyFrame(frame: unknown, isInflight: (id: unknown) => boolean, isHandshake: (id: unknown) => boolean): FrameKind;
+export declare class LockedTransport implements Transport {
+    #private;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: <T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void;
+    readonly gate: CallGate;
+    constructor(inner: Transport, options: LockOptions);
+    get sessionId(): string | undefined;
+    setProtocolVersion(version: string): void;
+    /** True after a list_changed notification until the next listing completes. */
+    get listingDue(): boolean;
+    /** The decision for the latest complete listing on this connection, or null. */
+    get decision(): Decision | null;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
+}
+/** Anything with the Client.connect signature. */
+export interface ConnectableClient {
+    connect(transport: Transport): Promise<void>;
+}
+/** Wrap `transport` in lock mode and connect `client` through it. */
+export declare function lockClient(client: ConnectableClient, transport: Transport, options: LockOptions): Promise<LockedTransport>;
+//# sourceMappingURL=rawList.d.ts.map

package/dist/src/lock/rawList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rawList.d.ts","sourceRoot":"","sources":["../../../src/lock/rawList.ts"],"names":[],"mappings":"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"}