Add mcp-trace and tracing integration

[mybytecode]

Add MCP Tracing Support with mcp-trace

Summary

This PR adds comprehensive tracing capabilities to the Notion MCP Server using the mcp-trace middleware. This enables observability and debugging of all MCP requests, tool calls, and responses, making it easier to monitor and troubleshoot the server in development and production environments.

Changes

Core Integration

• Added mcp-trace dependency (v0.2.0) - Already present in package.json
• Integrated TraceMiddleware into MCPProxy class to capture all MCP communication
• Added optional tracing configuration that can be enabled via CLI flags or environment variables
• Console adapter support - Traces are output to console for easy viewing

Files Modified

1. src/openapi-mcp-server/mcp/proxy.ts

   • Added TraceMiddleware import and integration
   • Added optional traceOptions parameter to MCPProxy constructor
   • Initialize tracing middleware when options are provided
   • Tracing automatically captures all incoming/outgoing MCP messages

2. src/init-server.ts

   • Added TraceMiddlewareOptions parameter to initProxy function
   • Passes tracing configuration to MCPProxy

3. scripts/start-server.ts

   • Added --trace / --enable-trace CLI flag to enable tracing
   • Added MCP_TRACE_ENABLED environment variable support
   • Added MCP_TRACE_LOG_FIELDS environment variable for log field configuration
   • Updated help text with tracing options and examples
   • Simplified implementation to use only ConsoleAdapter for tracing output

Usage

Enable Tracing via CLI

# Enable tracing with stdio transport
npx @notionhq/notion-mcp-server --trace

# Enable tracing with HTTP transport
npx @notionhq/notion-mcp-server --transport http --trace

# With custom auth token
npx @notionhq/notion-mcp-server --transport http --trace --auth-token "my-token"

Enable Tracing via Environment Variable

# Enable tracing via environment variable
MCP_TRACE_ENABLED=true npx @notionhq/notion-mcp-server

# With custom log fields configuration
MCP_TRACE_ENABLED=true MCP_TRACE_LOG_FIELDS='{"arguments":true,"response":true}' npx @notionhq/notion-mcp-server

What Gets Traced

When tracing is enabled, the middleware captures:

• All incoming MCP requests (initialize, tools/list, tools/call, etc.)
• All outgoing MCP responses
• Tool call arguments and responses
• Request/response timestamps and durations
• Session IDs and client information
• Error information when requests fail

Benefits

1. Debugging: Easily see all MCP communication in real-time
2. Monitoring: Track tool usage and performance metrics
3. Development: Understand how clients interact with the server
4. Troubleshooting: Identify issues with tool calls and responses
5. Observability: Gain insights into server behavior and usage patterns

Testing

Manual Testing

1. Test with STDIO transport:

   NOTION_TOKEN="your_token" npx tsx scripts/start-server.ts --trace

2. Test with HTTP transport:

   NOTION_TOKEN="your_token" npx tsx scripts/start-server.ts --transport http --trace

3. Verify tracing output:

   • Make MCP requests to the server
   • Check console output for trace logs showing requests, responses, and timing information

Expected Behavior

• When --trace flag is used, tracing is enabled and console output shows trace information
• When tracing is disabled (default), no trace output is generated
• Tracing works with both STDIO and HTTP transports
• No performance impact when tracing is disabled

Breaking Changes

None - This is a fully backward-compatible feature addition. Tracing is opt-in and disabled by default.

Dependencies

• mcp-trace@^0.2.0 - Already present in package.json

Related Issues

N/A - Feature addition

Checklist

• Code follows existing style guidelines
• Tracing is opt-in and disabled by default
• Works with both STDIO and HTTP transports
• Updated help text with tracing options
• No breaking changes
• Manual testing completed
• Console adapter implementation verified