@namzu/sdk 46.0.0 → 48.1.0

package/dist/connector/mcp/client.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { toErrorMessage } from '../../utils/error.js';
 import { generateMCPClientId } from '../../utils/id.js';
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js';
@@ -8,7 +9,7 @@ import { classifyModernHttpFailure, defaultMcpEraCache, mcpEraCacheKey, resolveM
 import { MCPHttpStatusError, MCPInputRequiredError, isHeaderMismatchError, protocolErrorFromReply, } from './errors.js';
 import { HttpSseTransport } from './http-sse.js';
 import { StdioTransport } from './stdio.js';
-import { StreamableHttpTransport } from './streamable-http.js';
+import { MCPSubscriptionResponseError, StreamableHttpTransport } from './streamable-http.js';
 import { validateMcpHeaderAnnotations } from './x-mcp-header.js';
 import { DEFAULT_MCP_ERA_PROBE_TIMEOUT_MS, DEFAULT_MCP_REQUEST_TIMEOUT_MS, JSON_RPC_METHOD_NOT_FOUND, MCP_DISCOVER_METHOD, MCP_LEGACY_VERSIONS, MCP_METHOD_HEADER, MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, MCP_SUPPORTED_PROTOCOL_VERSIONS, } from '../../constants/mcp/index.js';
 import { NAMZU } from '../../constants/telemetry/index.js';
@@ -17,7 +18,83 @@ import { VERSION } from '../../version.js';
 const MAX_LIST_PAGES = 100;
 /** A cancellation notification must never become the next unbounded wait. */
 const CANCEL_NOTIFICATION_TIMEOUT_MS = 1_000;
+const MAX_PROGRESS_MESSAGE_BYTES = 512;
+const ANSI_CSI_PATTERN = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, 'g');
+const SUBSCRIPTION_ID_META_KEY = 'io.modelcontextprotocol/subscriptionId';
+const SUBSCRIPTION_RETRY_MAX_MS = 30_000;
+/** Auth may refresh; timeouts, conflicts and rate limits can clear without reconnecting. */
+const RETRYABLE_SUBSCRIPTION_CLIENT_STATUSES = new Set([401, 403, 408, 409, 425, 429]);
+const SUBSCRIPTION_NOTIFICATIONS = {
+    'notifications/tools/list_changed': 'toolsListChanged',
+    'notifications/prompts/list_changed': 'promptsListChanged',
+    'notifications/resources/list_changed': 'resourcesListChanged',
+};
+function subscriptionFilter(capabilities) {
+    return {
+        ...(capabilities?.tools?.listChanged === true ? { toolsListChanged: true } : {}),
+        ...(capabilities?.prompts?.listChanged === true ? { promptsListChanged: true } : {}),
+        ...(capabilities?.resources?.listChanged === true
+            ? { resourcesListChanged: true }
+            : {}),
+    };
+}
+function acknowledgedFilter(value, requested) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const acknowledged = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (!Object.hasOwn(requested, key) || (entry !== true && entry !== false))
+            return undefined;
+        if (entry === true)
+            acknowledged[key] = true;
+    }
+    return acknowledged;
+}
+/** A rejected listen request with the same inputs cannot heal by repeating it. */
+function isPermanentSubscriptionFailure(error, requestId) {
+    if (!(error instanceof MCPHttpStatusError || error instanceof MCPSubscriptionResponseError))
+        return false;
+    try {
+        const reply = JSON.parse(error.bodyText);
+        if (reply?.jsonrpc === '2.0' &&
+            reply.id === requestId &&
+            reply.method === undefined &&
+            reply.error?.code === JSON_RPC_METHOD_NOT_FOUND) {
+            return true;
+        }
+    }
+    catch {
+        // Only a failed HTTP status can determine policy without a JSON-RPC reply.
+    }
+    return (error instanceof MCPHttpStatusError &&
+        error.status >= 400 &&
+        error.status < 500 &&
+        !RETRYABLE_SUBSCRIPTION_CLIENT_STATUSES.has(error.status));
+}
 const NAMZU_CLIENT_INFO = { name: 'namzu-sdk', version: VERSION };
