mcp-use 0.1.20 → 0.3.0

package/dist/src/observability/langfuse.js

@@ -1,211 +0,0 @@
-/**
- * Langfuse observability integration for MCP-use.
- *
- * This module provides automatic instrumentation and callback handler
- * for Langfuse observability platform.
- */
-import { config } from 'dotenv';
-import { logger } from '../logging.js';
-config();
-// Check if Langfuse is disabled via environment variable
-const langfuseDisabled = process.env.MCP_USE_LANGFUSE?.toLowerCase() === 'false';
-// Initialize variables - using const with object to avoid linter issues with mutable exports
-const langfuseState = {
-    handler: null,
-    client: null,
-    initPromise: null,
-};
-async function initializeLangfuse(agentId, metadata, metadataProvider, tagsProvider) {
-    try {
-        // Dynamically import to avoid errors if package not installed
-        const langfuseModule = await import('langfuse-langchain').catch(() => null);
-        if (!langfuseModule) {
-            logger.debug('Langfuse package not installed - tracing disabled. Install with: npm install langfuse-langchain');
-            return;
-        }
-        const { CallbackHandler } = langfuseModule;
-        // Create a custom CallbackHandler wrapper to add logging and custom metadata
-        class LoggingCallbackHandler extends CallbackHandler {
-            agentId;
-            metadata;
-            metadataProvider;
-            tagsProvider;
-            verbose;
-            constructor(config, agentId, metadata, metadataProvider, tagsProvider) {
-                super(config);
-                this.agentId = agentId;
-                this.metadata = metadata;
-                this.metadataProvider = metadataProvider;
-                this.tagsProvider = tagsProvider;
-                this.verbose = config?.verbose ?? false;
-            }
-            // Override to add custom metadata to traces
-            async handleChainStart(chain, inputs, runId, parentRunId, tags, metadata, name, kwargs) {
-                logger.debug('Langfuse: Chain start intercepted');
-                // Add custom tags and metadata
-                const customTags = this.getCustomTags();
-                const metadataToAdd = this.getMetadata();
-                // Merge with existing tags and metadata
-                const enhancedTags = [...(tags || []), ...customTags];
-                const enhancedMetadata = { ...(metadata || {}), ...metadataToAdd };
-                if (this.verbose) {
-                    logger.debug(`Langfuse: Chain start with custom tags: ${JSON.stringify(enhancedTags)}`);
-                    logger.debug(`Langfuse: Chain start with metadata: ${JSON.stringify(enhancedMetadata)}`);
-                }
-                return super.handleChainStart(chain, inputs, runId, parentRunId, enhancedTags, enhancedMetadata, name, kwargs);
-            }
-            // Get custom tags based on environment and agent configuration
-            getCustomTags() {
-                const tags = [];
-                // Add environment tag
-                const env = this.getEnvironmentTag();
-                if (env) {
-                    tags.push(`env:${env}`);
-                }
-                // Add agent ID tag if available
-                if (this.agentId) {
-                    tags.push(`agent_id:${this.agentId}`);
-                }
-                // Add tags from provider if available
-                if (this.tagsProvider) {
-                    const providerTags = this.tagsProvider();
-                    if (providerTags && providerTags.length > 0) {
-                        tags.push(...providerTags);
-                    }
-                }
-                return tags;
-            }
-            // Get metadata
-            getMetadata() {
-                const metadata = {};
-                // Add environment metadata
-                const env = this.getEnvironmentTag();
-                if (env) {
-                    metadata.env = env;
-                }
-                // Add agent ID metadata if available
-                if (this.agentId) {
-                    metadata.agent_id = this.agentId;
-                }
-                // Add static metadata if provided
-                if (this.metadata) {
-                    Object.assign(metadata, this.metadata);
-                }
-                // Add dynamic metadata from provider if available
-                if (this.metadataProvider) {
-                    const dynamicMetadata = this.metadataProvider();
-                    if (dynamicMetadata) {
-                        Object.assign(metadata, dynamicMetadata);
-                    }
-                }
-                return metadata;
-            }
-            // Determine environment tag based on MCP_USE_AGENT_ENV
-            getEnvironmentTag() {
-                const agentEnv = process.env.MCP_USE_AGENT_ENV;
-                if (!agentEnv) {
-                    // Default to 'unknown' if environment is not explicitly set
-                    return 'unknown';
-                }
-                const envLower = agentEnv.toLowerCase();
-                if (envLower === 'local' || envLower === 'development') {
-                    return 'local';
-                }
-                else if (envLower === 'production' || envLower === 'prod') {
-                    return 'production';
-                }
-                else if (envLower === 'staging' || envLower === 'stage') {
-                    return 'staging';
-                }
-                else if (envLower === 'hosted' || envLower === 'cloud') {
-                    return 'hosted';
-                }
-                // For any other values, use the value as-is but sanitized
-                return envLower.replace(/[^a-z0-9_-]/g, '_');
-            }
-            async handleLLMStart(...args) {
-                logger.debug('Langfuse: LLM start intercepted');
-                if (this.verbose) {
-                    logger.debug(`Langfuse: LLM start args: ${JSON.stringify(args)}`);
-                }
-                return super.handleLLMStart(...args);
-            }
-            async handleToolStart(...args) {
-                logger.debug('Langfuse: Tool start intercepted');
-                if (this.verbose) {
-                    logger.debug(`Langfuse: Tool start args: ${JSON.stringify(args)}`);
-                }
-                return super.handleToolStart(...args);
-            }
-            async handleRetrieverStart(...args) {
-                logger.debug('Langfuse: Retriever start intercepted');
-                if (this.verbose) {
-                    logger.debug(`Langfuse: Retriever start args: ${JSON.stringify(args)}`);
-                }
-                return super.handleRetrieverStart(...args);
-            }
-            async handleAgentAction(...args) {
-                logger.debug('Langfuse: Agent action intercepted');
-                if (this.verbose) {
-                    logger.debug(`Langfuse: Agent action args: ${JSON.stringify(args)}`);
-                }
-                return super.handleAgentAction(...args);
-            }
-            async handleAgentEnd(...args) {
-                logger.debug('Langfuse: Agent end intercepted');
-                if (this.verbose) {
-                    logger.debug(`Langfuse: Agent end args: ${JSON.stringify(args)}`);
-                }
-                return super.handleAgentEnd(...args);
-            }
-        }
-        // Create the handler with configuration
-        const config = {
-            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-            secretKey: process.env.LANGFUSE_SECRET_KEY,
-            baseUrl: process.env.LANGFUSE_HOST || process.env.LANGFUSE_BASEURL || 'https://cloud.langfuse.com',
-            flushAt: Number.parseInt(process.env.LANGFUSE_FLUSH_AT || '15'),
-            flushInterval: Number.parseInt(process.env.LANGFUSE_FLUSH_INTERVAL || '10000'),
-            release: process.env.LANGFUSE_RELEASE,
-            requestTimeout: Number.parseInt(process.env.LANGFUSE_REQUEST_TIMEOUT || '10000'),
-            enabled: process.env.LANGFUSE_ENABLED !== 'false',
-        };
-        langfuseState.handler = new LoggingCallbackHandler(config, agentId, metadata, metadataProvider, tagsProvider);
-        logger.debug('Langfuse observability initialized successfully with logging enabled');
-        // Also initialize the client for direct usage if needed
-        try {
-            const langfuseCore = await import('langfuse').catch(() => null);
-            if (langfuseCore) {
-                const { Langfuse } = langfuseCore;
-                langfuseState.client = new Langfuse({
-                    publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-                    secretKey: process.env.LANGFUSE_SECRET_KEY,
-                    baseUrl: process.env.LANGFUSE_HOST || 'https://cloud.langfuse.com',
-                });
-                logger.debug('Langfuse client initialized');
-            }
-        }
-        catch (error) {
-            logger.debug(`Langfuse client initialization failed: ${error}`);
-        }
-    }
-    catch (error) {
-        logger.debug(`Langfuse initialization error: ${error}`);
-    }
-}
-// Only initialize if not disabled and required keys are present
-if (langfuseDisabled) {
-    logger.debug('Langfuse tracing disabled via MCP_USE_LANGFUSE environment variable');
-}
-else if (!process.env.LANGFUSE_PUBLIC_KEY || !process.env.LANGFUSE_SECRET_KEY) {
-    logger.debug('Langfuse API keys not found - tracing disabled. Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY to enable');
-}
-else {
-    // Create initialization promise to ensure handlers are ready when needed
-    langfuseState.initPromise = initializeLangfuse();
-}
-// Export getters to access the state
-export const langfuseHandler = () => langfuseState.handler;
-export const langfuseClient = () => langfuseState.client;
-export const langfuseInitPromise = () => langfuseState.initPromise;
-export { initializeLangfuse };

