@mcp-z/client 1.0.0

package/dist/esm/connection/wait-for-http-ready.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/connection/wait-for-http-ready.ts"],"sourcesContent":["/**\n * wait-for-http-ready.ts\n *\n * Utility for waiting for HTTP servers to become ready.\n */\n\n/**\n * Wait for HTTP server to be ready by checking endpoint accessibility.\n * Used to handle HTTP servers that need time to start listening.\n *\n * @param url - URL to check for server readiness\n * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000)\n * @returns Promise that resolves when server is ready\n * @throws Error if server doesn't become ready within timeout\n */\nexport async function waitForHttpReady(url: string, timeoutMs = 30000): Promise<void> {\n  const start = Date.now();\n  const maxRetries = Math.ceil(timeoutMs / 100); // Check every 100ms\n\n  for (let i = 0; i < maxRetries; i++) {\n    try {\n      // Use HEAD request to check server is responding\n      const response = await fetch(url, {\n        method: 'HEAD',\n        headers: { Connection: 'close' },\n        signal: AbortSignal.timeout(500), // 500ms per attempt\n      });\n\n      // Server is responding if we get any HTTP status\n      if (response.status >= 200 && response.status < 500) {\n        return;\n      }\n\n      // Server error (5xx) - keep trying as it might still be starting\n    } catch (_error) {\n      // Connection refused, timeout, or network error\n      // Server not ready yet, continue polling\n      if (i === maxRetries - 1) {\n        const elapsed = Date.now() - start;\n        throw new Error(`HTTP server ${url} not ready after ${elapsed}ms`);\n      }\n    }\n\n    // Wait before retry\n    await new Promise((resolve) => setTimeout(resolve, 100));\n  }\n\n  throw new Error(`HTTP server ${url} not ready after ${timeoutMs}ms`);\n}\n"],"names":["waitForHttpReady","url","timeoutMs","start","Date","now","maxRetries","Math","ceil","i","response","fetch","method","headers","Connection","signal","AbortSignal","timeout","status","_error","elapsed","Error","Promise","resolve","setTimeout"],"mappings":"AAAA;;;;CAIC,GAED;;;;;;;;CAQC,GACD,OAAO,eAAeA,iBAAiBC,GAAW,EAAEC,YAAY,KAAK;IACnE,MAAMC,QAAQC,KAAKC,GAAG;IACtB,MAAMC,aAAaC,KAAKC,IAAI,CAACN,YAAY,MAAM,oBAAoB;IAEnE,IAAK,IAAIO,IAAI,GAAGA,IAAIH,YAAYG,IAAK;QACnC,IAAI;YACF,iDAAiD;YACjD,MAAMC,WAAW,MAAMC,MAAMV,KAAK;gBAChCW,QAAQ;gBACRC,SAAS;oBAAEC,YAAY;gBAAQ;gBAC/BC,QAAQC,YAAYC,OAAO,CAAC;YAC9B;YAEA,iDAAiD;YACjD,IAAIP,SAASQ,MAAM,IAAI,OAAOR,SAASQ,MAAM,GAAG,KAAK;gBACnD;YACF;QAEA,iEAAiE;QACnE,EAAE,OAAOC,QAAQ;YACf,gDAAgD;YAChD,yCAAyC;YACzC,IAAIV,MAAMH,aAAa,GAAG;gBACxB,MAAMc,UAAUhB,KAAKC,GAAG,KAAKF;gBAC7B,MAAM,IAAIkB,MAAM,CAAC,YAAY,EAAEpB,IAAI,iBAAiB,EAAEmB,QAAQ,EAAE,CAAC;YACnE;QACF;QAEA,oBAAoB;QACpB,MAAM,IAAIE,QAAQ,CAACC,UAAYC,WAAWD,SAAS;IACrD;IAEA,MAAM,IAAIF,MAAM,CAAC,YAAY,EAAEpB,IAAI,iBAAiB,EAAEC,UAAU,EAAE,CAAC;AACrE"}

package/dist/esm/dcr/dcr-authenticator.d.ts

@@ -0,0 +1,73 @@
+/**
+ * DCR Authenticator
+ * Consolidates DCR and OAuth flow logic for MCP HTTP servers
+ */
+import Keyv from 'keyv';
+import type { AuthCapabilities, TokenSet } from '../auth/types.js';
+import { type Logger } from '../utils/logger.js';
+/**
+ * DcrAuthenticator configuration options
+ */
+export interface DcrAuthenticatorOptions {
+    /** Custom Keyv store (for testing) - if not provided, uses default ~/.mcpeasy/tokens.json */
+    tokenStore?: Keyv;
+    /** Headless mode (don't open browser) */
+    headless?: boolean;
+    /** Required redirect URI for OAuth callback */
+    redirectUri: string;
+    /** Optional logger for debug output (defaults to singleton logger) */
+    logger?: Logger;
+}
+/**
+ * DcrAuthenticator manages authentication for MCP HTTP servers
+ * Handles DCR registration, OAuth flows, and token management
+ */
+export declare class DcrAuthenticator {
+    private tokenStore;
+    private dcrClient;
+    private oauthFlow;
+    private headless;
+    private redirectUri;
+    private logger;
+    constructor(options: DcrAuthenticatorOptions);
+    /**
+     * Detect if server is self-hosted DCR (vs external OAuth provider)
+     * Self-hosted servers have their own OAuth endpoints and manage token storage
+     */
+    private detectSelfHostedMode;
+    /**
+     * Ensure server is authenticated, performing DCR and OAuth if needed
+     * Proactively refreshes tokens if they're within 5 minutes of expiry
+     *
+     * @param baseUrl - Base URL of the server (e.g., https://example.com)
+     * @param capabilities - Auth capabilities from .well-known endpoint
+     * @returns Valid token set ready to use
+     *
+     * @throws Error if authentication fails
+     *
+     * @example
+     * const authenticator = new DcrAuthenticator({ redirectUri: 'http://localhost:3000/callback' });
+     * const tokens = await authenticator.ensureAuthenticated(
+     *   'https://example.com',
+     *   capabilities
+     * );
+     */
+    ensureAuthenticated(baseUrl: string, capabilities: AuthCapabilities): Promise<TokenSet>;
+    /**
+     * Handle authentication for self-hosted DCR servers
+     * Self-hosted servers manage their own token storage via /oauth/verify
+     */
+    private ensureAuthenticatedSelfHosted;
+    /**
+     * Handle authentication for external OAuth providers (original implementation)
+     */
+    private ensureAuthenticatedExternal;
+    /**
+     * Refresh access token using refresh token
+     */
+    private refreshTokens;
+    /**
+     * Delete stored tokens for a server
+     */
+    deleteTokens(baseUrl: string): Promise<void>;
+}

package/dist/esm/dcr/dcr-authenticator.js

@@ -0,0 +1,235 @@
+/**
+ * DCR Authenticator
+ * Consolidates DCR and OAuth flow logic for MCP HTTP servers
+ */ import path from 'node:path';
+import * as fs from 'fs';
+import Keyv from 'keyv';
+import { KeyvFile } from 'keyv-file';
+import { InteractiveOAuthFlow } from '../auth/interactive-oauth-flow.js';
+import { logger as defaultLogger } from '../utils/logger.js';
+import { DynamicClientRegistrar } from './dynamic-client-registrar.js';
+/**
+ * Buffer time before token expiry to trigger proactive refresh (5 minutes)
+ */ const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+/**
+ * DcrAuthenticator manages authentication for MCP HTTP servers
+ * Handles DCR registration, OAuth flows, and token management
+ */ export class DcrAuthenticator {
+    /**
+   * Detect if server is self-hosted DCR (vs external OAuth provider)
+   * Self-hosted servers have their own OAuth endpoints and manage token storage
+   */ async detectSelfHostedMode(baseUrl) {
+        try {
+            // Self-hosted DCR servers typically run their own OAuth server
+            // Check if this is a self-hosted instance by testing OAuth metadata
+            // For now, assume self-hosted if baseUrl matches common localhost patterns
+            // TODO: Implement proper self-hosted detection logic
+            return baseUrl.includes('localhost') || baseUrl.includes('127.0.0.1');
+        } catch (_error) {
+            return false; // Assume external mode if detection fails
+        }
+    }
+    /**
+   * Ensure server is authenticated, performing DCR and OAuth if needed
+   * Proactively refreshes tokens if they're within 5 minutes of expiry
+   *
+   * @param baseUrl - Base URL of the server (e.g., https://example.com)
+   * @param capabilities - Auth capabilities from .well-known endpoint
+   * @returns Valid token set ready to use
+   *
+   * @throws Error if authentication fails
+   *
+   * @example
+   * const authenticator = new DcrAuthenticator({ redirectUri: 'http://localhost:3000/callback' });
+   * const tokens = await authenticator.ensureAuthenticated(
+   *   'https://example.com',
+   *   capabilities
+   * );
+   */ async ensureAuthenticated(baseUrl, capabilities) {
+        // Auto-detect server mode
+        const isSelfHosted = await this.detectSelfHostedMode(baseUrl);
+        if (isSelfHosted) {
+            return this.ensureAuthenticatedSelfHosted(baseUrl, capabilities);
+        }
+        return this.ensureAuthenticatedExternal(baseUrl, capabilities);
+    }
+    /**
+   * Handle authentication for self-hosted DCR servers
+   * Self-hosted servers manage their own token storage via /oauth/verify
+   */ async ensureAuthenticatedSelfHosted(baseUrl, capabilities) {
+        const dcrTokenKey = `dcr-tokens:${baseUrl}`;
+        // 1. Check for existing DCR tokens (different from external tokens)
+        let tokens = await this.tokenStore.get(dcrTokenKey);
+        if (tokens) {
+            // 2. Verify token is still valid by calling /oauth/verify
+            try {
+                const verifyUrl = `${baseUrl}/oauth/verify`;
+                const verifyResponse = await fetch(verifyUrl, {
+                    headers: {
+                        Authorization: `Bearer ${tokens.accessToken}`,
+                        Connection: 'close'
+                    }
+                });
+                if (verifyResponse.ok) {
+                    const verifyData = await verifyResponse.json();
+                    if (verifyData.token === tokens.accessToken) {
+                        // Token is still valid with the self-hosted server
+                        return tokens;
+                    }
+                }
+            } catch (_error) {
+            // Token verification failed - need to re-authenticate
+            }
+            // Token is expired or invalid
+            await this.tokenStore.delete(dcrTokenKey);
+            tokens = undefined;
+        }
+        // 3. No valid tokens - perform full DCR + OAuth flow
+        if (!capabilities.registrationEndpoint || !capabilities.authorizationEndpoint || !capabilities.tokenEndpoint) {
+            throw new Error('Server does not provide required OAuth endpoints');
+        }
+        this.logger.debug('🔐 No valid tokens found, starting self-hosted DCR authentication...');
+        // Extract port from pre-resolved redirectUri
+        const port = parseInt(new URL(this.redirectUri).port, 10) || (this.redirectUri.startsWith('https:') ? 443 : 80);
+        // Register OAuth client via DCR
+        this.logger.debug('📝 Registering OAuth client with self-hosted server...');
+        const client = await this.dcrClient.registerClient(capabilities.registrationEndpoint, {
+            redirectUri: this.redirectUri
+        });
+        // Perform OAuth authorization flow with PKCE (RFC 7636)
+        const flowOptions = {
+            port,
+            headless: this.headless,
+            redirectUri: this.redirectUri,
+            pkce: true,
+            logger: this.logger
+        };
+        if (capabilities.scopes) {
+            flowOptions.scopes = capabilities.scopes;
+        }
+        tokens = await this.oauthFlow.performAuthFlow(capabilities.authorizationEndpoint, capabilities.tokenEndpoint, client.clientId, client.clientSecret, flowOptions);
+        // For self-hosted mode, verify the token works with /oauth/verify immediately
+        try {
+            const verifyUrl = `${baseUrl}/oauth/verify`;
+            const verifyResponse = await fetch(verifyUrl, {
+                headers: {
+                    Authorization: `Bearer ${tokens.accessToken}`,
+                    Connection: 'close'
+                }
+            });
+            if (!verifyResponse.ok) {
+                throw new Error(`DCR token verification failed after authentication: ${verifyResponse.status}`);
+            }
+            const verifyData = await verifyResponse.json();
+            if (verifyData.token !== tokens.accessToken) {
+                throw new Error('DCR server returned different token in verification');
+            }
+            this.logger.debug('✅ DCR token verified with self-hosted server');
+        } catch (error) {
+            this.logger.error('❌ DCR token verification failed:', error instanceof Error ? error.message : String(error));
+            throw new Error('Self-hosted DCR authentication completed but token verification failed');
+        }
+        // Save tokens for future use
+        await this.tokenStore.set(dcrTokenKey, tokens);
+        this.logger.debug('✅ Self-hosted DCR authentication successful, tokens saved');
+        return tokens;
+    }
+    /**
+   * Handle authentication for external OAuth providers (original implementation)
+   */ async ensureAuthenticatedExternal(baseUrl, capabilities) {
+        const tokenKey = `tokens:${baseUrl}`;
+        // 1. Check for existing tokens
+        let tokens = await this.tokenStore.get(tokenKey);
+        if (tokens) {
+            // 2. Proactive refresh if token expires within 5 minutes
+            if (tokens.expiresAt < Date.now() + REFRESH_BUFFER_MS) {
+                this.logger.debug('🔄 Refreshing access token...');
+                try {
+                    tokens = await this.refreshTokens(tokens, capabilities.tokenEndpoint);
+                    await this.tokenStore.set(tokenKey, tokens);
+                    this.logger.debug('✅ Token refreshed successfully');
+                } catch (_error) {
+                    // Refresh failed - clear tokens and re-authenticate
+                    this.logger.warn('⚠️  Token refresh failed, re-authenticating...');
+                    await this.tokenStore.delete(tokenKey);
+                    tokens = undefined;
+                }
+            }
+            if (tokens) {
+                return tokens;
+            }
+        }
+        // 3. No valid tokens - perform DCR + OAuth flow
+        if (!capabilities.registrationEndpoint || !capabilities.authorizationEndpoint || !capabilities.tokenEndpoint) {
+            throw new Error('Server does not provide required OAuth endpoints');
+        }
+        this.logger.debug('🔐 No valid tokens found, starting external OAuth authentication...');
+        // Extract port from pre-resolved redirectUri
+        const port = parseInt(new URL(this.redirectUri).port, 10) || (this.redirectUri.startsWith('https:') ? 443 : 80);
+        // Register OAuth client via DCR
+        this.logger.debug('📝 Registering OAuth client...');
+        const client = await this.dcrClient.registerClient(capabilities.registrationEndpoint, {
+            redirectUri: this.redirectUri
+        });
+        // Perform OAuth authorization flow with PKCE (RFC 7636)
+        const flowOptions = {
+            port,
+            headless: this.headless,
+            redirectUri: this.redirectUri,
+            pkce: true,
+            logger: this.logger
+        };
+        if (capabilities.scopes) {
+            flowOptions.scopes = capabilities.scopes;
+        }
+        tokens = await this.oauthFlow.performAuthFlow(capabilities.authorizationEndpoint, capabilities.tokenEndpoint, client.clientId, client.clientSecret, flowOptions);
+        // Save tokens for future use
+        await this.tokenStore.set(tokenKey, tokens);
+        this.logger.debug('✅ Authentication successful, tokens saved');
+        return tokens;
+    }
+    /**
+   * Refresh access token using refresh token
+   */ async refreshTokens(tokens, tokenEndpoint) {
+        if (!tokenEndpoint) {
+            throw new Error('Token endpoint not available for refresh');
+        }
+        if (!tokens.refreshToken) {
+            throw new Error('No refresh token available');
+        }
+        if (!tokens.clientId || !tokens.clientSecret) {
+            throw new Error('Client credentials not available for refresh');
+        }
+        return await this.oauthFlow.refreshTokens(tokenEndpoint, tokens.refreshToken, tokens.clientId, tokens.clientSecret);
+    }
+    /**
+   * Delete stored tokens for a server
+   */ async deleteTokens(baseUrl) {
+        const tokenKey = `tokens:${baseUrl}`;
+        await this.tokenStore.delete(tokenKey);
+        this.logger.debug(`🗑️  Deleted tokens for ${baseUrl}`);
+    }
+    constructor(options){
+        var _options_logger;
+        if (options.tokenStore) {
+            this.tokenStore = options.tokenStore;
+        } else {
+            // Default CLI store in .mcp-z directory (per-project)
+            const storePath = path.join(process.cwd(), '.mcp-z', 'tokens.json');
+            // Ensure directory exists before creating store
+            fs.mkdirSync(path.dirname(storePath), {
+                recursive: true
+            });
+            this.tokenStore = new Keyv({
+                store: new KeyvFile({
+                    filename: storePath
+                })
+            });
+        }
+        this.dcrClient = new DynamicClientRegistrar();
+        this.oauthFlow = new InteractiveOAuthFlow();
+        this.headless = options.headless || false;
+        this.redirectUri = options.redirectUri;
+        this.logger = (_options_logger = options.logger) !== null && _options_logger !== void 0 ? _options_logger : defaultLogger;
+    }
+}

package/dist/esm/dcr/dcr-authenticator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/dcr/dcr-authenticator.ts"],"sourcesContent":["/**\n * DCR Authenticator\n * Consolidates DCR and OAuth flow logic for MCP HTTP servers\n */\n\nimport path from 'node:path';\nimport * as fs from 'fs';\nimport Keyv from 'keyv';\nimport { KeyvFile } from 'keyv-file';\nimport { InteractiveOAuthFlow } from '../auth/interactive-oauth-flow.ts';\nimport type { AuthCapabilities, TokenSet } from '../auth/types.ts';\nimport { logger as defaultLogger, type Logger } from '../utils/logger.ts';\nimport { DynamicClientRegistrar } from './dynamic-client-registrar.ts';\n\n/**\n * DcrAuthenticator configuration options\n */\nexport interface DcrAuthenticatorOptions {\n  /** Custom Keyv store (for testing) - if not provided, uses default ~/.mcpeasy/tokens.json */\n  tokenStore?: Keyv;\n  /** Headless mode (don't open browser) */\n  headless?: boolean;\n  /** Required redirect URI for OAuth callback */\n  redirectUri: string;\n  /** Optional logger for debug output (defaults to singleton logger) */\n  logger?: Logger;\n}\n\n/**\n * Buffer time before token expiry to trigger proactive refresh (5 minutes)\n */\nconst REFRESH_BUFFER_MS = 5 * 60 * 1000;\n\n/**\n * DcrAuthenticator manages authentication for MCP HTTP servers\n * Handles DCR registration, OAuth flows, and token management\n */\nexport class DcrAuthenticator {\n  private tokenStore: Keyv;\n  private dcrClient: DynamicClientRegistrar;\n  private oauthFlow: InteractiveOAuthFlow;\n  private headless: boolean;\n  private redirectUri: string;\n  private logger: Logger;\n\n  constructor(options: DcrAuthenticatorOptions) {\n    if (options.tokenStore) {\n      this.tokenStore = options.tokenStore;\n    } else {\n      // Default CLI store in .mcp-z directory (per-project)\n      const storePath = path.join(process.cwd(), '.mcp-z', 'tokens.json');\n\n      // Ensure directory exists before creating store\n      fs.mkdirSync(path.dirname(storePath), { recursive: true });\n\n      this.tokenStore = new Keyv({\n        store: new KeyvFile({ filename: storePath }),\n      });\n    }\n    this.dcrClient = new DynamicClientRegistrar();\n    this.oauthFlow = new InteractiveOAuthFlow();\n    this.headless = options.headless || false;\n    this.redirectUri = options.redirectUri;\n    this.logger = options.logger ?? defaultLogger;\n  }\n\n  /**\n   * Detect if server is self-hosted DCR (vs external OAuth provider)\n   * Self-hosted servers have their own OAuth endpoints and manage token storage\n   */\n  private async detectSelfHostedMode(baseUrl: string): Promise<boolean> {\n    try {\n      // Self-hosted DCR servers typically run their own OAuth server\n      // Check if this is a self-hosted instance by testing OAuth metadata\n      // For now, assume self-hosted if baseUrl matches common localhost patterns\n      // TODO: Implement proper self-hosted detection logic\n      return baseUrl.includes('localhost') || baseUrl.includes('127.0.0.1');\n    } catch (_error) {\n      return false; // Assume external mode if detection fails\n    }\n  }\n\n  /**\n   * Ensure server is authenticated, performing DCR and OAuth if needed\n   * Proactively refreshes tokens if they're within 5 minutes of expiry\n   *\n   * @param baseUrl - Base URL of the server (e.g., https://example.com)\n   * @param capabilities - Auth capabilities from .well-known endpoint\n   * @returns Valid token set ready to use\n   *\n   * @throws Error if authentication fails\n   *\n   * @example\n   * const authenticator = new DcrAuthenticator({ redirectUri: 'http://localhost:3000/callback' });\n   * const tokens = await authenticator.ensureAuthenticated(\n   *   'https://example.com',\n   *   capabilities\n   * );\n   */\n  async ensureAuthenticated(baseUrl: string, capabilities: AuthCapabilities): Promise<TokenSet> {\n    // Auto-detect server mode\n    const isSelfHosted = await this.detectSelfHostedMode(baseUrl);\n\n    if (isSelfHosted) {\n      return this.ensureAuthenticatedSelfHosted(baseUrl, capabilities);\n    }\n    return this.ensureAuthenticatedExternal(baseUrl, capabilities);\n  }\n\n  /**\n   * Handle authentication for self-hosted DCR servers\n   * Self-hosted servers manage their own token storage via /oauth/verify\n   */\n  private async ensureAuthenticatedSelfHosted(baseUrl: string, capabilities: AuthCapabilities): Promise<TokenSet> {\n    const dcrTokenKey = `dcr-tokens:${baseUrl}`;\n\n    // 1. Check for existing DCR tokens (different from external tokens)\n    let tokens = (await this.tokenStore.get(dcrTokenKey)) as TokenSet | undefined;\n\n    if (tokens) {\n      // 2. Verify token is still valid by calling /oauth/verify\n      try {\n        const verifyUrl = `${baseUrl}/oauth/verify`;\n        const verifyResponse = await fetch(verifyUrl, {\n          headers: { Authorization: `Bearer ${tokens.accessToken}`, Connection: 'close' },\n        });\n\n        if (verifyResponse.ok) {\n          const verifyData = (await verifyResponse.json()) as { token?: string };\n          if (verifyData.token === tokens.accessToken) {\n            // Token is still valid with the self-hosted server\n            return tokens;\n          }\n        }\n      } catch (_error) {\n        // Token verification failed - need to re-authenticate\n      }\n\n      // Token is expired or invalid\n      await this.tokenStore.delete(dcrTokenKey);\n      tokens = undefined;\n    }\n\n    // 3. No valid tokens - perform full DCR + OAuth flow\n    if (!capabilities.registrationEndpoint || !capabilities.authorizationEndpoint || !capabilities.tokenEndpoint) {\n      throw new Error('Server does not provide required OAuth endpoints');\n    }\n\n    this.logger.debug('🔐 No valid tokens found, starting self-hosted DCR authentication...');\n\n    // Extract port from pre-resolved redirectUri\n    const port = parseInt(new URL(this.redirectUri).port, 10) || (this.redirectUri.startsWith('https:') ? 443 : 80);\n\n    // Register OAuth client via DCR\n    this.logger.debug('📝 Registering OAuth client with self-hosted server...');\n    const client = await this.dcrClient.registerClient(capabilities.registrationEndpoint, {\n      redirectUri: this.redirectUri,\n    });\n\n    // Perform OAuth authorization flow with PKCE (RFC 7636)\n    const flowOptions: { port: number; headless: boolean; scopes?: string[]; redirectUri: string; pkce: boolean; logger: Logger } = {\n      port,\n      headless: this.headless,\n      redirectUri: this.redirectUri,\n      pkce: true,\n      logger: this.logger,\n    };\n    if (capabilities.scopes) {\n      flowOptions.scopes = capabilities.scopes;\n    }\n\n    tokens = await this.oauthFlow.performAuthFlow(capabilities.authorizationEndpoint, capabilities.tokenEndpoint, client.clientId, client.clientSecret, flowOptions);\n\n    // For self-hosted mode, verify the token works with /oauth/verify immediately\n    try {\n      const verifyUrl = `${baseUrl}/oauth/verify`;\n      const verifyResponse = await fetch(verifyUrl, {\n        headers: { Authorization: `Bearer ${tokens.accessToken}`, Connection: 'close' },\n      });\n\n      if (!verifyResponse.ok) {\n        throw new Error(`DCR token verification failed after authentication: ${verifyResponse.status}`);\n      }\n\n      const verifyData = (await verifyResponse.json()) as { token?: string };\n      if (verifyData.token !== tokens.accessToken) {\n        throw new Error('DCR server returned different token in verification');\n      }\n\n      this.logger.debug('✅ DCR token verified with self-hosted server');\n    } catch (error) {\n      this.logger.error('❌ DCR token verification failed:', error instanceof Error ? error.message : String(error));\n      throw new Error('Self-hosted DCR authentication completed but token verification failed');\n    }\n\n    // Save tokens for future use\n    await this.tokenStore.set(dcrTokenKey, tokens);\n    this.logger.debug('✅ Self-hosted DCR authentication successful, tokens saved');\n\n    return tokens;\n  }\n\n  /**\n   * Handle authentication for external OAuth providers (original implementation)\n   */\n  private async ensureAuthenticatedExternal(baseUrl: string, capabilities: AuthCapabilities): Promise<TokenSet> {\n    const tokenKey = `tokens:${baseUrl}`;\n\n    // 1. Check for existing tokens\n    let tokens = (await this.tokenStore.get(tokenKey)) as TokenSet | undefined;\n\n    if (tokens) {\n      // 2. Proactive refresh if token expires within 5 minutes\n      if (tokens.expiresAt < Date.now() + REFRESH_BUFFER_MS) {\n        this.logger.debug('🔄 Refreshing access token...');\n\n        try {\n          tokens = await this.refreshTokens(tokens, capabilities.tokenEndpoint);\n          await this.tokenStore.set(tokenKey, tokens);\n          this.logger.debug('✅ Token refreshed successfully');\n        } catch (_error) {\n          // Refresh failed - clear tokens and re-authenticate\n          this.logger.warn('⚠️  Token refresh failed, re-authenticating...');\n          await this.tokenStore.delete(tokenKey);\n          tokens = undefined;\n        }\n      }\n\n      if (tokens) {\n        return tokens;\n      }\n    }\n\n    // 3. No valid tokens - perform DCR + OAuth flow\n    if (!capabilities.registrationEndpoint || !capabilities.authorizationEndpoint || !capabilities.tokenEndpoint) {\n      throw new Error('Server does not provide required OAuth endpoints');\n    }\n\n    this.logger.debug('🔐 No valid tokens found, starting external OAuth authentication...');\n\n    // Extract port from pre-resolved redirectUri\n    const port = parseInt(new URL(this.redirectUri).port, 10) || (this.redirectUri.startsWith('https:') ? 443 : 80);\n\n    // Register OAuth client via DCR\n    this.logger.debug('📝 Registering OAuth client...');\n    const client = await this.dcrClient.registerClient(capabilities.registrationEndpoint, {\n      redirectUri: this.redirectUri,\n    });\n\n    // Perform OAuth authorization flow with PKCE (RFC 7636)\n    const flowOptions: { port: number; headless: boolean; scopes?: string[]; redirectUri: string; pkce: boolean; logger: Logger } = {\n      port,\n      headless: this.headless,\n      redirectUri: this.redirectUri,\n      pkce: true,\n      logger: this.logger,\n    };\n    if (capabilities.scopes) {\n      flowOptions.scopes = capabilities.scopes;\n    }\n\n    tokens = await this.oauthFlow.performAuthFlow(capabilities.authorizationEndpoint, capabilities.tokenEndpoint, client.clientId, client.clientSecret, flowOptions);\n\n    // Save tokens for future use\n    await this.tokenStore.set(tokenKey, tokens);\n    this.logger.debug('✅ Authentication successful, tokens saved');\n\n    return tokens;\n  }\n\n  /**\n   * Refresh access token using refresh token\n   */\n  private async refreshTokens(tokens: TokenSet, tokenEndpoint?: string): Promise<TokenSet> {\n    if (!tokenEndpoint) {\n      throw new Error('Token endpoint not available for refresh');\n    }\n\n    if (!tokens.refreshToken) {\n      throw new Error('No refresh token available');\n    }\n\n    if (!tokens.clientId || !tokens.clientSecret) {\n      throw new Error('Client credentials not available for refresh');\n    }\n\n    return await this.oauthFlow.refreshTokens(tokenEndpoint, tokens.refreshToken, tokens.clientId, tokens.clientSecret);\n  }\n\n  /**\n   * Delete stored tokens for a server\n   */\n  async deleteTokens(baseUrl: string): Promise<void> {\n    const tokenKey = `tokens:${baseUrl}`;\n    await this.tokenStore.delete(tokenKey);\n    this.logger.debug(`🗑️  Deleted tokens for ${baseUrl}`);\n  }\n}\n"],"names":["path","fs","Keyv","KeyvFile","InteractiveOAuthFlow","logger","defaultLogger","DynamicClientRegistrar","REFRESH_BUFFER_MS","DcrAuthenticator","detectSelfHostedMode","baseUrl","includes","_error","ensureAuthenticated","capabilities","isSelfHosted","ensureAuthenticatedSelfHosted","ensureAuthenticatedExternal","dcrTokenKey","tokens","tokenStore","get","verifyUrl","verifyResponse","fetch","headers","Authorization","accessToken","Connection","ok","verifyData","json","token","delete","undefined","registrationEndpoint","authorizationEndpoint","tokenEndpoint","Error","debug","port","parseInt","URL","redirectUri","startsWith","client","dcrClient","registerClient","flowOptions","headless","pkce","scopes","oauthFlow","performAuthFlow","clientId","clientSecret","status","error","message","String","set","tokenKey","expiresAt","Date","now","refreshTokens","warn","refreshToken","deleteTokens","options","storePath","join","process","cwd","mkdirSync","dirname","recursive","store","filename"],"mappings":"AAAA;;;CAGC,GAED,OAAOA,UAAU,YAAY;AAC7B,YAAYC,QAAQ,KAAK;AACzB,OAAOC,UAAU,OAAO;AACxB,SAASC,QAAQ,QAAQ,YAAY;AACrC,SAASC,oBAAoB,QAAQ,oCAAoC;AAEzE,SAASC,UAAUC,aAAa,QAAqB,qBAAqB;AAC1E,SAASC,sBAAsB,QAAQ,gCAAgC;AAgBvE;;CAEC,GACD,MAAMC,oBAAoB,IAAI,KAAK;AAEnC;;;CAGC,GACD,OAAO,MAAMC;IA6BX;;;GAGC,GACD,MAAcC,qBAAqBC,OAAe,EAAoB;QACpE,IAAI;YACF,+DAA+D;YAC/D,oEAAoE;YACpE,2EAA2E;YAC3E,qDAAqD;YACrD,OAAOA,QAAQC,QAAQ,CAAC,gBAAgBD,QAAQC,QAAQ,CAAC;QAC3D,EAAE,OAAOC,QAAQ;YACf,OAAO,OAAO,0CAA0C;QAC1D;IACF;IAEA;;;;;;;;;;;;;;;;GAgBC,GACD,MAAMC,oBAAoBH,OAAe,EAAEI,YAA8B,EAAqB;QAC5F,0BAA0B;QAC1B,MAAMC,eAAe,MAAM,IAAI,CAACN,oBAAoB,CAACC;QAErD,IAAIK,cAAc;YAChB,OAAO,IAAI,CAACC,6BAA6B,CAACN,SAASI;QACrD;QACA,OAAO,IAAI,CAACG,2BAA2B,CAACP,SAASI;IACnD;IAEA;;;GAGC,GACD,MAAcE,8BAA8BN,OAAe,EAAEI,YAA8B,EAAqB;QAC9G,MAAMI,cAAc,CAAC,WAAW,EAAER,SAAS;QAE3C,oEAAoE;QACpE,IAAIS,SAAU,MAAM,IAAI,CAACC,UAAU,CAACC,GAAG,CAACH;QAExC,IAAIC,QAAQ;YACV,0DAA0D;YAC1D,IAAI;gBACF,MAAMG,YAAY,GAAGZ,QAAQ,aAAa,CAAC;gBAC3C,MAAMa,iBAAiB,MAAMC,MAAMF,WAAW;oBAC5CG,SAAS;wBAAEC,eAAe,CAAC,OAAO,EAAEP,OAAOQ,WAAW,EAAE;wBAAEC,YAAY;oBAAQ;gBAChF;gBAEA,IAAIL,eAAeM,EAAE,EAAE;oBACrB,MAAMC,aAAc,MAAMP,eAAeQ,IAAI;oBAC7C,IAAID,WAAWE,KAAK,KAAKb,OAAOQ,WAAW,EAAE;wBAC3C,mDAAmD;wBACnD,OAAOR;oBACT;gBACF;YACF,EAAE,OAAOP,QAAQ;YACf,sDAAsD;YACxD;YAEA,8BAA8B;YAC9B,MAAM,IAAI,CAACQ,UAAU,CAACa,MAAM,CAACf;YAC7BC,SAASe;QACX;QAEA,qDAAqD;QACrD,IAAI,CAACpB,aAAaqB,oBAAoB,IAAI,CAACrB,aAAasB,qBAAqB,IAAI,CAACtB,aAAauB,aAAa,EAAE;YAC5G,MAAM,IAAIC,MAAM;QAClB;QAEA,IAAI,CAAClC,MAAM,CAACmC,KAAK,CAAC;QAElB,6CAA6C;QAC7C,MAAMC,OAAOC,SAAS,IAAIC,IAAI,IAAI,CAACC,WAAW,EAAEH,IAAI,EAAE,OAAQ,CAAA,IAAI,CAACG,WAAW,CAACC,UAAU,CAAC,YAAY,MAAM,EAAC;QAE7G,gCAAgC;QAChC,IAAI,CAACxC,MAAM,CAACmC,KAAK,CAAC;QAClB,MAAMM,SAAS,MAAM,IAAI,CAACC,SAAS,CAACC,cAAc,CAACjC,aAAaqB,oBAAoB,EAAE;YACpFQ,aAAa,IAAI,CAACA,WAAW;QAC/B;QAEA,wDAAwD;QACxD,MAAMK,cAA0H;YAC9HR;YACAS,UAAU,IAAI,CAACA,QAAQ;YACvBN,aAAa,IAAI,CAACA,WAAW;YAC7BO,MAAM;YACN9C,QAAQ,IAAI,CAACA,MAAM;QACrB;QACA,IAAIU,aAAaqC,MAAM,EAAE;YACvBH,YAAYG,MAAM,GAAGrC,aAAaqC,MAAM;QAC1C;QAEAhC,SAAS,MAAM,IAAI,CAACiC,SAAS,CAACC,eAAe,CAACvC,aAAasB,qBAAqB,EAAEtB,aAAauB,aAAa,EAAEQ,OAAOS,QAAQ,EAAET,OAAOU,YAAY,EAAEP;QAEpJ,8EAA8E;QAC9E,IAAI;YACF,MAAM1B,YAAY,GAAGZ,QAAQ,aAAa,CAAC;YAC3C,MAAMa,iBAAiB,MAAMC,MAAMF,WAAW;gBAC5CG,SAAS;oBAAEC,eAAe,CAAC,OAAO,EAAEP,OAAOQ,WAAW,EAAE;oBAAEC,YAAY;gBAAQ;YAChF;YAEA,IAAI,CAACL,eAAeM,EAAE,EAAE;gBACtB,MAAM,IAAIS,MAAM,CAAC,oDAAoD,EAAEf,eAAeiC,MAAM,EAAE;YAChG;YAEA,MAAM1B,aAAc,MAAMP,eAAeQ,IAAI;YAC7C,IAAID,WAAWE,KAAK,KAAKb,OAAOQ,WAAW,EAAE;gBAC3C,MAAM,IAAIW,MAAM;YAClB;YAEA,IAAI,CAAClC,MAAM,CAACmC,KAAK,CAAC;QACpB,EAAE,OAAOkB,OAAO;YACd,IAAI,CAACrD,MAAM,CAACqD,KAAK,CAAC,oCAAoCA,iBAAiBnB,QAAQmB,MAAMC,OAAO,GAAGC,OAAOF;YACtG,MAAM,IAAInB,MAAM;QAClB;QAEA,6BAA6B;QAC7B,MAAM,IAAI,CAAClB,UAAU,CAACwC,GAAG,CAAC1C,aAAaC;QACvC,IAAI,CAACf,MAAM,CAACmC,KAAK,CAAC;QAElB,OAAOpB;IACT;IAEA;;GAEC,GACD,MAAcF,4BAA4BP,OAAe,EAAEI,YAA8B,EAAqB;QAC5G,MAAM+C,WAAW,CAAC,OAAO,EAAEnD,SAAS;QAEpC,+BAA+B;QAC/B,IAAIS,SAAU,MAAM,IAAI,CAACC,UAAU,CAACC,GAAG,CAACwC;QAExC,IAAI1C,QAAQ;YACV,yDAAyD;YACzD,IAAIA,OAAO2C,SAAS,GAAGC,KAAKC,GAAG,KAAKzD,mBAAmB;gBACrD,IAAI,CAACH,MAAM,CAACmC,KAAK,CAAC;gBAElB,IAAI;oBACFpB,SAAS,MAAM,IAAI,CAAC8C,aAAa,CAAC9C,QAAQL,aAAauB,aAAa;oBACpE,MAAM,IAAI,CAACjB,UAAU,CAACwC,GAAG,CAACC,UAAU1C;oBACpC,IAAI,CAACf,MAAM,CAACmC,KAAK,CAAC;gBACpB,EAAE,OAAO3B,QAAQ;oBACf,oDAAoD;oBACpD,IAAI,CAACR,MAAM,CAAC8D,IAAI,CAAC;oBACjB,MAAM,IAAI,CAAC9C,UAAU,CAACa,MAAM,CAAC4B;oBAC7B1C,SAASe;gBACX;YACF;YAEA,IAAIf,QAAQ;gBACV,OAAOA;YACT;QACF;QAEA,gDAAgD;QAChD,IAAI,CAACL,aAAaqB,oBAAoB,IAAI,CAACrB,aAAasB,qBAAqB,IAAI,CAACtB,aAAauB,aAAa,EAAE;YAC5G,MAAM,IAAIC,MAAM;QAClB;QAEA,IAAI,CAAClC,MAAM,CAACmC,KAAK,CAAC;QAElB,6CAA6C;QAC7C,MAAMC,OAAOC,SAAS,IAAIC,IAAI,IAAI,CAACC,WAAW,EAAEH,IAAI,EAAE,OAAQ,CAAA,IAAI,CAACG,WAAW,CAACC,UAAU,CAAC,YAAY,MAAM,EAAC;QAE7G,gCAAgC;QAChC,IAAI,CAACxC,MAAM,CAACmC,KAAK,CAAC;QAClB,MAAMM,SAAS,MAAM,IAAI,CAACC,SAAS,CAACC,cAAc,CAACjC,aAAaqB,oBAAoB,EAAE;YACpFQ,aAAa,IAAI,CAACA,WAAW;QAC/B;QAEA,wDAAwD;QACxD,MAAMK,cAA0H;YAC9HR;YACAS,UAAU,IAAI,CAACA,QAAQ;YACvBN,aAAa,IAAI,CAACA,WAAW;YAC7BO,MAAM;YACN9C,QAAQ,IAAI,CAACA,MAAM;QACrB;QACA,IAAIU,aAAaqC,MAAM,EAAE;YACvBH,YAAYG,MAAM,GAAGrC,aAAaqC,MAAM;QAC1C;QAEAhC,SAAS,MAAM,IAAI,CAACiC,SAAS,CAACC,eAAe,CAACvC,aAAasB,qBAAqB,EAAEtB,aAAauB,aAAa,EAAEQ,OAAOS,QAAQ,EAAET,OAAOU,YAAY,EAAEP;QAEpJ,6BAA6B;QAC7B,MAAM,IAAI,CAAC5B,UAAU,CAACwC,GAAG,CAACC,UAAU1C;QACpC,IAAI,CAACf,MAAM,CAACmC,KAAK,CAAC;QAElB,OAAOpB;IACT;IAEA;;GAEC,GACD,MAAc8C,cAAc9C,MAAgB,EAAEkB,aAAsB,EAAqB;QACvF,IAAI,CAACA,eAAe;YAClB,MAAM,IAAIC,MAAM;QAClB;QAEA,IAAI,CAACnB,OAAOgD,YAAY,EAAE;YACxB,MAAM,IAAI7B,MAAM;QAClB;QAEA,IAAI,CAACnB,OAAOmC,QAAQ,IAAI,CAACnC,OAAOoC,YAAY,EAAE;YAC5C,MAAM,IAAIjB,MAAM;QAClB;QAEA,OAAO,MAAM,IAAI,CAACc,SAAS,CAACa,aAAa,CAAC5B,eAAelB,OAAOgD,YAAY,EAAEhD,OAAOmC,QAAQ,EAAEnC,OAAOoC,YAAY;IACpH;IAEA;;GAEC,GACD,MAAMa,aAAa1D,OAAe,EAAiB;QACjD,MAAMmD,WAAW,CAAC,OAAO,EAAEnD,SAAS;QACpC,MAAM,IAAI,CAACU,UAAU,CAACa,MAAM,CAAC4B;QAC7B,IAAI,CAACzD,MAAM,CAACmC,KAAK,CAAC,CAAC,wBAAwB,EAAE7B,SAAS;IACxD;IA3PA,YAAY2D,OAAgC,CAAE;YAkB9BA;QAjBd,IAAIA,QAAQjD,UAAU,EAAE;YACtB,IAAI,CAACA,UAAU,GAAGiD,QAAQjD,UAAU;QACtC,OAAO;YACL,sDAAsD;YACtD,MAAMkD,YAAYvE,KAAKwE,IAAI,CAACC,QAAQC,GAAG,IAAI,UAAU;YAErD,gDAAgD;YAChDzE,GAAG0E,SAAS,CAAC3E,KAAK4E,OAAO,CAACL,YAAY;gBAAEM,WAAW;YAAK;YAExD,IAAI,CAACxD,UAAU,GAAG,IAAInB,KAAK;gBACzB4E,OAAO,IAAI3E,SAAS;oBAAE4E,UAAUR;gBAAU;YAC5C;QACF;QACA,IAAI,CAACxB,SAAS,GAAG,IAAIxC;QACrB,IAAI,CAAC8C,SAAS,GAAG,IAAIjD;QACrB,IAAI,CAAC8C,QAAQ,GAAGoB,QAAQpB,QAAQ,IAAI;QACpC,IAAI,CAACN,WAAW,GAAG0B,QAAQ1B,WAAW;QACtC,IAAI,CAACvC,MAAM,IAAGiE,kBAAAA,QAAQjE,MAAM,cAAdiE,6BAAAA,kBAAkBhE;IAClC;AAyOF"}

package/dist/esm/dcr/dynamic-client-registrar.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Dynamic Client Registration (DCR) Client
+ * Implements RFC 7591 for OAuth client registration
+ */
+import type { ClientCredentials, DcrRegistrationOptions } from '../auth/types.js';
+/**
+ * DynamicClientRegistrar handles Dynamic Client Registration with OAuth servers
+ */
+export declare class DynamicClientRegistrar {
+    /**
+     * Register a new OAuth client with the authorization server
+     *
+     * @param registrationEndpoint - DCR registration endpoint URL
+     * @param options - Registration options (client name, redirect URI)
+     * @returns Client credentials (client ID and secret)
+     *
+     * @throws Error if registration fails or server returns error
+     *
+     * @example
+     * const registrar = new DynamicClientRegistrar();
+     * const creds = await registrar.registerClient(
+     *   'https://example.com/oauth/register',
+     *   { clientName: '@mcp-z/client', redirectUri: 'http://localhost:3000/callback' }
+     * );
+     * console.log('Client ID:', creds.clientId);
+     */
+    registerClient(registrationEndpoint: string, options?: DcrRegistrationOptions): Promise<ClientCredentials>;
+}

package/dist/esm/dcr/dynamic-client-registrar.js

@@ -0,0 +1,66 @@
+/**
+ * Dynamic Client Registration (DCR) Client
+ * Implements RFC 7591 for OAuth client registration
+ */ /**
+ * DynamicClientRegistrar handles Dynamic Client Registration with OAuth servers
+ */ export class DynamicClientRegistrar {
+    /**
+   * Register a new OAuth client with the authorization server
+   *
+   * @param registrationEndpoint - DCR registration endpoint URL
+   * @param options - Registration options (client name, redirect URI)
+   * @returns Client credentials (client ID and secret)
+   *
+   * @throws Error if registration fails or server returns error
+   *
+   * @example
+   * const registrar = new DynamicClientRegistrar();
+   * const creds = await registrar.registerClient(
+   *   'https://example.com/oauth/register',
+   *   { clientName: '@mcp-z/client', redirectUri: 'http://localhost:3000/callback' }
+   * );
+   * console.log('Client ID:', creds.clientId);
+   */ async registerClient(registrationEndpoint, options = {}) {
+        const requestBody = {
+            client_name: options.clientName || '@mcp-z/client',
+            redirect_uris: options.redirectUri ? [
+                options.redirectUri
+            ] : [
+                'http://localhost:3000/callback'
+            ],
+            grant_types: [
+                'authorization_code',
+                'refresh_token'
+            ],
+            response_types: [
+                'code'
+            ],
+            token_endpoint_auth_method: 'client_secret_basic'
+        };
+        const response = await fetch(registrationEndpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                Connection: 'close'
+            },
+            body: JSON.stringify(requestBody)
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`DCR registration failed (${response.status}): ${errorText}`);
+        }
+        const data = await response.json();
+        if (!data.client_id) {
+            throw new Error('DCR registration response missing client_id');
+        }
+        const credentials = {
+            clientId: data.client_id,
+            clientSecret: data.client_secret || ''
+        };
+        if (data.client_id_issued_at) {
+            credentials.issuedAt = data.client_id_issued_at;
+        }
+        return credentials;
+    }
+}

package/dist/esm/dcr/dynamic-client-registrar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/dcr/dynamic-client-registrar.ts"],"sourcesContent":["/**\n * Dynamic Client Registration (DCR) Client\n * Implements RFC 7591 for OAuth client registration\n */\n\nimport type { ClientCredentials, DcrRegistrationOptions } from '../auth/types.ts';\n\n/**\n * DCR Registration Request (RFC 7591)\n */\ninterface DcrRegistrationRequest {\n  client_name?: string;\n  redirect_uris?: string[];\n  grant_types?: string[];\n  response_types?: string[];\n  token_endpoint_auth_method?: string;\n}\n\n/**\n * DCR Registration Response (RFC 7591)\n */\ninterface DcrRegistrationResponse {\n  client_id: string;\n  client_secret?: string;\n  client_id_issued_at?: number;\n  client_secret_expires_at?: number;\n}\n\n/**\n * DynamicClientRegistrar handles Dynamic Client Registration with OAuth servers\n */\nexport class DynamicClientRegistrar {\n  /**\n   * Register a new OAuth client with the authorization server\n   *\n   * @param registrationEndpoint - DCR registration endpoint URL\n   * @param options - Registration options (client name, redirect URI)\n   * @returns Client credentials (client ID and secret)\n   *\n   * @throws Error if registration fails or server returns error\n   *\n   * @example\n   * const registrar = new DynamicClientRegistrar();\n   * const creds = await registrar.registerClient(\n   *   'https://example.com/oauth/register',\n   *   { clientName: '@mcp-z/client', redirectUri: 'http://localhost:3000/callback' }\n   * );\n   * console.log('Client ID:', creds.clientId);\n   */\n  async registerClient(registrationEndpoint: string, options: DcrRegistrationOptions = {}): Promise<ClientCredentials> {\n    const requestBody: DcrRegistrationRequest = {\n      client_name: options.clientName || '@mcp-z/client',\n      redirect_uris: options.redirectUri ? [options.redirectUri] : ['http://localhost:3000/callback'],\n      grant_types: ['authorization_code', 'refresh_token'],\n      response_types: ['code'],\n      token_endpoint_auth_method: 'client_secret_basic',\n    };\n\n    const response = await fetch(registrationEndpoint, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        Accept: 'application/json',\n        Connection: 'close',\n      },\n      body: JSON.stringify(requestBody),\n    });\n\n    if (!response.ok) {\n      const errorText = await response.text();\n      throw new Error(`DCR registration failed (${response.status}): ${errorText}`);\n    }\n\n    const data = (await response.json()) as DcrRegistrationResponse;\n\n    if (!data.client_id) {\n      throw new Error('DCR registration response missing client_id');\n    }\n\n    const credentials: ClientCredentials = {\n      clientId: data.client_id,\n      clientSecret: data.client_secret || '',\n    };\n\n    if (data.client_id_issued_at) {\n      credentials.issuedAt = data.client_id_issued_at;\n    }\n\n    return credentials;\n  }\n}\n"],"names":["DynamicClientRegistrar","registerClient","registrationEndpoint","options","requestBody","client_name","clientName","redirect_uris","redirectUri","grant_types","response_types","token_endpoint_auth_method","response","fetch","method","headers","Accept","Connection","body","JSON","stringify","ok","errorText","text","Error","status","data","json","client_id","credentials","clientId","clientSecret","client_secret","client_id_issued_at","issuedAt"],"mappings":"AAAA;;;CAGC,GAyBD;;CAEC,GACD,OAAO,MAAMA;IACX;;;;;;;;;;;;;;;;GAgBC,GACD,MAAMC,eAAeC,oBAA4B,EAAEC,UAAkC,CAAC,CAAC,EAA8B;QACnH,MAAMC,cAAsC;YAC1CC,aAAaF,QAAQG,UAAU,IAAI;YACnCC,eAAeJ,QAAQK,WAAW,GAAG;gBAACL,QAAQK,WAAW;aAAC,GAAG;gBAAC;aAAiC;YAC/FC,aAAa;gBAAC;gBAAsB;aAAgB;YACpDC,gBAAgB;gBAAC;aAAO;YACxBC,4BAA4B;QAC9B;QAEA,MAAMC,WAAW,MAAMC,MAAMX,sBAAsB;YACjDY,QAAQ;YACRC,SAAS;gBACP,gBAAgB;gBAChBC,QAAQ;gBACRC,YAAY;YACd;YACAC,MAAMC,KAAKC,SAAS,CAAChB;QACvB;QAEA,IAAI,CAACQ,SAASS,EAAE,EAAE;YAChB,MAAMC,YAAY,MAAMV,SAASW,IAAI;YACrC,MAAM,IAAIC,MAAM,CAAC,yBAAyB,EAAEZ,SAASa,MAAM,CAAC,GAAG,EAAEH,WAAW;QAC9E;QAEA,MAAMI,OAAQ,MAAMd,SAASe,IAAI;QAEjC,IAAI,CAACD,KAAKE,SAAS,EAAE;YACnB,MAAM,IAAIJ,MAAM;QAClB;QAEA,MAAMK,cAAiC;YACrCC,UAAUJ,KAAKE,SAAS;YACxBG,cAAcL,KAAKM,aAAa,IAAI;QACtC;QAEA,IAAIN,KAAKO,mBAAmB,EAAE;YAC5BJ,YAAYK,QAAQ,GAAGR,KAAKO,mBAAmB;QACjD;QAEA,OAAOJ;IACT;AACF"}