+/** Keep server-authored status text safe and small before it reaches a host UI. */
+function progressMessage(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const plain = value
+        .slice(0, MAX_PROGRESS_MESSAGE_BYTES * 4)
+        .replace(ANSI_CSI_PATTERN, '')
+        .replace(/[\p{Cc}\p{Cf}\p{Cs}]/gu, ' ')
+        .trim();
+    if (!plain)
+        return undefined;
+    let bounded = '';
+    let bytes = 0;
+    for (const character of plain) {
+        const length = Buffer.byteLength(character, 'utf8');
+        if (bytes + length > MAX_PROGRESS_MESSAGE_BYTES)
+            break;
+        bounded += character;
+        bytes += length;
+    }
+    return bounded;
+}
 /**
  * The three header names the protocol owns, lower-cased for matching.
  *
@@ -60,13 +137,18 @@ export class MCPClient {
     status = 'disconnected';
     serverInfo;
     serverCapabilities;
+    serverInstructions;
     era;
     connectedAt;
     error;
     pendingRequests = new Map();
     nextRequestId = 1;
+    progressRequests = new Map();
     notificationHandlers = [];
     lifecycleListeners = [];
+    modernSubscription;
+    subscriptionRestartTimer;
+    subscriptionFailures = 0;
     /** Best-effort protocol cancellations still belong to this connection generation. */
     cancellationControllers = new Set();
     log;
