@mcp-z/client 1.0.0

package/dist/esm/auth/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared types for OAuth and DCR authentication
+ */ /**
+ * OAuth callback result from authorization server
+ */ /**
+ * Options for OAuth authorization flow
+ */ export { };

package/dist/esm/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/auth/types.ts"],"sourcesContent":["/**\n * Shared types for OAuth and DCR authentication\n */\n\n/**\n * OAuth callback result from authorization server\n */\nexport interface CallbackResult {\n  /** Authorization code from OAuth server */\n  code: string;\n  /** State parameter for CSRF protection */\n  state?: string;\n}\n\n/**\n * PKCE (Proof Key for Code Exchange) parameters (RFC 7636)\n * Used to secure OAuth 2.0 authorization code flow for public clients\n */\nexport interface PkceParams {\n  /** Code verifier - cryptographically random string (43-128 characters) */\n  codeVerifier: string;\n  /** Code challenge - derived from code verifier using challenge method */\n  codeChallenge: string;\n  /** Code challenge method - S256 (SHA-256) or plain */\n  codeChallengeMethod: 'S256' | 'plain';\n}\n\n/**\n * OAuth token set with access and refresh tokens\n */\nexport interface TokenSet {\n  /** Access token for API requests */\n  accessToken: string;\n  /** Refresh token for obtaining new access tokens */\n  refreshToken: string;\n  /** Timestamp when access token expires (milliseconds since epoch) */\n  expiresAt: number;\n  /** Scopes granted for this token set */\n  scopes?: string[];\n  /** Client ID used for DCR registration (stored for future use) */\n  clientId?: string;\n  /** Client secret used for DCR registration (stored for future use) */\n  clientSecret?: string;\n}\n\n/**\n * OAuth 2.0 Protected Resource Metadata (RFC 9728)\n * Response from .well-known/oauth-protected-resource endpoint\n */\nexport interface ProtectedResourceMetadata {\n  /** The protected resource identifier */\n  resource: string;\n  /** List of authorization server URLs that can issue tokens for this resource */\n  authorization_servers: string[];\n  /** Optional list of scopes supported by this resource */\n  scopes_supported?: string[];\n  /** Optional list of bearer token methods supported (header, query, body) */\n  bearer_methods_supported?: string[];\n}\n\n/**\n * OAuth 2.0 Authorization Server Metadata (RFC 8414)\n * Response from .well-known/oauth-authorization-server endpoint\n */\nexport interface AuthorizationServerMetadata {\n  /** The authorization server's issuer identifier */\n  issuer?: string;\n  /** URL of the authorization endpoint */\n  authorization_endpoint?: string;\n  /** URL of the token endpoint */\n  token_endpoint?: string;\n  /** URL of the client registration endpoint (DCR - RFC 7591) */\n  registration_endpoint?: string;\n  /** URL of the token introspection endpoint */\n  introspection_endpoint?: string;\n  /** List of OAuth scopes supported by the authorization server */\n  scopes_supported?: string[];\n  /** Response types supported (code, token, etc.) */\n  response_types_supported?: string[];\n  /** Grant types supported (authorization_code, refresh_token, etc.) */\n  grant_types_supported?: string[];\n  /** Token endpoint authentication methods supported */\n  token_endpoint_auth_methods_supported?: string[];\n}\n\n/**\n * OAuth server capabilities discovered from .well-known endpoint\n */\nexport interface AuthCapabilities {\n  /** Whether the server supports Dynamic Client Registration (RFC 7591) */\n  supportsDcr: boolean;\n  /** DCR client registration endpoint */\n  registrationEndpoint?: string;\n  /** OAuth authorization endpoint */\n  authorizationEndpoint?: string;\n  /** OAuth token endpoint */\n  tokenEndpoint?: string;\n  /** Token introspection endpoint */\n  introspectionEndpoint?: string;\n  /** Supported OAuth scopes */\n  scopes?: string[];\n}\n\n/**\n * Client credentials from DCR registration\n */\nexport interface ClientCredentials {\n  /** OAuth client ID */\n  clientId: string;\n  /** OAuth client secret */\n  clientSecret: string;\n  /** Timestamp when client was registered */\n  issuedAt?: number;\n}\n\n/**\n * Options for DCR client registration\n */\nexport interface DcrRegistrationOptions {\n  /** Client name to register */\n  clientName?: string;\n  /** Redirect URI for OAuth callback */\n  redirectUri?: string;\n}\n\n/**\n * Options for OAuth authorization flow\n */\nexport interface OAuthFlowOptions {\n  /** Port for OAuth callback listener (required - use get-port to find available port) */\n  port: number;\n  /** Redirect URI for OAuth callback (optional - will be built from port if not provided) */\n  redirectUri?: string;\n  /** OAuth scopes to request */\n  scopes?: string[];\n  /** Resource parameter (RFC 8707) - target resource server identifier */\n  resource?: string;\n  /** Enable PKCE (RFC 7636) - recommended for all clients, required for public clients */\n  pkce?: boolean;\n  /** Headless mode (don't open browser) */\n  headless?: boolean;\n  /** Timeout for callback (milliseconds) */\n  timeout?: number;\n  /** Optional logger for debug output (defaults to singleton logger) */\n  logger?: import('../utils/logger.ts').Logger;\n}\n"],"names":[],"mappings":"AAAA;;CAEC,GAED;;CAEC,GAuHD;;CAEC,GACD,WAiBC"}

package/dist/esm/client-helpers.d.ts