package/dist/src/observability/manager.js

@@ -1,199 +0,0 @@
-/**
- * Observability callbacks manager for MCP-use.
- *
- * This module provides a centralized manager for handling observability callbacks
- * from various platforms (Langfuse, Laminar, etc.) in a clean and extensible way.
- */
-import { logger } from '../logging.js';
-export class ObservabilityManager {
-    customCallbacks;
-    availableHandlers = [];
-    handlerNames = [];
-    initialized = false;
-    verbose;
-    observe;
-    agentId;
-    metadata;
-    metadataProvider;
-    tagsProvider;
-    constructor(config = {}) {
-        this.customCallbacks = config.customCallbacks;
-        this.verbose = config.verbose ?? false;
-        this.observe = config.observe ?? true;
-        this.agentId = config.agentId;
-        this.metadata = config.metadata;
-        this.metadataProvider = config.metadataProvider;
-        this.tagsProvider = config.tagsProvider;
-    }
-    /**
-     * Collect all available observability handlers from configured platforms.
-     */
-    async collectAvailableHandlers() {
-        if (this.initialized) {
-            return;
-        }
-        // Import handlers lazily to avoid circular imports
-        try {
-            const { langfuseHandler, langfuseInitPromise } = await import('./langfuse.js');
-            // If we have an agent ID, metadata, or providers, we need to reinitialize Langfuse
-            if (this.agentId || this.metadata || this.metadataProvider || this.tagsProvider) {
-                // Import the initialization function directly
-                const { initializeLangfuse } = await import('./langfuse.js');
-                await initializeLangfuse(this.agentId, this.metadata, this.metadataProvider, this.tagsProvider);
-                logger.debug(`ObservabilityManager: Reinitialized Langfuse with agent ID: ${this.agentId}, metadata: ${JSON.stringify(this.metadata)}`);
-            }
-            else {
-                // Wait for existing initialization to complete
-                const initPromise = langfuseInitPromise();
-                if (initPromise) {
-                    await initPromise;
-                }
-            }
-            const handler = langfuseHandler();
-            if (handler) {
-                this.availableHandlers.push(handler);
-                this.handlerNames.push('Langfuse');
-                logger.debug('ObservabilityManager: Langfuse handler available');
-            }
-        }
-        catch {
-            logger.debug('ObservabilityManager: Langfuse module not available');
-        }
-        // Future: Add more platforms here...
-        this.initialized = true;
-    }
-    /**
-     * Get the list of callbacks to use.
-     * @returns List of callbacks - either custom callbacks if provided, or all available observability handlers.
-     */
-    async getCallbacks() {
-        // If observability is disabled, return empty array
-        if (!this.observe) {
-            logger.debug('ObservabilityManager: Observability disabled via observe=false');
-            return [];
-        }
-        // If custom callbacks were provided, use those
-        if (this.customCallbacks) {
-            logger.debug(`ObservabilityManager: Using ${this.customCallbacks.length} custom callbacks`);
-            return this.customCallbacks;
-        }
-        // Otherwise, collect and return all available handlers
-        await this.collectAvailableHandlers();
-        if (this.availableHandlers.length > 0) {
-            logger.debug(`ObservabilityManager: Using ${this.availableHandlers.length} handlers`);
-        }
-        else {
-            logger.debug('ObservabilityManager: No callbacks configured');
-        }
-        return this.availableHandlers;
-    }
-    /**
-     * Get the names of available handlers.
-     * @returns List of handler names (e.g., ["Langfuse", "Laminar"])
-     */
-    async getHandlerNames() {
-        // If observability is disabled, return empty array
-        if (!this.observe) {
-            return [];
-        }
-        if (this.customCallbacks) {
-            // For custom callbacks, try to get their class names
-            return this.customCallbacks.map(cb => cb.constructor.name);
-        }
-        await this.collectAvailableHandlers();
-        return this.handlerNames;
-    }
-    /**
-     * Check if any callbacks are available.
-     * @returns True if callbacks are available, False otherwise.
-     */
-    async hasCallbacks() {
-        // If observability is disabled, no callbacks are available
-        if (!this.observe) {
-            return false;
-        }
-        const callbacks = await this.getCallbacks();
-        return callbacks.length > 0;
-    }
-    /**
-     * Add a callback to the custom callbacks list.
-     * @param callback The callback to add.
-     */
-    addCallback(callback) {
-        if (!this.customCallbacks) {
-            this.customCallbacks = [];
-        }
-        this.customCallbacks.push(callback);
-        logger.debug(`ObservabilityManager: Added custom callback: ${callback.constructor.name}`);
-    }
-    /**
-     * Clear all custom callbacks.
-     */
-    clearCallbacks() {
-        this.customCallbacks = [];
-        logger.debug('ObservabilityManager: Cleared all custom callbacks');
-    }
-    /**
-     * Flush all pending traces to observability platforms.
-     * Important for serverless environments and short-lived processes.
-     */
-    async flush() {
-        // Flush Langfuse traces
-        const callbacks = await this.getCallbacks();
-        for (const callback of callbacks) {
-            if ('flushAsync' in callback && typeof callback.flushAsync === 'function') {
-                await callback.flushAsync();
-            }
-        }
-        logger.debug('ObservabilityManager: All traces flushed');
-    }
-    /**
-     * Shutdown all handlers gracefully (for serverless environments).
-     */
-    async shutdown() {
-        // Flush before shutdown
-        await this.flush();
-        // Shutdown other callbacks
-        const callbacks = await this.getCallbacks();
-        for (const callback of callbacks) {
-            // Check if the callback has a shutdown method (like Langfuse)
-            if ('shutdownAsync' in callback && typeof callback.shutdownAsync === 'function') {
-                await callback.shutdownAsync();
-            }
-            else if ('shutdown' in callback && typeof callback.shutdown === 'function') {
-                await callback.shutdown();
-            }
-        }
-        logger.debug('ObservabilityManager: All handlers shutdown');
-    }
-    /**
-     * String representation of the ObservabilityManager.
-     */
-    toString() {
-        const names = this.handlerNames;
-        if (names.length > 0) {
-            return `ObservabilityManager(handlers=${names.join(', ')})`;
-        }
-        return 'ObservabilityManager(no handlers)';
-    }
-}
-// Singleton instance for easy access
-let defaultManager = null;
-/**
- * Get the default ObservabilityManager instance.
- * @returns The default ObservabilityManager instance (singleton).
- */
-export function getDefaultManager() {
-    if (!defaultManager) {
-        defaultManager = new ObservabilityManager();
-    }
-    return defaultManager;
-}
-/**
- * Create a new ObservabilityManager instance.
- * @param config Configuration options
- * @returns A new ObservabilityManager instance.
- */
-export function createManager(config = {}) {
-    return new ObservabilityManager(config);
-}