@@ -108,6 +190,7 @@ export class MCPClient {
         if (this.status === 'connected') {
             throw new Error(`MCPClient already connected to "${this.config.serverName}"`);
         }
+        this.stopModernSubscription(false);
         this.status = 'connecting';
         // Tool schemas belong to a listing, and a listing belongs to a
         // connection. Carrying bindings across a reconnect would mirror the
@@ -122,6 +205,7 @@ export class MCPClient {
         try {
             this.transport.onMessage((msg) => this.handleMessage(msg));
             this.transport.onClose(() => {
+                this.stopModernSubscription(false);
                 this.status = 'disconnected';
                 this.abortCancellations(new Error('MCP transport closed'));
                 this.log.info('MCP transport closed');
@@ -129,6 +213,7 @@ export class MCPClient {
                 this.rejectAllPending(`MCP transport to "${this.config.serverName}" closed`);
             });
             this.transport.onError((err) => {
+                this.stopModernSubscription(false);
                 this.status = 'error';
                 this.abortCancellations(err);
                 this.error = err.message;
@@ -220,6 +305,7 @@ export class MCPClient {
         this.era = { kind: 'legacy', version: negotiated };
         this.serverInfo = result.serverInfo;
         this.serverCapabilities = result.capabilities;
+        this.serverInstructions = result.instructions;
         await this.notify('notifications/initialized', {});
         return result;
     }
@@ -380,6 +466,7 @@ export class MCPClient {
         const result = this.modernInitializeResult(era.version, resolution.discover);
         this.serverInfo = result.serverInfo;
         this.serverCapabilities = result.capabilities;
+        this.serverInstructions = result.instructions;
         this.status = 'connected';
         this.connectedAt = Date.now();
         this.emitLifecycle({
@@ -391,6 +478,7 @@ export class MCPClient {
             [NAMZU.SERVER_NAME]: result.serverInfo.name,
         };
         this.log.info('Connected to MCP server', connectedAttributes);
+        this.startModernSubscription();
         return result;
     }
     /**
@@ -401,6 +489,9 @@ export class MCPClient {
      * not name itself is reported under the name the operator gave it.
      * Inventing a placeholder like "unknown" would put a word in the
      * server's mouth in the one field a person reads to identify it.
+     *
+     * `instructions` is left unset: the modern era has no `initialize`
+     * round trip, so there is nothing in a `DiscoverResult` to carry it.
      */
     modernInitializeResult(version, discover) {
         return {
@@ -409,8 +500,140 @@ export class MCPClient {
             serverInfo: serverInfoFromDiscover(discover) ?? { name: this.config.serverName },
         };
     }
+    /** Subscribe only to change kinds the modern server actually advertised. */
+    startModernSubscription() {
+        if (this.status !== 'connected' || this.era?.kind !== 'modern' || this.modernSubscription) {
+            return;
+        }
+        const requested = subscriptionFilter(this.serverCapabilities);
+        if (Object.keys(requested).length === 0)
+            return;
+        const id = this.nextRequestId++;
+        const controller = new AbortController();
+        const envelope = buildEnvelope({
+            era: this.era,
+            method: 'subscriptions/listen',
+            params: { notifications: requested },
+            clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
+            capabilities: this.config.capabilities ?? {},
+        });
+        const subscription = {
+            id,
+            requested,
+            controller,
+            ackTimer: setTimeout(() => {
+                this.finishModernSubscription(subscription, 'acknowledgment timed out', true);
+            }, this.requestTimeoutMs),
+        };
+        subscription.ackTimer.unref?.();
+        this.modernSubscription = subscription;
+        const message = {
+            jsonrpc: '2.0',
+            id,
+            method: 'subscriptions/listen',
+            params: envelope.params,
+        };
+        try {
+            const options = {
+                signal: controller.signal,
+                ...this.eraHeaderOptions(envelope.headers),
+            };
+            const transport = this.transport;
+            const streaming = transport instanceof StreamableHttpTransport;
+            const sending = transport instanceof StreamableHttpTransport
+                ? transport.sendSubscription(message, options, (frame) => {
+                    if (this.modernSubscription !== subscription)
+                        return;
+                    // This callback belongs to the listen POST alone, so its first
+                    // JSON-RPC frame must be this request's acknowledgment.
+                    if (!subscription.acknowledged) {
+                        const meta = frame.params?._meta;
+                        const frameId = meta && typeof meta === 'object' && !Array.isArray(meta)
+                            ? meta[SUBSCRIPTION_ID_META_KEY]
+                            : undefined;
+                        if (frame.method !== 'notifications/subscriptions/acknowledged' || frameId !== id) {
+                            // A final JSON-RPC result is a valid graceful or error close.
+                            if (frame.id === id)
+                                this.handleMessage(frame);
+                            else
+                                this.finishModernSubscription(subscription, 'first stream message was not its acknowledgment', true);
+                            return;
+                        }
+                    }
+                    this.handleMessage(frame);
+                })
+                : transport.send(message, options);
+            void sending.then(() => {
+                // stdio's send only writes the request. Its eventual result
+                // arrives through handleMessage, whereas HTTP's send owns the
+                // response stream and settling means it closed.
+                if (streaming)
+                    this.finishModernSubscription(subscription, 'stream ended', false);
+            }, (err) => {
+                if (!controller.signal.aborted) {
+                    this.failModernSubscription(subscription, err);
+                }
+            });
+        }
+        catch (err) {
+            this.failModernSubscription(subscription, err);
+        }
+    }
+    failModernSubscription(subscription, error) {
+        if (this.modernSubscription !== subscription)
+            return;
+        const retry = !isPermanentSubscriptionFailure(error, subscription.id);
+        if (!retry) {
+            this.log.warn('Modern MCP subscription rejected; live updates stopped until reconnection', {
+                'namzu.connector.server': this.config.serverName,
+                'namzu.connector.reason': toErrorMessage(error),
+            });
+        }
+        this.finishModernSubscription(subscription, toErrorMessage(error), true, retry);
+    }
+    /** Stop one subscription, and retry with a bounded delay while connected. */
+    finishModernSubscription(subscription, reason, cancelPeer, retry = true) {
+        if (this.modernSubscription !== subscription)
+            return;
+        this.modernSubscription = undefined;
+        clearTimeout(subscription.ackTimer);
+        subscription.controller.abort(new Error(`MCP subscription ${reason}`));
+        if (cancelPeer && !(this.transport instanceof StreamableHttpTransport) && this.isConnected()) {
+            this.sendCancellation(subscription.id, `Subscription ${reason}`);
+        }
+        if (!retry || this.status !== 'connected' || this.era?.kind !== 'modern')
+            return;
+        this.subscriptionFailures++;
+        const delay = Math.min(1_000 * 2 ** Math.min(this.subscriptionFailures - 1, 5), SUBSCRIPTION_RETRY_MAX_MS);
+        this.log.warn('Modern MCP subscription ended; retrying', {
+            'namzu.connector.server': this.config.serverName,
+            'namzu.connector.reason': reason,
+            'namzu.connector.retry_ms': delay,
+        });
+        this.subscriptionRestartTimer = setTimeout(() => {
+            this.subscriptionRestartTimer = undefined;
+            this.startModernSubscription();
+        }, delay);
+        this.subscriptionRestartTimer.unref?.();
+    }
+    stopModernSubscription(cancelPeer) {
+        if (this.subscriptionRestartTimer)
+            clearTimeout(this.subscriptionRestartTimer);
+        this.subscriptionRestartTimer = undefined;
+        const subscription = this.modernSubscription;
+        this.modernSubscription = undefined;
+        this.subscriptionFailures = 0;
+        if (!subscription)
+            return;
+        clearTimeout(subscription.ackTimer);
+        subscription.controller.abort(new Error('MCP connection closed'));
+        if (cancelPeer && !(this.transport instanceof StreamableHttpTransport) && this.isConnected()) {
+            this.sendCancellation(subscription.id, 'Subscription closed');
+        }
+    }
     async disconnect() {
         const reason = new Error('MCPClient disconnecting');
+        this.stopModernSubscription(true);
         this.abortCancellations(reason);
         const alreadyDisconnected = this.status === 'disconnected';
         this.rejectAllPending('MCPClient disconnecting');
@@ -442,6 +665,7 @@ export class MCPClient {
             status: this.status,
             serverInfo: this.serverInfo,
             serverCapabilities: this.serverCapabilities,
+            serverInstructions: this.serverInstructions,
             connectedAt: this.connectedAt,
             error: this.error,
         };
@@ -675,8 +899,32 @@ export class MCPClient {
             cursor = next;
         }
     }
+    /**
+     * Returns an unsubscribe, mirroring {@link onLifecycle} below — a listener
+     * that cannot be removed keeps whatever it closes over (a discovery
+     * object, a logger, a caller's own state) referenced by this client for
+     * as long as the client lives, even after the listener's own owner is
+     * done with it.
+     */
     onNotification(handler) {
         this.notificationHandlers.push(handler);
+        // A list may have changed between the first fetch and the subscription
+        // acknowledgment. Reconcile when a listener joins an already-acknowledged
+        // stream, as well as when a stream is acknowledged with listeners present.
+        const subscription = this.modernSubscription;
+        if (subscription?.acknowledged) {
+            queueMicrotask(() => {
+                if (this.modernSubscription === subscription &&
+                    this.notificationHandlers.includes(handler)) {
+                    this.reconcileSubscription(subscription, handler);
+                }
+            });
+        }
+        return () => {
+            const index = this.notificationHandlers.indexOf(handler);
+            if (index >= 0)
+                this.notificationHandlers.splice(index, 1);
+        };
     }
     /**
      * Watch this client come up, go down, or fail.
@@ -688,9 +936,7 @@ export class MCPClient {
      * this adds no state, it just says out loud what the client already
      * knew.
      *
-     * Returns an unsubscribe. `onNotification` above does not, which is the
-     * bug this avoids repeating: a listener that cannot be removed keeps a
-     * disposed host object alive for as long as the client lives.
+     * Returns an unsubscribe, the same shape `onNotification` above returns.
      */
     onLifecycle(listener) {
         this.lifecycleListeners.push(listener);
@@ -746,10 +992,20 @@ export class MCPClient {
         // Refuse before allocating an id or asking the transport to do work.
         options?.signal?.throwIfAborted();
         const id = this.nextRequestId++;
+        const progressToken = method === 'tools/call' && options?.onProgress ? randomUUID() : undefined;
+        const requestParams = progressToken === undefined
+            ? params
+            : {
+                ...params,
+                _meta: {
+                    ...params._meta,
+                    progressToken,
+                },
+            };
         const envelope = buildEnvelope({
             era: this.era,
             method,
-            params,
+            params: requestParams,
             clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
             capabilities: this.config.capabilities ?? {},
             ...this.paramHeaderBindings(method, params),
@@ -782,6 +1038,8 @@ export class MCPClient {
             options?.signal?.removeEventListener('abort', onCallerAbort);
             if (this.pendingRequests.get(id) === entry)
                 this.pendingRequests.delete(id);
+            if (progressToken !== undefined)
+                this.progressRequests.delete(progressToken);
         };
         const settle = (terminal, value) => {
             if (settled)
@@ -822,6 +1080,9 @@ export class MCPClient {
             entry.reject(reason);
         };
         this.pendingRequests.set(id, entry);
+        if (progressToken !== undefined && options?.onProgress) {
+            this.progressRequests.set(progressToken, { onProgress: options.onProgress });
+        }
         const timer = setTimeout(() => {
             const error = new Error(`MCP request "${method}" to "${this.config.serverName}" timed out after ${this.requestTimeoutMs}ms`);
             error.name = 'TimeoutError';
@@ -1044,6 +1305,11 @@ export class MCPClient {
         await this.transport.send(message, this.eraHeaderOptions(envelope.headers));
     }
     handleMessage(message) {
+        if (message.method === 'notifications/progress' && message.id === undefined) {
+            this.handleProgressNotification(message.params);
+        }
+        if (this.handleModernSubscriptionMessage(message))
+            return;
         if (message.id !== undefined) {
             const pending = this.pendingRequests.get(message.id);
             if (pending) {
@@ -1089,6 +1355,118 @@ export class MCPClient {
             });
         }
     }
+    handleProgressNotification(params) {
+        const token = params?.progressToken;
+        if (typeof token !== 'string')
+            return;
+        const pending = this.progressRequests.get(token);
+        if (!pending)
+            return;
+        const progress = params?.progress;
+        if (typeof progress !== 'number' || !Number.isFinite(progress) || progress < 0)
+            return;
+        if (pending.lastProgress !== undefined && progress <= pending.lastProgress)
+            return;
+        pending.lastProgress = progress;
+        const total = params?.total;
+        const message = progressMessage(params?.message);
+        const update = {
+            progress,
+            ...(typeof total === 'number' && Number.isFinite(total) && total > 0 ? { total } : {}),
+            ...(message === undefined ? {} : { message }),
+        };
+        try {
+            pending.onProgress(update);
+        }
+        catch (error) {
+            this.log.warn('MCP progress listener threw', {
+                'exception.message': toErrorMessage(error),
+            });
+        }
+    }
+    /**
+     * The modern subscription stream is authority-scoped by its request ID.
+     * A bare or wrong-ID list_changed notification must not refresh a live
+     * toolset, and no event may precede its acknowledgment.
+     */
+    handleModernSubscriptionMessage(message) {
+        if (this.era?.kind !== 'modern')
+            return false;
+        const subscription = this.modernSubscription;
+        if (subscription && message.id === subscription.id) {
+            if (message.error?.code === JSON_RPC_METHOD_NOT_FOUND) {
+                this.log.warn('Modern MCP subscription rejected; live updates stopped until reconnection', {
+                    'namzu.connector.server': this.config.serverName,
+                    'namzu.connector.reason': `MCP error ${message.error.code}: ${message.error.message}`,
+                });
+            }
+            this.finishModernSubscription(subscription, message.error
+                ? `server rejected subscription: ${message.error.message}`
+                : 'server closed stream', false, message.error?.code !== JSON_RPC_METHOD_NOT_FOUND && message.error !== undefined);
+            return true;
+        }
+        const method = message.method;
+        if (!method)
+            return false;
+        const isAck = method === 'notifications/subscriptions/acknowledged';
+        const kind = Object.hasOwn(SUBSCRIPTION_NOTIFICATIONS, method)
+            ? SUBSCRIPTION_NOTIFICATIONS[method]
+            : undefined;
+        const isSubscribedEvent = isAck || kind !== undefined || method === 'notifications/resources/updated';
+        if (!isSubscribedEvent)
+            return false;
+        const meta = message.params?._meta;
+        const id = meta && typeof meta === 'object' && !Array.isArray(meta)
+            ? meta[SUBSCRIPTION_ID_META_KEY]
+            : undefined;
+        if (!subscription || id !== subscription.id || message.id !== undefined) {
+            this.log.warn('Ignoring MCP subscription notification without the active subscription ID', {
+                'namzu.connector.server': this.config.serverName,
+                'namzu.connector.method': method,
+            });
+            return true;
+        }
+        if (isAck) {
+            if (subscription.acknowledged) {
+                this.finishModernSubscription(subscription, 'duplicate acknowledgment', true);
+                return true;
+            }
+            const acknowledged = acknowledgedFilter(message.params?.notifications, subscription.requested);
+            if (!acknowledged) {
+                this.finishModernSubscription(subscription, 'invalid acknowledgment filter', true);
+                return true;
+            }
+            subscription.acknowledged = acknowledged;
+            clearTimeout(subscription.ackTimer);
+            for (const handler of [...this.notificationHandlers]) {
+                this.reconcileSubscription(subscription, handler);
+            }
+            return true;
+        }
+        if (!subscription.acknowledged) {
+            this.finishModernSubscription(subscription, 'notification arrived before acknowledgment', true);
+            return true;
+        }
+        if (!kind || subscription.acknowledged[kind] !== true) {
+            this.log.warn('Ignoring unrequested MCP subscription notification', {
+                'namzu.connector.server': this.config.serverName,
+                'namzu.connector.method': method,
+            });
+            return true;
+        }
+        for (const handler of [...this.notificationHandlers])
+            handler(method, message.params);
+        return true;
+    }
+    /** Re-list once when a subscription becomes live; it may have missed a change while opening. */
+    reconcileSubscription(subscription, handler) {
+        if (this.modernSubscription !== subscription)
+            return;
+        for (const [method, kind] of Object.entries(SUBSCRIPTION_NOTIFICATIONS)) {
+            if (subscription.acknowledged?.[kind])
+                handler(method);
+        }
+    }
     requireConnected() {
         if (this.status !== 'connected') {
             throw new Error(`MCPClient "${this.config.serverName}" is not connected (status: ${this.status})`);