feat: enhance observability with improved metadata and tag handling

- Add ObservabilityManager export to main index.ts for better accessibility
- Refactor MCPAgent to support dynamic metadata and tag providers
- Enhance Langfuse integration with custom metadata and tag support
- Improve observability manager with better initialization and callback handling
- Update examples and tests to reflect new observability features
- Add support for runtime metadata and tag updates during agent execution
- Add comprehensive observability documentation to README with setup guides,
  usage examples, and production configuration instructions

Author: tonxxd

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,214 @@ export function Chat() {
 
 ---
 
+## 📊 Observability & Monitoring
+
+mcp-use-ts provides built-in observability support through the `ObservabilityManager`, with seamless integration for Langfuse and other observability platforms.
+
+### Features
+
+- **Automatic Tracing**: All agent executions, tool calls, and LLM interactions are automatically traced
+- **Dynamic Metadata**: Add contextual metadata to traces at runtime
+- **Tag Support**: Tag traces with dynamic information for better organization
+- **Langfuse Integration**: Native support for Langfuse observability platform
+- **Custom Callbacks**: Support for additional custom callback handlers
+
+### Setup
+
+#### 1. Install Observability Dependencies
+
+```bash
+npm install langfuse langfuse-langchain
+```
+
+#### 2. 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
+```
+
+#### 3. Basic Usage
+
+```ts
+import { MCPAgent, MCPClient, ObservabilityManager } from 'mcp-use'
+import { ChatOpenAI } from '@langchain/openai'
+
+const client = new MCPClient({
+  mcpServers: {
+    everything: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-everything'] }
+  }
+})
+
+const llm = new ChatOpenAI({ model: 'gpt-4o' })
+
+// Create agent with observability enabled
+const agent = new MCPAgent({
+  llm,
+  client,
+  maxSteps: 10,
+  verbose: true  // Enable verbose logging for better observability
+})
+
+// Initialize to set up observability callbacks
+await agent.initialize()
+
+// Run queries - all interactions will be automatically traced
+const result = await agent.run('What tools are available?')
+```
+
+### Advanced Observability Features
+
+#### Dynamic Metadata and Tags
+
+```ts
+// Set 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')
+```
+
+#### Custom Observability Manager
+
+```ts
+import { ObservabilityManager } from 'mcp-use'
+
+// Create custom observability manager
+const observabilityManager = new ObservabilityManager({
+  verbose: true,
+  agentId: 'my-custom-agent',
+  metadata: {
+    version: '1.0.0',
+    deployment: 'production'
+  },
+  metadataProvider: () => ({
+    timestamp: new Date().toISOString(),
+    requestId: crypto.randomUUID()
+  }),
+  tagsProvider: () => ['automated', 'scheduled']
+})
+
+// Use with MCPAgent
+const agent = new MCPAgent({
+  llm,
+  client,
+  callbacks: await observabilityManager.getCallbacks()
+})
+```
+
+#### Runtime Metadata Updates
+
+```ts
+// Update metadata during execution
+agent.setMetadata({
+  currentStep: 1,
+  toolsUsed: ['search', 'browse']
+})
+
+// Add more tags
+agent.setTags(['step-1', 'search-complete'])
+
+// Continue execution with updated context
+const result = await agent.run('Continue with the search')
+```
+
+### Observability in Production
+
+#### Environment Configuration
+
+```ts
+// Production setup with comprehensive observability
+const agent = new MCPAgent({
+  llm,
+  client,
+  maxSteps: 20,
+  verbose: process.env.NODE_ENV === 'development',
+  // Observability is automatically enabled when environment variables are set
+})
+
+await agent.initialize()
+
+// Set production metadata
+agent.setMetadata({
+  service: 'mcp-agent',
+  version: process.env.APP_VERSION,
+  environment: process.env.NODE_ENV,
+  region: process.env.AWS_REGION
+})
+
+agent.setTags(['production', 'api', 'mcp-agent'])
+```
+
+#### 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, set the environment variable:
+
+```ini
+MCP_USE_LANGFUSE=false
+```
+
+Or programmatically:
+
+```ts
+const agent = new MCPAgent({
+  llm,
+  client,
+  callbacks: []  // No callbacks = no observability
+})
+```
+
+### Available Observability Exports
+
+```ts
+import { 
+  ObservabilityManager, 
+  type ObservabilityConfig 
+} from 'mcp-use'
+
+// Use ObservabilityManager directly for custom setups
+const manager = new ObservabilityManager({
+  verbose: true,
+  agentId: 'custom-agent'
+})
+```
+
+---
+
 ## 📂 Configuration File
 
 You can store servers in a JSON file:

examples/mcp_everything.ts

@@ -5,28 +5,57 @@
 
 import { ChatOpenAI } from '@langchain/openai'
 import { config } from 'dotenv'
-import { MCPAgent, MCPClient } from '../index.js'
+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 Everything 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 })
+  const agent = new MCPAgent({
+    llm,
+    client,
+    maxSteps: 30,
+  })
+
+  console.log('🔧 Initializing agent...')
+  await agent.initialize()
 
+  // Set additional metadata for testing
+  agent.setMetadata({
+    agent_id: 'test-agent-123',
+    test_run: true,
+    example: 'mcp_everything',
+  })
+
+  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(`\nResult: ${result}`)
+  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]}`) {

index.ts

@@ -17,6 +17,9 @@ export { ServerManager } from './src/managers/server_manager.js'
 
 export * from './src/managers/tools/index.js'
 
+// Export observability utilities
+export { type ObservabilityConfig, ObservabilityManager } from './src/observability/index.js'
+
 // Export telemetry utilities
 export { setTelemetrySource, Telemetry } from './src/telemetry/index.js'