@mcp-z/client 1.0.0

package/dist/cjs/connection/wait-for-http-ready.js

@@ -0,0 +1,232 @@
+/**
+ * wait-for-http-ready.ts
+ *
+ * Utility for waiting for HTTP servers to become ready.
+ */ /**
+ * Wait for HTTP server to be ready by checking endpoint accessibility.
+ * Used to handle HTTP servers that need time to start listening.
+ *
+ * @param url - URL to check for server readiness
+ * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000)
+ * @returns Promise that resolves when server is ready
+ * @throws Error if server doesn't become ready within timeout
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "waitForHttpReady", {
+    enumerable: true,
+    get: function() {
+        return waitForHttpReady;
+    }
+});
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+function waitForHttpReady(url) {
+    var timeoutMs = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 30000;
+    return _async_to_generator(function() {
+        var start, maxRetries, i, response, _error, elapsed;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    start = Date.now();
+                    maxRetries = Math.ceil(timeoutMs / 100); // Check every 100ms
+                    i = 0;
+                    _state.label = 1;
+                case 1:
+                    if (!(i < maxRetries)) return [
+                        3,
+                        8
+                    ];
+                    _state.label = 2;
+                case 2:
+                    _state.trys.push([
+                        2,
+                        4,
+                        ,
+                        5
+                    ]);
+                    return [
+                        4,
+                        fetch(url, {
+                            method: 'HEAD',
+                            headers: {
+                                Connection: 'close'
+                            },
+                            signal: AbortSignal.timeout(500)
+                        })
+                    ];
+                case 3:
+                    response = _state.sent();
+                    // Server is responding if we get any HTTP status
+                    if (response.status >= 200 && response.status < 500) {
+                        return [
+                            2
+                        ];
+                    }
+                    return [
+                        3,
+                        5
+                    ];
+                case 4:
+                    _error = _state.sent();
+                    // Connection refused, timeout, or network error
+                    // Server not ready yet, continue polling
+                    if (i === maxRetries - 1) {
+                        elapsed = Date.now() - start;
+                        throw new Error("HTTP server ".concat(url, " not ready after ").concat(elapsed, "ms"));
+                    }
+                    return [
+                        3,
+                        5
+                    ];
+                case 5:
+                    // Wait before retry
+                    return [
+                        4,
+                        new Promise(function(resolve) {
+                            return setTimeout(resolve, 100);
+                        })
+                    ];
+                case 6:
+                    _state.sent();
+                    _state.label = 7;
+                case 7:
+                    i++;
+                    return [
+                        3,
+                        1
+                    ];
+                case 8:
+                    throw new Error("HTTP server ".concat(url, " not ready after ").concat(timeoutMs, "ms"));
+            }
+        });
+    })();
+}
+/* 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/connection/wait-for-http-ready.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/connection/wait-for-http-ready.ts"],"sourcesContent":["/**\n * wait-for-http-ready.ts\n *\n * Utility for waiting for HTTP servers to become ready.\n */\n\n/**\n * Wait for HTTP server to be ready by checking endpoint accessibility.\n * Used to handle HTTP servers that need time to start listening.\n *\n * @param url - URL to check for server readiness\n * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000)\n * @returns Promise that resolves when server is ready\n * @throws Error if server doesn't become ready within timeout\n */\nexport async function waitForHttpReady(url: string, timeoutMs = 30000): Promise<void> {\n  const start = Date.now();\n  const maxRetries = Math.ceil(timeoutMs / 100); // Check every 100ms\n\n  for (let i = 0; i < maxRetries; i++) {\n    try {\n      // Use HEAD request to check server is responding\n      const response = await fetch(url, {\n        method: 'HEAD',\n        headers: { Connection: 'close' },\n        signal: AbortSignal.timeout(500), // 500ms per attempt\n      });\n\n      // Server is responding if we get any HTTP status\n      if (response.status >= 200 && response.status < 500) {\n        return;\n      }\n\n      // Server error (5xx) - keep trying as it might still be starting\n    } catch (_error) {\n      // Connection refused, timeout, or network error\n      // Server not ready yet, continue polling\n      if (i === maxRetries - 1) {\n        const elapsed = Date.now() - start;\n        throw new Error(`HTTP server ${url} not ready after ${elapsed}ms`);\n      }\n    }\n\n    // Wait before retry\n    await new Promise((resolve) => setTimeout(resolve, 100));\n  }\n\n  throw new Error(`HTTP server ${url} not ready after ${timeoutMs}ms`);\n}\n"],"names":["waitForHttpReady","url","timeoutMs","start","maxRetries","i","response","_error","elapsed","Date","now","Math","ceil","fetch","method","headers","Connection","signal","AbortSignal","timeout","status","Error","Promise","resolve","setTimeout"],"mappings":"AAAA;;;;CAIC,GAED;;;;;;;;CAQC;;;;+BACqBA;;;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAf,SAAeA,iBAAiBC,GAAW;QAAEC,YAAAA,iEAAY;;YACxDC,OACAC,YAEGC,GAGCC,UAYCC,QAICC;;;;oBAtBNL,QAAQM,KAAKC,GAAG;oBAChBN,aAAaO,KAAKC,IAAI,CAACV,YAAY,MAAM,oBAAoB;oBAE1DG,IAAI;;;yBAAGA,CAAAA,IAAID,UAAS;;;;;;;;;;;;oBAGR;;wBAAMS,MAAMZ,KAAK;4BAChCa,QAAQ;4BACRC,SAAS;gCAAEC,YAAY;4BAAQ;4BAC/BC,QAAQC,YAAYC,OAAO,CAAC;wBAC9B;;;oBAJMb,WAAW;oBAMjB,iDAAiD;oBACjD,IAAIA,SAASc,MAAM,IAAI,OAAOd,SAASc,MAAM,GAAG,KAAK;wBACnD;;;oBACF;;;;;;oBAGOb;oBACP,gDAAgD;oBAChD,yCAAyC;oBACzC,IAAIF,MAAMD,aAAa,GAAG;wBAClBI,UAAUC,KAAKC,GAAG,KAAKP;wBAC7B,MAAM,IAAIkB,MAAM,AAAC,eAAqCb,OAAvBP,KAAI,qBAA2B,OAARO,SAAQ;oBAChE;;;;;;oBAGF,oBAAoB;oBACpB;;wBAAM,IAAIc,QAAQ,SAACC;mCAAYC,WAAWD,SAAS;;;;oBAAnD;;;oBAzB8BlB;;;;;;oBA4BhC,MAAM,IAAIgB,MAAM,AAAC,eAAqCnB,OAAvBD,KAAI,qBAA6B,OAAVC,WAAU;;;IAClE"}

package/dist/cjs/dcr/dcr-authenticator.d.cts

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

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

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