mcp-use 0.1.14 → 0.1.16

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/index.d.ts

@@ -1,4 +1,5 @@
 import { MCPAgent } from './src/agents/mcp_agent.js';
+import { RemoteAgent } from './src/agents/remote.js';
 import { MCPClient } from './src/client.js';
 import { loadConfigFile } from './src/config.js';
 import { BaseConnector } from './src/connectors/base.js';
@@ -14,5 +15,5 @@ export * from './src/managers/tools/index.js';
 export { setTelemetrySource, Telemetry } from './src/telemetry/index.js';
 export { AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage } from '@langchain/core/messages';
 export type { StreamEvent } from '@langchain/core/tracers/log_stream';
-export { BaseConnector, HttpConnector, loadConfigFile, Logger, logger, MCPAgent, MCPClient, MCPSession, StdioConnector, WebSocketConnector };
+export { BaseConnector, HttpConnector, loadConfigFile, Logger, logger, MCPAgent, MCPClient, MCPSession, RemoteAgent, StdioConnector, WebSocketConnector };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAElE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAEvE,cAAc,6BAA6B,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAEhE,cAAc,+BAA+B,CAAA;AAG7C,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAGxE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAG3G,YAAY,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAA;AAErE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAElE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAEvE,cAAc,6BAA6B,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAEhE,cAAc,+BAA+B,CAAA;AAG7C,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAGxE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAG3G,YAAY,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAA;AAErE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/index.js

@@ -1,4 +1,5 @@
 import { MCPAgent } from './src/agents/mcp_agent.js';
+import { RemoteAgent } from './src/agents/remote.js';
 import { MCPClient } from './src/client.js';
 import { loadConfigFile } from './src/config.js';
 import { BaseConnector } from './src/connectors/base.js';
@@ -16,4 +17,4 @@ export * from './src/managers/tools/index.js';
 export { setTelemetrySource, Telemetry } from './src/telemetry/index.js';
 // Re-export message classes to ensure a single constructor instance is shared by consumers
 export { AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage } from '@langchain/core/messages';
-export { BaseConnector, HttpConnector, loadConfigFile, Logger, logger, MCPAgent, MCPClient, MCPSession, StdioConnector, WebSocketConnector };
+export { BaseConnector, HttpConnector, loadConfigFile, Logger, logger, MCPAgent, MCPClient, MCPSession, RemoteAgent, StdioConnector, WebSocketConnector };

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

@@ -1,3 +1,4 @@
 export { BaseAgent } from './base.js';
 export { MCPAgent } from './mcp_agent.js';
+export { RemoteAgent } from './remote.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/agents/index.js

@@ -1,2 +1,3 @@
 export { BaseAgent } from './base.js';
 export { MCPAgent } from './mcp_agent.js';
