@mcp-z/client 1.0.0

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

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "validateServers", {
+    enumerable: true,
+    get: function() {
+        return validateServers;
+    }
+});
+var _ajv = require("ajv");
+var _fs = /*#__PURE__*/ _interop_require_wildcard(require("fs"));
+var _module = require("module");
+var _modulerootsync = /*#__PURE__*/ _interop_require_default(require("module-root-sync"));
+var _path = /*#__PURE__*/ _interop_require_wildcard(require("path"));
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+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;
+}
+// Import ajv-formats (CommonJS module - use createRequire for ESM compatibility)
+var require1 = (0, _module.createRequire)(require("url").pathToFileURL(__filename).toString());
+var addFormats = require1('ajv-formats');
+var packageRoot = (0, _modulerootsync.default)(__filename);
+// Module-level cache for schema and validator
+var schemaCache = null;
+var validatorCache = null;
+/**
+ * Get servers schema (loads once from bundled file, then caches)
+ */ function getSchema() {
+    if (schemaCache) {
+        return schemaCache;
+    }
+    var schemaPath = _path.join(packageRoot, 'schemas/servers.schema.json');
+    if (!_fs.existsSync(schemaPath)) {
+        throw new Error("Servers schema not found at: ".concat(schemaPath));
+    }
+    schemaCache = JSON.parse(_fs.readFileSync(schemaPath, 'utf8'));
+    return schemaCache;
+}
+/**
+ * Get compiled AJV validator (creates once, then caches)
+ */ function getValidator() {
+    if (validatorCache) {
+        return validatorCache;
+    }
+    var schema = getSchema();
+    var ajv = new _ajv.Ajv({
+        allErrors: true,
+        verbose: true,
+        strictSchema: false
+    });
+    // Add format validators (uri, email, etc.)
+    addFormats(ajv);
+    validatorCache = ajv.compile(schema);
+    return validatorCache;
+}
+function validateServers(servers) {
+    try {
+        var validate = getValidator();
+        var valid = validate(servers);
+        if (!valid) {
+            var _validate_errors;
+            var errors = ((_validate_errors = validate.errors) === null || _validate_errors === void 0 ? void 0 : _validate_errors.map(function(e) {
+                var path = e.instancePath || '(root)';
+                return "".concat(path, ": ").concat(e.message);
+            })) || [];
+            return {
+                valid: false,
+                errors: errors
+            };
+        }
+        var warnings = [];
+        return {
+            valid: true,
+            warnings: warnings
+        };
+    } catch (err) {
+        return {
+            valid: false,
+            errors: [
+                "Configuration validation failed: ".concat(err.message)
+            ]
+        };
+    }
+}
+/* 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/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":["validateServers","require","createRequire","addFormats","packageRoot","moduleRoot","schemaCache","validatorCache","getSchema","schemaPath","path","join","fs","existsSync","Error","JSON","parse","readFileSync","getValidator","schema","ajv","Ajv","allErrors","verbose","strictSchema","compile","servers","validate","valid","errors","map","e","instancePath","message","warnings","err"],"mappings":";;;;+BAqEgBA;;;eAAAA;;;mBArEsB;0DAClB;sBACU;qEACP;4DACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEtB,iFAAiF;AACjF,IAAMC,WAAUC,IAAAA,qBAAa,EAAC;AAC9B,IAAMC,aAAaF,SAAQ;AAC3B,IAAMG,cAAcC,IAAAA,uBAAU,EAAC;AAW/B,8CAA8C;AAC9C,IAAIC,cAA6B;AACjC,IAAIC,iBAAoD;AAExD;;CAEC,GACD,SAASC;IACP,IAAIF,aAAa;QACf,OAAOA;IACT;IAEA,IAAMG,aAAaC,MAAKC,IAAI,CAACP,aAAa;IAC1C,IAAI,CAACQ,IAAGC,UAAU,CAACJ,aAAa;QAC9B,MAAM,IAAIK,MAAM,AAAC,gCAA0C,OAAXL;IAClD;IAEAH,cAAcS,KAAKC,KAAK,CAACJ,IAAGK,YAAY,CAACR,YAAY;IACrD,OAAOH;AACT;AAEA;;CAEC,GACD,SAASY;IACP,IAAIX,gBAAgB;QAClB,OAAOA;IACT;IAEA,IAAMY,SAASX;IACf,IAAMY,MAAM,IAAIC,QAAG,CAAC;QAClBC,WAAW;QACXC,SAAS;QACTC,cAAc;IAChB;IAEA,2CAA2C;IAC3CrB,WAAWiB;IAEXb,iBAAiBa,IAAIK,OAAO,CAACN;IAC7B,OAAOZ;AACT;AAQO,SAASP,gBAAgB0B,OAAgB;IAC9C,IAAI;QACF,IAAMC,WAAWT;QACjB,IAAMU,QAAQD,SAASD;QAEvB,IAAI,CAACE,OAAO;gBAERD;YADF,IAAME,SACJF,EAAAA,mBAAAA,SAASE,MAAM,cAAfF,uCAAAA,iBAAiBG,GAAG,CAAC,SAACC;gBACpB,IAAMrB,OAAOqB,EAAEC,YAAY,IAAI;gBAC/B,OAAO,AAAC,GAAWD,OAATrB,MAAK,MAAc,OAAVqB,EAAEE,OAAO;YAC9B,OAAM,EAAE;YAEV,OAAO;gBAAEL,OAAO;gBAAOC,QAAAA;YAAO;QAChC;QAEA,IAAMK,WAAqB,EAAE;QAC7B,OAAO;YAAEN,OAAO;YAAMM,UAAAA;QAAS;IACjC,EAAE,OAAOC,KAAK;QACZ,OAAO;YACLP,OAAO;YACPC,QAAQ;gBAAE,oCAA0D,OAAvB,AAACM,IAAcF,OAAO;aAAG;QACxE;IACF;AACF"}

package/dist/cjs/connection/connect-client.d.cts

@@ -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 {};

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