feat: enhance observability with improved metadata and tag handling

DEVELOPMENT.md

@@ -5,26 +5,19 @@ This document provides guidance for developers contributing to this project and
 ## Setting Up Development Environment
 
 1. Clone the repository:
-
    ```bash
    git clone https://github.com/zandko/mcp-use.git
    cd mcp-use
    ```
-
 2. Install dependencies:
-
    ```bash
    pnpm install
    ```
-
    > **Note**: This project requires Node.js version 22 or higher.
-
 3. Build the project:
-
    ```bash
    pnpm build
    ```
-
 4. Watch for changes during development:
    ```bash
    pnpm watch
@@ -62,33 +55,25 @@ We use GitHub Actions to automate our release process, connecting GitHub Release
 #### For Maintainers
 
 1. **Prepare for Release**:
-
    Update the version in `package.json` using one of these commands:
-
    ```bash
    # For patch releases (0.0.x) - Bug fixes
    pnpm run release
-
    # For minor releases (0.x.0) - New features
    pnpm run release:minor
-
    # For major releases (x.0.0) - Breaking changes
    pnpm run release:major
    ```
-
    This will:
    - Update the version in package.json
    - Create a git tag
    - Push the changes and tag to GitHub
-
 2. **Create GitHub Release**:
    - Go to GitHub repository → "Releases" → "Draft a new release"
    - Choose the tag that was just created
    - Fill in release notes detailing what's new, fixes, and any breaking changes
    - Click "Publish release"
-
 3. **Automated Publishing**:
-
    The GitHub Action will automatically:
    - Verify the package version matches the GitHub tag
    - Run linting and build checks
@@ -105,11 +90,9 @@ To set up automated publishing:
 1. Generate an NPM access token:
    - Go to npmjs.com → User Settings → Access Tokens
    - Create a new token with "Automation" type and publish permissions
-
 2. Add the token to GitHub repository secrets:
    - Go to your GitHub repository → Settings → Secrets → Actions
    - Add a new secret named `NPM_TOKEN` with the value of your NPM token
-
 3. (Optional) Discord notifications:
    - Create a Discord webhook in your server
    - Add the webhook URL as a GitHub repository secret named `DISCORD_WEBHOOK`

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:

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)
+}

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'
 

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",
@@ -122,6 +123,10 @@
     "*.{js,ts}": [
       "eslint --fix",
       "eslint"
+    ],
+    "*.md": [
+      "eslint --fix",
+      "eslint"
     ]
   }
 }