@@ -0,0 +1,55 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { ToolArguments } from './connection/types.js';
+import { PromptResponseWrapper, ResourceResponseWrapper, ToolResponseWrapper } from './response-wrappers.js';
+export type PromptArguments = Record<string, string>;
+type NativeCallToolParams = Parameters<Client['callTool']>;
+type NativeCallToolReturn = ReturnType<Client['callTool']>;
+/**
+ * Fetch-style wrapper returned by `ManagedClient.callTool()`.
+ * @public
+ */
+export type WrappedCallToolReturn = Promise<ToolResponseWrapper>;
+type NativeGetPromptParams = Parameters<Client['getPrompt']>;
+type NativeGetPromptReturn = ReturnType<Client['getPrompt']>;
+/**
+ * Fetch-style wrapper returned by `ManagedClient.getPrompt()`.
+ * @public
+ */
+export type WrappedGetPromptReturn = Promise<PromptResponseWrapper>;
+type NativeReadResourceParams = Parameters<Client['readResource']>;
+type NativeReadResourceReturn = ReturnType<Client['readResource']>;
+/**
+ * Fetch-style wrapper returned by `ManagedClient.readResource()`.
+ * @public
+ */
+export type WrappedReadResourceReturn = Promise<ResourceResponseWrapper>;
+/**
+ * Client returned by registry.connect() with convenience overloads for
+ * calling tools, reading resources, and getting prompts using simple arguments.
+ */
+export type ManagedClient = Omit<Client, 'callTool' | 'getPrompt' | 'readResource'> & {
+    /** Name of the server this client is connected to. */
+    readonly serverName: string;
+    /** Underlying MCP SDK client for advanced scenarios. */
+    readonly nativeClient: Client;
+    callTool(toolName: string, args?: ToolArguments, requestOptions?: RequestOptions): WrappedCallToolReturn;
+    callTool(invocation: NativeCallToolParams[0], sessionId?: NativeCallToolParams[1], requestOptions?: NativeCallToolParams[2]): WrappedCallToolReturn;
+    callToolRaw(toolName: string, args?: ToolArguments, requestOptions?: RequestOptions): NativeCallToolReturn;
+    callToolRaw(invocation: NativeCallToolParams[0], sessionId?: NativeCallToolParams[1], requestOptions?: NativeCallToolParams[2]): NativeCallToolReturn;
+    getPrompt(name: string, args?: PromptArguments, requestOptions?: NativeGetPromptParams[1]): WrappedGetPromptReturn;
+    getPrompt(invocation: NativeGetPromptParams[0], requestOptions?: NativeGetPromptParams[1]): WrappedGetPromptReturn;
+    getPromptRaw(name: string, args?: PromptArguments, requestOptions?: NativeGetPromptParams[1]): NativeGetPromptReturn;
+    getPromptRaw(invocation: NativeGetPromptParams[0], requestOptions?: NativeGetPromptParams[1]): NativeGetPromptReturn;
+    readResource(uri: string, requestOptions?: NativeReadResourceParams[1]): WrappedReadResourceReturn;
+    readResource(request: NativeReadResourceParams[0], requestOptions?: NativeReadResourceParams[1]): WrappedReadResourceReturn;
+    readResourceRaw(uri: string, requestOptions?: NativeReadResourceParams[1]): NativeReadResourceReturn;
+    readResourceRaw(request: NativeReadResourceParams[0], requestOptions?: NativeReadResourceParams[1]): NativeReadResourceReturn;
+};
+/**
+ * Enhance an MCP SDK client with convenience overloads.
+ */
+export declare function decorateClient(client: Client, metadata: {
+    serverName: string;
+}): ManagedClient;
+export {};

package/dist/esm/client-helpers.js

@@ -0,0 +1,81 @@
+import { PromptResponseWrapper, ResourceResponseWrapper, ToolResponseWrapper } from './response-wrappers.js';
+/**
+ * Enhance an MCP SDK client with convenience overloads.
+ */ export function decorateClient(client, metadata) {
+    const enhanced = client;
+    Object.defineProperty(enhanced, 'serverName', {
+        value: metadata.serverName,
+        enumerable: true,
+        configurable: false,
+        writable: false
+    });
+    Object.defineProperty(enhanced, 'nativeClient', {
+        value: client,
+        enumerable: false,
+        configurable: false,
+        writable: false
+    });
+    const nativeCallTool = client.callTool.bind(client);
+    const wrapCallTool = (promise)=>promise.then((payload)=>new ToolResponseWrapper(payload));
+    enhanced.callTool = (nameOrInvocation, argsOrSession, requestOptions)=>{
+        if (typeof nameOrInvocation === 'string') {
+            return wrapCallTool(nativeCallTool({
+                name: nameOrInvocation,
+                arguments: argsOrSession !== null && argsOrSession !== void 0 ? argsOrSession : {}
+            }, undefined, requestOptions));
+        }
+        return wrapCallTool(nativeCallTool(nameOrInvocation, argsOrSession, requestOptions));
+    };
+    enhanced.callToolRaw = (nameOrInvocation, argsOrSession, requestOptions)=>{
+        if (typeof nameOrInvocation === 'string') {
+            return nativeCallTool({
+                name: nameOrInvocation,
+                arguments: argsOrSession !== null && argsOrSession !== void 0 ? argsOrSession : {}
+            }, undefined, requestOptions);
+        }
+        return nativeCallTool(nameOrInvocation, argsOrSession, requestOptions);
+    };
+    const nativeGetPrompt = client.getPrompt.bind(client);
+    const wrapPrompt = (promise)=>promise.then((payload)=>new PromptResponseWrapper(payload));
+    enhanced.getPrompt = (nameOrParams, argsOrOptions, requestOptions)=>{
+        if (typeof nameOrParams === 'string') {
+            return wrapPrompt(nativeGetPrompt({
+                name: nameOrParams,
+                ...argsOrOptions ? {
+                    arguments: argsOrOptions
+                } : {}
+            }, requestOptions));
+        }
+        return wrapPrompt(nativeGetPrompt(nameOrParams, argsOrOptions));
+    };
+    enhanced.getPromptRaw = (nameOrParams, argsOrOptions, requestOptions)=>{
+        if (typeof nameOrParams === 'string') {
+            return nativeGetPrompt({
+                name: nameOrParams,
+                ...argsOrOptions ? {
+                    arguments: argsOrOptions
+                } : {}
+            }, requestOptions);
+        }
+        return nativeGetPrompt(nameOrParams, argsOrOptions);
+    };
+    const nativeReadResource = client.readResource.bind(client);
+    const wrapResource = (promise)=>promise.then((payload)=>new ResourceResponseWrapper(payload));
+    enhanced.readResource = (uriOrRequest, requestOptions)=>{
+        if (typeof uriOrRequest === 'string') {
+            return wrapResource(nativeReadResource({
+                uri: uriOrRequest
+            }, requestOptions));
+        }
+        return wrapResource(nativeReadResource(uriOrRequest, requestOptions));
+    };
+    enhanced.readResourceRaw = (uriOrRequest, requestOptions)=>{
+        if (typeof uriOrRequest === 'string') {
+            return nativeReadResource({
+                uri: uriOrRequest
+            }, requestOptions);
+        }
+        return nativeReadResource(uriOrRequest, requestOptions);
+    };
+    return enhanced;
+}

