npm package: @mcp-monitoring/sdk
Description: MCP Monitoring SDK for Node.js - Track and monitor your MCP servers
Author: MCP Monitoring
Latest version: 0.1.0

# MCP Monitoring SDK for Node.js

A lightweight monitoring SDK for Model Context Protocol (MCP) servers. Track errors, performance, and tool executions with real-time insights.

## Installation

```bash
npm install @mcp-monitoring/sdk
```

## Quick Start

```typescript
import { init, error, info, trackToolExecution } from '@mcp-monitoring/sdk'

// Initialize the SDK with your API key
init({
  apiKey: 'your-api-key-here',
  endpoint: 'https://your-monitoring-endpoint.com/api/v1', // optional
  serverId: 'my-mcp-server', // optional, defaults to MCP_SERVER_ID env var
})

// Track events
error('Database connection failed', { database: 'users', error: 'ECONNREFUSED' })
info('User authenticated', { userId: '123', method: 'oauth' })

// Track tool execution
trackToolExecution('read_file', {
  duration: 150,
  success: true,
  input_size: 1024,
  output_size: 2048,
  parameters: { path: '/home/user/document.txt' }
})
```

## Configuration

```typescript
interface MCPMonitoringConfig {
  apiKey: string              // Required: Your MCP Monitoring API key
  endpoint?: string           // Optional: API endpoint (default: http://localhost:8080/api/v1)
  projectId?: number          // Optional: Project ID
  serverId?: string           // Optional: Server identifier (default: MCP_SERVER_ID env var)
  flushInterval?: number      // Optional: How often to send events in ms (default: 5000)
  maxBatchSize?: number       // Optional: Max events per batch (default: 100)
}
```

## API Reference

### Basic Event Tracking

```typescript
// Track custom events
track({
  level: 'error',
  message: 'Something went wrong',
  context: { userId: '123' },
  mcp_context: {
    tool_name: 'my-tool',
    server_id: 'my-server'
  }
})

// Convenience methods
error('Error message', context, mcpContext)
warning('Warning message', context, mcpContext)
info('Info message', context, mcpContext)
debug('Debug message', context, mcpContext)
```

### Tool Execution Tracking

```typescript
// Manual tracking
trackToolExecution('file_reader', {
  duration: 150,
  success: true,
  input_size: 1024,
  output_size: 2048,
  parameters: { path: '/file.txt' }
})

// Automatic wrapper (recommended)
const result = await wrapToolExecution('file_reader', async () => {
  // Your tool logic here
  return await readFile('/file.txt')
}, { path: '/file.txt' })
```

### Manual Flushing

```typescript
// Force send all pending events
await flush()

// Clean shutdown
await close()
```

## MCP Integration Examples

### Basic MCP Server

```typescript
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { init, wrapToolExecution, error } from '@mcp-monitoring/sdk'

// Initialize monitoring
init({
  apiKey: process.env.MCP_MONITORING_API_KEY!,
  serverId: 'my-file-server'
})

const server = new Server(
  {
    name: 'my-file-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
)

// Wrap your tool handlers
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params

  try {
    return await wrapToolExecution(name, async () => {
      switch (name) {
        case 'read_file':
          return await readFile(args.path)
        case 'write_file':
          return await writeFile(args.path, args.content)
        default:
          throw new Error(`Unknown tool: ${name}`)
      }
    }, args)
  } catch (err) {
    error(`Tool execution failed: ${name}`, { 
      toolName: name, 
      arguments: args,
      error: err.message 
    })
    throw err
  }
})
```

### Error Handling

```typescript
import { error, warning } from '@mcp-monitoring/sdk'

try {
  await dangerousOperation()
} catch (err) {
  error('Operation failed', {
    operation: 'dangerousOperation',
    error: err.message,
    stack: err.stack
  }, {
    tool_name: 'my-tool',
    custom_data: { retryCount: 3 }
  })
  throw err
}

// Track warnings for non-fatal issues
if (response.warnings.length > 0) {
  warning('API returned warnings', {
    warnings: response.warnings,
    endpoint: '/api/data'
  })
}
```

## Environment Variables

- `MCP_SERVER_ID`: Default server identifier
- `MCP_MONITORING_API_KEY`: API key (alternative to config)
- `MCP_MONITORING_ENDPOINT`: API endpoint (alternative to config)

## Best Practices

1. **Initialize Early**: Call `init()` as early as possible in your application
2. **Use Tool Wrappers**: Use `wrapToolExecution()` for automatic performance tracking
3. **Include Context**: Always provide relevant context in your events
4. **Handle Errors Gracefully**: The SDK handles network failures internally
5. **Clean Shutdown**: Call `close()` on process exit for reliable event delivery

## Event Levels

- **error**: System errors, exceptions, failures
- **warning**: Non-fatal issues, deprecations, performance concerns  
- **info**: General operational events, successful operations
- **debug**: Detailed diagnostic information

## License

MIT - see LICENSE file for details