mcp-use 0.0.1

package/dist/src/config.js

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs';
+import { HttpConnector } from './connectors/http.js';
+import { StdioConnector } from './connectors/stdio.js';
+import { WebSocketConnector } from './connectors/websocket.js';
+export function loadConfigFile(filepath) {
+    const raw = readFileSync(filepath, 'utf-8');
+    return JSON.parse(raw);
+}
+export function createConnectorFromConfig(serverConfig) {
+    if ('command' in serverConfig && 'args' in serverConfig) {
+        return new StdioConnector({
+            command: serverConfig.command,
+            args: serverConfig.args,
+            env: serverConfig.env,
+        });
+    }
+    if ('url' in serverConfig) {
+        return new HttpConnector(serverConfig.url, {
+            headers: serverConfig.headers,
+            authToken: serverConfig.auth_token,
+        });
+    }
+    if ('ws_url' in serverConfig) {
+        return new WebSocketConnector(serverConfig.ws_url, {
+            headers: serverConfig.headers,
+            authToken: serverConfig.auth_token,
+        });
+    }
+    throw new Error('Cannot determine connector type from config');
+}

package/dist/src/connectors/base.js

@@ -0,0 +1,129 @@
+import { logger } from '../logging.js';
+/**
+ * Base class for MCP connectors.
+ */
+export class BaseConnector {
+    client = null;
+    connectionManager = null;
+    toolsCache = null;
+    connected = false;
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    /** Disconnect and release resources. */
+    async disconnect() {
+        if (!this.connected) {
+            logger.debug('Not connected to MCP implementation');
+            return;
+        }
+        logger.debug('Disconnecting from MCP implementation');
+        await this.cleanupResources();
+        this.connected = false;
+        logger.debug('Disconnected from MCP implementation');
+    }
+    /** Check if the client is connected */
+    get isClientConnected() {
+        return this.client != null;
+    }
+    /**
+     * Initialise the MCP session **after** `connect()` has succeeded.
+     *
+     * In the SDK, `Client.connect(transport)` automatically performs the
+     * protocol‑level `initialize` handshake, so we only need to cache the list of
+     * tools and expose some server info.
+     */
+    async initialize(defaultRequestOptions = this.opts.defaultRequestOptions ?? {}) {
+        if (!this.client) {
+            throw new Error('MCP client is not connected');
+        }
+        logger.debug('Caching server capabilities & tools');
+        // Cache server capabilities for callers who need them.
+        const capabilities = this.client.getServerCapabilities();
+        // Fetch and cache tools
+        const listToolsRes = await this.client.listTools(undefined, defaultRequestOptions);
+        this.toolsCache = (listToolsRes.tools ?? []);
+        logger.debug(`Fetched ${this.toolsCache.length} tools from server`);
+        return capabilities;
+    }
+    /** Lazily expose the cached tools list. */
+    get tools() {
+        if (!this.toolsCache) {
+            throw new Error('MCP client is not initialized; call initialize() first');
+        }
+        return this.toolsCache;
+    }
+    /** Call a tool on the server. */
+    async callTool(name, args, options) {
+        if (!this.client) {
+            throw new Error('MCP client is not connected');
+        }
+        logger.debug(`Calling tool '${name}' with args`, args);
+        const res = await this.client.callTool({ name, arguments: args }, undefined, options);
+        logger.debug(`Tool '${name}' returned`, res);
+        return res;
+    }
+    /** List resources from the server. */
+    async listResources(options) {
+        if (!this.client) {
+            throw new Error('MCP client is not connected');
+        }
+        logger.debug('Listing resources');
+        return await this.client.listResources(undefined, options);
+    }
+    /** Read a resource by URI. */
+    async readResource(uri, options) {
+        if (!this.client) {
+            throw new Error('MCP client is not connected');
+        }
+        logger.debug(`Reading resource ${uri}`);
+        const res = await this.client.readResource({ uri }, options);
+        return { content: res.content, mimeType: res.mimeType };
+    }
+    /** Send a raw request through the client. */
+    async request(method, params = null, options) {
+        if (!this.client) {
+            throw new Error('MCP client is not connected');
+        }
+        logger.debug(`Sending raw request '${method}' with params`, params);
+        return await this.client.request({ method, params: params ?? {} }, undefined, options);
+    }
+    /**
+     * Helper to tear down the client & connection manager safely.
+     */
+    async cleanupResources() {
+        const issues = [];
+        if (this.client) {
+            try {
+                if (typeof this.client.close === 'function') {
+                    await this.client.close();
+                }
+            }
+            catch (e) {
+                const msg = `Error closing client: ${e}`;
+                logger.warn(msg);
+                issues.push(msg);
+            }
+            finally {
+                this.client = null;
+            }
+        }
+        if (this.connectionManager) {
+            try {
+                await this.connectionManager.stop();
+            }
+            catch (e) {
+                const msg = `Error stopping connection manager: ${e}`;
+                logger.warn(msg);
+                issues.push(msg);
+            }
+            finally {
+                this.connectionManager = null;
+            }
+        }
+        this.toolsCache = null;
+        if (issues.length) {
+            logger.warn(`Resource cleanup finished with ${issues.length} issue(s)`);
+        }
+    }
+}

