# jaeger-mcp

Read-only MCP server for querying Jaeger environments from Codex.

The server talks to Jaeger Query API over HTTP and returns compact, sanitized summaries instead of raw traces. This is important because production spans can contain sensitive values such as `rpc.request.params`, user text, emails, SQL text, headers, and provider payloads.

## Environments

This repository does not ship real Jaeger URLs. Configure them locally through environment variables.

Logical environments:

- `dev`
- `test`
- `preview`
- `prod`

When two logical environments share the same Jaeger Query endpoint, use grouped URL variables:

```bash
export JAEGER_DEV_TEST_URL="<dev-test-jaeger-query-url>"
export JAEGER_PREVIEW_PROD_URL="<preview-prod-jaeger-query-url>"
export JAEGER_DEFAULT_ENV="dev"
export JAEGER_TIMEOUT_SECONDS="20"
```

`JAEGER_DEV_TEST_URL` configures both `dev` and `test`. `JAEGER_PREVIEW_PROD_URL` configures both `preview` and `prod`.

Explicit per-environment variables override grouped variables:

```bash
export JAEGER_DEV_URL="<dev-jaeger-query-url>"
export JAEGER_TEST_URL="<test-jaeger-query-url>"
export JAEGER_PREVIEW_URL="<preview-jaeger-query-url>"
export JAEGER_PROD_URL="<prod-jaeger-query-url>"
```

For custom environments:

```bash
export JAEGER_ENVIRONMENTS='{"dev":"<dev-jaeger-query-url>","prod":"<prod-jaeger-query-url>"}'
```

For headers:

```bash
export JAEGER_HEADERS='{"X-Debug":"1"}'
export JAEGER_PROD_HEADERS='{"Authorization":"Bearer ..."}'
```

## Run

From this repository:

```bash
python3 -m jaeger_mcp.server
```

For Codex MCP configuration, point the command at the source tree without installing:

```json
{
  "mcpServers": {
    "jaeger": {
      "command": "python3",
      "args": ["-m", "jaeger_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/jaeger-mcp/src"
      }
    }
  }
}
```

Replace `/path/to/jaeger-mcp` with the local checkout path on the machine running Codex.

## Tools

- `jaeger_list_services(env?)`
- `jaeger_list_operations(env?, service, span_kind?)`
- `jaeger_search_traces(env?, service, operation?, lookback?, start_us?, end_us?, min_duration?, max_duration?, limit?, tags?)`
- `jaeger_search_error_traces(env?, service, operation?, lookback?, limit?)`
- `jaeger_get_trace_summary(env?, trace_id, max_error_spans?, max_slow_spans?)`
- `jaeger_find_error_spans(env?, trace_id, max_spans?, include_logs?)`
- `jaeger_get_span_detail(env?, trace_id, span_id, include_logs?)`

## Design boundaries

- Read-only only.
- Default output is JSON text suitable for Codex reasoning.
- Raw tags are not returned wholesale.
- Sensitive keys are redacted or omitted.
- Long strings are truncated.
- Trace search is capped by `JAEGER_MAX_LIMIT` with a default cap of `50`.

## Code layout

- `server.py`: stdio entrypoint.
- `rpc.py`: JSON-RPC request handling.
- `tools.py`: MCP tool schemas and dispatch.
- `client.py`: Jaeger Query API client and tool implementations.
- `trace_analysis.py`: span classification, summaries, and trace URLs.
- `redaction.py`: sensitive-key detection and output sanitization.
- `config.py`: local environment-variable configuration.

## Local tests

```bash
python3 -B -m unittest discover -s tests
```