MCP Trace

io.github.abhishekashv0.1.1更新于 Oct 8, 2026

Query OpenTelemetry traces from agent runs through MCP.

已验证STDIO仅桌面Developer ToolsSecurity & MonitoringData & Analytics

概览

AI 生成的概览

让助手查询本地 OpenTelemetry 智能体运行轨迹文件，获取运行记录、跨度树、慢跨度、审批记录和 token 成本。

功能
从轨迹目录读取纯 OpenTelemetry JSONL 跨度文件，并以可查询工具的形式提供。工具包括 list_runs、run_summary、span_tree、slowest_spans、approval_log、token_usage 和 search_spans，覆盖近期运行、嵌套跨度结构、最慢跨度、人工批准/拒绝/编辑决定，以及按运行或汇总的 token 与成本用量。轨迹 ID 支持前缀匹配。当前版本所有工具均为只读。
适用场景
适合让助手在对话中检查自身或其他智能体的历史运行，例如解释运行为何变慢、找出反复超时的工具，或审计人工审批决定。适用于已经生成 OTel 结构 JSONL 跨度的环境，例如 agent-harness，或任何兼容的轨迹文件。
运行要求
需要本地 Python 运行时和 uv/uvx，以 stdio 方式运行 PyPI 包 abhishekash-mcp-trace，并通过 --trace-dir 指定存放 OTel 结构 JSONL 轨迹文件的目录。未声明需要账号、API 密钥或网络访问。文档给出了 Claude Desktop 和 pi 的桌面客户端配置示例。
安装前请注意
该服务器会读取所配置目录中的轨迹文件，因此只应指向你愿意让助手看到的轨迹；轨迹可能包含任务文本、文件路径、工具参数和审批理由。v0.1 为只读，但轨迹修改已在路线图中。轨迹目录扫描不递归，结果是调用时的快照而非实时数据。

安装

在 SourceWeft 中

  1. 打开 控制台中的 MCP Trace，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

mcp-trace

[CI] [License: MIT]

Agents that can debug themselves. An MCP server that exposes your agent runs — stored as plain OpenTelemetry JSONL span files — as queryable tools: runs, span trees, slow spans, human-approval logs, token/cost usage.

The idea: observability shouldn't be a dashboard you read after the fact. It should be tools your agent can call mid-run — "why was I slow yesterday?", "what did the human deny me last time?", "which tool keeps timing out?" — or query interactively from Claude Desktop / pi / any MCP client.

Pairs with agent-harness (which writes the traces), but the reader is format-simple: any JSONL of OTel-shaped spans works.

Install & run

The mcp-trace name is occupied on PyPI by an unrelated project, so this server is published as abhishekash-mcp-trace; it exposes both the abhishekash-mcp-trace and mcp-trace commands.

bash
uvx abhishekash-mcp-trace --trace-dir ./traces# or, for local development:git clone https://github.com/abhishekash/mcp-tracecd mcp-trace && uv pip install -e .mcp-trace --trace-dir ./traces

The package is published on PyPI, and the validated server.json is live in the official MCP Registry.

Client configuration

Claude Desktop (claude_desktop_config.json):

json
{  "mcpServers": {    "agent-traces": {      "command": "uvx",      "args": ["abhishekash-mcp-trace", "--trace-dir", "/path/to/traces"]    }  }}

pi (~/.pi/agent/settings.json):

json
{  "mcpServers": {    "agent-traces": {      "command": "uvx",      "args": ["abhishekash-mcp-trace", "--trace-dir", "/path/to/traces"]    }  }}

agent-harness (mounted as gated tools):

bash
harness run "Why was my last run slow?" --mcp "uvx abhishekash-mcp-trace --trace-dir ./traces"

Tools

ToolUse it when
list_runsStarting out — recent runs with task, model, duration, cost, decision counts
run_summaryOne run at a glance (accepts trace-id prefix)
span_tree"What did the agent actually do?" — nested shape of the run
slowest_spans"Why was it slow?" — top-k spans by duration
approval_logHITL audit — every approve/deny/edit, who decided, and the rationale
token_usageCost questions — aggregated across runs or per-run
search_spansFind spans by tool name, file path, "denied", …

Tool descriptions are written as prompts (when-to-use, not just what-it-does) — descriptions are the interface for agent-called tools.

Example session (real fixture trace)

> list_runs[{ "trace_id": "f920798dd255…", "task": "Summarize the workspace's notes…",   "tool_calls": 4, "human_decisions": 2, "stopped_reason": "completed" }]
> approval_log[{ "tool": "write_file", "decision": "approve", "approver": "auto", … }, { "tool": "run_shell",  "decision": "approve", "approver": "auto", … }]

Design

traces/*.jsonl ──▶ mcp_trace.core (pure query functions, zero deps)                          │                   mcp_trace.server (thin MCPServer adapter, mcp 2.x)                          │                    stdio (NDJSON JSON-RPC)
  • core/server split: all logic is pure functions over parsed spans; the MCP layer only parses args and JSON-encodes results. Tests hit both layers.
  • trace_id prefixes: agents fumble full 32-char hex ids; every tool accepts prefixes.
  • The demo fixture (examples/example_trace.jsonl) is a real agent-harness run, not hand-written.

Honest limitations

  • stdio transport only (no Streamable HTTP yet)
  • non-recursive trace-dir scan; very large dirs should use per-file loading
  • no span streaming/watching — snapshots at call time
  • v0.1: read-only tools; trace mutation (annotations) is roadmap

License

MIT

来源：README.md，提交 65966f5

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v0.1.1最新Oct 8, 2026