mcp-use 0.1.15 → 0.1.17

package/README.md

@@ -61,6 +61,9 @@
 npm install mcp-use
 # LangChain.js and your LLM provider (e.g., OpenAI)
 npm install langchain @langchain/openai dotenv
+
+# Optional: Install observability packages for monitoring
+npm install langfuse langfuse-langchain  # For Langfuse observability
 ```
 
 Create a `.env`:

package/dist/src/agents/mcp_agent.d.ts

@@ -1,3 +1,4 @@
+import type { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import type { BaseLanguageModelInterface } from '@langchain/core/language_models/base';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { StructuredToolInterface } from '@langchain/core/tools';
@@ -34,6 +35,8 @@ export declare class MCPAgent {
     private telemetry;
     private modelProvider;
     private modelName;
+    private observabilityManager;
+    private callbacks;
     private isRemote;
     private remoteAgent;
     constructor(options: {
@@ -52,6 +55,7 @@ export declare class MCPAgent {
         verbose?: boolean;
         adapter?: LangChainAdapter;
         serverManagerFactory?: (client: MCPClient) => ServerManager;
+        callbacks?: BaseCallbackHandler[];
         agentId?: string;
         apiKey?: string;
         baseUrl?: string;

package/dist/src/agents/mcp_agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp_agent.d.ts","sourceRoot":"","sources":["../../../src/agents/mcp_agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp_agent.d.ts","sourceRoot":"","sources":["../../../src/agents/mcp_agent.ts"],"names":[],"mappings":"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"}

package/dist/src/agents/mcp_agent.js

@@ -1,11 +1,13 @@
+import { CallbackManager } from '@langchain/core/callbacks/manager';
 import { AIMessage, HumanMessage, SystemMessage, ToolMessage, } from '@langchain/core/messages';
 import { OutputParserException } from '@langchain/core/output_parsers';
 import { ChatPromptTemplate, MessagesPlaceholder, } from '@langchain/core/prompts';
-import { AgentExecutor, createToolCallingAgent, } from 'langchain/agents';
+import { AgentExecutor, createToolCallingAgent } from 'langchain/agents';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { LangChainAdapter } from '../adapters/langchain_adapter.js';
 import { logger } from '../logging.js';
 import { ServerManager } from '../managers/server_manager.js';
+import { ObservabilityManager } from '../observability/index.js';
 import { extractModelInfo, Telemetry } from '../telemetry/index.js';
 import { createSystemMessage } from './prompts/system_prompt_builder.js';
 import { DEFAULT_SYSTEM_PROMPT_TEMPLATE, SERVER_MANAGER_SYSTEM_PROMPT_TEMPLATE } from './prompts/templates.js';
@@ -35,6 +37,9 @@ export class MCPAgent {
     telemetry;
     modelProvider;
     modelName;
+    // Observability support
+    observabilityManager;
+    callbacks = [];
     // Remote agent support
     isRemote = false;
     remoteAgent = null;
@@ -60,6 +65,8 @@ export class MCPAgent {
             this.telemetry = Telemetry.getInstance();
             this.modelProvider = 'remote';
             this.modelName = 'remote-agent';
+            this.observabilityManager = new ObservabilityManager({ customCallbacks: options.callbacks });
+            this.callbacks = [];
             return;
         }
         // Validate requirements for local execution
@@ -105,6 +112,11 @@ export class MCPAgent {
             this.modelProvider = 'unknown';
             this.modelName = 'unknown';
         }
+        // Set up observability callbacks using the ObservabilityManager
+        this.observabilityManager = new ObservabilityManager({
+            customCallbacks: options.callbacks,
+            verbose: this.verbose,
+        });
         // Make getters configurable for test mocking
         Object.defineProperty(this, 'agentExecutor', {
             get: () => this._agentExecutor,
@@ -126,6 +138,12 @@ export class MCPAgent {
             return;
         }
         logger.info('🚀 Initializing MCP agent and connecting to services...');
+        // Initialize observability callbacks
+        this.callbacks = await this.observabilityManager.getCallbacks();
+        const handlerNames = await this.observabilityManager.getHandlerNames();
+        if (handlerNames.length > 0) {
+            logger.info(`📊 Observability enabled with: ${handlerNames.join(', ')}`);
+        }
         // If using server manager, initialize it
         if (this.useServerManager && this.serverManager) {
             await this.serverManager.initialize();
@@ -141,7 +159,7 @@ export class MCPAgent {
             // Standard initialization - if using client, get or create sessions
             if (this.client) {
                 // First try to get existing sessions
-                this.sessions = await this.client.getAllActiveSessions();
+                this.sessions = this.client.getAllActiveSessions();
                 logger.info(`🔌 Found ${Object.keys(this.sessions).length} existing sessions`);
                 // If no active sessions exist, create new ones
                 if (Object.keys(this.sessions).length === 0) {
@@ -210,6 +228,7 @@ export class MCPAgent {
             maxIterations: this.maxSteps,
             verbose: this.verbose,
             returnIntermediateSteps: true,
+            callbacks: this.callbacks,
         });
     }
     getConversationHistory() {
@@ -331,6 +350,22 @@ export class MCPAgent {
             const inputs = { input: query, chat_history: langchainHistory };
             let nameToToolMap = Object.fromEntries(this._tools.map(t => [t.name, t]));
             logger.info(`🏁 Starting agent execution with max_steps=${steps}`);
+            // Create a run manager with our callbacks if we have any - ONCE for the entire execution
+            let runManager;
+            if (this.callbacks?.length > 0) {
+                // Create an async callback manager with our callbacks
+                const callbackManager = new CallbackManager(undefined, {
+                    handlers: this.callbacks,
+                    inheritableHandlers: this.callbacks,
+                });
+                // Create a run manager for this chain execution
+                runManager = await callbackManager.handleChainStart({
+                    name: 'MCPAgent (mcp-use)',
+                    id: ['MCPAgent (mcp-use)'],
+                    lc: 1,
+                    type: 'not_implemented',
+                }, inputs);
+            }
             for (let stepNum = 0; stepNum < steps; stepNum++) {
                 stepsTaken = stepNum + 1;
                 if (this.useServerManager && this.serverManager) {
@@ -352,11 +387,12 @@ export class MCPAgent {
                 logger.info(`👣 Step ${stepNum + 1}/${steps}`);
                 try {
                     logger.debug('Starting agent step execution');
-                    const nextStepOutput = await this._agentExecutor._takeNextStep(nameToToolMap, inputs, intermediateSteps);
-                    // Agent finish handling
-                    if (nextStepOutput.returnValues) {
+                    const nextStepOutput = await this._agentExecutor._takeNextStep(nameToToolMap, inputs, intermediateSteps, runManager);
+                    // Agent finish handling (AgentFinish contains returnValues property)
+                    if ('returnValues' in nextStepOutput) {
                         logger.info(`✅ Agent finished at step ${stepNum + 1}`);
                         result = nextStepOutput.returnValues?.output ?? 'No output generated';
+                        runManager?.handleChainEnd({ output: result });
                         // If structured output is requested, attempt to create it
                         if (outputSchema && structuredLlm) {
                             try {
@@ -433,11 +469,13 @@ export class MCPAgent {
                     if (e instanceof OutputParserException) {
                         logger.error(`❌ Output parsing error during step ${stepNum + 1}: ${e}`);
                         result = `Agent stopped due to a parsing error: ${e}`;
+                        runManager?.handleChainError(result);
                         break;
                     }
                     logger.error(`❌ Error during agent execution step ${stepNum + 1}: ${e}`);
                     console.error(e);
                     result = `Agent stopped due to an error: ${e}`;
+                    runManager?.handleChainError(result);
                     break;
                 }
             }
@@ -445,6 +483,7 @@ export class MCPAgent {
             if (!result) {
                 logger.warn(`⚠️ Agent stopped after reaching max iterations (${steps})`);
                 result = `Agent stopped after reaching the maximum number of steps (${steps}).`;
+                runManager?.handleChainEnd({ output: result });
             }
             logger.info('🎉 Agent execution complete');
             success = true;
@@ -464,7 +503,7 @@ export class MCPAgent {
             const executionTimeMs = Date.now() - startTime;
             let serverCount = 0;
             if (this.client) {
-                serverCount = Object.keys(await this.client.getAllActiveSessions()).length;
+                serverCount = Object.keys(this.client.getAllActiveSessions()).length;
             }
             else if (this.connectors) {
                 serverCount = this.connectors.length;
@@ -507,6 +546,8 @@ export class MCPAgent {
             return;
         }
         logger.info('🔌 Closing MCPAgent resources…');
+        // Shutdown observability handlers (important for serverless)
+        await this.observabilityManager.shutdown();
         try {
             this._agentExecutor = null;
             this._tools = [];
@@ -578,8 +619,12 @@ export class MCPAgent {
             }
             // Prepare inputs
             const inputs = { input: query, chat_history: langchainHistory };
+            logger.info('callbacks', this.callbacks);
             // Stream events from the agent executor
-            const eventStream = agentExecutor.streamEvents(inputs, { version: 'v2' });
+            const eventStream = agentExecutor.streamEvents(inputs, {
+                version: 'v2',
+                callbacks: this.callbacks.length > 0 ? this.callbacks : undefined,
+            });
             // Yield each event
             for await (const event of eventStream) {
                 eventCount++;
@@ -620,7 +665,7 @@ export class MCPAgent {
             const executionTimeMs = Date.now() - startTime;
             let serverCount = 0;
             if (this.client) {
-                serverCount = Object.keys(await this.client.getAllActiveSessions()).length;
+                serverCount = Object.keys(this.client.getAllActiveSessions()).length;
             }
             else if (this.connectors) {
                 serverCount = this.connectors.length;

package/dist/src/observability/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Observability module for MCP-use.
+ *
+ * This module provides centralized observability management for LangChain agents,
+ * supporting multiple platforms like Langfuse and Laminar.
+ */
+import './langfuse.js';
+export { langfuseClient, langfuseHandler, langfuseInitPromise, } from './langfuse.js';
+export { createManager, getDefaultManager, type ObservabilityConfig, ObservabilityManager, } from './manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,eAAe,CAAA;AAGtB,OAAO,EACL,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,oBAAoB,GACrB,MAAM,cAAc,CAAA"}

package/dist/src/observability/index.js

@@ -0,0 +1,12 @@
+/**
+ * Observability module for MCP-use.
+ *
+ * This module provides centralized observability management for LangChain agents,
+ * supporting multiple platforms like Langfuse and Laminar.
+ */
+// Import observability providers - order matters for initialization
+import './langfuse.js';
+// Re-export individual handlers for direct usage if needed
+export { langfuseClient, langfuseHandler, langfuseInitPromise, } from './langfuse.js';
+// Export the manager and its utilities
+export { createManager, getDefaultManager, ObservabilityManager, } from './manager.js';

package/dist/src/observability/langfuse.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Langfuse observability integration for MCP-use.
+ *
+ * This module provides automatic instrumentation and callback handler
+ * for Langfuse observability platform.
+ */
+import type { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+export declare const langfuseHandler: () => BaseCallbackHandler | null;
+export declare const langfuseClient: () => any;
+export declare const langfuseInitPromise: () => Promise<void> | null;
+//# sourceMappingURL=langfuse.d.ts.map

package/dist/src/observability/langfuse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langfuse.d.ts","sourceRoot":"","sources":["../../../src/observability/langfuse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAqIzE,eAAO,MAAM,eAAe,kCAA8B,CAAA;AAC1D,eAAO,MAAM,cAAc,WAA6B,CAAA;AACxD,eAAO,MAAM,mBAAmB,4BAAkC,CAAA"}

package/dist/src/observability/langfuse.js

@@ -0,0 +1,123 @@
+/**
+ * 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() {
+    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
+        class LoggingCallbackHandler extends CallbackHandler {
+            constructor(config) {
+                super(config);
+            }
+            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 handleChainStart(...args) {
+                logger.debug('Langfuse: Chain start intercepted');
+                if (this.verbose) {
+                    logger.debug(`Langfuse: Chain start args: ${JSON.stringify(args)}`);
+                }
+                return super.handleChainStart(...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);
+        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;

package/dist/src/observability/manager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 type { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+export interface ObservabilityConfig {
+    /** Custom callbacks to use instead of defaults */
+    customCallbacks?: BaseCallbackHandler[];
+    /** Whether to enable verbose logging */
+    verbose?: boolean;
+}
+export declare class ObservabilityManager {
+    private customCallbacks?;
+    private availableHandlers;
+    private handlerNames;
+    private initialized;
+    private verbose;
+    constructor(config?: ObservabilityConfig);
+    /**
+     * Collect all available observability handlers from configured platforms.
+     */
+    private collectAvailableHandlers;
+    /**
+     * Get the list of callbacks to use.
+     * @returns List of callbacks - either custom callbacks if provided, or all available observability handlers.
+     */
+    getCallbacks(): Promise<BaseCallbackHandler[]>;
+    /**
+     * Get the names of available handlers.
+     * @returns List of handler names (e.g., ["Langfuse", "Laminar"])
+     */
+    getHandlerNames(): Promise<string[]>;
+    /**
+     * Check if any callbacks are available.
+     * @returns True if callbacks are available, False otherwise.
+     */
+    hasCallbacks(): Promise<boolean>;
+    /**
+     * Add a callback to the custom callbacks list.
+     * @param callback The callback to add.
+     */
+    addCallback(callback: BaseCallbackHandler): void;
+    /**
+     * Clear all custom callbacks.
+     */
+    clearCallbacks(): void;
+    /**
+     * Flush all pending traces to observability platforms.
+     * Important for serverless environments and short-lived processes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown all handlers gracefully (for serverless environments).
+     */
+    shutdown(): Promise<void>;
+    /**
+     * String representation of the ObservabilityManager.
+     */
+    toString(): string;
+}
+/**
+ * Get the default ObservabilityManager instance.
+ * @returns The default ObservabilityManager instance (singleton).
+ */
+export declare function getDefaultManager(): ObservabilityManager;
+/**
+ * Create a new ObservabilityManager instance.
+ * @param config Configuration options
+ * @returns A new ObservabilityManager instance.
+ */
+export declare function createManager(config?: ObservabilityConfig): ObservabilityManager;
+//# sourceMappingURL=manager.d.ts.map

package/dist/src/observability/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/observability/manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAGzE,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAA;IACvC,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAuB;IAC/C,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,GAAE,mBAAwB;IAK5C;;OAEG;YACW,wBAAwB;IA6BtC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAoBpD;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAU1C;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAKtC;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAQhD;;OAEG;IACH,cAAc,IAAI,IAAI;IAKtB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB/B;;OAEG;IACH,QAAQ,IAAI,MAAM;CAOnB;AAKD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,oBAAoB,CAKxD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,mBAAwB,GAAG,oBAAoB,CAEpF"}

package/dist/src/observability/manager.js

@@ -0,0 +1,167 @@
+/**
+ * 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;
+    constructor(config = {}) {
+        this.customCallbacks = config.customCallbacks;
+        this.verbose = config.verbose ?? false;
+    }
+    /**
+     * 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');
+            // Wait for 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 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 (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() {
+        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.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Type definitions for observability module
+ */
+import type { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+/**
+ * Configuration for Langfuse integration
+ */
+export interface LangfuseConfig {
+    publicKey?: string;
+    secretKey?: string;
+    baseUrl?: string;
+    flushAt?: number;
+    flushInterval?: number;
+    release?: string;
+    requestTimeout?: number;
+    enabled?: boolean;
+}
+/**
+ * Configuration for Laminar integration
+ */
+export interface LaminarConfig {
+    projectApiKey?: string;
+    baseUrl?: string;
+}
+/**
+ * Extended callback handler with shutdown support
+ */
+export interface ObservabilityCallbackHandler extends BaseCallbackHandler {
+    /** Optional shutdown method for cleanup */
+    shutdownAsync?: () => Promise<void>;
+    shutdown?: () => void | Promise<void>;
+}
+/**
+ * Observability platform information
+ */
+export interface ObservabilityPlatform {
+    name: string;
+    handler?: ObservabilityCallbackHandler;
+    initialized: boolean;
+    autoInstrumentation?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/observability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/observability/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEzE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA6B,SAAQ,mBAAmB;IACvE,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,4BAA4B,CAAA;IACtC,WAAW,EAAE,OAAO,CAAA;IACpB,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B"}

package/dist/src/observability/types.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-use",
   "type": "module",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "packageManager": "pnpm@10.6.1",
   "description": "A utility library for integrating Model Context Protocol (MCP) with LangChain, Zod, and related tools. Provides helpers for schema conversion, event streaming, and SDK usage.",
   "author": "Zane",
@@ -76,10 +76,22 @@
     "example:add_server": "npm run build && node dist/examples/add_server_tool.js",
     "example:structured": "npm run build && node dist/examples/structured_output.js"
   },
+  "peerDependencies": {
+    "langfuse": "^3.32.0",
+    "langfuse-langchain": "^3.38.4"
+  },
+  "peerDependenciesMeta": {
+    "langfuse": {
+      "optional": true
+    },
+    "langfuse-langchain": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@dmitryrechkin/json-schema-to-zod": "^1.0.1",
     "@langchain/anthropic": "^0.3.14",
-    "@langchain/core": "0.3.58",
+    "@langchain/core": "0.3.71",
     "@langchain/openai": "^0.5.15",
     "@modelcontextprotocol/sdk": "1.12.1",
     "@scarf/scarf": "^1.4.0",