package/dist/src/connectors/http.js

@@ -0,0 +1,51 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { logger } from '../logging.js';
+import { SseConnectionManager } from '../task_managers/sse.js';
+import { BaseConnector } from './base.js';
+export class HttpConnector extends BaseConnector {
+    baseUrl;
+    headers;
+    timeout;
+    sseReadTimeout;
+    clientInfo;
+    constructor(baseUrl, opts = {}) {
+        super(opts);
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.headers = { ...(opts.headers ?? {}) };
+        if (opts.authToken) {
+            this.headers.Authorization = `Bearer ${opts.authToken}`;
+        }
+        this.timeout = opts.timeout ?? 5;
+        this.sseReadTimeout = opts.sseReadTimeout ?? 60 * 5;
+        this.clientInfo = opts.clientInfo ?? { name: 'http-connector', version: '1.0.0' };
+    }
+    /** Establish connection to the MCP implementation via SSE. */
+    async connect() {
+        if (this.connected) {
+            logger.debug('Already connected to MCP implementation');
+            return;
+        }
+        logger.debug(`Connecting to MCP implementation via HTTP/SSE: ${this.baseUrl}`);
+        try {
+            // Build the SSE URL (root of server endpoint)
+            const sseUrl = this.baseUrl;
+            // Create and start the connection manager -> returns an SSE transport
+            this.connectionManager = new SseConnectionManager(sseUrl, {
+                requestInit: {
+                    headers: this.headers,
+                },
+            });
+            const transport = await this.connectionManager.start();
+            // Create and connect the client
+            this.client = new Client(this.clientInfo, this.opts.clientOptions);
+            await this.client.connect(transport);
+            this.connected = true;
+            logger.debug(`Successfully connected to MCP implementation via HTTP/SSE: ${this.baseUrl}`);
+        }
+        catch (err) {
+            logger.error(`Failed to connect to MCP implementation via HTTP/SSE: ${err}`);
+            await this.cleanupResources();
+            throw err;
+        }
+    }
+}

package/dist/src/connectors/index.js

@@ -0,0 +1,4 @@
+export { BaseConnector } from './base.js';
+export { HttpConnector } from './http.js';
+export { StdioConnector } from './stdio.js';
+export { WebSocketConnector } from './websocket.js';

package/dist/src/connectors/stdio.js

@@ -0,0 +1,49 @@
+import process from 'node:process';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { logger } from '../logging.js';
+import { StdioConnectionManager } from '../task_managers/stdio.js';
+import { BaseConnector } from './base.js';
+export class StdioConnector extends BaseConnector {
+    command;
+    args;
+    env;
+    errlog;
+    clientInfo;
+    constructor({ command = 'npx', args = [], env, errlog = process.stderr, ...rest } = {}) {
+        super(rest);
+        this.command = command;
+        this.args = args;
+        this.env = env;
+        this.errlog = errlog;
+        this.clientInfo = rest.clientInfo ?? { name: 'stdio-connector', version: '1.0.0' };
+    }
+    /** Establish connection to the MCP implementation. */
+    async connect() {
+        if (this.connected) {
+            logger.debug('Already connected to MCP implementation');
+            return;
+        }
+        logger.debug(`Connecting to MCP implementation via stdio: ${this.command}`);
+        try {
+            // 1. Build server parameters for the transport
+            const serverParams = {
+                command: this.command,
+                args: this.args,
+                env: this.env,
+            };
+            // 2. Start the connection manager -> returns a live transport
+            this.connectionManager = new StdioConnectionManager(serverParams, this.errlog);
+            const transport = await this.connectionManager.start();
+            // 3. Create & connect the MCP client
+            this.client = new Client(this.clientInfo, this.opts.clientOptions);
+            await this.client.connect(transport);
+            this.connected = true;
+            logger.debug(`Successfully connected to MCP implementation: ${this.command}`);
+        }
+        catch (err) {
+            logger.error(`Failed to connect to MCP implementation: ${err}`);
+            await this.cleanupResources();
+            throw err;
+        }
+    }
+}

