mcp-use 0.1.17 → 0.1.19

package/README.md

@@ -44,6 +44,7 @@
 | 🧩 **Multi-Server Support**     | Use multiple MCP servers in one agent.                                     |
 | 🛡️ **Tool Restrictions**        | Restrict unsafe tools like filesystem or network.                          |
 | 🔧 **Custom Agents**            | Build your own agents with LangChain.js adapter or implement new adapters. |
+| 📊 **Observability**            | Built-in support for Langfuse with dynamic metadata and tag handling.      |
 
 ---
 
@@ -295,6 +296,77 @@ export function Chat() {
 
 ---
 
+## 📊 Observability & Monitoring
+
+mcp-use-ts provides built-in observability support through the `ObservabilityManager`, with integration for Langfuse and other observability platforms.
+
+#### To enable observability simply configure Environment Variables
+
+```ini
+# .env
+LANGFUSE_PUBLIC_KEY=pk-lf-your-public-key
+LANGFUSE_SECRET_KEY=sk-lf-your-secret-key
+LANGFUSE_HOST=https://cloud.langfuse.com  # or your self-hosted instance
+```
+
+### Advanced Observability Features
+
+#### Dynamic Metadata and Tags
+
+```ts
+// Set custom metadata for the current execution
+agent.setMetadata({
+  userId: 'user123',
+  sessionId: 'session456',
+  environment: 'production'
+})
+
+// Set tags for better organization
+agent.setTags(['production', 'user-query', 'tool-discovery'])
+
+// Run query with metadata and tags
+const result = await agent.run('Search for restaurants in Tokyo')
+```
+
+#### Monitoring Agent Performance
+
+```ts
+// Stream events for detailed monitoring
+const eventStream = agent.streamEvents('Complex multi-step query')
+
+for await (const event of eventStream) {
+  // Monitor different event types
+  switch (event.event) {
+    case 'on_llm_start':
+      console.log('LLM call started:', event.data)
+      break
+    case 'on_tool_start':
+      console.log('Tool execution started:', event.name, event.data)
+      break
+    case 'on_tool_end':
+      console.log('Tool execution completed:', event.name, event.data)
+      break
+    case 'on_chain_end':
+      console.log('Agent execution completed:', event.data)
+      break
+  }
+}
+```
+
+### Disabling Observability
+
+To disable observability, either remove langfuse env variables or
+
+```ts
+const agent = new MCPAgent({
+  llm,
+  client,
+  observe: false
+})
+```
+
+---
+
 ## 📂 Configuration File
 
 You can store servers in a JSON file:

package/dist/examples/observability.d.ts

@@ -0,0 +1,6 @@
+/**
+ * This example shows how to test the different functionalities of MCPs using the MCP server from
+ * anthropic.
+ */
+export {};
+//# sourceMappingURL=observability.d.ts.map

package/dist/examples/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../examples/observability.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/examples/observability.js

@@ -0,0 +1,50 @@
+/**
+ * This example shows how to test the different functionalities of MCPs using the MCP server from
+ * anthropic.
+ */
+import { ChatOpenAI } from '@langchain/openai';
+import { config } from 'dotenv';
+import { Logger, MCPAgent, MCPClient } from '../index.js';
+// Load environment variables from .env file
+config();
+// Enable debug logging to see observability messages
+Logger.setDebug(true);
+const everythingServer = {
+    mcpServers: { everything: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-everything'] } },
+};
+async function main() {
+    console.log('🚀 Starting MCP Observability example with Langfuse tracing...');
+    console.log('📊 Environment variables:');
+    console.log(`   LANGFUSE_PUBLIC_KEY: ${process.env.LANGFUSE_PUBLIC_KEY ? '✅ Set' : '❌ Missing'}`);
+    console.log(`   LANGFUSE_SECRET_KEY: ${process.env.LANGFUSE_SECRET_KEY ? '✅ Set' : '❌ Missing'}`);
+    console.log(`   LANGFUSE_HOST: ${process.env.LANGFUSE_HOST || 'Not set'}`);
+    console.log(`   MCP_USE_LANGFUSE: ${process.env.MCP_USE_LANGFUSE || 'Not set'}`);
+    const client = new MCPClient(everythingServer);
+    const llm = new ChatOpenAI({ model: 'gpt-4o', temperature: 0 });
+    const agent = new MCPAgent({
+        llm,
+        client,
+        maxSteps: 30,
+    });
+    // console.log('🔧 Initializing agent...')
+    // await agent.initialize()
+    // Set additional metadata for testing (Optional)
+    agent.setMetadata({
+        agent_id: 'test-agent-123',
+        test_run: true,
+        example: 'mcp_observability',
+    });
+    agent.setTags(['test-tag-1', 'test-tag-2']);
+    console.log('💬 Running agent query...');
+    const result = await agent.run(`Hello, you are a tester can you please answer the follwing questions:
+- Which resources do you have access to?
+- Which prompts do you have access to?
+- Which tools do you have access to?`, 30);
+    console.log(`\n✅ Result: ${result}`);
+    // console.log('🧹 Closing agent...')
+    // await agent.close()
+    // console.log('🎉 Example completed! Check your Langfuse dashboard for traces.')
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch(console.error);
+}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { BaseAdapter, LangChainAdapter } from './src/adapters/index.js';
 export * from './src/agents/utils/index.js';
 export { ServerManager } from './src/managers/server_manager.js';
 export * from './src/managers/tools/index.js';
+export { type ObservabilityConfig, ObservabilityManager } from './src/observability/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';

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,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"}
+{"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,KAAK,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAA;AAG7F,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

@@ -13,6 +13,8 @@ export { BaseAdapter, LangChainAdapter } from './src/adapters/index.js';
 export * from './src/agents/utils/index.js';
 export { ServerManager } from './src/managers/server_manager.js';
 export * from './src/managers/tools/index.js';
+// Export observability utilities
+export { ObservabilityManager } from './src/observability/index.js';
 // Export telemetry utilities
 export { setTelemetrySource, Telemetry } from './src/telemetry/index.js';
 // Re-export message classes to ensure a single constructor instance is shared by consumers

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

@@ -21,6 +21,7 @@ export declare class MCPAgent {
     private additionalTools;
     private useServerManager;
     private verbose;
+    private observe;
     private systemPrompt?;
     private systemPromptTemplateOverride?;
     private additionalInstructions?;
@@ -37,6 +38,8 @@ export declare class MCPAgent {
     private modelName;
     private observabilityManager;
     private callbacks;
+    private metadata;
+    private tags;
     private isRemote;
     private remoteAgent;
     constructor(options: {
@@ -53,6 +56,7 @@ export declare class MCPAgent {
         additionalTools?: StructuredToolInterface[];
         useServerManager?: boolean;
         verbose?: boolean;
+        observe?: boolean;
         adapter?: LangChainAdapter;
         serverManagerFactory?: (client: MCPClient) => ServerManager;
         callbacks?: BaseCallbackHandler[];
@@ -70,6 +74,42 @@ export declare class MCPAgent {
     setSystemMessage(message: string): void;
     setDisallowedTools(disallowedTools: string[]): void;
     getDisallowedTools(): string[];
+    /**
+     * Set metadata for observability traces
+     * @param newMetadata - Key-value pairs to add to metadata. Keys should be strings, values should be serializable.
+     */
+    setMetadata(newMetadata: Record<string, any>): void;
+    /**
+     * Get current metadata
+     * @returns A copy of the current metadata object
+     */
+    getMetadata(): Record<string, any>;
+    /**
+     * Set tags for observability traces
+     * @param newTags - Array of tag strings to add. Duplicates will be automatically removed.
+     */
+    setTags(newTags: string[]): void;
+    /**
+     * Get current tags
+     * @returns A copy of the current tags array
+     */
+    getTags(): string[];
+    /**
+     * Sanitize metadata to ensure compatibility with observability platforms
+     * @param metadata - Raw metadata object
+     * @returns Sanitized metadata object
+     */
+    private sanitizeMetadata;
+    /**
+     * Sanitize tags to ensure compatibility with observability platforms
+     * @param tags - Array of tag strings
+     * @returns Array of sanitized tag strings
+     */
+    private sanitizeTags;
+    /**
+     * Get MCP server information for observability metadata
+     */
+    private getMCPServerInfo;
     private _consumeAndReturn;
     /**
      * Runs the agent and returns a promise for the final result.

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":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEzE,OAAO,KAAK,EAAE,0BAA0B,EAAqB,MAAM,sCAAsC,CAAA;AAEzG,OAAO,KAAK,EACV,WAAW,EACZ,MAAM,0BAA0B,CAAA;AACjC,OAAO,KAAK,EAAE,uBAAuB,EAAiB,MAAM,uBAAuB,CAAA;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAA;AACrE,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAG1D,OAAO,EAGL,aAAa,EAEd,MAAM,0BAA0B,CAAA;AAQjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAA;AAEnE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAO7D,qBAAa,QAAQ;IACnB,OAAO,CAAC,GAAG,CAAC,CAA4B;IACxC,OAAO,CAAC,MAAM,CAAC,CAAW;IAC1B,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,4BAA4B,CAAC,CAAe;IACpD,OAAO,CAAC,sBAAsB,CAAC,CAAe;IAE9C,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,mBAAmB,CAAoB;IAC/C,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,SAAS,CAAQ;IAGzB,OAAO,CAAC,oBAAoB,CAAsB;IAClD,OAAO,CAAC,SAAS,CAA4B;IAG7C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,WAAW,CAA2B;gBAElC,OAAO,EAAE;QACnB,GAAG,CAAC,EAAE,0BAA0B,CAAA;QAChC,MAAM,CAAC,EAAE,SAAS,CAAA;QAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;QAC5B,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,cAAc,CAAC,EAAE,OAAO,CAAA;QACxB,aAAa,CAAC,EAAE,OAAO,CAAA;QACvB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QAC5B,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACpC,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACtC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;QAC1B,eAAe,CAAC,EAAE,uBAAuB,EAAE,CAAA;QAC3C,gBAAgB,CAAC,EAAE,OAAO,CAAA;QAC1B,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,OAAO,CAAC,EAAE,gBAAgB,CAAA;QAC1B,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,aAAa,CAAA;QAC3D,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAA;QAEjC,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB;IAiGY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YA8E1B,4BAA4B;IAuB1C,OAAO,CAAC,WAAW;IA8BZ,sBAAsB,IAAI,WAAW,EAAE;IAIvC,wBAAwB,IAAI,IAAI;IAIvC,OAAO,CAAC,YAAY;IAKb,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAIxC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAavC,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI;IAQnD,kBAAkB,IAAI,MAAM,EAAE;YAIvB,iBAAiB;IAc/B;;OAEG;IACU,GAAG,CACd,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,OAAO,EACzB,eAAe,CAAC,EAAE,WAAW,EAAE,GAC9B,OAAO,CAAC,MAAM,CAAC;IAElB;;OAEG;IACU,GAAG,CAAC,CAAC,EAChB,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;IAwBb;;;OAGG;IACW,MAAM,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,eAAe,UAAO,EACtB,eAAe,CAAC,EAAE,WAAW,EAAE,EAC/B,YAAY,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC;IA0SjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCnC;;;OAGG;IACW,YAAY,CACxB,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,eAAe,UAAO,EACtB,eAAe,CAAC,EAAE,WAAW,EAAE,GAC9B,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC;IAqJ1C;;OAEG;YACW,wBAAwB;IAqFtC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAgCjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAuBhC"}
+{"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

@@ -23,6 +23,7 @@ export class MCPAgent {
     additionalTools;
     useServerManager;
     verbose;
+    observe;
     systemPrompt;
     systemPromptTemplateOverride;
     additionalInstructions;
@@ -40,6 +41,8 @@ export class MCPAgent {
     // Observability support
     observabilityManager;
     callbacks = [];
+    metadata = {};
+    tags = [];
     // Remote agent support
     isRemote = false;
     remoteAgent = null;
@@ -57,6 +60,7 @@ export class MCPAgent {
             this.memoryEnabled = options.memoryEnabled ?? true;
             this.autoInitialize = options.autoInitialize ?? false;
             this.verbose = options.verbose ?? false;
+            this.observe = options.observe ?? true;
             this.connectors = [];
             this.disallowedTools = [];
             this.additionalTools = [];
@@ -65,7 +69,10 @@ export class MCPAgent {
             this.telemetry = Telemetry.getInstance();
             this.modelProvider = 'remote';
             this.modelName = 'remote-agent';
-            this.observabilityManager = new ObservabilityManager({ customCallbacks: options.callbacks });
+            this.observabilityManager = new ObservabilityManager({
+                customCallbacks: options.callbacks,
+                agentId: options.agentId,
+            });
             this.callbacks = [];
             return;
         }
@@ -86,6 +93,7 @@ export class MCPAgent {
         this.additionalTools = options.additionalTools ?? [];
         this.useServerManager = options.useServerManager ?? false;
         this.verbose = options.verbose ?? false;
+        this.observe = options.observe ?? true;
         if (!this.client && this.connectors.length === 0) {
             throw new Error('Either \'client\' or at least one \'connector\' must be provided.');
         }
@@ -116,6 +124,10 @@ export class MCPAgent {
         this.observabilityManager = new ObservabilityManager({
             customCallbacks: options.callbacks,
             verbose: this.verbose,
+            observe: this.observe,
+            agentId: options.agentId,
+            metadataProvider: () => this.getMetadata(),
+            tagsProvider: () => this.getTags(),
         });
         // Make getters configurable for test mocking
         Object.defineProperty(this, 'agentExecutor', {
@@ -193,6 +205,12 @@ export class MCPAgent {
         // Create the agent executor and mark initialized
         this._agentExecutor = this.createAgent();
         this._initialized = true;
+        // Add MCP server information to observability metadata
+        const mcpServerInfo = this.getMCPServerInfo();
+        if (Object.keys(mcpServerInfo).length > 0) {
+            this.setMetadata(mcpServerInfo);
+            logger.debug(`MCP server info added to metadata: ${JSON.stringify(mcpServerInfo)}`);
+        }
         logger.info('✨ Agent initialization complete');
     }
     async createSystemMessageFromTools(tools) {
@@ -265,6 +283,161 @@ export class MCPAgent {
     getDisallowedTools() {
         return this.disallowedTools;
     }
+    /**
+     * Set metadata for observability traces
+     * @param newMetadata - Key-value pairs to add to metadata. Keys should be strings, values should be serializable.
+     */
+    setMetadata(newMetadata) {
+        // Validate and sanitize metadata
+        const sanitizedMetadata = this.sanitizeMetadata(newMetadata);
+        // Merge with existing metadata instead of replacing it
+        this.metadata = { ...this.metadata, ...sanitizedMetadata };
+        logger.debug(`Metadata set: ${JSON.stringify(this.metadata)}`);
+    }
+    /**
+     * Get current metadata
+     * @returns A copy of the current metadata object
+     */
+    getMetadata() {
+        return { ...this.metadata };
+    }
+    /**
+     * Set tags for observability traces
+     * @param newTags - Array of tag strings to add. Duplicates will be automatically removed.
+     */
+    setTags(newTags) {
+        // Validate and sanitize tags
+        const sanitizedTags = this.sanitizeTags(newTags);
+        this.tags = [...new Set([...this.tags, ...sanitizedTags])]; // Remove duplicates
+        logger.debug(`Tags set: ${JSON.stringify(this.tags)}`);
+    }
+    /**
+     * Get current tags
+     * @returns A copy of the current tags array
+     */
+    getTags() {
+        return [...this.tags];
+    }
+    /**
+     * Sanitize metadata to ensure compatibility with observability platforms
+     * @param metadata - Raw metadata object
+     * @returns Sanitized metadata object
+     */
+    sanitizeMetadata(metadata) {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(metadata)) {
+            // Validate key
+            if (typeof key !== 'string' || key.length === 0) {
+                logger.warn(`Invalid metadata key: ${key}. Skipping.`);
+                continue;
+            }
+            // Sanitize key (remove special characters that might cause issues)
+            const sanitizedKey = key.replace(/[^\w-]/g, '_');
+            // Validate and sanitize value
+            if (value === null || value === undefined) {
+                sanitized[sanitizedKey] = value;
+            }
+            else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                sanitized[sanitizedKey] = value;
+            }
+            else if (Array.isArray(value)) {
+                // Only allow arrays of primitives
+                const sanitizedArray = value.filter(item => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean');
+                if (sanitizedArray.length > 0) {
+                    sanitized[sanitizedKey] = sanitizedArray;
+                }
+            }
+            else if (typeof value === 'object') {
+                // Try to serialize objects, but limit depth to prevent circular references
+                try {
+                    const serialized = JSON.stringify(value);
+                    if (serialized.length > 1000) {
+                        logger.warn(`Metadata value for key '${sanitizedKey}' is too large. Truncating.`);
+                        sanitized[sanitizedKey] = `${serialized.substring(0, 1000)}...`;
+                    }
+                    else {
+                        sanitized[sanitizedKey] = value;
+                    }
+                }
+                catch (error) {
+                    logger.warn(`Failed to serialize metadata value for key '${sanitizedKey}': ${error}. Skipping.`);
+                }
+            }
+            else {
+                logger.warn(`Unsupported metadata value type for key '${sanitizedKey}': ${typeof value}. Skipping.`);
+            }
+        }
+        return sanitized;
+    }
+    /**
+     * Sanitize tags to ensure compatibility with observability platforms
+     * @param tags - Array of tag strings
+     * @returns Array of sanitized tag strings
+     */
+    sanitizeTags(tags) {
+        return tags
+            .filter(tag => typeof tag === 'string' && tag.length > 0)
+            .map(tag => tag.replace(/[^\w:-]/g, '_'))
+            .filter(tag => tag.length <= 50); // Limit tag length
+    }
+    /**
+     * Get MCP server information for observability metadata
+     */
+    getMCPServerInfo() {
+        const serverInfo = {};
+        try {
+            if (this.client) {
+                const serverNames = this.client.getServerNames();
+                serverInfo.mcp_servers_count = serverNames.length;
+                serverInfo.mcp_server_names = serverNames;
+                // Get server types and configurations
+                const serverConfigs = {};
+                for (const serverName of serverNames) {
+                    try {
+                        const config = this.client.getServerConfig(serverName);
+                        if (config) {
+                            // Determine server type based on configuration
+                            let serverType = 'unknown';
+                            if (config.command) {
+                                serverType = 'command';
+                            }
+                            else if (config.url) {
+                                serverType = 'http';
+                            }
+                            else if (config.ws_url) {
+                                serverType = 'websocket';
+                            }
+                            serverConfigs[serverName] = {
+                                type: serverType,
+                                // Include safe configuration details (avoid sensitive data)
+                                has_args: !!config.args,
+                                has_env: !!config.env,
+                                has_headers: !!config.headers,
+                                url: config.url || null,
+                                command: config.command || null,
+                            };
+                        }
+                    }
+                    catch (error) {
+                        logger.warn(`Failed to get config for server '${serverName}': ${error}`);
+                        serverConfigs[serverName] = { type: 'error', error: 'config_unavailable' };
+                    }
+                }
+                serverInfo.mcp_server_configs = serverConfigs;
+            }
+            else if (this.connectors && this.connectors.length > 0) {
+                // Handle direct connectors
+                serverInfo.mcp_servers_count = this.connectors.length;
+                serverInfo.mcp_server_names = this.connectors.map(c => c.publicIdentifier);
+                serverInfo.mcp_server_types = this.connectors.map(c => c.constructor.name);
+            }
+        }
+        catch (error) {
+            logger.warn(`Failed to collect MCP server info: ${error}`);
+            serverInfo.error = 'collection_failed';
+        }
+        return serverInfo;
+    }
     async _consumeAndReturn(generator) {
         // Manually iterate through the generator to consume the steps.
         // The for-await-of loop is not used because it discards the generator's

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

@@ -5,7 +5,9 @@
  * for Langfuse observability platform.
  */
 import type { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+declare function initializeLangfuse(agentId?: string, metadata?: Record<string, any>, metadataProvider?: () => Record<string, any>, tagsProvider?: () => string[]): Promise<void>;
 export declare const langfuseHandler: () => BaseCallbackHandler | null;
 export declare const langfuseClient: () => any;
 export declare const langfuseInitPromise: () => Promise<void> | null;
+export { initializeLangfuse };
 //# sourceMappingURL=langfuse.d.ts.map

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

@@ -1 +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"}
+{"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;AAgBzE,iBAAe,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8M9K;AAiBD,eAAO,MAAM,eAAe,kCAA8B,CAAA;AAC1D,eAAO,MAAM,cAAc,WAA6B,CAAA;AACxD,eAAO,MAAM,mBAAmB,4BAAkC,CAAA;AAClE,OAAO,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/src/observability/langfuse.js

@@ -15,7 +15,7 @@ const langfuseState = {
     client: null,
     initPromise: null,
 };
-async function initializeLangfuse() {
+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);
@@ -24,10 +24,104 @@ async function initializeLangfuse() {
             return;
         }
         const { CallbackHandler } = langfuseModule;
-        // Create a custom CallbackHandler wrapper to add logging
+        // Create a custom CallbackHandler wrapper to add logging and custom metadata
         class LoggingCallbackHandler extends CallbackHandler {
-            constructor(config) {
+            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');
@@ -36,13 +130,6 @@ async function initializeLangfuse() {
                 }
                 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) {
@@ -83,7 +170,7 @@ async function initializeLangfuse() {
             requestTimeout: Number.parseInt(process.env.LANGFUSE_REQUEST_TIMEOUT || '10000'),
             enabled: process.env.LANGFUSE_ENABLED !== 'false',
         };
-        langfuseState.handler = new LoggingCallbackHandler(config);
+        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 {
@@ -121,3 +208,4 @@ else {
 export const langfuseHandler = () => langfuseState.handler;
 export const langfuseClient = () => langfuseState.client;
 export const langfuseInitPromise = () => langfuseState.initPromise;
+export { initializeLangfuse };

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

@@ -10,6 +10,16 @@ export interface ObservabilityConfig {
     customCallbacks?: BaseCallbackHandler[];
     /** Whether to enable verbose logging */
     verbose?: boolean;
+    /** Whether to enable observability (defaults to true) */
+    observe?: boolean;
+    /** Agent ID for tagging traces */
+    agentId?: string;
+    /** Metadata to add to traces */
+    metadata?: Record<string, any>;
+    /** Function to get current metadata from agent */
+    metadataProvider?: () => Record<string, any>;
+    /** Function to get current tags from agent */
+    tagsProvider?: () => string[];
 }
 export declare class ObservabilityManager {
     private customCallbacks?;
@@ -17,6 +27,11 @@ export declare class ObservabilityManager {
     private handlerNames;
     private initialized;
     private verbose;
+    private observe;
+    private agentId?;
+    private metadata?;
+    private metadataProvider?;
+    private tagsProvider?;
     constructor(config?: ObservabilityConfig);
     /**
      * Collect all available observability handlers from configured platforms.

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

@@ -1 +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"}
+{"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;IACjB,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5C,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,MAAM,EAAE,CAAA;CAC9B;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;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAC,CAAQ;IACxB,OAAO,CAAC,QAAQ,CAAC,CAAqB;IACtC,OAAO,CAAC,gBAAgB,CAAC,CAA2B;IACpD,OAAO,CAAC,YAAY,CAAC,CAAgB;gBAEzB,MAAM,GAAE,mBAAwB;IAU5C;;OAEG;YACW,wBAAwB;IAwCtC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IA0BpD;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAe1C;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAUtC;;;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

@@ -11,9 +11,19 @@ export class ObservabilityManager {
     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.
@@ -25,10 +35,19 @@ export class ObservabilityManager {
         // 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;
+            // 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) {
@@ -48,6 +67,11 @@ export class ObservabilityManager {
      * @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`);
@@ -68,6 +92,10 @@ export class ObservabilityManager {
      * @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);
@@ -80,6 +108,10 @@ export class ObservabilityManager {
      * @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;
     }

package/dist/tests/stream_events.test.js

@@ -75,7 +75,7 @@ describe('mCPAgent streamEvents()', () => {
             yield {
                 event: 'on_chain_end',
                 name: 'AgentExecutor',
-                data: { output: 'Hello world' },
+                data: { output: [{ text: 'Hello world' }] },
             };
         });
         // Mock initialize method
@@ -290,6 +290,7 @@ describe('mCPAgent streamEvents() edge cases', () => {
                     yield { event: 'malformed' }; // Missing required fields
                     yield null; // Invalid event
                     yield { event: 'on_chat_model_stream', data: { chunk: { content: 'test' } } };
+                    yield { event: 'on_chain_end', data: { output: [{ text: 'test response' }] } };
                 }),
                 maxIterations: 3,
             }),

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "mcp-use",
   "type": "module",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "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",
+  "author": "mcp-use, Inc.",
   "license": "MIT",
   "homepage": "https://github.com/mcp-use/mcp-use-ts#readme",
   "repository": {
@@ -74,7 +74,8 @@
     "example:oauth": "npm run build && node dist/examples/simple_oauth_example.js",
     "example:blender": "npm run build && node dist/examples/blender_use.js",
     "example:add_server": "npm run build && node dist/examples/add_server_tool.js",
-    "example:structured": "npm run build && node dist/examples/structured_output.js"
+    "example:structured": "npm run build && node dist/examples/structured_output.js",
+    "example:observability": "npm run build && node dist/examples/observability.js"
   },
   "peerDependencies": {
     "langfuse": "^3.32.0",
@@ -90,15 +91,13 @@
   },
   "dependencies": {
     "@dmitryrechkin/json-schema-to-zod": "^1.0.1",
-    "@langchain/anthropic": "^0.3.14",
-    "@langchain/core": "0.3.71",
-    "@langchain/openai": "^0.5.15",
+    "@langchain/anthropic": "^0.3.26",
+    "@langchain/core": "^0.3.72",
+    "@langchain/openai": "^0.6.9",
     "@modelcontextprotocol/sdk": "1.12.1",
     "@scarf/scarf": "^1.4.0",
     "ai": "^4.3.19",
     "dotenv": "^16.5.0",
-    "eventsource": "^3.0.6",
-    "fastembed": "^1.14.4",
     "langchain": "^0.3.27",
     "lodash-es": "^4.17.21",
     "posthog-node": "^5.1.1",
@@ -117,7 +116,6 @@
     "eslint-plugin-format": "^1.0.1",
     "husky": "^9.1.7",
     "lint-staged": "^15.2.11",
-    "shx": "^0.4.0",
     "typescript": "^5.8.3",
     "vitest": "^2.1.9"
   },
@@ -125,6 +123,10 @@
     "*.{js,ts}": [
       "eslint --fix",
       "eslint"
+    ],
+    "*.md": [
+      "eslint --fix",
+      "eslint"
     ]
   }
 }