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