package/dist/esm/client-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/client-helpers.ts"],"sourcesContent":["import type { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';\nimport type { ToolArguments } from './connection/types.ts';\nimport { type NativeCallToolResponse, type NativeGetPromptResponse, type NativeReadResourceResponse, PromptResponseWrapper, ResourceResponseWrapper, ToolResponseWrapper } from './response-wrappers.ts';\n\nexport type PromptArguments = Record<string, string>;\n\ntype NativeCallToolParams = Parameters<Client['callTool']>;\ntype NativeCallToolReturn = ReturnType<Client['callTool']>;\n/**\n * Fetch-style wrapper returned by `ManagedClient.callTool()`.\n * @public\n */\nexport type WrappedCallToolReturn = Promise<ToolResponseWrapper>;\n\ntype NativeGetPromptParams = Parameters<Client['getPrompt']>;\ntype NativeGetPromptReturn = ReturnType<Client['getPrompt']>;\n/**\n * Fetch-style wrapper returned by `ManagedClient.getPrompt()`.\n * @public\n */\nexport type WrappedGetPromptReturn = Promise<PromptResponseWrapper>;\n\ntype NativeReadResourceParams = Parameters<Client['readResource']>;\ntype NativeReadResourceReturn = ReturnType<Client['readResource']>;\n/**\n * Fetch-style wrapper returned by `ManagedClient.readResource()`.\n * @public\n */\nexport type WrappedReadResourceReturn = Promise<ResourceResponseWrapper>;\n\n/**\n * Client returned by registry.connect() with convenience overloads for\n * calling tools, reading resources, and getting prompts using simple arguments.\n */\nexport type ManagedClient = Omit<Client, 'callTool' | 'getPrompt' | 'readResource'> & {\n  /** Name of the server this client is connected to. */\n  readonly serverName: string;\n  /** Underlying MCP SDK client for advanced scenarios. */\n  readonly nativeClient: Client;\n\n  callTool(toolName: string, args?: ToolArguments, requestOptions?: RequestOptions): WrappedCallToolReturn;\n  callTool(invocation: NativeCallToolParams[0], sessionId?: NativeCallToolParams[1], requestOptions?: NativeCallToolParams[2]): WrappedCallToolReturn;\n  callToolRaw(toolName: string, args?: ToolArguments, requestOptions?: RequestOptions): NativeCallToolReturn;\n  callToolRaw(invocation: NativeCallToolParams[0], sessionId?: NativeCallToolParams[1], requestOptions?: NativeCallToolParams[2]): NativeCallToolReturn;\n\n  getPrompt(name: string, args?: PromptArguments, requestOptions?: NativeGetPromptParams[1]): WrappedGetPromptReturn;\n  getPrompt(invocation: NativeGetPromptParams[0], requestOptions?: NativeGetPromptParams[1]): WrappedGetPromptReturn;\n  getPromptRaw(name: string, args?: PromptArguments, requestOptions?: NativeGetPromptParams[1]): NativeGetPromptReturn;\n  getPromptRaw(invocation: NativeGetPromptParams[0], requestOptions?: NativeGetPromptParams[1]): NativeGetPromptReturn;\n\n  readResource(uri: string, requestOptions?: NativeReadResourceParams[1]): WrappedReadResourceReturn;\n  readResource(request: NativeReadResourceParams[0], requestOptions?: NativeReadResourceParams[1]): WrappedReadResourceReturn;\n  readResourceRaw(uri: string, requestOptions?: NativeReadResourceParams[1]): NativeReadResourceReturn;\n  readResourceRaw(request: NativeReadResourceParams[0], requestOptions?: NativeReadResourceParams[1]): NativeReadResourceReturn;\n};\n\n/**\n * Enhance an MCP SDK client with convenience overloads.\n */\nexport function decorateClient(client: Client, metadata: { serverName: string }): ManagedClient {\n  const enhanced = client as unknown as ManagedClient;\n\n  Object.defineProperty(enhanced, 'serverName', {\n    value: metadata.serverName,\n    enumerable: true,\n    configurable: false,\n    writable: false,\n  });\n  Object.defineProperty(enhanced, 'nativeClient', {\n    value: client,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  });\n\n  const nativeCallTool = client.callTool.bind(client);\n  const wrapCallTool = (promise: NativeCallToolReturn): WrappedCallToolReturn => promise.then((payload) => new ToolResponseWrapper(payload as NativeCallToolResponse));\n\n  enhanced.callTool = ((nameOrInvocation: string | NativeCallToolParams[0], argsOrSession?: ToolArguments | NativeCallToolParams[1], requestOptions?: NativeCallToolParams[2]) => {\n    if (typeof nameOrInvocation === 'string') {\n      return wrapCallTool(nativeCallTool({ name: nameOrInvocation, arguments: (argsOrSession as ToolArguments) ?? {} }, undefined, requestOptions));\n    }\n    return wrapCallTool(nativeCallTool(nameOrInvocation, argsOrSession as NativeCallToolParams[1], requestOptions));\n  }) as ManagedClient['callTool'];\n\n  enhanced.callToolRaw = ((nameOrInvocation: string | NativeCallToolParams[0], argsOrSession?: ToolArguments | NativeCallToolParams[1], requestOptions?: NativeCallToolParams[2]) => {\n    if (typeof nameOrInvocation === 'string') {\n      return nativeCallTool({ name: nameOrInvocation, arguments: (argsOrSession as ToolArguments) ?? {} }, undefined, requestOptions);\n    }\n    return nativeCallTool(nameOrInvocation, argsOrSession as NativeCallToolParams[1], requestOptions);\n  }) as ManagedClient['callToolRaw'];\n\n  const nativeGetPrompt = client.getPrompt.bind(client);\n  const wrapPrompt = (promise: NativeGetPromptReturn): WrappedGetPromptReturn => promise.then((payload) => new PromptResponseWrapper(payload as NativeGetPromptResponse));\n\n  enhanced.getPrompt = ((nameOrParams: string | NativeGetPromptParams[0], argsOrOptions?: PromptArguments | NativeGetPromptParams[1], requestOptions?: NativeGetPromptParams[1]) => {\n    if (typeof nameOrParams === 'string') {\n      return wrapPrompt(nativeGetPrompt({ name: nameOrParams, ...(argsOrOptions ? { arguments: argsOrOptions as PromptArguments } : {}) }, requestOptions));\n    }\n    return wrapPrompt(nativeGetPrompt(nameOrParams, argsOrOptions as NativeGetPromptParams[1]));\n  }) as ManagedClient['getPrompt'];\n\n  enhanced.getPromptRaw = ((nameOrParams: string | NativeGetPromptParams[0], argsOrOptions?: PromptArguments | NativeGetPromptParams[1], requestOptions?: NativeGetPromptParams[1]) => {\n    if (typeof nameOrParams === 'string') {\n      return nativeGetPrompt({ name: nameOrParams, ...(argsOrOptions ? { arguments: argsOrOptions as PromptArguments } : {}) }, requestOptions);\n    }\n    return nativeGetPrompt(nameOrParams, argsOrOptions as NativeGetPromptParams[1]);\n  }) as ManagedClient['getPromptRaw'];\n\n  const nativeReadResource = client.readResource.bind(client);\n  const wrapResource = (promise: NativeReadResourceReturn): WrappedReadResourceReturn => promise.then((payload) => new ResourceResponseWrapper(payload as NativeReadResourceResponse));\n\n  enhanced.readResource = ((uriOrRequest: string | NativeReadResourceParams[0], requestOptions?: NativeReadResourceParams[1]) => {\n    if (typeof uriOrRequest === 'string') {\n      return wrapResource(nativeReadResource({ uri: uriOrRequest }, requestOptions));\n    }\n    return wrapResource(nativeReadResource(uriOrRequest, requestOptions));\n  }) as ManagedClient['readResource'];\n\n  enhanced.readResourceRaw = ((uriOrRequest: string | NativeReadResourceParams[0], requestOptions?: NativeReadResourceParams[1]) => {\n    if (typeof uriOrRequest === 'string') {\n      return nativeReadResource({ uri: uriOrRequest }, requestOptions);\n    }\n    return nativeReadResource(uriOrRequest, requestOptions);\n  }) as ManagedClient['readResourceRaw'];\n\n  return enhanced;\n}\n"],"names":["PromptResponseWrapper","ResourceResponseWrapper","ToolResponseWrapper","decorateClient","client","metadata","enhanced","Object","defineProperty","value","serverName","enumerable","configurable","writable","nativeCallTool","callTool","bind","wrapCallTool","promise","then","payload","nameOrInvocation","argsOrSession","requestOptions","name","arguments","undefined","callToolRaw","nativeGetPrompt","getPrompt","wrapPrompt","nameOrParams","argsOrOptions","getPromptRaw","nativeReadResource","readResource","wrapResource","uriOrRequest","uri","readResourceRaw"],"mappings":"AAGA,SAAqGA,qBAAqB,EAAEC,uBAAuB,EAAEC,mBAAmB,QAAQ,yBAAyB;AAsDzM;;CAEC,GACD,OAAO,SAASC,eAAeC,MAAc,EAAEC,QAAgC;IAC7E,MAAMC,WAAWF;IAEjBG,OAAOC,cAAc,CAACF,UAAU,cAAc;QAC5CG,OAAOJ,SAASK,UAAU;QAC1BC,YAAY;QACZC,cAAc;QACdC,UAAU;IACZ;IACAN,OAAOC,cAAc,CAACF,UAAU,gBAAgB;QAC9CG,OAAOL;QACPO,YAAY;QACZC,cAAc;QACdC,UAAU;IACZ;IAEA,MAAMC,iBAAiBV,OAAOW,QAAQ,CAACC,IAAI,CAACZ;IAC5C,MAAMa,eAAe,CAACC,UAAyDA,QAAQC,IAAI,CAAC,CAACC,UAAY,IAAIlB,oBAAoBkB;IAEjId,SAASS,QAAQ,GAAI,CAACM,kBAAoDC,eAAyDC;QACjI,IAAI,OAAOF,qBAAqB,UAAU;YACxC,OAAOJ,aAAaH,eAAe;gBAAEU,MAAMH;gBAAkBI,SAAS,EAAGH,0BAAAA,2BAAAA,gBAAmC,CAAC;YAAE,GAAGI,WAAWH;QAC/H;QACA,OAAON,aAAaH,eAAeO,kBAAkBC,eAA0CC;IACjG;IAEAjB,SAASqB,WAAW,GAAI,CAACN,kBAAoDC,eAAyDC;QACpI,IAAI,OAAOF,qBAAqB,UAAU;YACxC,OAAOP,eAAe;gBAAEU,MAAMH;gBAAkBI,SAAS,EAAGH,0BAAAA,2BAAAA,gBAAmC,CAAC;YAAE,GAAGI,WAAWH;QAClH;QACA,OAAOT,eAAeO,kBAAkBC,eAA0CC;IACpF;IAEA,MAAMK,kBAAkBxB,OAAOyB,SAAS,CAACb,IAAI,CAACZ;IAC9C,MAAM0B,aAAa,CAACZ,UAA2DA,QAAQC,IAAI,CAAC,CAACC,UAAY,IAAIpB,sBAAsBoB;IAEnId,SAASuB,SAAS,GAAI,CAACE,cAAiDC,eAA4DT;QAClI,IAAI,OAAOQ,iBAAiB,UAAU;YACpC,OAAOD,WAAWF,gBAAgB;gBAAEJ,MAAMO;gBAAc,GAAIC,gBAAgB;oBAAEP,WAAWO;gBAAiC,IAAI,CAAC,CAAC;YAAE,GAAGT;QACvI;QACA,OAAOO,WAAWF,gBAAgBG,cAAcC;IAClD;IAEA1B,SAAS2B,YAAY,GAAI,CAACF,cAAiDC,eAA4DT;QACrI,IAAI,OAAOQ,iBAAiB,UAAU;YACpC,OAAOH,gBAAgB;gBAAEJ,MAAMO;gBAAc,GAAIC,gBAAgB;oBAAEP,WAAWO;gBAAiC,IAAI,CAAC,CAAC;YAAE,GAAGT;QAC5H;QACA,OAAOK,gBAAgBG,cAAcC;IACvC;IAEA,MAAME,qBAAqB9B,OAAO+B,YAAY,CAACnB,IAAI,CAACZ;IACpD,MAAMgC,eAAe,CAAClB,UAAiEA,QAAQC,IAAI,CAAC,CAACC,UAAY,IAAInB,wBAAwBmB;IAE7Id,SAAS6B,YAAY,GAAI,CAACE,cAAoDd;QAC5E,IAAI,OAAOc,iBAAiB,UAAU;YACpC,OAAOD,aAAaF,mBAAmB;gBAAEI,KAAKD;YAAa,GAAGd;QAChE;QACA,OAAOa,aAAaF,mBAAmBG,cAAcd;IACvD;IAEAjB,SAASiC,eAAe,GAAI,CAACF,cAAoDd;QAC/E,IAAI,OAAOc,iBAAiB,UAAU;YACpC,OAAOH,mBAAmB;gBAAEI,KAAKD;YAAa,GAAGd;QACnD;QACA,OAAOW,mBAAmBG,cAAcd;IAC1C;IAEA,OAAOjB;AACT"}

package/dist/esm/config/server-loader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Load server definitions from .mcp.json (data-driven)
+ */
+export interface McpServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface MCPConfiguration {
+    mcpServers: Record<string, McpServerConfig>;
+}
+/**
+ * Load available servers from resources/.mcp.json
+ */
+export declare function loadAvailableServers(): MCPConfiguration;
+/**
+ * Get list of all available server names
+ */
+export declare function getAllServerNames(): string[];
+/**
+ * Parse comma-separated server list or "all"
+ */
+export declare function parseServerList(input: string): string[];
+/**
+ * Get server configuration by name
+ */
+export declare function getServerConfig(serverName: string): McpServerConfig;

package/dist/esm/config/server-loader.js

@@ -0,0 +1,49 @@
+/**
+ * Load server definitions from .mcp.json (data-driven)
+ */ import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+// Get package root: dist/esm/lib -> ../../../ or dist/cjs/lib -> ../../../
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '../../..');
+/**
+ * Load available servers from resources/.mcp.json
+ */ export function loadAvailableServers() {
+    const configPath = path.join(packageRoot, 'resources/.mcp.json');
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`Server configuration not found: ${configPath}`);
+    }
+    const content = fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(content);
+}
+/**
+ * Get list of all available server names
+ */ export function getAllServerNames() {
+    const config = loadAvailableServers();
+    return Object.keys(config.mcpServers);
+}
+/**
+ * Parse comma-separated server list or "all"
+ */ export function parseServerList(input) {
+    const allServers = getAllServerNames();
+    if (input === 'all') {
+        return allServers;
+    }
+    const requested = input.split(',').map((s)=>s.trim());
+    const invalid = requested.filter((s)=>!allServers.includes(s));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid server names: ${invalid.join(', ')}.\nAvailable: ${allServers.join(', ')}`);
+    }
+    return requested;
+}
+/**
+ * Get server configuration by name
+ */ export function getServerConfig(serverName) {
+    const config = loadAvailableServers();
+    const serverConfig = config.mcpServers[serverName];
+    if (!serverConfig) {
+        throw new Error(`Unknown server: ${serverName}.\nAvailable: ${getAllServerNames().join(', ')}`);
+    }
+    return serverConfig;
+}

package/dist/esm/config/server-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/config/server-loader.ts"],"sourcesContent":["/**\n * Load server definitions from .mcp.json (data-driven)\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { fileURLToPath } from 'url';\n\n// Get package root: dist/esm/lib -> ../../../ or dist/cjs/lib -> ../../../\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\nconst packageRoot = path.resolve(__dirname, '../../..');\n\nexport interface McpServerConfig {\n  command: string;\n  args: string[];\n  env?: Record<string, string>;\n}\n\nexport interface MCPConfiguration {\n  mcpServers: Record<string, McpServerConfig>;\n}\n\n/**\n * Load available servers from resources/.mcp.json\n */\nexport function loadAvailableServers(): MCPConfiguration {\n  const configPath = path.join(packageRoot, 'resources/.mcp.json');\n\n  if (!fs.existsSync(configPath)) {\n    throw new Error(`Server configuration not found: ${configPath}`);\n  }\n\n  const content = fs.readFileSync(configPath, 'utf-8');\n  return JSON.parse(content) as MCPConfiguration;\n}\n\n/**\n * Get list of all available server names\n */\nexport function getAllServerNames(): string[] {\n  const config = loadAvailableServers();\n  return Object.keys(config.mcpServers);\n}\n\n/**\n * Parse comma-separated server list or \"all\"\n */\nexport function parseServerList(input: string): string[] {\n  const allServers = getAllServerNames();\n\n  if (input === 'all') {\n    return allServers;\n  }\n\n  const requested = input.split(',').map((s) => s.trim());\n  const invalid = requested.filter((s) => !allServers.includes(s));\n\n  if (invalid.length > 0) {\n    throw new Error(`Invalid server names: ${invalid.join(', ')}.\\nAvailable: ${allServers.join(', ')}`);\n  }\n\n  return requested;\n}\n\n/**\n * Get server configuration by name\n */\nexport function getServerConfig(serverName: string): McpServerConfig {\n  const config = loadAvailableServers();\n  const serverConfig = config.mcpServers[serverName];\n\n  if (!serverConfig) {\n    throw new Error(`Unknown server: ${serverName}.\\nAvailable: ${getAllServerNames().join(', ')}`);\n  }\n\n  return serverConfig;\n}\n"],"names":["fs","path","fileURLToPath","__filename","url","__dirname","dirname","packageRoot","resolve","loadAvailableServers","configPath","join","existsSync","Error","content","readFileSync","JSON","parse","getAllServerNames","config","Object","keys","mcpServers","parseServerList","input","allServers","requested","split","map","s","trim","invalid","filter","includes","length","getServerConfig","serverName","serverConfig"],"mappings":"AAAA;;CAEC,GAED,YAAYA,QAAQ,KAAK;AACzB,YAAYC,UAAU,OAAO;AAC7B,SAASC,aAAa,QAAQ,MAAM;AAEpC,2EAA2E;AAC3E,MAAMC,aAAaD,cAAc,YAAYE,GAAG;AAChD,MAAMC,YAAYJ,KAAKK,OAAO,CAACH;AAC/B,MAAMI,cAAcN,KAAKO,OAAO,CAACH,WAAW;AAY5C;;CAEC,GACD,OAAO,SAASI;IACd,MAAMC,aAAaT,KAAKU,IAAI,CAACJ,aAAa;IAE1C,IAAI,CAACP,GAAGY,UAAU,CAACF,aAAa;QAC9B,MAAM,IAAIG,MAAM,CAAC,gCAAgC,EAAEH,YAAY;IACjE;IAEA,MAAMI,UAAUd,GAAGe,YAAY,CAACL,YAAY;IAC5C,OAAOM,KAAKC,KAAK,CAACH;AACpB;AAEA;;CAEC,GACD,OAAO,SAASI;IACd,MAAMC,SAASV;IACf,OAAOW,OAAOC,IAAI,CAACF,OAAOG,UAAU;AACtC;AAEA;;CAEC,GACD,OAAO,SAASC,gBAAgBC,KAAa;IAC3C,MAAMC,aAAaP;IAEnB,IAAIM,UAAU,OAAO;QACnB,OAAOC;IACT;IAEA,MAAMC,YAAYF,MAAMG,KAAK,CAAC,KAAKC,GAAG,CAAC,CAACC,IAAMA,EAAEC,IAAI;IACpD,MAAMC,UAAUL,UAAUM,MAAM,CAAC,CAACH,IAAM,CAACJ,WAAWQ,QAAQ,CAACJ;IAE7D,IAAIE,QAAQG,MAAM,GAAG,GAAG;QACtB,MAAM,IAAIrB,MAAM,CAAC,sBAAsB,EAAEkB,QAAQpB,IAAI,CAAC,MAAM,cAAc,EAAEc,WAAWd,IAAI,CAAC,OAAO;IACrG;IAEA,OAAOe;AACT;AAEA;;CAEC,GACD,OAAO,SAASS,gBAAgBC,UAAkB;IAChD,MAAMjB,SAASV;IACf,MAAM4B,eAAelB,OAAOG,UAAU,CAACc,WAAW;IAElD,IAAI,CAACC,cAAc;QACjB,MAAM,IAAIxB,MAAM,CAAC,gBAAgB,EAAEuB,WAAW,cAAc,EAAElB,oBAAoBP,IAAI,CAAC,OAAO;IAChG;IAEA,OAAO0B;AACT"}

package/dist/esm/config/validate-config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validation result for servers configuration
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+    warnings?: string[];
+}
+/**
+ * Validate servers configuration against JSON Schema
+ *
+ * @param servers - Servers configuration object to validate (map of server names to configs)
+ * @returns ValidationResult with valid flag, errors, and warnings
+ */
+export declare function validateServers(servers: unknown): ValidationResult;

package/dist/esm/config/validate-config.js

@@ -0,0 +1,76 @@
+import { Ajv } from 'ajv';
+import * as fs from 'fs';
+import { createRequire } from 'module';
+import moduleRoot from 'module-root-sync';
+import * as path from 'path';
+// Import ajv-formats (CommonJS module - use createRequire for ESM compatibility)
+const require = createRequire(import.meta.url);
+const addFormats = require('ajv-formats');
+const packageRoot = moduleRoot(import.meta.filename);
+// Module-level cache for schema and validator
+let schemaCache = null;
+let validatorCache = null;
+/**
+ * Get servers schema (loads once from bundled file, then caches)
+ */ function getSchema() {
+    if (schemaCache) {
+        return schemaCache;
+    }
+    const schemaPath = path.join(packageRoot, 'schemas/servers.schema.json');
+    if (!fs.existsSync(schemaPath)) {
+        throw new Error(`Servers schema not found at: ${schemaPath}`);
+    }
+    schemaCache = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+    return schemaCache;
+}
+/**
+ * Get compiled AJV validator (creates once, then caches)
+ */ function getValidator() {
+    if (validatorCache) {
+        return validatorCache;
+    }
+    const schema = getSchema();
+    const ajv = new Ajv({
+        allErrors: true,
+        verbose: true,
+        strictSchema: false
+    });
+    // Add format validators (uri, email, etc.)
+    addFormats(ajv);
+    validatorCache = ajv.compile(schema);
+    return validatorCache;
+}
+/**
+ * Validate servers configuration against JSON Schema
+ *
+ * @param servers - Servers configuration object to validate (map of server names to configs)
+ * @returns ValidationResult with valid flag, errors, and warnings
+ */ export function validateServers(servers) {
+    try {
+        const validate = getValidator();
+        const valid = validate(servers);
+        if (!valid) {
+            var _validate_errors;
+            const errors = ((_validate_errors = validate.errors) === null || _validate_errors === void 0 ? void 0 : _validate_errors.map((e)=>{
+                const path = e.instancePath || '(root)';
+                return `${path}: ${e.message}`;
+            })) || [];
+            return {
+                valid: false,
+                errors
+            };
+        }
+        const warnings = [];
+        return {
+            valid: true,
+            warnings
+        };
+    } catch (err) {
+        return {
+            valid: false,
+            errors: [
+                `Configuration validation failed: ${err.message}`
+            ]
+        };
+    }
+}

package/dist/esm/config/validate-config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/config/validate-config.ts"],"sourcesContent":["import { Ajv, type ErrorObject } from 'ajv';\nimport * as fs from 'fs';\nimport { createRequire } from 'module';\nimport moduleRoot from 'module-root-sync';\nimport * as path from 'path';\n\n// Import ajv-formats (CommonJS module - use createRequire for ESM compatibility)\nconst require = createRequire(import.meta.url);\nconst addFormats = require('ajv-formats');\nconst packageRoot = moduleRoot(import.meta.filename);\n\n/**\n * Validation result for servers configuration\n */\nexport interface ValidationResult {\n  valid: boolean;\n  errors?: string[];\n  warnings?: string[];\n}\n\n// Module-level cache for schema and validator\nlet schemaCache: object | null = null;\nlet validatorCache: ReturnType<Ajv['compile']> | null = null;\n\n/**\n * Get servers schema (loads once from bundled file, then caches)\n */\nfunction getSchema(): object {\n  if (schemaCache) {\n    return schemaCache;\n  }\n\n  const schemaPath = path.join(packageRoot, 'schemas/servers.schema.json');\n  if (!fs.existsSync(schemaPath)) {\n    throw new Error(`Servers schema not found at: ${schemaPath}`);\n  }\n\n  schemaCache = JSON.parse(fs.readFileSync(schemaPath, 'utf8')) as object;\n  return schemaCache;\n}\n\n/**\n * Get compiled AJV validator (creates once, then caches)\n */\nfunction getValidator(): ReturnType<Ajv['compile']> {\n  if (validatorCache) {\n    return validatorCache;\n  }\n\n  const schema = getSchema();\n  const ajv = new Ajv({\n    allErrors: true,\n    verbose: true,\n    strictSchema: false, // Allow non-standard keywords like \"example\"\n  });\n\n  // Add format validators (uri, email, etc.)\n  addFormats(ajv);\n\n  validatorCache = ajv.compile(schema);\n  return validatorCache;\n}\n\n/**\n * Validate servers configuration against JSON Schema\n *\n * @param servers - Servers configuration object to validate (map of server names to configs)\n * @returns ValidationResult with valid flag, errors, and warnings\n */\nexport function validateServers(servers: unknown): ValidationResult {\n  try {\n    const validate = getValidator();\n    const valid = validate(servers);\n\n    if (!valid) {\n      const errors =\n        validate.errors?.map((e: ErrorObject) => {\n          const path = e.instancePath || '(root)';\n          return `${path}: ${e.message}`;\n        }) || [];\n\n      return { valid: false, errors };\n    }\n\n    const warnings: string[] = [];\n    return { valid: true, warnings };\n  } catch (err) {\n    return {\n      valid: false,\n      errors: [`Configuration validation failed: ${(err as Error).message}`],\n    };\n  }\n}\n"],"names":["Ajv","fs","createRequire","moduleRoot","path","require","url","addFormats","packageRoot","filename","schemaCache","validatorCache","getSchema","schemaPath","join","existsSync","Error","JSON","parse","readFileSync","getValidator","schema","ajv","allErrors","verbose","strictSchema","compile","validateServers","servers","validate","valid","errors","map","e","instancePath","message","warnings","err"],"mappings":"AAAA,SAASA,GAAG,QAA0B,MAAM;AAC5C,YAAYC,QAAQ,KAAK;AACzB,SAASC,aAAa,QAAQ,SAAS;AACvC,OAAOC,gBAAgB,mBAAmB;AAC1C,YAAYC,UAAU,OAAO;AAE7B,iFAAiF;AACjF,MAAMC,UAAUH,cAAc,YAAYI,GAAG;AAC7C,MAAMC,aAAaF,QAAQ;AAC3B,MAAMG,cAAcL,WAAW,YAAYM,QAAQ;AAWnD,8CAA8C;AAC9C,IAAIC,cAA6B;AACjC,IAAIC,iBAAoD;AAExD;;CAEC,GACD,SAASC;IACP,IAAIF,aAAa;QACf,OAAOA;IACT;IAEA,MAAMG,aAAaT,KAAKU,IAAI,CAACN,aAAa;IAC1C,IAAI,CAACP,GAAGc,UAAU,CAACF,aAAa;QAC9B,MAAM,IAAIG,MAAM,CAAC,6BAA6B,EAAEH,YAAY;IAC9D;IAEAH,cAAcO,KAAKC,KAAK,CAACjB,GAAGkB,YAAY,CAACN,YAAY;IACrD,OAAOH;AACT;AAEA;;CAEC,GACD,SAASU;IACP,IAAIT,gBAAgB;QAClB,OAAOA;IACT;IAEA,MAAMU,SAAST;IACf,MAAMU,MAAM,IAAItB,IAAI;QAClBuB,WAAW;QACXC,SAAS;QACTC,cAAc;IAChB;IAEA,2CAA2C;IAC3ClB,WAAWe;IAEXX,iBAAiBW,IAAII,OAAO,CAACL;IAC7B,OAAOV;AACT;AAEA;;;;;CAKC,GACD,OAAO,SAASgB,gBAAgBC,OAAgB;IAC9C,IAAI;QACF,MAAMC,WAAWT;QACjB,MAAMU,QAAQD,SAASD;QAEvB,IAAI,CAACE,OAAO;gBAERD;YADF,MAAME,SACJF,EAAAA,mBAAAA,SAASE,MAAM,cAAfF,uCAAAA,iBAAiBG,GAAG,CAAC,CAACC;gBACpB,MAAM7B,OAAO6B,EAAEC,YAAY,IAAI;gBAC/B,OAAO,GAAG9B,KAAK,EAAE,EAAE6B,EAAEE,OAAO,EAAE;YAChC,OAAM,EAAE;YAEV,OAAO;gBAAEL,OAAO;gBAAOC;YAAO;QAChC;QAEA,MAAMK,WAAqB,EAAE;QAC7B,OAAO;YAAEN,OAAO;YAAMM;QAAS;IACjC,EAAE,OAAOC,KAAK;QACZ,OAAO;YACLP,OAAO;YACPC,QAAQ;gBAAC,CAAC,iCAAiC,EAAE,AAACM,IAAcF,OAAO,EAAE;aAAC;QACxE;IACF;AACF"}

package/dist/esm/connection/connect-client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * connect-mcp-client.ts
+ *
+ * Helper to connect MCP SDK clients to servers with intelligent transport inference.
+ * Automatically detects transport type from URL protocol or type field.
+ */
+import '../monkey-patches.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type DcrAuthenticatorOptions } from '../dcr/index.js';
+import type { ServerProcess } from '../spawn/spawn-server.js';
+import type { ServersConfig } from '../spawn/spawn-servers.js';
+/**
+ * Minimal interface for connecting to servers.
+ * Only needs config and servers map for connection logic.
+ */
+interface RegistryLike {
+    config: ServersConfig;
+    servers: Map<string, ServerProcess>;
+}
+import { type Logger } from '../utils/logger.js';
+/**
+ * Connect MCP SDK client to server with full readiness handling.
+ * @internal - Use registry.connect() instead
+ *
+ * **Completely handles readiness**: transport availability + MCP protocol handshake.
+ *
+ * Transport is intelligently inferred and handled:
+ * - **Stdio servers**: Direct MCP connect (fast for spawned processes)
+ * - **HTTP servers**: Transport polling (/mcp endpoint) + MCP connect
+ * - **Registry result**: Handles both spawned and external servers
+ *
+ * Returns only when server is fully MCP-ready (initialize handshake complete).
+ *
+ * @param registryOrConfig - Result from createServerRegistry() or servers config object
+ * @param serverName - Server name from servers config
+ * @returns Connected MCP SDK Client (guaranteed ready)
+ *
+ * @example
+ * // Using registry (recommended)
+ * const registry = createServerRegistry({ echo: { command: 'node', args: ['server.ts'] } });
+ * const client = await registry.connect('echo');
+ * // Server is fully ready - transport available + MCP handshake complete
+ *
+ * @example
+ * // HTTP server readiness (waits for /mcp polling + MCP handshake)
+ * const registry = createServerRegistry(
+ *   { http: { type: 'http', url: 'http://localhost:3000/mcp', start: {...} } },
+ *   { dialects: ['start'] }
+ * );
+ * const client = await registry.connect('http');
+ * // 1. Waits for HTTP server to respond on /mcp
+ * // 2. Performs MCP initialize handshake
+ * // 3. Returns ready client
+ */
+export declare function connectMcpClient(registryOrConfig: RegistryLike | ServersConfig, serverName: string, options?: {
+    dcrAuthenticator?: Partial<DcrAuthenticatorOptions>;
+    logger?: Logger;
+}): Promise<Client>;
+export {};