mcp-trace-inspector 0.3.0__tar.gz

mcp_trace_inspector-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q

mcp_trace_inspector-0.3.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,43 @@
+name: publish-pypi
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI with trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-mcp:
+    needs: publish
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+      - name: Install mcp-publisher
+        run: |
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+          chmod +x mcp-publisher
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server metadata
+        run: ./mcp-publisher publish

mcp_trace_inspector-0.3.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.coverage
+htmlcov/
+traces/
+runs.jsonl
+.env

mcp_trace_inspector-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to mcp-trace-inspector
+
+## Development setup
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+pytest -q
+```
+
+The core query engine is dependency-light and should remain pure. Server tests exercise the MCP 2.x protocol adapter as well as the core functions.
+
+## Pull requests
+
+- Add a deterministic fixture for new query behavior.
+- Test the tool through `MCPServer.call_tool`, not only by calling the underlying function.
+- Keep tool descriptions phrased as when-to-use prompts.
+- Preserve trace-id prefix support and compact output defaults.
+- Update the README's tool table and limitations when behavior changes.

mcp_trace_inspector-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Ash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_trace_inspector-0.3.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: mcp-trace-inspector
+Version: 0.3.0
+Summary: Agent observability MCP server for querying OpenTelemetry traces, failures, tool health, security evidence, and regressions.
+Project-URL: Homepage, https://github.com/abhishekash/mcp-trace-inspector
+Project-URL: Repository, https://github.com/abhishekash/mcp-trace-inspector
+Project-URL: Issues, https://github.com/abhishekash/mcp-trace-inspector/issues
+Author-email: Abhishek Ash <ash.abhishek@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent-evals,ai-agents,mcp,model-context-protocol,observability,opentelemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: mcp>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-trace-inspector
+
+<!-- mcp-name: io.github.abhishekash/mcp-trace-inspector -->
+
+[![CI](https://github.com/abhishekash/mcp-trace-inspector/actions/workflows/ci.yml/badge.svg)](https://github.com/abhishekash/mcp-trace-inspector/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+mcp-trace-inspector is a small, local-first stdio MCP server for querying JSONL
+OpenTelemetry spans emitted by agent runs. It exposes focused queries for
+run summaries, tool failures, approvals, activity, and comparisons instead of
+requiring an application-specific dashboard.
+
+It pairs with [agent-harness](https://github.com/abhishekash/agent-harness),
+but the reader is format-simple: any JSONL of OTel-shaped spans works. The
+project's concrete origin was a shell-boundary regression: the harness blocked
+`cat ../outside.txt`, but the old trace recorded only that `run_shell` was
+called, not the returned diagnostic. mcp-trace-inspector and the harness now preserve and
+query that bounded error.
+
+## AI-native use cases
+
+| Question during an agent run | MCP tool | Evidence returned |
+|---|---|---|
+| "Why did yesterday's run stall?" | `list_runs` → `slowest_spans` | Run IDs and the longest model or tool spans. |
+| "Did the agent act after I denied the write?" | `approval_log` → `span_tree` | The recorded decision and subsequent execution path. |
+| "How many model tokens did this run use?" | `token_usage` → `span_tree` | Run-level usage totals and the span tree for context. |
+| "Which tool is failing or timing out?" | `failure_report` / `tool_stats` | Redacted diagnostics, error rates, denials, and p95 latency. |
+| "Who/what was allowed to act?" | `security_audit` | Caller, tenant, server provenance, risk, and missing-evidence findings. |
+| "What is happening in the run right now?" | `recent_activity` | Cursor-based polling of newly written spans. |
+| "Did this model/version regress?" | `compare_runs` | Cost, latency, tokens, tool calls, and failure deltas. |
+
+The tools read stored traces and can poll files being written, but they do not push events or infer intent from the final answer. Start with the [installation and user guide](docs/user-guide.md), then see the [real trace fixture](examples/example_trace.jsonl) and the [tool descriptions](src/mcp_trace/server.py) for the query contract.
+
+## Install & run
+
+```bash
+uvx mcp-trace-inspector --trace-dir ./traces
+# or, for local development:
+git clone https://github.com/abhishekash/mcp-trace-inspector
+cd mcp-trace-inspector && uv pip install -e .
+mcp-trace-inspector --trace-dir ./traces
+```
+
+## Client configuration
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-traces": {
+      "command": "uvx",
+      "args": ["mcp-trace-inspector", "--trace-dir", "/path/to/traces"]
+    }
+  }
+}
+```
+
+**pi** (`~/.pi/agent/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-traces": {
+      "command": "uvx",
+      "args": ["mcp-trace-inspector", "--trace-dir", "/path/to/traces"]
+    }
+  }
+}
+```
+
+**agent-harness** (mounted as gated tools):
+
+```bash
+harness run "Why was my last run slow?" --mcp "uvx mcp-trace-inspector --trace-dir ./traces"
+```
+
+## Tools
+
+| Tool | Use it when |
+|---|---|
+| `list_runs` | Starting out — recent runs with task, model, duration, cost, decision counts |
+| `run_summary` | One 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_log` | HITL audit — every approve/deny/**edit**, who decided, and *the rationale* |
+| `token_usage` | Cost questions — aggregated across runs or per-run |
+| `search_spans` | Find spans by tool name, file path, "denied", … |
+| `failure_report` | Find actionable, bounded, redacted errors and failed tool calls. |
+| `tool_stats` | Rank tools by volume, error rate, denials, and latency. |
+| `security_audit` | Audit caller identity, tenant, server provenance, risk, and approval evidence. |
+| `recent_activity` | Poll new spans with a cursor while a run is active. |
+| `compare_runs` | Compare selected traces for regressions across models or versions. |
+
+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.
+- **bounded output**: diagnostics are truncated and obvious credentials are redacted before query results leave the server.
+- **honest cost totals**: `token_usage` returns `cost_known: false` and a null cost when any producer marks pricing as unavailable; unknown pricing is never presented as `$0`.
+- **cursor polling**: `recent_activity` makes the snapshot reader useful while a run is still writing spans.
+- The demo fixture ([`examples/example_trace.jsonl`](examples/example_trace.jsonl)) is a *real* agent-harness run, not hand-written.
+
+## Honest limitations
+
+- stdio transport only (Streamable HTTP plus authenticated remote access is the next transport boundary)
+- live polling re-reads snapshots; it is not a push subscription
+- security audit can only report identity/provenance that the trace producer records
+- read-only tools; trace mutation (annotations) is roadmap
+- The Python query and server modules are available as `mcp_trace`; older import and command aliases remain for existing clients.
+
+## License
+
+MIT

mcp_trace_inspector-0.3.0/README.md

@@ -0,0 +1,135 @@
+# mcp-trace-inspector
+
+<!-- mcp-name: io.github.abhishekash/mcp-trace-inspector -->
+
+[![CI](https://github.com/abhishekash/mcp-trace-inspector/actions/workflows/ci.yml/badge.svg)](https://github.com/abhishekash/mcp-trace-inspector/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+mcp-trace-inspector is a small, local-first stdio MCP server for querying JSONL
+OpenTelemetry spans emitted by agent runs. It exposes focused queries for
+run summaries, tool failures, approvals, activity, and comparisons instead of
+requiring an application-specific dashboard.
+
+It pairs with [agent-harness](https://github.com/abhishekash/agent-harness),
+but the reader is format-simple: any JSONL of OTel-shaped spans works. The
+project's concrete origin was a shell-boundary regression: the harness blocked
+`cat ../outside.txt`, but the old trace recorded only that `run_shell` was
+called, not the returned diagnostic. mcp-trace-inspector and the harness now preserve and
+query that bounded error.
+
+## AI-native use cases
+
+| Question during an agent run | MCP tool | Evidence returned |
+|---|---|---|
+| "Why did yesterday's run stall?" | `list_runs` → `slowest_spans` | Run IDs and the longest model or tool spans. |
+| "Did the agent act after I denied the write?" | `approval_log` → `span_tree` | The recorded decision and subsequent execution path. |
+| "How many model tokens did this run use?" | `token_usage` → `span_tree` | Run-level usage totals and the span tree for context. |
+| "Which tool is failing or timing out?" | `failure_report` / `tool_stats` | Redacted diagnostics, error rates, denials, and p95 latency. |
+| "Who/what was allowed to act?" | `security_audit` | Caller, tenant, server provenance, risk, and missing-evidence findings. |
+| "What is happening in the run right now?" | `recent_activity` | Cursor-based polling of newly written spans. |
+| "Did this model/version regress?" | `compare_runs` | Cost, latency, tokens, tool calls, and failure deltas. |
+
+The tools read stored traces and can poll files being written, but they do not push events or infer intent from the final answer. Start with the [installation and user guide](docs/user-guide.md), then see the [real trace fixture](examples/example_trace.jsonl) and the [tool descriptions](src/mcp_trace/server.py) for the query contract.
+
+## Install & run
+
+```bash
+uvx mcp-trace-inspector --trace-dir ./traces
+# or, for local development:
+git clone https://github.com/abhishekash/mcp-trace-inspector
+cd mcp-trace-inspector && uv pip install -e .
+mcp-trace-inspector --trace-dir ./traces
+```
+
+## Client configuration
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-traces": {
+      "command": "uvx",
+      "args": ["mcp-trace-inspector", "--trace-dir", "/path/to/traces"]
+    }
+  }
+}
+```
+
+**pi** (`~/.pi/agent/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-traces": {
+      "command": "uvx",
+      "args": ["mcp-trace-inspector", "--trace-dir", "/path/to/traces"]
+    }
+  }
+}
+```
+
+**agent-harness** (mounted as gated tools):
+
+```bash
+harness run "Why was my last run slow?" --mcp "uvx mcp-trace-inspector --trace-dir ./traces"
+```
+
+## Tools
+
+| Tool | Use it when |
+|---|---|
+| `list_runs` | Starting out — recent runs with task, model, duration, cost, decision counts |
+| `run_summary` | One 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_log` | HITL audit — every approve/deny/**edit**, who decided, and *the rationale* |
+| `token_usage` | Cost questions — aggregated across runs or per-run |
+| `search_spans` | Find spans by tool name, file path, "denied", … |
+| `failure_report` | Find actionable, bounded, redacted errors and failed tool calls. |
+| `tool_stats` | Rank tools by volume, error rate, denials, and latency. |
+| `security_audit` | Audit caller identity, tenant, server provenance, risk, and approval evidence. |
+| `recent_activity` | Poll new spans with a cursor while a run is active. |
+| `compare_runs` | Compare selected traces for regressions across models or versions. |
+
+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.
+- **bounded output**: diagnostics are truncated and obvious credentials are redacted before query results leave the server.
+- **honest cost totals**: `token_usage` returns `cost_known: false` and a null cost when any producer marks pricing as unavailable; unknown pricing is never presented as `$0`.
+- **cursor polling**: `recent_activity` makes the snapshot reader useful while a run is still writing spans.
+- The demo fixture ([`examples/example_trace.jsonl`](examples/example_trace.jsonl)) is a *real* agent-harness run, not hand-written.
+
+## Honest limitations
+
+- stdio transport only (Streamable HTTP plus authenticated remote access is the next transport boundary)
+- live polling re-reads snapshots; it is not a push subscription
+- security audit can only report identity/provenance that the trace producer records
+- read-only tools; trace mutation (annotations) is roadmap
+- The Python query and server modules are available as `mcp_trace`; older import and command aliases remain for existing clients.
+
+## License
+
+MIT

mcp_trace_inspector-0.3.0/docs/user-guide.md

@@ -0,0 +1,204 @@
+# mcp-trace-inspector user guide
+
+mcp-trace-inspector lets an MCP client ask questions about an agent's recorded traces.
+Point it at a directory of JSONL span records, connect it to an MCP client, and
+ask about a run's tool calls, failures, approvals, timing, or token usage.
+
+## What it helps with
+
+Use mcp-trace-inspector when you want to:
+
+- Find a slow model or tool call without reading every trace line.
+- See recorded tool failures and bounded diagnostic messages.
+- Review approval decisions, including denials and edited calls.
+- Compare recorded latency, tokens, tool calls, and failures across runs.
+- Keep traces on your own machine and query them from an MCP-capable client.
+
+mcp-trace-inspector is a read-only trace viewer. It does not run, change, retry, or stop
+the agent being observed. Live activity is returned by polling the trace files;
+there is no push stream. Results describe evidence in the traces. Missing
+identity or approval fields mean the producer did not record that evidence;
+they do not prove a person or policy authorized an action.
+
+## Requirements
+
+- Python 3.11 or newer.
+- An MCP client that can launch a local stdio server.
+- JSONL traces in the project's OTel-shaped span format. The reader expects each
+  line to contain a span with `trace_id`, `span_id`, `name`,
+  `start_unix_nano`, `end_unix_nano`, `attributes`, and, where available,
+  `parent_span_id`, `status`, and `events`. Tool, model, and approval details
+  depend on the attributes your trace producer records.
+
+The bundled example trace works immediately. Other producers may need an
+export adapter to map their OTel export format into these JSONL span records.
+
+## Install and start
+
+The simplest option is `uvx`, which runs the published package without a
+project checkout:
+
+```bash
+uvx --from mcp-trace-inspector==0.3.0 mcp-trace-inspector --trace-dir /absolute/path/to/traces
+```
+
+The server speaks MCP over standard input and output, so this command waits for
+an MCP client. Its startup message goes to standard error. To use a different
+trace directory, change `/absolute/path/to/traces` to the directory containing
+your `.jsonl` files. Relative paths are resolved from the server's working
+directory.
+
+For a local development install:
+
+```bash
+git clone https://github.com/abhishekash/mcp-trace-inspector.git
+cd mcp-trace-inspector
+uv pip install -e .
+mcp-trace-inspector --trace-dir /absolute/path/to/traces
+```
+
+You can also set `MCP_TRACE_DIR` and omit `--trace-dir`:
+
+```bash
+MCP_TRACE_DIR=/absolute/path/to/traces uvx --from mcp-trace-inspector==0.3.0 mcp-trace-inspector
+```
+
+The server is local and read-only. Connecting an MCP client gives that client
+access to trace-derived information, including task text and recorded tool
+diagnostics. Choose a trace directory appropriate for the client that will
+query it.
+
+## Connect an MCP client
+
+Configure the client to launch `uvx` with the package and trace directory.
+Restart or reload its MCP connections after saving the configuration.
+
+For clients using the `mcpServers` JSON format, the entry looks like this:
+
+```json
+{
+  "mcpServers": {
+    "mcp-trace-inspector": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "mcp-trace-inspector==0.3.0",
+        "mcp-trace-inspector",
+        "--trace-dir",
+        "/absolute/path/to/traces"
+      ]
+    }
+  }
+}
+```
+
+Use the configuration file and field names documented by your MCP client. For
+example, clients can place MCP server entries in user-level or project-level
+settings. Use an absolute trace path so the server does not depend on the
+client's working directory.
+
+With the mcp-trace-inspector repository checked out locally, run the server directly:
+
+```json
+{
+  "mcpServers": {
+    "mcp-trace-inspector": {
+      "command": "/absolute/path/to/mcp-trace-inspector/.venv/bin/mcp-trace-inspector",
+      "args": ["--trace-dir", "/absolute/path/to/traces"]
+    }
+  }
+}
+```
+
+On Windows, use the executable path from your virtual environment, commonly
+`C:\\path\\to\\mcp-trace-inspector\\.venv\\Scripts\\mcp-trace-inspector.exe`.
+
+## First questions to ask
+
+Start with `list_runs` to find a recent trace. It returns a shortened trace ID;
+the other tools accept ID prefixes.
+
+Try these prompts in your MCP client:
+
+```text
+List the recent runs and tell me which one had a failure.
+For trace <prefix>, show the tool failures and their diagnostics.
+For trace <prefix>, show each approval decision and why it was made.
+For trace <prefix>, what were the three slowest spans?
+Compare traces <prefix-a> and <prefix-b>. Did tokens, latency, or failures change?
+```
+
+The model chooses which tools to call. Ask for the trace IDs and returned
+evidence in its answer so you can check the result against the source data.
+
+## Tool reference
+
+| Tool | What it returns | Useful question |
+|---|---|---|
+| `list_runs` | Recent run summaries with shortened trace IDs | “What ran recently?” |
+| `run_summary` | Task, model, duration, calls, tokens, cost, outcome | “What happened in this run?” |
+| `span_tree` | Nested spans, durations, selected attributes, event names | “What was the execution sequence?” |
+| `slowest_spans` | Longest spans across runs or one trace | “Where did this run spend time?” |
+| `approval_log` | Decision, approver, rationale, and whether an edit was recorded | “What did the reviewer approve or deny?” |
+| `token_usage` | Token totals and cost when producer pricing is known | “How much model usage did these runs record?” |
+| `search_spans` | Spans whose names or attributes contain a search phrase | “Find calls involving `write_file`.” |
+| `failure_report` | Bounded, redacted errors and failed calls | “Why did this tool fail?” |
+| `tool_stats` | Call volume, errors, denials, and latency by tool | “Which integration has the most errors?” |
+| `security_audit` | Recorded identity, tenant, server, risk, and approval evidence | “Which provenance fields were recorded?” |
+| `recent_activity` | Newly written spans after a polling cursor | “What new spans appeared?” |
+| `compare_runs` | Per-run metrics and deltas from the first trace | “What changed between these runs?” |
+
+## Connect agent-harness
+
+mcp-trace-inspector can run as a stdio MCP server mounted by `agent-harness`:
+
+```bash
+harness run "Inspect the last run and explain its failure" \
+  --mcp "uvx --from mcp-trace-inspector==0.3.0 mcp-trace-inspector --trace-dir ./traces" \
+  --approve cli
+```
+
+The harness treats mounted MCP tools as execute-risk by default, so its
+interactive approval mode asks before invoking them. Read the harness's MCP
+and approval documentation for its current policy options.
+
+## Troubleshooting
+
+**The client says the server is unavailable.** Confirm that `uvx` is installed,
+the package can be fetched, and the configured trace path exists. Reload the
+client's MCP configuration and check its server logs; the server writes its
+startup message to standard error.
+
+**No runs appear.** Check that the path points to a directory
+containing `.jsonl` files. The server searches subdirectories. The included
+example is at `examples/example_trace.jsonl` in the repository.
+
+**Runs appear, but model or approval details are missing.** The server only
+reports fields present in the trace. Check whether your producer exports model
+names, token counts, cost-known status, tool call spans, and approval events.
+Missing fields are not inferred from the final answer.
+
+**The JSONL is rejected.** Each line must be a JSON object representing one
+span with the required trace ID, span ID, name, and start and end timestamps.
+Ask your tracing exporter to produce one span object per line.
+
+## Privacy and limits
+
+mcp-trace-inspector processes the files in the configured directory and returns selected
+trace fields to the connected MCP client. Failure messages are bounded and
+credential patterns are redacted, but redaction is not a guarantee that every
+private value is removed. Review trace contents and client access before using
+it with sensitive data.
+
+The current server uses local stdio transport. It polls stored files for new
+spans rather than receiving push events. `security_audit` summarizes recorded
+identity and provenance; it does not independently verify them. Cost totals
+are unknown when the trace producer does not provide reliable pricing.
+
+## Example data
+
+Try mcp-trace-inspector against the checked-in
+[example trace](../examples/example_trace.jsonl). It contains a run emitted by
+`agent-harness` and can be queried using the tools above.
+
+[Back to the README](../README.md)

mcp_trace_inspector-0.3.0/examples/example_trace.jsonl

@@ -0,0 +1,15 @@
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "047527cfe5a06b79", "parent_span_id": "b3870190725e6c0a", "name": "llm.complete", "start_unix_nano": 1791446657381364374, "end_unix_nano": 1791446657381395204, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 92, "llm.usage.output_tokens": 9, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "cf9ec887533385eb", "parent_span_id": "b3870190725e6c0a", "name": "tool.call", "start_unix_nano": 1791446657381557076, "end_unix_nano": 1791446657381753320, "status": "UNSET", "attributes": {"tool.name": "list_dir", "tool.risk": "read", "tool.call_id": "call_1d4b88534934", "tool.duration_ms": 0.17095799557864666}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "b3870190725e6c0a", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657381336939, "end_unix_nano": 1791446657381830109, "status": "UNSET", "attributes": {"step.index": 1}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "3a1883f304c6810a", "parent_span_id": "060258fcbbc7b4b2", "name": "llm.complete", "start_unix_nano": 1791446657381913540, "end_unix_nano": 1791446657381938066, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 94, "llm.usage.output_tokens": 9, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "ec96e325ccf2812b", "parent_span_id": "060258fcbbc7b4b2", "name": "tool.call", "start_unix_nano": 1791446657382001356, "end_unix_nano": 1791446657382097431, "status": "UNSET", "attributes": {"tool.name": "read_file", "tool.risk": "read", "tool.call_id": "call_e67e16d926b0", "tool.duration_ms": 0.08226605132222176}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "060258fcbbc7b4b2", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657381892888, "end_unix_nano": 1791446657382146922, "status": "UNSET", "attributes": {"step.index": 2}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "b07c48a63a82f767", "parent_span_id": "0bd568f46e01fc65", "name": "llm.complete", "start_unix_nano": 1791446657382220834, "end_unix_nano": 1791446657382241746, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 125, "llm.usage.output_tokens": 9, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "d6bc66fcba6ba958", "parent_span_id": "0bd568f46e01fc65", "name": "tool.call", "start_unix_nano": 1791446657382294447, "end_unix_nano": 1791446657382449645, "status": "UNSET", "attributes": {"tool.name": "write_file", "tool.risk": "write", "tool.call_id": "call_8a5a534020b7", "hitl.required": true, "tool.duration_ms": 0.11282693594694138}, "events": [{"name": "hitl.decision", "time_unix_nano": 1791446657382326440, "attributes": {"hitl.decision": "approve", "hitl.approver": "auto", "hitl.rationale": "auto-approved (unattended run)"}}]}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "0bd568f46e01fc65", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657382193796, "end_unix_nano": 1791446657382508737, "status": "UNSET", "attributes": {"step.index": 3}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "70d5591a02be91d6", "parent_span_id": "e83a45284010e5c7", "name": "llm.complete", "start_unix_nano": 1791446657382582514, "end_unix_nano": 1791446657382605733, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 132, "llm.usage.output_tokens": 9, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "0f176ff0f2ed3f5f", "parent_span_id": "e83a45284010e5c7", "name": "tool.call", "start_unix_nano": 1791446657382663037, "end_unix_nano": 1791446657384990883, "status": "UNSET", "attributes": {"tool.name": "run_shell", "tool.risk": "execute", "tool.call_id": "call_9a19cc1b4ead", "hitl.required": true, "tool.duration_ms": 2.2949520498514175}, "events": [{"name": "hitl.decision", "time_unix_nano": 1791446657382685591, "attributes": {"hitl.decision": "approve", "hitl.approver": "auto", "hitl.rationale": "auto-approved (unattended run)"}}]}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "e83a45284010e5c7", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657382563796, "end_unix_nano": 1791446657385069850, "status": "UNSET", "attributes": {"step.index": 4}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "7e5dff5291ab7ee6", "parent_span_id": "7523732e099104c7", "name": "llm.complete", "start_unix_nano": 1791446657385145680, "end_unix_nano": 1791446657385168372, "status": "UNSET", "attributes": {"llm.model": "scripted", "llm.usage.input_tokens": 196, "llm.usage.output_tokens": 14, "llm.cost_usd": 0.0}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "7523732e099104c7", "parent_span_id": "aec12b5c51ce2580", "name": "agent.step", "start_unix_nano": 1791446657385127184, "end_unix_nano": 1791446657385204759, "status": "UNSET", "attributes": {"step.index": 5}, "events": []}
+{"trace_id": "f920798dd2558fcb84f9977736432a8b", "span_id": "aec12b5c51ce2580", "parent_span_id": null, "name": "agent.run", "start_unix_nano": 1791446657381269974, "end_unix_nano": 1791446657385251046, "status": "UNSET", "attributes": {"agent.task": "Summarize the workspace's notes into SUMMARY.md, then verify it with ls", "agent.max_steps": 12, "agent.tools": ["list_dir", "read_file", "run_shell", "write_file"], "agent.skills": [], "llm.model": "scripted", "agent.steps": 5, "agent.stopped_reason": "completed", "agent.usage.input_tokens": 639, "agent.usage.output_tokens": 50, "agent.cost_usd": 0.0, "agent.approvals": 2}, "events": []}