@openrouter/mcp 0.0.1 → 1.0.0

package/esm/tool-wrapper.d.ts

@@ -1,5 +1,5 @@
-import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import type { McpBranded } from '@openrouter/agent/tool-types';
+import type { Client } from '@modelcontextprotocol/client';
+import type { McpBranded, ToolLoopKey } from '@openrouter/agent/tool-types';
 import type { UnconvertibleSchemaMode } from './schema/json-schema-to-zod.js';
 /** A discovered MCP tool definition (the fields we consume). */
 export interface McpToolDef {
@@ -7,6 +7,15 @@ export interface McpToolDef {
     description?: string;
     inputSchema: Record<string, unknown>;
     outputSchema?: Record<string, unknown>;
+    /**
+     * Doom-loop identity advertised by the server via
+     * `_meta['openrouter/loopKey']` on the tool definition: a field-name
+     * array (the declarative subset of arguments that identifies a call) or
+     * `false` (the tool is exempt — repetition is its job, e.g. polling).
+     * Data, not code — survives cache snapshots. A client-side `loopKeys`
+     * entry in {@link WrapToolOptions} takes precedence.
+     */
+    loopKey?: readonly string[] | false;
 }
 export interface WrapToolOptions {
     client: Client;
@@ -14,6 +23,12 @@ export interface WrapToolOptions {
     schemaMode?: UnconvertibleSchemaMode;
     emitProgress?: boolean;
     signal?: AbortSignal;
+    /**
+     * Per-tool doom-loop identities, keyed by the tool's UNPREFIXED MCP name.
+     * Any `ToolLoopKey` form (function | field list | `false`). Takes
+     * precedence over a server-advertised `loopKey` on the definition.
+     */
+    loopKeys?: Readonly<Record<string, ToolLoopKey<Record<string, unknown>>>>;
 }
 /**
  * Wrap one discovered MCP tool as an `@openrouter/agent` tool. Emits a

package/esm/tool-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-wrapper.d.ts","sourceRoot":"","sources":["../src/tool-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAK/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAG9E,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA4CD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,UAAU,CAuFjF"}
+{"version":3,"file":"tool-wrapper.d.ts","sourceRoot":"","sources":["../src/tool-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAY,MAAM,8BAA8B,CAAC;AAErE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAK5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAG9E,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3E;AA8CD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,UAAU,CAqGjF"}

package/esm/tool-wrapper.js

@@ -15,10 +15,13 @@ function callToolResultIsRaw(value) {
 }
 async function invokeTool(invokeArgs) {
     const { options, mcpName, args, onprogress } = invokeArgs;
+    // SDK v2 signature is `callTool(params, options)` — v1's middle result-schema
+    // argument is gone. Passing three args here would silently drop `signal` and
+    // `onprogress` into an unread slot, killing cancellation and progress.
     const result = await options.client.callTool({
         name: mcpName,
         arguments: args,
-    }, undefined, {
+    }, {
         ...(options.signal !== undefined && {
             signal: options.signal,
         }),
@@ -44,6 +47,16 @@ export function wrapMcpTool(def, options) {
     const outputSchema = def.outputSchema !== undefined
         ? convertMcpInputSchema(def.outputSchema, options.schemaMode)
         : undefined;
+    // Client-side config wins over the server-advertised declaration; both
+    // ride markMcp's injection point so every tool kind gets the same wiring.
+    const loopKey = options.loopKeys !== undefined && Object.hasOwn(options.loopKeys, def.name)
+        ? options.loopKeys[def.name]
+        : def.loopKey;
+    const markOptions = loopKey !== undefined
+        ? {
+            loopKey,
+        }
+        : undefined;
     if (options.emitProgress === true) {
         return markMcp(tool({
             name,
@@ -97,7 +110,7 @@ export function wrapMcpTool(def, options) {
                 }
                 return await finalize;
             },
-        }));
+        }), markOptions);
     }
     return markMcp(tool({
         name,
@@ -113,6 +126,6 @@ export function wrapMcpTool(def, options) {
             mcpName: def.name,
             args,
         }),
-    }));
+    }), markOptions);
 }
 //# sourceMappingURL=tool-wrapper.js.map

package/esm/tool-wrapper.js.map

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

package/esm/transport-types.d.ts

@@ -1,3 +1,45 @@
-/** Non-stdio MCP transports this package supports. */
+/**
+ * Non-stdio MCP transports this package supports.
+ *
+ * `'sse'` (HTTP+SSE) is reclassified as Deprecated by MCP protocol revision
+ * 2026-07-28 (SEP-2596) and remains only for legacy servers. Prefer
+ * `'streamableHttp'`. See MIGRATION notes in the package README.
+ */
 export type MCPTransportKind = 'streamableHttp' | 'sse';
+/**
+ * How to negotiate the MCP protocol revision.
+ *
+ * - `'auto'` (our default) — probe the server with `server/discover`, then speak
+ *   whichever revision it offers. Definitive modern evidence selects
+ *   2026-07-28; anything else falls back to the 2025-era `initialize`
+ *   handshake. Costs one extra round trip against legacy servers.
+ * - `'legacy'` — skip the probe and always use the `initialize` handshake. Saves
+ *   that round trip when you already know the server is 2025-era.
+ * - `{ pin }` — require exactly that revision; fail loudly rather than
+ *   falling back.
+ *
+ * **Setting this at all opts out of the automatic legacy retry.** When you leave
+ * it unset, a failed connect is retried once with `'legacy'`, so a server behind
+ * a probe-hostile proxy or gateway still connects. Naming a mode — including
+ * `'auto'` — means you want that mode's failures too, and silently overriding a
+ * `{ pin }` would defeat the point of pinning. So `'legacy'` is a performance
+ * choice here, not a compatibility one.
+ *
+ * This is a policy, not a version — `{ pin: '2026-07-28' }` is how you request
+ * a specific revision. Declared here rather than re-exported from the SDK so
+ * the public API does not depend on SDK types.
+ */
+export type MCPProtocolNegotiation = 'legacy' | 'auto' | {
+    /**
+     * Exact revision to speak, skipping negotiation.
+     *
+     * The two known revisions autocomplete and typo-check; the `(string & {})`
+     * arm keeps any other value assignable, so pinning a revision this package
+     * predates still compiles rather than forcing a cast. A wrong string there
+     * fails at connect time, as before.
+     */
+    pin: MCPProtocolRevision | (string & {});
+};
+/** Protocol revisions this package knows by name. */
+export type MCPProtocolRevision = '2025-11-25' | '2026-07-28';
 //# sourceMappingURL=transport-types.d.ts.map

package/esm/transport-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-types.d.ts","sourceRoot":"","sources":["../src/transport-types.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,KAAK,CAAC"}
+{"version":3,"file":"transport-types.d.ts","sourceRoot":"","sources":["../src/transport-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,KAAK,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,sBAAsB,GAC9B,QAAQ,GACR,MAAM,GACN;IACE;;;;;;;OAOG;IACH,GAAG,EAAE,mBAAmB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;CAC1C,CAAC;AAEN,qDAAqD;AACrD,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,YAAY,CAAC"}

package/esm/types.d.ts

@@ -1,9 +1,9 @@
-import type { Tool } from '@openrouter/agent/tool-types';
+import type { Tool, ToolLoopKey } from '@openrouter/agent/tool-types';
 import type { MCPAuth } from './auth/auth-types.js';
 import type { MCPCacheStore } from './cache/cache-store.js';
 import type { UnconvertibleSchemaMode } from './schema/json-schema-to-zod.js';
-import type { MCPTransportKind } from './transport-types.js';
-export type { MCPTransportKind };
+import type { MCPProtocolNegotiation, MCPProtocolRevision, MCPTransportKind } from './transport-types.js';
+export type { MCPProtocolNegotiation, MCPProtocolRevision, MCPTransportKind };
 /**
  * Response to a server-initiated elicitation request. `accept` must carry
  * `content` matching the server's `requestedSchema`.
@@ -34,11 +34,29 @@ export interface CreateMCPToolsOptions {
     url: string | URL;
     /** Transport to use; defaults to `streamableHttp` with SSE fallback. */
     transport?: MCPTransportKind;
+    /**
+     * Protocol-revision negotiation policy. Defaults to `'auto'`, which probes
+     * the server and speaks either 2025-11-25 or 2026-07-28 as appropriate.
+     */
+    protocolNegotiation?: MCPProtocolNegotiation;
+    /**
+     * Ceiling on the `server/discover` probe, in ms. Defaults to 30000 —
+     * `DEFAULT_PROBE_TIMEOUT_MS` in `mcp-connection.ts` is the source of truth.
+     *
+     * Raise it for a server slow to answer its first request. The SDK's own default
+     * is the full request timeout, which makes a hanging gateway far slower to fail
+     * than it needs to be.
+     */
+    probeTimeoutMs?: number;
     /** Authentication, supplied once and reused for discovery + every call. */
     auth?: MCPAuth;
     /** Custom fetch implementation for all network requests. */
     fetch?: typeof fetch;
-    /** Client identity sent during `initialize`. */
+    /**
+     * Client identity self-reported to the server while connecting — via the
+     * `initialize` handshake on revision 2025-11-25, or the per-request `_meta`
+     * envelope on 2026-07-28 (which has no `initialize`). Honoured on both.
+     */
     clientInfo?: {
         name: string;
         version: string;
@@ -64,7 +82,12 @@ export interface CreateMCPToolsOptions {
         store: MCPCacheStore;
         key?: string;
     };
-    /** Persist resolved tokens/session into the snapshot. Off by default. */
+    /**
+     * Persist resolved credentials (bearer/header values, or the OAuth provider's
+     * current tokens) into the snapshot. Off by default. Session ids are never
+     * serialized — protocol sessions are removed in revision 2026-07-28
+     * (SEP-2567), and a rehydrate always performs a fresh handshake.
+     */
     cacheCredentials?: boolean;
     /** Re-list tools when a cached snapshot is older than this. */
     staleness?: {
@@ -74,11 +97,37 @@ export interface CreateMCPToolsOptions {
     resources?: ResourcesOption;
     /** Map MCP progress notifications to generator-tool events. Default true. */
     emitProgress?: boolean;
+    /**
+     * Doom-loop identities for wrapped tools (see the `doomLoop` option on
+     * `callModel`), keyed by the tool's UNPREFIXED MCP name. Any `ToolLoopKey`
+     * form: a function computing key material, a declarative field-name array
+     * (e.g. `{ run_command: ['command', 'cwd'] }`), or `false` to exempt a
+     * tool. Takes precedence over a server-advertised
+     * `_meta['openrouter/loopKey']` declaration. Function forms are
+     * client-side only (they cannot be cached or transported); prefer field
+     * lists where possible.
+     */
+    loopKeys?: Readonly<Record<string, ToolLoopKey<Record<string, unknown>>>>;
     /** Auto-refresh tools on `tools/list_changed`. Default true when connected. */
     autoRefreshOnListChanged?: boolean;
-    /** Handler for server-initiated elicitation; auto-declines when omitted. */
+    /**
+     * Handler for elicitation requests; auto-declines when omitted.
+     *
+     * Works against both protocol revisions. On 2025-11-25 the server sends
+     * `elicitation/create` directly. On 2026-07-28 that request no longer
+     * exists — the server answers with an `input_required` result instead
+     * (SEP-2322) — but the SDK's multi-round-trip driver dispatches it through
+     * this same handler and then retries the original call, so callers see
+     * identical behavior either way.
+     */
     onElicitation?: ElicitationHandler;
-    /** Abort signal threaded into every underlying `callTool`. */
+    /**
+     * Abort signal threaded into every underlying `callTool` — and, new in this
+     * release, into the connection itself: connecting, the negotiation probe, the
+     * implicit legacy retry, and any reconnect all abort with it. An early
+     * cancellation can therefore surface as a connection failure, not only as a
+     * cancelled tool call.
+     */
     signal?: AbortSignal;
 }
 /**

package/esm/types.d.ts.map

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

package/esm/version.d.ts

@@ -0,0 +1,3 @@
+/** This package's version, self-reported to MCP servers as `clientInfo`. */
+export declare const PACKAGE_VERSION = "1.0.0";
+//# sourceMappingURL=version.d.ts.map

package/esm/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAGA,4EAA4E;AAC5E,eAAO,MAAM,eAAe,UAAU,CAAC"}

package/esm/version.js

@@ -0,0 +1,5 @@
+// DO NOT EDIT — generated from package.json by scripts/gen-version.mjs.
+// Run `pnpm --filter @openrouter/mcp gen:version` after bumping the version.
+/** This package's version, self-reported to MCP servers as `clientInfo`. */
+export const PACKAGE_VERSION = '1.0.0';
+//# sourceMappingURL=version.js.map

package/esm/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,6EAA6E;AAE7E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@openrouter/mcp",
-  "version": "0.0.1",
+  "version": "1.0.0",
+  "engines": {
+    "node": ">=20"
+  },
   "author": "OpenRouter",
   "description": "Expose remote MCP server tools (Streamable HTTP / SSE) as tools for @openrouter/agent's callModel, with serializable caching and pluggable auth.",
   "keywords": [
@@ -54,19 +57,20 @@
     "package.json",
     "README.md"
   ],
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "zod": "^4.0.0",
+    "@openrouter/agent": "0.9.0"
+  },
   "scripts": {
     "lint": "biome check src tests",
     "lint:fix": "biome check --write src tests",
-    "build": "tsc",
+    "gen:version": "node scripts/gen-version.mjs",
+    "build": "node scripts/gen-version.mjs && tsc",
     "test": "vitest --run --project unit",
     "test:e2e": "vitest --run --project e2e",
     "test:watch": "vitest --watch --project unit",
     "typecheck": "tsc --noEmit",
-    "compile": "tsc"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openrouter/agent": "workspace:*",
-    "zod": "^4.0.0"
+    "compile": "node scripts/gen-version.mjs && tsc"
   }
-}
+}