implement an MCP server for exposing traces to a coding agent

CHANGELOG.md

@@ -1,3 +1,16 @@
+## [0.5.1] - 2025
+
+Prototype an MCP server.
+
+### Added
+
+- Added Model Context Provider (MCP) server for agent-assisted code understanding
+  - analyzes spans to extract code context (file paths, line numbers, function names)
+  - provides a web UI for exploring traces
+  - includes WebSocket API for real-time updates
+  - offers REST APIs for querying traces, spans, and file associations
+  - has an embedded UI with go:embed
+
 ## [0.5.0] - 2025-04-21
 
 Fork otel-cli to @tobert's personal GitHub.

README.md

@@ -1,10 +1,8 @@
 # otel-cli
 
-[![](https://img.shields.io/badge/stability-experimental-lightgrey.svg)](https://github.com/packethost/standards/blob/master/experimental-statement.md)
-
-otel-cli is a command-line tool for sending OpenTelemetry traces. It is written in
-Go and intended to be used in shell scripts and other places where the best option
-available for sending spans is executing another program.
+otel-cli is a command-line tool for sending and working with OpenTelemetry traces.
+It is written in Go and intended to be used in shell scripts and other places where
+the best option available for sending spans is executing another program.
 
 otel-cli can be added to your scripts with no configuration and it will run as normal
 but in non-recording mode and will emit no traces. This follows the OpenTelemetry community's
@@ -56,6 +54,9 @@ go build
 # run this in its own terminal and try some of the commands below!
 otel-cli server tui
 
+# or run as a Model Context Provider server (see MCP Server section below)
+otel-cli server mcp --port 8080
+
 # configure otel-cli to talk the the local server spawned above
 export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
 
@@ -202,12 +203,15 @@ But, if you just want to quickly try out otel-cli, you can also just install it
 
 ### 3. A system to receive/inspect the traces you generate
 
-otel-cli can run as a server and accept OTLP connections. It has two modes, one prints to your console
-while the other writes to JSON files.
+otel-cli can run as a server and accept OTLP connections. It has three modes:
+- `tui` which prints traces to your console in a text-based UI
+- `json` which writes traces to JSON files
+- `mcp` which collects traces, analyzes code context, and provides a web UI and API (see MCP Server section above)
 
 ```shell
 otel-cli server tui
 otel-cli server json --dir $dir --timeout 60 --max-spans 5
+otel-cli server mcp --port 8080 --project-root $(pwd)
 ```
 
 Many SaaS vendors accept OTLP these days so one option is to send directly to those. This is not
@@ -252,6 +256,61 @@ otel-cli exec --service my-service --name "curl google" curl https://google.com
 
 This trace will be available at `localhost:8000`.
 
+## MCP Server (Model Context Provider)
+
+The MCP Server is a specialized component designed to make otel trace data
+available to coding agents like Claude Code.
+
+### Starting the MCP Server
+
+```shell
+# you can start with defaults, OTLP in 4317 and MCP/http on 8080
+otel-cli server mcp
+
+# or you can configure things exactly the way you want to
+otel-cli server mcp \
+   --port 9000 \
+   --project-root $HOME/src/otel-cli \
+   --retention 1h \
+   --max-spans 500 \
+   --allow-origins "http://localhost:3000,https://myapp.com"
+```
+
+### Using the MCP Server
+
+Once the server is running, direct your OpenTelemetry traces to it:
+
+```shell
+# Send traces to the MCP server
+export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:8080
+otel-cli exec --service my-service --name "my-function" ./my-program
+```
+
+### Accessing the MCP Web UI and API
+
+- Web UI: http://localhost:8080/ (change the port if you used --port)
+- WebSocket endpoint: ws://localhost:8080/ws
+- REST API endpoints:
+  - `GET /api/traces` - List all traces
+  - `GET /api/trace/{id}` - Get a specific trace
+  - `GET /api/files` - List all files with spans
+  - `GET /api/file/{path}` - Get traces for a specific file
+  - `POST /api/spans/search` - Search across traces
+
+### Integrating with AI Tools
+
+The MCP Server is designed to provide structured context about your code's runtime behavior to coding agents. For example:
+
+```shell
+# capture traces in memory with otel-cli
+otel-cli server mcp &
+# point applications at the otel-cli OTLP server
+export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
+# generate a trace with the application
+otel-cli exec --service my-service ./my-program
+# now you an ask your agent questions about the traces
+```
+
 ### SaaS tracing vendor
 
 We've provided Honeycomb, LightStep, and Elastic configurations that you could also use,

go.mod

@@ -6,6 +6,7 @@ toolchain go1.22.4
 
 require (
 	github.com/google/go-cmp v0.6.0
+	github.com/gorilla/websocket v1.5.3
 	github.com/pterm/pterm v0.12.79
 	github.com/spf13/cobra v1.8.0
 	go.opentelemetry.io/otel v1.27.0

go.sum

@@ -33,6 +33,8 @@ github.com/gookit/color v1.4.2/go.mod h1:fqRyamkC1W8uxl+lxCQxOT09l/vYfZ+QeiX3rKQ
 github.com/gookit/color v1.5.0/go.mod h1:43aQb+Zerm/BWh2GnrgOQm7ffz7tvQXEKV6BFMl7wAo=
 github.com/gookit/color v1.5.4 h1:FZmqs7XOyGgCAxmWyPslpiok1k05wmY3SJTytgvYFs0=
 github.com/gookit/color v1.5.4/go.mod h1:pZJOeOS8DM43rXbp4AZo1n9zCU2qjpcRko0b6/QJi9w=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.19.0 h1:Wqo399gCIufwto+VfwCSvsnfGpF/w5E9CNxSwbpD6No=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.19.0/go.mod h1:qmOFXW2epJhM0qSnUUYpldc7gVz2KMQwJ/QYCDIa7XU=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=