package/dist/src/observability/types.js

@@ -1,4 +0,0 @@
-/**
- * Type definitions for observability module
- */
-export {};

package/dist/src/session.js

@@ -1,23 +0,0 @@
-export class MCPSession {
-    connector;
-    autoConnect;
-    constructor(connector, autoConnect = true) {
-        this.connector = connector;
-        this.autoConnect = autoConnect;
-    }
-    async connect() {
-        await this.connector.connect();
-    }
-    async disconnect() {
-        await this.connector.disconnect();
-    }
-    async initialize() {
-        if (!this.isConnected && this.autoConnect) {
-            await this.connect();
-        }
-        await this.connector.initialize();
-    }
-    get isConnected() {
-        return this.connector && this.connector.isClientConnected;
-    }
-}

package/dist/src/task_managers/base.js

@@ -1,127 +0,0 @@
-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

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

package/dist/src/task_managers/sse.js

@@ -1,43 +0,0 @@
-import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import { logger } from '../logging.js';
-import { ConnectionManager } from './base.js';
-export class SseConnectionManager extends ConnectionManager {
-    url;
-    opts;
-    _transport = null;
-    /**
-     * Create an SSE connection manager.
-     *
-     * @param url  The SSE endpoint URL.
-     * @param opts Optional transport options (auth, headers, etc.).
-     */
-    constructor(url, opts) {
-        super();
-        this.url = typeof url === 'string' ? new URL(url) : url;
-        this.opts = opts;
-    }
-    /**
-     * Spawn a new `SSEClientTransport` and start the connection.
-     */
-    async establishConnection() {
-        this._transport = new SSEClientTransport(this.url, this.opts);
-        logger.debug(`${this.constructor.name} connected successfully`);
-        return this._transport;
-    }
-    /**
-     * Close the underlying transport and clean up resources.
-     */
-    async closeConnection(_connection) {
-        if (this._transport) {
-            try {
-                await this._transport.close();
-            }
-            catch (e) {
-                logger.warn(`Error closing SSE transport: ${e}`);
-            }
-            finally {
-                this._transport = null;
-            }
-        }
-    }
-}