package/dist/src/connectors/websocket.js

@@ -0,0 +1,151 @@
+import { v4 as uuidv4 } from 'uuid';
+import { logger } from '../logging.js';
+import { WebSocketConnectionManager } from '../task_managers/websocket.js';
+import { BaseConnector } from './base.js';
+export class WebSocketConnector extends BaseConnector {
+    url;
+    headers;
+    connectionManager = null;
+    ws = null;
+    receiverTask = null;
+    pending = new Map();
+    toolsCache = null;
+    constructor(url, opts = {}) {
+        super();
+        this.url = url;
+        this.headers = { ...(opts.headers ?? {}) };
+        if (opts.authToken)
+            this.headers.Authorization = `Bearer ${opts.authToken}`;
+    }
+    async connect() {
+        if (this.connected) {
+            logger.debug('Already connected to MCP implementation');
+            return;
+        }
+        logger.debug(`Connecting via WebSocket: ${this.url}`);
+        try {
+            this.connectionManager = new WebSocketConnectionManager(this.url, this.headers);
+            this.ws = await this.connectionManager.start();
+            this.receiverTask = this.receiveLoop();
+            this.connected = true;
+            logger.debug('WebSocket connected successfully');
+        }
+        catch (e) {
+            logger.error(`Failed to connect: ${e}`);
+            await this.cleanupResources();
+            throw e;
+        }
+    }
+    async disconnect() {
+        if (!this.connected) {
+            logger.debug('Not connected to MCP implementation');
+            return;
+        }
+        logger.debug('Disconnecting …');
+        await this.cleanupResources();
+        this.connected = false;
+    }
+    sendRequest(method, params = null) {
+        if (!this.ws)
+            throw new Error('WebSocket is not connected');
+        const id = uuidv4();
+        const payload = JSON.stringify({ id, method, params: params ?? {} });
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.ws.send(payload, (err) => {
+                if (err) {
+                    this.pending.delete(id);
+                    reject(err);
+                }
+            });
+        });
+    }
+    async receiveLoop() {
+        if (!this.ws)
+            return;
+        const socket = this.ws; // Node.ws or browser WS
+        const onMessage = (msg) => {
+            let data;
+            try {
+                data = JSON.parse(msg.data ?? msg);
+            }
+            catch (e) {
+                logger.warn('Received non‑JSON frame');
+                return;
+            }
+            const id = data.id;
+            if (id && this.pending.has(id)) {
+                const { resolve, reject } = this.pending.get(id);
+                this.pending.delete(id);
+                if ('result' in data)
+                    resolve(data.result);
+                else if ('error' in data)
+                    reject(data.error);
+            }
+            else {
+                logger.debug('Received unsolicited message', data);
+            }
+        };
+        socket.addEventListener ? socket.addEventListener('message', onMessage) : socket.on('message', onMessage);
+        // keep promise pending until close
+        return new Promise((resolve) => {
+            const onClose = () => {
+                socket.removeEventListener ? socket.removeEventListener('message', onMessage) : socket.off('message', onMessage);
+                this.rejectAll(new Error('WebSocket closed'));
+                resolve();
+            };
+            socket.addEventListener ? socket.addEventListener('close', onClose) : socket.on('close', onClose);
+        });
+    }
+    rejectAll(err) {
+        for (const { reject } of this.pending.values())
+            reject(err);
+        this.pending.clear();
+    }
+    async initialize() {
+        logger.debug('Initializing MCP session over WebSocket');
+        const result = await this.sendRequest('initialize');
+        const toolsList = await this.listTools();
+        this.toolsCache = toolsList.map(t => t);
+        logger.debug(`Initialized with ${this.toolsCache.length} tools`);
+        return result;
+    }
+    async listTools() {
+        const res = await this.sendRequest('tools/list');
+        return res.tools ?? [];
+    }
+    async callTool(name, args, options) {
+        return await this.sendRequest('tools/call', { name, arguments: args });
+    }
+    async listResources(options) {
+        const resources = await this.sendRequest('resources/list');
+        return { resources: Array.isArray(resources) ? resources : [] };
+    }
+    async readResource(uri, options) {
+        const res = await this.sendRequest('resources/read', { uri });
+        return { content: res.content, mimeType: res.mimeType };
+    }
+    async request(method, params = null, options) {
+        return await this.sendRequest(method, params);
+    }
+    get tools() {
+        if (!this.toolsCache)
+            throw new Error('MCP client is not initialized');
+        return this.toolsCache;
+    }
+    async cleanupResources() {
+        // Stop receiver
+        if (this.receiverTask)
+            await this.receiverTask.catch(() => { });
+        this.receiverTask = null;
+        // Reject pending
+        this.rejectAll(new Error('WebSocket disconnected'));
+        // Stop connection manager → closes socket
+        if (this.connectionManager) {
+            await this.connectionManager.stop();
+            this.connectionManager = null;
+            this.ws = null;
+        }
+        this.toolsCache = null;
+    }
+}

