opentelemetry-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Opentelemetry MCP Server (opentelemetry-mcp) is an MCP (Model Context Protocol) server that enables AI agents to query and analyze OpenTelemetry traces from LLM applications. It parses Opentelemetry semantic conventions (the gen_ai.* attributes) to enable automated debugging and observability.

Key Features:

• Multi-backend support: Jaeger, Grafana Tempo, and Traceloop
• 9 MCP tools: Core tools + LLM-oriented discovery and analysis tools
• Token usage tracking and aggregation across models/services
• Finish reasons tracking for debugging truncated/filtered responses
• Enhanced token calculation supporting all gen_ai.usage.* attributes
• Dual transport modes: stdio (Claude Desktop) and HTTP/SSE (network access)

Development Commands

Package Manager: This project uses UV (not pip). All commands should use uv run.

# Install dependencies
uv sync

# Run the server (stdio transport for Claude Desktop)
uv run opentelemetry-mcp

# Run with HTTP transport
uv run opentelemetry-mcp --transport http --port 8000

# Override backend configuration
uv run opentelemetry-mcp --backend jaeger --url http://localhost:16686

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=opentelemetry_mcp --cov-report=html

# Run specific test file
uv run pytest tests/test_models.py

# Format code (always run before committing)
uv run ruff format .

# Lint code
uv run ruff check .

# Type check (strict mode, must pass)
uv run mypy src/

Architecture

Backend Abstraction Pattern

All trace storage backends implement the BaseBackend abstract interface in opentelemetry_mcp/backends/base.py:

class BaseBackend(ABC):
    @abstractmethod
    async def search_traces(self, query: TraceQuery) -> list[TraceData]: ...
    @abstractmethod
    async def search_spans(self, query: SpanQuery) -> list[SpanData]: ...
    @abstractmethod
    async def get_trace(self, trace_id: str) -> TraceData: ...
    @abstractmethod
    async def list_services(self) -> list[str]: ...
    @abstractmethod
    async def get_service_operations(self, service: str) -> list[str]: ...
    @abstractmethod
    async def health_check(self) -> bool: ...