[otel] Update MCP server with OTEL

[mattpodwysocki]

Description

Implements comprehensive OTEL tracing enhancements with additional multi-cloud observability platform support.

Key Changes

1. Environment Variable Loading with OTEL Tracing

• Replaced dotenv package with Node.js built-in parseEnv() (src/index.ts:4-55)
• Added retrospective OTEL span config.load_env capturing:
  • File path and existence
  • Number of variables loaded
  • Load success/failure status
  • Error details if loading fails
• Added MCP logging messages for environment variables (with sensitive values masked)
• Removed dotenv dependency from package.json

2. CloudFront Correlation ID Tracking

• Added TracingPolicy class (src/utils/httpPipeline.ts:164-220) capturing:
  • x-amz-cf-id - CloudFront request ID for correlation
  • x-amz-cf-pop - CloudFront Point of Presence location
  • x-cache - Cache hit/miss status
  • etag - Entity tag
  • http.response.status_code - HTTP status for all requests
• Smart filtering: Only captures Mapbox-specific headers for Mapbox API requests
• Respects MAPBOX_API_ENDPOINT environment variable
• Added 7 comprehensive tests (test/utils/httpPipeline.test.ts)

3. Simplified Configuration Management

• Consolidated .env.tracing.example and .env.aws.example into single .env.example
• Added configuration examples for 6 observability platforms:
  • AWS X-Ray (existing)
  • Azure Monitor / Application Insights (new)
  • Google Cloud Trace (new)
  • Datadog (new)
  • New Relic (new)
  • Honeycomb (new)
• Removed hardcoded environment variables from npm scripts
• Simplified inspect:build and inspect:dev to automatically use .env

4. Cleaned Up npm Scripts

Removed:

• test:tracing - Redundant with .env configuration
• tracing:demo - Console output not useful for stdio transport
• tracing:test - Internal testing script
• inspect:build:tracing - Now uses .env instead
• inspect:dev:tracing - Now uses .env instead
• scripts/tracing-demo.ts
• scripts/test-tracing.ts

Kept:

• tracing:jaeger:start / tracing:jaeger:stop - Docker helpers
• tracing:verify - Updated with .env instructions

5. Documentation Updates

• README.md: Updated tracing quick start, added multi-cloud platform list
• docs/tracing.md:
  • Added configuration loading spans documentation
  • Added CloudFront correlation IDs section
  • Updated supported backends with setup guides for each platform
  • Replaced inline env vars with .env file approach
• docs/complete-observability.md: Added config loading and CloudFront tracing sections

Benefits

✅ End-to-End Observability: Configuration loading → Tool execution → HTTP requests → CloudFront
✅ Multi-Cloud Support: Ready-to-use configs for AWS, Azure, GCP
✅ Vendor Flexibility: Easy switching between observability platforms
✅ Debugging: CloudFront correlation IDs for troubleshooting with Mapbox support
✅ Cleaner Config: Single .env.example with all options
✅ No External Deps: Using Node.js built-in parseEnv instead of dotenv package

Testing

Test Coverage

• ✅ Total tests: 341 passing (334 existing + 7 new)
• ✅ New tests: TracingPolicy (test/utils/httpPipeline.test.ts)
  • Captures CloudFront headers for Mapbox API requests when span is active
  • Does not capture headers when span is not active
  • Only captures headers that are present in the response
  • Does not capture Mapbox-specific headers for non-Mapbox URLs
  • Respects MAPBOX_API_ENDPOINT environment variable
  • Generates automatic ID if not provided
  • Uses provided ID when specified

Manual Testing

1. Configuration Loading:

   cp .env.example .env
   # Edit .env to add MAPBOX_ACCESS_TOKEN
   npm run inspect:build
   # Verify: Check traces for config.load_env span
   

2. CloudFront Correlation IDs:

Start Jaeger

npm run tracing:jaeger:start
npm run inspect:build

Make API call via inspector

Verify: Check traces at http://localhost:16686 for x-amz-cf-id attributes

3. Multi-Cloud Configuration:
   - Verified .env.example has valid endpoint URLs for all 6 platforms
   - Tested that uncommenting each platform section works without conflicts

Build & Lint

• ✅ npm run build - Successful
• ✅ npm test - All 341 tests passing
• ✅ npm run lint - No issues
• ✅ No breaking changes introduced

Compatibility

• Node.js built-in parseEnv requires Node.js ≥ 20.12.0 or ≥ 21.7.0
• All OpenTelemetry dependencies remain unchanged
• Backward compatible: Existing .env files continue to work

Checklist

• Code has been tested locally
• Unit tests have been added or updated
• Documentation has been updated if needed

---

Additional Notes