package/dist/src/logging.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createLogger, format, transports } from 'winston';
+const { combine, timestamp, label, printf } = format;
+let MCP_USE_DEBUG = 0;
+const debugEnv = process.env.DEBUG?.toLowerCase();
+if (debugEnv === '2') {
+    MCP_USE_DEBUG = 2;
+}
+else if (debugEnv === '1') {
+    MCP_USE_DEBUG = 1;
+}
+const defaultFormat = printf(({ level, message, label, timestamp }) => `${timestamp} [${label}] ${level.toUpperCase()}: ${message}`);
+export class Logger {
+    static loggers = {};
+    static getLogger(name = 'mcp_use') {
+        if (!this.loggers[name]) {
+            this.loggers[name] = createLogger({
+                level: 'warn',
+                format: combine(label({ label: name }), timestamp(), defaultFormat),
+                transports: [],
+            });
+        }
+        return this.loggers[name];
+    }
+    static configure(level, toConsole = true, toFile) {
+        const root = this.getLogger();
+        if (!level) {
+            level
+                = MCP_USE_DEBUG === 2
+                    ? 'debug'
+                    : MCP_USE_DEBUG === 1 ? 'info' : 'warn';
+        }
+        root.level = level;
+        root.clear();
+        if (toConsole) {
+            root.add(new transports.Console());
+        }
+        if (toFile) {
+            const dir = path.dirname(toFile);
+            if (dir && !fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            root.add(new transports.File({ filename: toFile }));
+        }
+    }
+    static setDebug(debugLevel = 2) {
+        MCP_USE_DEBUG = debugLevel;
+        process.env.LANGCHAIN_VERBOSE = debugLevel >= 1 ? 'true' : 'false';
+        const newLevel = debugLevel === 2
+            ? 'debug'
+            : debugLevel === 1 ? 'info' : 'warn';
+        Object.values(this.loggers).forEach((log) => {
+            log.level = newLevel;
+        });
+    }
+}
+Logger.configure();
+export const logger = Logger.getLogger();

package/dist/src/session.js

@@ -0,0 +1,52 @@
+import { logger } from './logging.js';
+export class MCPSession {
+    connector;
+    autoConnect;
+    _sessionInfo = null;
+    _tools = [];
+    constructor(connector, autoConnect = true) {
+        this.connector = connector;
+        this.autoConnect = autoConnect;
+    }
+    async open() {
+        await this.connect();
+        return this;
+    }
+    async close() {
+        await this.disconnect();
+    }
+    async connect() {
+        await this.connector.connect();
+    }
+    async disconnect() {
+        await this.connector.disconnect();
+    }
+    async initialize() {
+        if (!this.isConnected && this.autoConnect) {
+            await this.connect();
+        }
+        this._sessionInfo = await this.connector.initialize() ?? {};
+        await this.discoverTools();
+        return this._sessionInfo;
+    }
+    get isConnected() {
+        return this.connector && this.connector.isClientConnected;
+    }
+    get sessionInfo() {
+        return this._sessionInfo;
+    }
+    get tools() {
+        return this._tools;
+    }
+    async discoverTools() {
+        this._tools = this.connector.tools;
+        return this._tools;
+    }
+    async callTool(name, args) {
+        if (!this.isConnected && this.autoConnect) {
+            await this.connect();
+        }
+        logger.debug(`MCPSession calling tool '${name}'`);
+        return await this.connector.callTool(name, args);
+    }
+}

package/dist/src/task_managers/base.js

@@ -0,0 +1,127 @@
+import { logger } from '../logging.js';
+export class ConnectionManager {
+    _readyPromise;
+    _readyResolver;
+    _donePromise;
+    _doneResolver;
+    _exception = null;
+    _connection = null;
+    _task = null;
+    _abortController = null;
+    constructor() {
+        this.reset();
+    }
+    /**
+     * Start the connection manager and establish a connection.
+     *
+     * @returns The established connection.
+     * @throws If the connection cannot be established.
+     */
+    async start() {
+        // Reset internal state before starting
+        this.reset();
+        logger.debug(`Starting ${this.constructor.name}`);
+        // Kick off the background task that manages the connection
+        this._task = this.connectionTask();
+        // Wait until the connection is ready or an error occurs
+        await this._readyPromise;
+        // If an exception occurred during startup, re‑throw it
+        if (this._exception) {
+            throw this._exception;
+        }
+        if (this._connection === null) {
+            throw new Error('Connection was not established');
+        }
+        return this._connection;
+    }
+    /**
+     * Stop the connection manager and close the connection.
+     */
+    async stop() {
+        if (this._task && this._abortController) {
+            logger.debug(`Cancelling ${this.constructor.name} task`);
+            this._abortController.abort();
+            try {
+                await this._task;
+            }
+            catch (e) {
+                if (e instanceof Error && e.name === 'AbortError') {
+                    logger.debug(`${this.constructor.name} task aborted successfully`);
+                }
+                else {
+                    logger.warn(`Error stopping ${this.constructor.name} task: ${e}`);
+                }
+            }
+        }
+        // Wait until the connection cleanup has completed
+        await this._donePromise;
+        logger.debug(`${this.constructor.name} task completed`);
+    }
+    /**
+     * Reset all internal state.
+     */
+    reset() {
+        this._readyPromise = new Promise(res => (this._readyResolver = res));
+        this._donePromise = new Promise(res => (this._doneResolver = res));
+        this._exception = null;
+        this._connection = null;
+        this._task = null;
+        this._abortController = new AbortController();
+    }
+    /**
+     * The background task responsible for establishing and maintaining the
+     * connection until it is cancelled.
+     */
+    async connectionTask() {
+        logger.debug(`Running ${this.constructor.name} task`);
+        try {
+            // Establish the connection
+            this._connection = await this.establishConnection();
+            logger.debug(`${this.constructor.name} connected successfully`);
+            // Signal that the connection is ready
+            this._readyResolver();
+            // Keep the task alive until it is cancelled
+            await this.waitForAbort();
+        }
+        catch (err) {
+            this._exception = err;
+            logger.error(`Error in ${this.constructor.name} task: ${err}`);
+            // Ensure the ready promise resolves so that start() can handle the error
+            this._readyResolver();
+        }
+        finally {
+            // Clean up the connection if it was established
+            if (this._connection !== null) {
+                try {
+                    await this.closeConnection(this._connection);
+                }
+                catch (closeErr) {
+                    logger.warn(`Error closing connection in ${this.constructor.name}: ${closeErr}`);
+                }
+                this._connection = null;
+            }
+            // Signal that cleanup is finished
+            this._doneResolver();
+        }
+    }
+    /**
+     * Helper that returns a promise which resolves when the abort signal fires.
+     */
+    async waitForAbort() {
+        return new Promise((_resolve, _reject) => {
+            if (!this._abortController) {
+                return;
+            }
+            const signal = this._abortController.signal;
+            if (signal.aborted) {
+                _resolve();
+                return;
+            }
+            const onAbort = () => {
+                signal.removeEventListener('abort', onAbort);
+                _resolve();
+            };
+            signal.addEventListener('abort', onAbort);
+        });
+    }
+}

package/dist/src/task_managers/index.js

@@ -0,0 +1,4 @@
+export { ConnectionManager } from './base.js';
+export { SseConnectionManager } from './sse.js';
+export { StdioConnectionManager } from './stdio.js';
+export { WebSocketConnectionManager } from './websocket.js';