feat: add observability example and enhance README documentation

- Introduced a new example for observability integration in mcp_everything.ts
- Updated README to streamline observability setup instructions and remove redundant sections
- Added support for an 'observe' option in MCPAgent and ObservabilityManager to control observability behavior
- Improved observability manager to handle cases when observability is disabled
- Cleaned up example code for better clarity and removed unnecessary debug logging

Author: tonxxd

README.md

@@ -298,25 +298,9 @@ 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.
+mcp-use-ts provides built-in observability support through the `ObservabilityManager`, with 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
+#### To enable observability simply configure Environment Variables
 
 ```ini
 # .env
@@ -325,41 +309,12 @@ LANGFUSE_SECRET_KEY=sk-lf-your-secret-key
 LANGFUSE_HOST=https://cloud.langfuse.com  # or your self-hosted instance
 ```
 
-#### 3. Basic Usage
-
-```ts
-import { ChatOpenAI } from '@langchain/openai'
-import { MCPAgent, MCPClient, ObservabilityManager } from 'mcp-use'
-
-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
+// Set custom metadata for the current execution
 agent.setMetadata({
   userId: 'user123',
   sessionId: 'session456',
@@ -373,77 +328,6 @@ agent.setTags(['production', 'user-query', 'tool-discovery'])
 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
@@ -471,32 +355,13 @@ for await (const event of eventStream) {
 
 ### Disabling Observability
 
-To disable observability, set the environment variable:
-
-```ini
-MCP_USE_LANGFUSE=false
-```
-
-Or programmatically:
+To disable observability, either remove langfuse env variables or
 
 ```ts
 const agent = new MCPAgent({
   llm,
   client,
-  callbacks: [] // No callbacks = no observability
-})
-```
-
-### Available Observability Exports
-
-```ts
-import type { ObservabilityConfig } from 'mcp-use'
-import { ObservabilityManager } from 'mcp-use'
-
-// Use ObservabilityManager directly for custom setups
-const manager = new ObservabilityManager({
-  verbose: true,
-  agentId: 'custom-agent'
+  observe: false
 })
 ```
 

examples/mcp_everything.ts

@@ -5,57 +5,28 @@
 
 import { ChatOpenAI } from '@langchain/openai'
 import { config } from 'dotenv'
-import { Logger, MCPAgent, MCPClient } from '../index.js'
+import { 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,
-  })
-
-  console.log('🔧 Initializing agent...')
-  await agent.initialize()
+  const agent = new MCPAgent({ llm, client, maxSteps: 30 })
 
-  // 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(`\n✅ Result: ${result}`)
-
-  console.log('🧹 Closing agent...')
-  await agent.close()
-  console.log('🎉 Example completed! Check your Langfuse dashboard for traces.')
+  console.log(`\nResult: ${result}`)
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

examples/observability.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.json

@@ -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",

src/agents/mcp_agent.ts

@@ -46,6 +46,7 @@ export class MCPAgent {
   private additionalTools: StructuredToolInterface[]
   private useServerManager: boolean
   private verbose: boolean
+  private observe: boolean
   private systemPrompt?: string | null
   private systemPromptTemplateOverride?: string | null
   private additionalInstructions?: string | null
@@ -86,6 +87,7 @@ export class MCPAgent {
     additionalTools?: StructuredToolInterface[]
     useServerManager?: boolean
     verbose?: boolean
+    observe?: boolean
     adapter?: LangChainAdapter
     serverManagerFactory?: (client: MCPClient) => ServerManager
     callbacks?: BaseCallbackHandler[]
@@ -107,6 +109,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 = []
@@ -142,6 +145,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.')
@@ -176,6 +180,7 @@ 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(),