+export { RemoteAgent } from './remote.js';

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';
@@ -10,7 +11,7 @@ import { SystemMessage } from '@langchain/core/messages';
 import { LangChainAdapter } from '../adapters/langchain_adapter.js';
 import { ServerManager } from '../managers/server_manager.js';
 export declare class MCPAgent {
-    private llm;
+    private llm?;
     private client?;
     private connectors;
     private maxSteps;
@@ -34,8 +35,12 @@ export declare class MCPAgent {
     private telemetry;
     private modelProvider;
     private modelName;
+    private observabilityManager;
+    private callbacks;
+    private isRemote;
+    private remoteAgent;
     constructor(options: {
-        llm: BaseLanguageModelInterface;
+        llm?: BaseLanguageModelInterface;
         client?: MCPClient;
         connectors?: BaseConnector[];
         maxSteps?: number;
@@ -50,6 +55,10 @@ export declare class MCPAgent {
         verbose?: boolean;
         adapter?: LangChainAdapter;
         serverManagerFactory?: (client: MCPClient) => ServerManager;
+        callbacks?: BaseCallbackHandler[];
+        agentId?: string;
+        apiKey?: string;
+        baseUrl?: string;
     });
     initialize(): Promise<void>;
     private createSystemMessageFromTools;

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,14 +1,17 @@
+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';
+import { RemoteAgent } from './remote.js';
 export class MCPAgent {
     llm;
     client;
@@ -34,7 +37,42 @@ export class MCPAgent {
     telemetry;
     modelProvider;
     modelName;
+    // Observability support
+    observabilityManager;
+    callbacks = [];
+    // Remote agent support
+    isRemote = false;
+    remoteAgent = null;
     constructor(options) {
+        // Handle remote execution
+        if (options.agentId) {
+            this.isRemote = true;
+            this.remoteAgent = new RemoteAgent({
+                agentId: options.agentId,
+                apiKey: options.apiKey,
+                baseUrl: options.baseUrl,
+            });
+            // Set default values for remote agent
+            this.maxSteps = options.maxSteps ?? 5;
+            this.memoryEnabled = options.memoryEnabled ?? true;
+            this.autoInitialize = options.autoInitialize ?? false;
+            this.verbose = options.verbose ?? false;
+            this.connectors = [];
+            this.disallowedTools = [];
+            this.additionalTools = [];
+            this.useServerManager = false;
+            this.adapter = new LangChainAdapter();
+            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
+        if (!options.llm) {
+            throw new Error('llm is required for local execution. For remote execution, provide agentId instead.');
+        }
         this.llm = options.llm;
         this.client = options.client;
         this.connectors = options.connectors ?? [];
@@ -65,9 +103,20 @@ export class MCPAgent {
         // Initialize telemetry
         this.telemetry = Telemetry.getInstance();
         // Track model info for telemetry
-        const [provider, name] = extractModelInfo(this.llm);
-        this.modelProvider = provider;
-        this.modelName = name;
+        if (this.llm) {
+            const [provider, name] = extractModelInfo(this.llm);
+            this.modelProvider = provider;
+            this.modelName = name;
+        }
+        else {
+            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,
@@ -83,7 +132,18 @@ export class MCPAgent {
         });
     }
     async initialize() {
+        // Skip initialization for remote agents
+        if (this.isRemote) {
+            this._initialized = true;
+            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();
@@ -99,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) {
@@ -147,6 +207,9 @@ export class MCPAgent {
         }
     }
     createAgent() {
+        if (!this.llm) {
+            throw new Error('LLM is required to create agent');
+        }
         const systemContent = this.systemMessage?.content ?? 'You are a helpful assistant.';
         const prompt = ChatPromptTemplate.fromMessages([
             ['system', systemContent],
@@ -165,6 +228,7 @@ export class MCPAgent {
             maxIterations: this.maxSteps,
             verbose: this.verbose,
             returnIntermediateSteps: true,
+            callbacks: this.callbacks,
         });
     }
     getConversationHistory() {
@@ -213,6 +277,10 @@ export class MCPAgent {
         }
     }
     async run(query, maxSteps, manageConnector, externalHistory, outputSchema) {
+        // Delegate to remote agent if in remote mode
+        if (this.isRemote && this.remoteAgent) {
+            return this.remoteAgent.run(query, maxSteps, manageConnector, externalHistory, outputSchema);
+        }
         const generator = this.stream(query, maxSteps, manageConnector, externalHistory, outputSchema);
         return this._consumeAndReturn(generator);
     }
@@ -221,6 +289,11 @@ export class MCPAgent {
      * If outputSchema is provided, returns structured output of type T.
      */
     async *stream(query, maxSteps, manageConnector = true, externalHistory, outputSchema) {
+        // Delegate to remote agent if in remote mode
+        if (this.isRemote && this.remoteAgent) {
+            const result = await this.remoteAgent.run(query, maxSteps, manageConnector, externalHistory, outputSchema);
+            return result;
+        }
         let result = '';
         let initializedHere = false;
         const startTime = Date.now();
@@ -234,13 +307,16 @@ export class MCPAgent {
             query = this._enhanceQueryWithSchema(query, outputSchema);
             logger.debug(`🔄 Structured output requested, schema: ${JSON.stringify(zodToJsonSchema(outputSchema), null, 2)}`);
             // Check if withStructuredOutput method exists
-            if ('withStructuredOutput' in this.llm && typeof this.llm.withStructuredOutput === 'function') {
+            if (this.llm && 'withStructuredOutput' in this.llm && typeof this.llm.withStructuredOutput === 'function') {
                 structuredLlm = this.llm.withStructuredOutput(outputSchema);
             }
-            else {
+            else if (this.llm) {
                 // Fallback: use the same LLM but we'll handle structure in our helper method
                 structuredLlm = this.llm;
             }
+            else {
+                throw new Error('LLM is required for structured output');
+            }
             schemaDescription = JSON.stringify(zodToJsonSchema(outputSchema), null, 2);
         }
         try {
@@ -274,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) {
@@ -295,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 {
@@ -376,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;
                 }
             }
@@ -388,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;
@@ -407,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;
@@ -444,7 +540,14 @@ export class MCPAgent {
         }
     }
     async close() {
+        // Delegate to remote agent if in remote mode
+        if (this.isRemote && this.remoteAgent) {
+            await this.remoteAgent.close();
+            return;
+        }
         logger.info('🔌 Closing MCPAgent resources…');
+        // Shutdown observability handlers (important for serverless)
+        await this.observabilityManager.shutdown();
         try {
             this._agentExecutor = null;
             this._tools = [];
@@ -516,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++;
@@ -558,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/agents/remote.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Remote agent implementation for executing agents via API.
+ */
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ZodSchema } from 'zod';
+export declare class RemoteAgent {
+    private agentId;
+    private apiKey;
+    private baseUrl;
+    private chatId;
+    constructor(options: {
+        agentId: string;
+        apiKey?: string;
+        baseUrl?: string;
+    });
+    private pydanticToJsonSchema;
+    private parseStructuredResponse;
+    private createChatSession;
+    run<T = string>(query: string, maxSteps?: number, manageConnector?: boolean, externalHistory?: BaseMessage[], outputSchema?: ZodSchema<T>): Promise<T>;
+    stream<T = string>(query: string, maxSteps?: number, manageConnector?: boolean, externalHistory?: BaseMessage[], outputSchema?: ZodSchema<T>): AsyncGenerator<any, T, void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=remote.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../../src/agents/remote.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAQpC,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,MAAM,CAAsB;gBAExB,OAAO,EAAE;QACnB,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB;IAgBD,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,uBAAuB;YAoDjB,iBAAiB;IAmDlB,GAAG,CAAC,CAAC,GAAG,MAAM,EACzB,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,OAAO,EACzB,eAAe,CAAC,EAAE,WAAW,EAAE,EAC/B,YAAY,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC;IAwJC,MAAM,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,OAAO,EACzB,eAAe,CAAC,EAAE,WAAW,EAAE,EAC/B,YAAY,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC;IASlB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAUpC"}

package/dist/src/agents/remote.js

@@ -0,0 +1,264 @@
+/**
+ * Remote agent implementation for executing agents via API.
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { logger } from '../logging.js';
+// API endpoint constants
+const API_CHATS_ENDPOINT = '/api/v1/chats';
+const API_CHAT_EXECUTE_ENDPOINT = '/api/v1/chats/{chat_id}/execute';
+export class RemoteAgent {
+    agentId;
+    apiKey;
+    baseUrl;
+    chatId = null;
+    constructor(options) {
+        this.agentId = options.agentId;
+        this.baseUrl = options.baseUrl ?? 'https://cloud.mcp-use.com';
+        // Handle API key validation
+        const apiKey = options.apiKey ?? process.env.MCP_USE_API_KEY;
+        if (!apiKey) {
+            throw new Error('API key is required for remote execution. '
+                + 'Please provide it as a parameter or set the MCP_USE_API_KEY environment variable. '
+                + 'You can get an API key from https://cloud.mcp-use.com');
+        }
+        this.apiKey = apiKey;
+    }
+    pydanticToJsonSchema(schema) {
+        /**
+         * Convert a Zod schema to JSON schema for API transmission.
+         */
+        return zodToJsonSchema(schema);
+    }
+    parseStructuredResponse(responseData, outputSchema) {
+        /**
+         * Parse the API response into the structured output format.
+         */
+        let resultData;
+        // Handle different response formats
+        if (typeof responseData === 'object' && responseData !== null) {
+            if ('result' in responseData) {
+                const outerResult = responseData.result;
+                // Check if this is a nested result structure (agent execution response)
+                if (typeof outerResult === 'object' && outerResult !== null && 'result' in outerResult) {
+                    // Extract the actual structured output from the nested result
+                    resultData = outerResult.result;
+                }
+                else {
+                    // Use the outer result directly
+                    resultData = outerResult;
+                }
+            }
+            else {
+                resultData = responseData;
+            }
+        }
+        else if (typeof responseData === 'string') {
+            try {
+                resultData = JSON.parse(responseData);
+            }
+            catch {
+                // If it's not valid JSON, try to create the model from the string content
+                resultData = { content: responseData };
+            }
+        }
+        else {
+            resultData = responseData;
+        }
+        // Parse into the Zod schema
+        try {
+            return outputSchema.parse(resultData);
+        }
+        catch (e) {
+            logger.warn(`Failed to parse structured output: ${e}`);
+            // Fallback: try to parse it as raw content if the schema has a content field
+            const schemaShape = outputSchema._def?.shape();
+            if (schemaShape && 'content' in schemaShape) {
+                return outputSchema.parse({ content: String(resultData) });
+            }
+            throw e;
+        }
+    }
+    async createChatSession() {
+        /**
+         * Create a persistent chat session for the agent.
+         */
+        const chatPayload = {
+            title: `Remote Agent Session - ${this.agentId}`,
+            agent_id: this.agentId,
+            type: 'agent_execution',
+        };
+        const headers = {
+            'Content-Type': 'application/json',
+            'x-api-key': this.apiKey,
+        };
+        const chatUrl = `${this.baseUrl}${API_CHATS_ENDPOINT}`;
+        logger.info(`📝 Creating chat session for agent ${this.agentId}`);
+        try {
+            const response = await fetch(chatUrl, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(chatPayload),
+            });
+            if (!response.ok) {
+                const responseText = await response.text();
+                const statusCode = response.status;
+                if (statusCode === 404) {
+                    throw new Error(`Agent not found: Agent '${this.agentId}' does not exist or you don't have access to it. `
+                        + 'Please verify the agent ID and ensure it exists in your account.');
+                }
+                throw new Error(`Failed to create chat session: ${statusCode} - ${responseText}`);
+            }
+            const chatData = await response.json();
+            const chatId = chatData.id;
+            logger.info(`✅ Chat session created: ${chatId}`);
+            return chatId;
+        }
+        catch (e) {
+            if (e instanceof Error) {
+                throw new TypeError(`Failed to create chat session: ${e.message}`);
+            }
+            throw new Error(`Failed to create chat session: ${String(e)}`);
+        }
+    }
+    async run(query, maxSteps, manageConnector, externalHistory, outputSchema) {
+        /**
+         * Run a query on the remote agent.
+         */
+        if (externalHistory !== undefined) {
+            logger.warn('External history is not yet supported for remote execution');
+        }
+        try {
+            logger.info(`🌐 Executing query on remote agent ${this.agentId}`);
+            // Step 1: Create a chat session for this agent (only if we don't have one)
+            if (this.chatId === null) {
+                this.chatId = await this.createChatSession();
+            }
+            const chatId = this.chatId;
+            // Step 2: Execute the agent within the chat context
+            const executionPayload = {
+                query,
+                max_steps: maxSteps ?? 10,
+            };
+            // Add structured output schema if provided
+            if (outputSchema) {
+                executionPayload.output_schema = this.pydanticToJsonSchema(outputSchema);
+                logger.info(`🔧 Using structured output with schema`);
+            }
+            const headers = {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+            };
+            const executionUrl = `${this.baseUrl}${API_CHAT_EXECUTE_ENDPOINT.replace('{chat_id}', chatId)}`;
+            logger.info(`🚀 Executing agent in chat ${chatId}`);
+            const response = await fetch(executionUrl, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(executionPayload),
+                signal: AbortSignal.timeout(300000), // 5 minute timeout
+            });
+            if (!response.ok) {
+                const responseText = await response.text();
+                const statusCode = response.status;
+                // Provide specific error messages based on status code
+                if (statusCode === 401) {
+                    logger.error(`❌ Authentication failed: ${responseText}`);
+                    throw new Error('Authentication failed: Invalid or missing API key. '
+                        + 'Please check your API key and ensure the MCP_USE_API_KEY environment variable is set correctly.');
+                }
+                else if (statusCode === 403) {
+                    logger.error(`❌ Access forbidden: ${responseText}`);
+                    throw new Error(`Access denied: You don't have permission to execute agent '${this.agentId}'. `
+                        + 'Check if the agent exists and you have the necessary permissions.');
+                }
+                else if (statusCode === 404) {
+                    logger.error(`❌ Agent not found: ${responseText}`);
+                    throw new Error(`Agent not found: Agent '${this.agentId}' does not exist or you don't have access to it. `
+                        + 'Please verify the agent ID and ensure it exists in your account.');
+                }
+                else if (statusCode === 422) {
+                    logger.error(`❌ Validation error: ${responseText}`);
+                    throw new Error(`Request validation failed: ${responseText}. `
+                        + 'Please check your query parameters and output schema format.');
+                }
+                else if (statusCode === 500) {
+                    logger.error(`❌ Server error: ${responseText}`);
+                    throw new Error('Internal server error occurred during agent execution. '
+                        + 'Please try again later or contact support if the issue persists.');
+                }
+                else {
+                    logger.error(`❌ Remote execution failed with status ${statusCode}: ${responseText}`);
+                    throw new Error(`Remote agent execution failed: ${statusCode} - ${responseText}`);
+                }
+            }
+            const result = await response.json();
+            logger.info(`🔧 Response: ${JSON.stringify(result)}`);
+            logger.info('✅ Remote execution completed successfully');
+            // Check for error responses (even with 200 status)
+            if (typeof result === 'object' && result !== null) {
+                // Check for actual error conditions (not just presence of error field)
+                if (result.status === 'error' || result.error !== null) {
+                    const errorMsg = result.error ?? String(result);
+                    logger.error(`❌ Remote agent execution failed: ${errorMsg}`);
+                    throw new Error(`Remote agent execution failed: ${errorMsg}`);
+                }
+                // Check if the response indicates agent initialization failure
+                if (String(result).includes('failed to initialize')) {
+                    logger.error(`❌ Agent initialization failed: ${result}`);
+                    throw new Error('Agent initialization failed on remote server. '
+                        + 'This usually indicates:\n'
+                        + '• Invalid agent configuration (LLM model, system prompt)\n'
+                        + '• Missing or invalid MCP server configurations\n'
+                        + '• Network connectivity issues with MCP servers\n'
+                        + '• Missing environment variables or credentials\n'
+                        + `Raw error: ${result}`);
+                }
+            }
+            // Handle structured output
+            if (outputSchema) {
+                return this.parseStructuredResponse(result, outputSchema);
+            }
+            // Regular string output
+            if (typeof result === 'object' && result !== null && 'result' in result) {
+                return result.result;
+            }
+            else if (typeof result === 'string') {
+                return result;
+            }
+            else {
+                return String(result);
+            }
+        }
+        catch (e) {
+            if (e instanceof Error) {
+                // Check for specific error types
+                if (e.name === 'AbortError') {
+                    logger.error(`❌ Remote execution timed out: ${e}`);
+                    throw new Error('Remote agent execution timed out. The server may be overloaded or the query is taking too long to '
+                        + 'process. Try again or use a simpler query.');
+                }
+                logger.error(`❌ Remote execution error: ${e}`);
+                throw new Error(`Remote agent execution failed: ${e.message}`);
+            }
+            logger.error(`❌ Remote execution error: ${e}`);
+            throw new Error(`Remote agent execution failed: ${String(e)}`);
+        }
+    }
+    async *stream(query, maxSteps, manageConnector, externalHistory, outputSchema) {
+        /**
+         * Stream implementation for remote agent - currently just wraps run.
+         * In the future, this could be enhanced to support actual streaming from the API.
+         */
+        const result = await this.run(query, maxSteps, manageConnector, externalHistory, outputSchema);
+        return result;
+    }
+    async close() {
+        /**
+         * Close the remote agent connection.
+         */
+        logger.info('🔌 Remote agent client closed');
+        // In the future, we might want to delete the chat session here
+        // if (this.chatId) {
+        //   await this.deleteChatSession(this.chatId)
+        // }
+    }
+}

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.14",
+  "version": "0.1.16",
   "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,6 +76,18 @@
     "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",
@@ -111,10 +123,8 @@
   },
   "lint-staged": {
     "*.{js,ts}": [
-      "npm run lint"
-    ],
-    "**/*.ts": [
-      "npm run build"
+      "eslint --fix",
+      "eslint"
     ]
   }
 }