package/dist/esm/dcr/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DCR (Dynamic Client Registration) Module
+ * Exports public API for DCR authentication
+ */
+export type { ClientCredentials, DcrRegistrationOptions } from '../auth/types.js';
+export type { DcrAuthenticatorOptions } from './dcr-authenticator.js';
+export { DcrAuthenticator } from './dcr-authenticator.js';
+export { DynamicClientRegistrar } from './dynamic-client-registrar.js';

package/dist/esm/dcr/index.js

@@ -0,0 +1,5 @@
+/**
+ * DCR (Dynamic Client Registration) Module
+ * Exports public API for DCR authentication
+ */ export { DcrAuthenticator } from './dcr-authenticator.js';
+export { DynamicClientRegistrar } from './dynamic-client-registrar.js';

package/dist/esm/dcr/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/dcr/index.ts"],"sourcesContent":["/**\n * DCR (Dynamic Client Registration) Module\n * Exports public API for DCR authentication\n */\n\nexport type { ClientCredentials, DcrRegistrationOptions } from '../auth/types.ts';\nexport type { DcrAuthenticatorOptions } from './dcr-authenticator.ts';\nexport { DcrAuthenticator } from './dcr-authenticator.ts';\nexport { DynamicClientRegistrar } from './dynamic-client-registrar.ts';\n"],"names":["DcrAuthenticator","DynamicClientRegistrar"],"mappings":"AAAA;;;CAGC,GAID,SAASA,gBAAgB,QAAQ,yBAAyB;AAC1D,SAASC,sBAAsB,QAAQ,gCAAgC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @mcp-z/client - MCP Client Library
+ */
+export type { McpServerEntry, StartConfig } from '../schemas/servers.d.js';
+export { probeAuthCapabilities } from './auth/capability-discovery.js';
+export type { AuthCapabilities, CallbackResult, OAuthCallbackListenerOptions, OAuthFlowOptions, TokenSet } from './auth/index.js';
+export { InteractiveOAuthFlow } from './auth/interactive-oauth-flow.js';
+export { OAuthCallbackListener } from './auth/oauth-callback-listener.js';
+export { decorateClient, type ManagedClient, type PromptArguments, type WrappedCallToolReturn, type WrappedGetPromptReturn, type WrappedReadResourceReturn } from './client-helpers.js';
+export { type ValidationResult, validateServers } from './config/validate-config.js';
+export type { JsonValue, PromptArgument, ToolArguments } from './connection/types.js';
+export { DcrAuthenticator } from './dcr/dcr-authenticator.js';
+export { DynamicClientRegistrar } from './dcr/dynamic-client-registrar.js';
+export type { ClientCredentials, DcrAuthenticatorOptions, DcrRegistrationOptions } from './dcr/index.js';
+export { type JsonValidator, type NativeCallToolResponse, type NativeGetPromptResponse, type NativeReadResourceResponse, PromptResponseError, PromptResponseWrapper, ResourceResponseError, ResourceResponseWrapper, ToolResponseError, ToolResponseWrapper, } from './response-wrappers.js';
+export type { CapabilityClient, CapabilityIndex, CapabilityType, IndexedCapability, IndexedPrompt, IndexedResource, IndexedTool, SearchField, SearchOptions, SearchResponse, SearchResult } from './search/index.js';
+export { buildCapabilityIndex, search, searchCapabilities } from './search/index.js';
+export { type CloseResult, type CreateServerRegistryOptions, createServerRegistry, type Dialect, type ServerRegistry, type ServersConfig } from './spawn/spawn-servers.js';
+export type { TransportType } from './types.js';
+export { getLogLevel, type Logger, type LogLevel, logger, setLogLevel } from './utils/logger.js';
+export { resolveArgsPaths, resolvePath } from './utils/path-utils.js';

