@mcp-z/client 1.0.0

package/dist/cjs/auth/types.d.ts

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

package/dist/cjs/auth/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared types for OAuth and DCR authentication
+ */ /**
+ * OAuth callback result from authorization server
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/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"}

package/dist/cjs/client-helpers.d.cts

@@ -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/cjs/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/cjs/client-helpers.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "decorateClient", {
+    enumerable: true,
+    get: function() {
+        return decorateClient;
+    }
+});
+var _responsewrappersts = require("./response-wrappers.js");
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function decorateClient(client, metadata) {
+    var 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
+    });
+    var nativeCallTool = client.callTool.bind(client);
+    var wrapCallTool = function(promise) {
+        return promise.then(function(payload) {
+            return new _responsewrappersts.ToolResponseWrapper(payload);
+        });
+    };
+    enhanced.callTool = function(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 = function(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);
+    };
+    var nativeGetPrompt = client.getPrompt.bind(client);
+    var wrapPrompt = function(promise) {
+        return promise.then(function(payload) {
+            return new _responsewrappersts.PromptResponseWrapper(payload);
+        });
+    };
+    enhanced.getPrompt = function(nameOrParams, argsOrOptions, requestOptions) {
+        if (typeof nameOrParams === 'string') {
+            return wrapPrompt(nativeGetPrompt(_object_spread({
+                name: nameOrParams
+            }, argsOrOptions ? {
+                arguments: argsOrOptions
+            } : {}), requestOptions));
+        }
+        return wrapPrompt(nativeGetPrompt(nameOrParams, argsOrOptions));
+    };
+    enhanced.getPromptRaw = function(nameOrParams, argsOrOptions, requestOptions) {
+        if (typeof nameOrParams === 'string') {
+            return nativeGetPrompt(_object_spread({
+                name: nameOrParams
+            }, argsOrOptions ? {
+                arguments: argsOrOptions
+            } : {}), requestOptions);
+        }
+        return nativeGetPrompt(nameOrParams, argsOrOptions);
+    };
+    var nativeReadResource = client.readResource.bind(client);
+    var wrapResource = function(promise) {
+        return promise.then(function(payload) {
+            return new _responsewrappersts.ResourceResponseWrapper(payload);
+        });
+    };
+    enhanced.readResource = function(uriOrRequest, requestOptions) {
+        if (typeof uriOrRequest === 'string') {
+            return wrapResource(nativeReadResource({
+                uri: uriOrRequest
+            }, requestOptions));
+        }
+        return wrapResource(nativeReadResource(uriOrRequest, requestOptions));
+    };
+    enhanced.readResourceRaw = function(uriOrRequest, requestOptions) {
+        if (typeof uriOrRequest === 'string') {
+            return nativeReadResource({
+                uri: uriOrRequest
+            }, requestOptions);
+        }
+        return nativeReadResource(uriOrRequest, requestOptions);
+    };
+    return enhanced;
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/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":["decorateClient","client","metadata","enhanced","Object","defineProperty","value","serverName","enumerable","configurable","writable","nativeCallTool","callTool","bind","wrapCallTool","promise","then","payload","ToolResponseWrapper","nameOrInvocation","argsOrSession","requestOptions","name","arguments","undefined","callToolRaw","nativeGetPrompt","getPrompt","wrapPrompt","PromptResponseWrapper","nameOrParams","argsOrOptions","getPromptRaw","nativeReadResource","readResource","wrapResource","ResourceResponseWrapper","uriOrRequest","uri","readResourceRaw"],"mappings":";;;;+BA4DgBA;;;eAAAA;;;kCAzDgK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDzK,SAASA,eAAeC,MAAc,EAAEC,QAAgC;IAC7E,IAAMC,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,IAAMC,iBAAiBV,OAAOW,QAAQ,CAACC,IAAI,CAACZ;IAC5C,IAAMa,eAAe,SAACC;eAAyDA,QAAQC,IAAI,CAAC,SAACC;mBAAY,IAAIC,uCAAmB,CAACD;;;IAEjId,SAASS,QAAQ,GAAI,SAACO,kBAAoDC,eAAyDC;QACjI,IAAI,OAAOF,qBAAqB,UAAU;YACxC,OAAOL,aAAaH,eAAe;gBAAEW,MAAMH;gBAAkBI,SAAS,EAAGH,0BAAAA,2BAAAA,gBAAmC,CAAC;YAAE,GAAGI,WAAWH;QAC/H;QACA,OAAOP,aAAaH,eAAeQ,kBAAkBC,eAA0CC;IACjG;IAEAlB,SAASsB,WAAW,GAAI,SAACN,kBAAoDC,eAAyDC;QACpI,IAAI,OAAOF,qBAAqB,UAAU;YACxC,OAAOR,eAAe;gBAAEW,MAAMH;gBAAkBI,SAAS,EAAGH,0BAAAA,2BAAAA,gBAAmC,CAAC;YAAE,GAAGI,WAAWH;QAClH;QACA,OAAOV,eAAeQ,kBAAkBC,eAA0CC;IACpF;IAEA,IAAMK,kBAAkBzB,OAAO0B,SAAS,CAACd,IAAI,CAACZ;IAC9C,IAAM2B,aAAa,SAACb;eAA2DA,QAAQC,IAAI,CAAC,SAACC;mBAAY,IAAIY,yCAAqB,CAACZ;;;IAEnId,SAASwB,SAAS,GAAI,SAACG,cAAiDC,eAA4DV;QAClI,IAAI,OAAOS,iBAAiB,UAAU;YACpC,OAAOF,WAAWF,gBAAgB;gBAAEJ,MAAMQ;eAAkBC,gBAAgB;gBAAER,WAAWQ;YAAiC,IAAI,CAAC,IAAMV;QACvI;QACA,OAAOO,WAAWF,gBAAgBI,cAAcC;IAClD;IAEA5B,SAAS6B,YAAY,GAAI,SAACF,cAAiDC,eAA4DV;QACrI,IAAI,OAAOS,iBAAiB,UAAU;YACpC,OAAOJ,gBAAgB;gBAAEJ,MAAMQ;eAAkBC,gBAAgB;gBAAER,WAAWQ;YAAiC,IAAI,CAAC,IAAMV;QAC5H;QACA,OAAOK,gBAAgBI,cAAcC;IACvC;IAEA,IAAME,qBAAqBhC,OAAOiC,YAAY,CAACrB,IAAI,CAACZ;IACpD,IAAMkC,eAAe,SAACpB;eAAiEA,QAAQC,IAAI,CAAC,SAACC;mBAAY,IAAImB,2CAAuB,CAACnB;;;IAE7Id,SAAS+B,YAAY,GAAI,SAACG,cAAoDhB;QAC5E,IAAI,OAAOgB,iBAAiB,UAAU;YACpC,OAAOF,aAAaF,mBAAmB;gBAAEK,KAAKD;YAAa,GAAGhB;QAChE;QACA,OAAOc,aAAaF,mBAAmBI,cAAchB;IACvD;IAEAlB,SAASoC,eAAe,GAAI,SAACF,cAAoDhB;QAC/E,IAAI,OAAOgB,iBAAiB,UAAU;YACpC,OAAOJ,mBAAmB;gBAAEK,KAAKD;YAAa,GAAGhB;QACnD;QACA,OAAOY,mBAAmBI,cAAchB;IAC1C;IAEA,OAAOlB;AACT"}

package/dist/cjs/config/server-loader.d.cts

@@ -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/cjs/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/cjs/config/server-loader.js

@@ -0,0 +1,111 @@
+/**
+ * Load server definitions from .mcp.json (data-driven)
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get getAllServerNames () {
+        return getAllServerNames;
+    },
+    get getServerConfig () {
+        return getServerConfig;
+    },
+    get loadAvailableServers () {
+        return loadAvailableServers;
+    },
+    get parseServerList () {
+        return parseServerList;
+    }
+});
+var _fs = /*#__PURE__*/ _interop_require_wildcard(require("fs"));
+var _path = /*#__PURE__*/ _interop_require_wildcard(require("path"));
+var _url = require("url");
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+// Get package root: dist/esm/lib -> ../../../ or dist/cjs/lib -> ../../../
+var __filename1 = (0, _url.fileURLToPath)(require("url").pathToFileURL(__filename).toString());
+var __dirname = _path.dirname(__filename1);
+var packageRoot = _path.resolve(__dirname, '../../..');
+function loadAvailableServers() {
+    var configPath = _path.join(packageRoot, 'resources/.mcp.json');
+    if (!_fs.existsSync(configPath)) {
+        throw new Error("Server configuration not found: ".concat(configPath));
+    }
+    var content = _fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(content);
+}
+function getAllServerNames() {
+    var config = loadAvailableServers();
+    return Object.keys(config.mcpServers);
+}
+function parseServerList(input) {
+    var allServers = getAllServerNames();
+    if (input === 'all') {
+        return allServers;
+    }
+    var requested = input.split(',').map(function(s) {
+        return s.trim();
+    });
+    var invalid = requested.filter(function(s) {
+        return !allServers.includes(s);
+    });
+    if (invalid.length > 0) {
+        throw new Error("Invalid server names: ".concat(invalid.join(', '), ".\nAvailable: ").concat(allServers.join(', ')));
+    }
+    return requested;
+}
+function getServerConfig(serverName) {
+    var config = loadAvailableServers();
+    var serverConfig = config.mcpServers[serverName];
+    if (!serverConfig) {
+        throw new Error("Unknown server: ".concat(serverName, ".\nAvailable: ").concat(getAllServerNames().join(', ')));
+    }
+    return serverConfig;
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/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":["getAllServerNames","getServerConfig","loadAvailableServers","parseServerList","__filename","fileURLToPath","__dirname","path","dirname","packageRoot","resolve","configPath","join","fs","existsSync","Error","content","readFileSync","JSON","parse","config","Object","keys","mcpServers","input","allServers","requested","split","map","s","trim","invalid","filter","includes","length","serverName","serverConfig"],"mappings":"AAAA;;CAEC;;;;;;;;;;;QAsCeA;eAAAA;;QA4BAC;eAAAA;;QA1CAC;eAAAA;;QAsBAC;eAAAA;;;0DA5CI;4DACE;mBACQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAE9B,2EAA2E;AAC3E,IAAMC,cAAaC,IAAAA,kBAAa,EAAC;AACjC,IAAMC,YAAYC,MAAKC,OAAO,CAACJ;AAC/B,IAAMK,cAAcF,MAAKG,OAAO,CAACJ,WAAW;AAerC,SAASJ;IACd,IAAMS,aAAaJ,MAAKK,IAAI,CAACH,aAAa;IAE1C,IAAI,CAACI,IAAGC,UAAU,CAACH,aAAa;QAC9B,MAAM,IAAII,MAAM,AAAC,mCAA6C,OAAXJ;IACrD;IAEA,IAAMK,UAAUH,IAAGI,YAAY,CAACN,YAAY;IAC5C,OAAOO,KAAKC,KAAK,CAACH;AACpB;AAKO,SAAShB;IACd,IAAMoB,SAASlB;IACf,OAAOmB,OAAOC,IAAI,CAACF,OAAOG,UAAU;AACtC;AAKO,SAASpB,gBAAgBqB,KAAa;IAC3C,IAAMC,aAAazB;IAEnB,IAAIwB,UAAU,OAAO;QACnB,OAAOC;IACT;IAEA,IAAMC,YAAYF,MAAMG,KAAK,CAAC,KAAKC,GAAG,CAAC,SAACC;eAAMA,EAAEC,IAAI;;IACpD,IAAMC,UAAUL,UAAUM,MAAM,CAAC,SAACH;eAAM,CAACJ,WAAWQ,QAAQ,CAACJ;;IAE7D,IAAIE,QAAQG,MAAM,GAAG,GAAG;QACtB,MAAM,IAAInB,MAAM,AAAC,yBAA2DU,OAAnCM,QAAQnB,IAAI,CAAC,OAAM,kBAAsC,OAAtBa,WAAWb,IAAI,CAAC;IAC9F;IAEA,OAAOc;AACT;AAKO,SAASzB,gBAAgBkC,UAAkB;IAChD,IAAMf,SAASlB;IACf,IAAMkC,eAAehB,OAAOG,UAAU,CAACY,WAAW;IAElD,IAAI,CAACC,cAAc;QACjB,MAAM,IAAIrB,MAAM,AAAC,mBAA6Cf,OAA3BmC,YAAW,kBAA+C,OAA/BnC,oBAAoBY,IAAI,CAAC;IACzF;IAEA,OAAOwB;AACT"}

package/dist/cjs/config/validate-config.d.cts

@@ -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/cjs/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;