package/dist/src/task_managers/stdio.js

@@ -1,51 +0,0 @@
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { logger } from '../logging.js';
-import { ConnectionManager } from './base.js';
-export class StdioConnectionManager extends ConnectionManager {
-    serverParams;
-    errlog;
-    _transport = null;
-    /**
-     * Create a new stdio connection manager.
-     *
-     * @param serverParams Parameters for the stdio server process.
-     * @param errlog       Stream to which the server's stderr should be piped.
-     *                     Defaults to `process.stderr`.
-     */
-    constructor(serverParams, errlog = process.stderr) {
-        super();
-        this.serverParams = serverParams;
-        this.errlog = errlog;
-    }
-    /**
-     * Establish the stdio connection by spawning the server process and starting
-     * the SDK's transport. Returns the live `StdioClientTransport` instance.
-     */
-    async establishConnection() {
-        // Instantiate and start the transport
-        this._transport = new StdioClientTransport(this.serverParams);
-        // If stderr was piped, forward it to `errlog` for visibility
-        if (this._transport.stderr && typeof this._transport.stderr.pipe === 'function') {
-            this._transport.stderr.pipe(this.errlog);
-        }
-        logger.debug(`${this.constructor.name} connected successfully`);
-        return this._transport;
-    }
-    /**
-     * Close the stdio connection, making sure the transport cleans up the child
-     * process and associated resources.
-     */
-    async closeConnection(_connection) {
-        if (this._transport) {
-            try {
-                await this._transport.close();
-            }
-            catch (e) {
-                logger.warn(`Error closing stdio transport: ${e}`);
-            }
-            finally {
-                this._transport = null;
-            }
-        }
-    }
-}