package/dist/esm/index.js

@@ -0,0 +1,22 @@
+/**
+ * @mcp-z/client - MCP Client Library
+ */ // Config types (from schema)
+// Auth - OAuth utilities
+export { probeAuthCapabilities } from './auth/capability-discovery.js';
+export { InteractiveOAuthFlow } from './auth/interactive-oauth-flow.js';
+export { OAuthCallbackListener } from './auth/oauth-callback-listener.js';
+// Client helpers and lightweight overloads
+export { decorateClient } from './client-helpers.js';
+// Config - Configuration validation
+export { validateServers } from './config/validate-config.js';
+// DCR - Dynamic Client Registration utilities
+export { DcrAuthenticator } from './dcr/dcr-authenticator.js';
+export { DynamicClientRegistrar } from './dcr/dynamic-client-registrar.js';
+export { PromptResponseError, PromptResponseWrapper, ResourceResponseError, ResourceResponseWrapper, ToolResponseError, ToolResponseWrapper } from './response-wrappers.js';
+// Search - Capability discovery
+export { buildCapabilityIndex, search, searchCapabilities } from './search/index.js';
+// Spawn - Server registry (v3 API)
+export { createServerRegistry } from './spawn/spawn-servers.js';
+// Utils - Shared utilities
+export { getLogLevel, logger, setLogLevel } from './utils/logger.js';
+export { resolveArgsPaths, resolvePath } from './utils/path-utils.js';

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/index.ts"],"sourcesContent":["/**\n * @mcp-z/client - MCP Client Library\n */\n\n// Config types (from schema)\nexport type { McpServerEntry, StartConfig } from '../schemas/servers.d.ts';\n// Auth - OAuth utilities\nexport { probeAuthCapabilities } from './auth/capability-discovery.ts';\nexport type { AuthCapabilities, CallbackResult, OAuthCallbackListenerOptions, OAuthFlowOptions, TokenSet } from './auth/index.ts';\nexport { InteractiveOAuthFlow } from './auth/interactive-oauth-flow.ts';\nexport { OAuthCallbackListener } from './auth/oauth-callback-listener.ts';\n// Client helpers and lightweight overloads\nexport { decorateClient, type ManagedClient, type PromptArguments, type WrappedCallToolReturn, type WrappedGetPromptReturn, type WrappedReadResourceReturn } from './client-helpers.ts';\n// Config - Configuration validation\nexport { type ValidationResult, validateServers } from './config/validate-config.ts';\n// Connection - MCP client connection utilities (internal helpers exposed for advanced use)\nexport type { JsonValue, PromptArgument, ToolArguments } from './connection/types.ts';\n// DCR - Dynamic Client Registration utilities\nexport { DcrAuthenticator } from './dcr/dcr-authenticator.ts';\nexport { DynamicClientRegistrar } from './dcr/dynamic-client-registrar.ts';\nexport type { ClientCredentials, DcrAuthenticatorOptions, DcrRegistrationOptions } from './dcr/index.ts';\nexport {\n  type JsonValidator,\n  type NativeCallToolResponse,\n  type NativeGetPromptResponse,\n  type NativeReadResourceResponse,\n  PromptResponseError,\n  PromptResponseWrapper,\n  ResourceResponseError,\n  ResourceResponseWrapper,\n  ToolResponseError,\n  ToolResponseWrapper,\n} from './response-wrappers.ts';\nexport type { CapabilityClient, CapabilityIndex, CapabilityType, IndexedCapability, IndexedPrompt, IndexedResource, IndexedTool, SearchField, SearchOptions, SearchResponse, SearchResult } from './search/index.ts';\n// Search - Capability discovery\nexport { buildCapabilityIndex, search, searchCapabilities } from './search/index.ts';\n// Spawn - Server registry (v3 API)\nexport { type CloseResult, type CreateServerRegistryOptions, createServerRegistry, type Dialect, type ServerRegistry, type ServersConfig } from './spawn/spawn-servers.ts';\nexport type { TransportType } from './types.ts';\n// Utils - Shared utilities\nexport { getLogLevel, type Logger, type LogLevel, logger, setLogLevel } from './utils/logger.ts';\nexport { resolveArgsPaths, resolvePath } from './utils/path-utils.ts';\n"],"names":["probeAuthCapabilities","InteractiveOAuthFlow","OAuthCallbackListener","decorateClient","validateServers","DcrAuthenticator","DynamicClientRegistrar","PromptResponseError","PromptResponseWrapper","ResourceResponseError","ResourceResponseWrapper","ToolResponseError","ToolResponseWrapper","buildCapabilityIndex","search","searchCapabilities","createServerRegistry","getLogLevel","logger","setLogLevel","resolveArgsPaths","resolvePath"],"mappings":"AAAA;;CAEC,GAED,6BAA6B;AAE7B,yBAAyB;AACzB,SAASA,qBAAqB,QAAQ,iCAAiC;AAEvE,SAASC,oBAAoB,QAAQ,mCAAmC;AACxE,SAASC,qBAAqB,QAAQ,oCAAoC;AAC1E,2CAA2C;AAC3C,SAASC,cAAc,QAA2I,sBAAsB;AACxL,oCAAoC;AACpC,SAAgCC,eAAe,QAAQ,8BAA8B;AAGrF,8CAA8C;AAC9C,SAASC,gBAAgB,QAAQ,6BAA6B;AAC9D,SAASC,sBAAsB,QAAQ,oCAAoC;AAE3E,SAKEC,mBAAmB,EACnBC,qBAAqB,EACrBC,qBAAqB,EACrBC,uBAAuB,EACvBC,iBAAiB,EACjBC,mBAAmB,QACd,yBAAyB;AAEhC,gCAAgC;AAChC,SAASC,oBAAoB,EAAEC,MAAM,EAAEC,kBAAkB,QAAQ,oBAAoB;AACrF,mCAAmC;AACnC,SAA6DC,oBAAoB,QAA+D,2BAA2B;AAE3K,2BAA2B;AAC3B,SAASC,WAAW,EAA8BC,MAAM,EAAEC,WAAW,QAAQ,oBAAoB;AACjG,SAASC,gBAAgB,EAAEC,WAAW,QAAQ,wBAAwB"}

