@mcp-z/client 2.1.0 → 2.2.1

package/README.md

@@ -156,6 +156,28 @@ const client = await registry.connect('todoist', {
 });
 ```
 
+## Protocol version negotiation
+
+By default a connect performs the plain 2025 MCP connect sequence. Pass `versionNegotiation` to negotiate the protocol revision instead:
+
+```ts
+// Probe the server first; connect at the newest revision it offers,
+// falling back to the 2025 sequence when it cannot serve the modern era
+const client = await registry.connect('modern-server', {
+  versionNegotiation: { mode: 'auto' }
+});
+
+// Require the 2026-07-28 revision; a server that cannot serve it fails
+// the connect with SdkErrorCode.EraNegotiationFailed
+const pinned = await registry.connect('strict-server', {
+  versionNegotiation: { mode: { pin: '2026-07-28' } }
+});
+```
+
+After connecting, `client.getProtocolEra()` returns `'modern'` or `'legacy'` and `client.getNegotiatedProtocolVersion()` the revision the server settled on.
+
+Note: with `mode: 'auto'` against a stdio server, a legacy server that never answers the `server/discover` probe costs the full request timeout (60s) before the client falls back to the 2025 sequence. The probe ends fast when the server answers it at all — with any reply, even a "method not found" error.
+
 ## Requirements
 
 - Node.js >= 22

package/dist/cjs/auth/discovery-fetch.d.cts

@@ -1,6 +1,15 @@
 export declare class DiscoveryFetchError extends Error {
     constructor(message: string);
 }
+type LookupRecord = {
+    address: string;
+    family: number;
+};
+/** DNS implementation, injectable for deterministic tests. Same contract as `dns.lookup` with `{ all: true, verbatim: true }`. */
+type Lookup = (hostname: string, options: {
+    all: true;
+    verbatim: true;
+}, callback: (error: NodeJS.ErrnoException | null, addresses: LookupRecord[]) => void) => void;
 /**
  * True if `rawUrl`'s host is loopback, used to decide `allowLoopback` grants
  * from the URL the caller configured, not remote-supplied data. Fails closed on an unparseable URL.
@@ -13,15 +22,25 @@ export interface DiscoveryFetchOptions {
      */
     allowLoopback?: boolean;
     /**
-     * Per-request connect/read timeout in ms. Defaults to `DEFAULT_TIMEOUT_MS`;
-     * overridable so tests can bound slow-failure cases.
+     * Per-hop timeout in ms, applied to both the DNS resolution and the request.
+     * Defaults to `DEFAULT_TIMEOUT_MS`; overridable so tests can bound slow-failure cases.
      */
     timeoutMs?: number;
+    /**
+     * DNS implementation used for the pre-request resolution, injectable for
+     * deterministic tests. Defaults to `dns.lookup`.
+     */
+    lookup?: Lookup;
 }
 /**
  * Fetches an OAuth-discovery URL with SSRF mitigations applied to the
  * initial URL and every redirect hop; redirects are validated, not auto-followed.
  *
+ * The hostname is resolved once, every returned address is validated, and the
+ * validated set is pinned into the request through a custom `lookup`, so the
+ * request cannot resolve the hostname a second time and cannot be steered to
+ * a different address by a DNS-rebinding answer.
+ *
  * @param rawUrl - URL to fetch; may be remote-server-supplied (the threat this guards against).
  * @param init - Standard fetch options; `redirect` is always forced to `'manual'`.
  * @param context - Short label used only in error messages, never echoing the URL.
@@ -33,3 +52,4 @@ export declare function discoveryFetch(rawUrl: string, init?: RequestInit, conte
  * while reading (not after buffering the whole thing).
  */
 export declare function readDiscoveryJson<T>(response: Response, context: string): Promise<T>;
+export {};

package/dist/cjs/auth/discovery-fetch.d.ts

@@ -1,6 +1,15 @@
 export declare class DiscoveryFetchError extends Error {
     constructor(message: string);
 }
+type LookupRecord = {
+    address: string;
+    family: number;
+};
+/** DNS implementation, injectable for deterministic tests. Same contract as `dns.lookup` with `{ all: true, verbatim: true }`. */
+type Lookup = (hostname: string, options: {
+    all: true;
+    verbatim: true;
+}, callback: (error: NodeJS.ErrnoException | null, addresses: LookupRecord[]) => void) => void;
 /**
  * True if `rawUrl`'s host is loopback, used to decide `allowLoopback` grants
  * from the URL the caller configured, not remote-supplied data. Fails closed on an unparseable URL.
@@ -13,15 +22,25 @@ export interface DiscoveryFetchOptions {
      */
     allowLoopback?: boolean;
     /**
-     * Per-request connect/read timeout in ms. Defaults to `DEFAULT_TIMEOUT_MS`;
-     * overridable so tests can bound slow-failure cases.
+     * Per-hop timeout in ms, applied to both the DNS resolution and the request.
+     * Defaults to `DEFAULT_TIMEOUT_MS`; overridable so tests can bound slow-failure cases.
      */
     timeoutMs?: number;
+    /**
+     * DNS implementation used for the pre-request resolution, injectable for
+     * deterministic tests. Defaults to `dns.lookup`.
+     */
+    lookup?: Lookup;
 }
 /**
  * Fetches an OAuth-discovery URL with SSRF mitigations applied to the
  * initial URL and every redirect hop; redirects are validated, not auto-followed.
  *
+ * The hostname is resolved once, every returned address is validated, and the
+ * validated set is pinned into the request through a custom `lookup`, so the
+ * request cannot resolve the hostname a second time and cannot be steered to
+ * a different address by a DNS-rebinding answer.
+ *
  * @param rawUrl - URL to fetch; may be remote-server-supplied (the threat this guards against).
  * @param init - Standard fetch options; `redirect` is always forced to `'manual'`.
  * @param context - Short label used only in error messages, never echoing the URL.
@@ -33,3 +52,4 @@ export declare function discoveryFetch(rawUrl: string, init?: RequestInit, conte
  * while reading (not after buffering the whole thing).
  */
 export declare function readDiscoveryJson<T>(response: Response, context: string): Promise<T>;
+export {};