mcp-agenthub-monitor

# AgentHub Monitor

An MCP **App** server: it renders an interactive pipeline dashboard *inside* the host window
(Claude Desktop, Claude Code, and other MCP App–capable clients) instead of returning a wall of text.

The dashboard shows two things side by side:

- **DAG state** — nodes of a pipeline run, grouped into waves, each with its own status.
- **Harness metrics** — scenario pass rate, critical failures, accumulated cost and latency.

Point it at your own pipeline's JSON export and it becomes a live view of your runs. With no
configuration it serves a built-in sample, so the UI is useful the moment you install it.

## Tools

| Tool | What it does | Read-only |
|---|---|---|
| `show_agenthub_monitor` | Renders the dashboard inline in the host | yes |
| `get_status` | Returns the current pipeline state as structured JSON | yes |
| `trigger_action` | Records an action request in the server's own state | no |

**`trigger_action` does not execute anything.** It annotates the server's in-memory state so the
dashboard can show that an action was requested. This server runs no commands, spawns no
processes, and makes no network calls.

## Install

Requires Python 3.10+. No third-party dependencies.

```bash
git clone https://github.com/NEVELSK65/mcp-agenthub-monitor.git
cd mcp-agenthub-monitor
python3 -m unittest discover -s tests    # optional: verify
```

## Configure

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "agenthub-monitor": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp-agenthub-monitor/server.py"],
      "env": {
        "AGENTHUB_STATE_FILE": "/absolute/path/to/your/pipeline-state.json"
      }
    }
  }
}
```

`AGENTHUB_STATE_FILE` is optional. Without it the server returns sample data, flagged with
`is_sample_data: true` so it is never mistaken for a real run.

## State file format

Write this JSON from your own CI, orchestrator, or test harness:

```json
{
  "dag": {
    "title": "Nightly build",
    "total_nodes": 6,
    "completed_nodes": 4,
    "waves": 3,
    "node_states": {
      "node_01_checkout": "COMPLETED",
      "node_02_unit_tests": "COMPLETED",
      "node_03_integration": "RUNNING",
      "node_04_security_scan": "PENDING"
    }
  },
  "harness": {
    "pass_rate_pct": 93.75,
    "total_scenarios": 16,
    "passed_scenarios": 15,
    "critical_failures": 0,
    "total_cost_usd": 0.112,
    "total_latency_ms": 41700
  },
  "log": "Integration stage in progress."
}
```

The file is re-read on every tool call, so the dashboard reflects whatever your pipeline last wrote.
Node status strings are passed through to the UI as-is; `COMPLETED`, `RUNNING`, `PENDING` and
`FAILED` get distinct colours.

## Resource

The UI is exposed as an MCP resource at `ui://agenthub/mcp-app.html` with MIME type
`text/html;profile=mcp-app`. Hosts that support MCP Apps render it inline; hosts that do not can
still read it as an HTML document.

## Privacy

The server reads one local file (the one you name in `AGENTHUB_STATE_FILE`) and sends nothing
anywhere. See [PRIVACY.md](PRIVACY.md).

## License

MIT — see [LICENSE](LICENSE).