package/dist/esm/monkey-patches.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Monkey patches for MCP SDK bugs
+ *
+ * These patches fix bugs in dependencies that haven't been fixed upstream yet.
+ */
+export {};

package/dist/esm/monkey-patches.js

@@ -0,0 +1,32 @@
+/**
+ * Monkey patches for MCP SDK bugs
+ *
+ * These patches fix bugs in dependencies that haven't been fixed upstream yet.
+ */ import { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
+/**
+ * FIX: Protocol.close() doesn't clear pending timeouts
+ *
+ * BUG: The MCP SDK's Protocol.close() only closes the transport but does NOT
+ * clear pending timeouts from the internal _timeoutInfo Map. This causes Node.js
+ * to hang until timeouts fire (default 60 seconds).
+ *
+ * PATCH: Wrap Protocol.close() to clear all pending timeouts before closing.
+ *
+ * TO TEST IF STILL NEEDED:
+ * 1. Comment out this patch
+ * 2. Run: npm run test:unit
+ * 3. If tests hang ~60 seconds after completing, bug still exists
+ * 4. If tests exit promptly, SDK is fixed and this can be removed
+ *
+ * UPSTREAM: https://github.com/modelcontextprotocol/typescript-sdk/issues/XXX
+ */ const originalClose = Protocol.prototype.close;
+Protocol.prototype.close = async function() {
+    const self = this;
+    if (self._timeoutInfo) {
+        for (const [, info] of self._timeoutInfo){
+            clearTimeout(info.timeoutId);
+        }
+        self._timeoutInfo.clear();
+    }
+    return originalClose.call(this);
+};

package/dist/esm/monkey-patches.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/monkey-patches.ts"],"sourcesContent":["/**\n * Monkey patches for MCP SDK bugs\n *\n * These patches fix bugs in dependencies that haven't been fixed upstream yet.\n */\n\nimport { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';\n\n/**\n * FIX: Protocol.close() doesn't clear pending timeouts\n *\n * BUG: The MCP SDK's Protocol.close() only closes the transport but does NOT\n * clear pending timeouts from the internal _timeoutInfo Map. This causes Node.js\n * to hang until timeouts fire (default 60 seconds).\n *\n * PATCH: Wrap Protocol.close() to clear all pending timeouts before closing.\n *\n * TO TEST IF STILL NEEDED:\n * 1. Comment out this patch\n * 2. Run: npm run test:unit\n * 3. If tests hang ~60 seconds after completing, bug still exists\n * 4. If tests exit promptly, SDK is fixed and this can be removed\n *\n * UPSTREAM: https://github.com/modelcontextprotocol/typescript-sdk/issues/XXX\n */\nconst originalClose = Protocol.prototype.close;\nProtocol.prototype.close = async function () {\n  const self = this as unknown as { _timeoutInfo?: Map<unknown, { timeoutId: ReturnType<typeof setTimeout> }> };\n  if (self._timeoutInfo) {\n    for (const [, info] of self._timeoutInfo) {\n      clearTimeout(info.timeoutId);\n    }\n    self._timeoutInfo.clear();\n  }\n  return originalClose.call(this);\n};\n"],"names":["Protocol","originalClose","prototype","close","self","_timeoutInfo","info","clearTimeout","timeoutId","clear","call"],"mappings":"AAAA;;;;CAIC,GAED,SAASA,QAAQ,QAAQ,+CAA+C;AAExE;;;;;;;;;;;;;;;;CAgBC,GACD,MAAMC,gBAAgBD,SAASE,SAAS,CAACC,KAAK;AAC9CH,SAASE,SAAS,CAACC,KAAK,GAAG;IACzB,MAAMC,OAAO,IAAI;IACjB,IAAIA,KAAKC,YAAY,EAAE;QACrB,KAAK,MAAM,GAAGC,KAAK,IAAIF,KAAKC,YAAY,CAAE;YACxCE,aAAaD,KAAKE,SAAS;QAC7B;QACAJ,KAAKC,YAAY,CAACI,KAAK;IACzB;IACA,OAAOR,cAAcS,IAAI,CAAC,IAAI;AAChC"}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/dist/esm/response-wrappers.d.ts

@@ -0,0 +1,41 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+export type NativeCallToolResponse = Awaited<ReturnType<Client['callTool']>>;
+export type NativeGetPromptResponse = Awaited<ReturnType<Client['getPrompt']>>;
+export type NativeReadResourceResponse = Awaited<ReturnType<Client['readResource']>>;
+export type JsonValidator<T> = (value: unknown) => asserts value is T;
+export declare class ToolResponseError extends Error {
+    readonly response: NativeCallToolResponse;
+    constructor(message: string, response: NativeCallToolResponse);
+}
+export declare class ToolResponseWrapper {
+    private readonly payload;
+    constructor(payload: NativeCallToolResponse);
+    raw(): NativeCallToolResponse;
+    json<T = unknown>(validator?: JsonValidator<T>): T;
+    text(): string;
+    private resolveJsonPayload;
+    private throwIfError;
+}
+export declare class PromptResponseError extends Error {
+    readonly response: NativeGetPromptResponse;
+    constructor(message: string, response: NativeGetPromptResponse);
+}
+export declare class PromptResponseWrapper {
+    private readonly payload;
+    constructor(payload: NativeGetPromptResponse);
+    raw(): NativeGetPromptResponse;
+    text(): string;
+    json<T = unknown>(validator?: JsonValidator<T>): T;
+}
+export declare class ResourceResponseError extends Error {
+    readonly response: NativeReadResourceResponse;
+    constructor(message: string, response: NativeReadResourceResponse);
+}
+export declare class ResourceResponseWrapper {
+    private readonly payload;
+    constructor(payload: NativeReadResourceResponse);
+    raw(): NativeReadResourceResponse;
+    text(): string;
+    json<T = unknown>(validator?: JsonValidator<T>): T;
+    private firstEntry;
+}