nntrivi2001
4aae61297f
Analytics parity phases 2–7 (docs/plans/analytics-parity/), built on
138e706 and ported onto v2.3.1:
- Cost by AI tool (?tool= on cost/analytics/stats/workflows, by_tool,
Codex fast/priority and flex tiers, agenthub_cost_usd_total{tool,model})
- Date ranges (from/to) on cost/analytics/workflows; Analytics range select
with Today / This week (Monday) / This month (1st) / 7d / 30d / 90d / All /
Custom; workflow filters carried into workflow-stats.js (read worker)
- Budgets and cost alerts as alert rule types (alert_rules rebuilt without
its rule_type CHECK), GET /api/budgets/status, rule preview, spend pace,
status-bar budget chip; rules stay editable in place
- Query Explorer (/query, allowlisted sort, CSV/JSON export) and scheduled
reports (report_definitions/report_runs, Settings → Reports)
- Session Replay tab and immutable snapshots (session_snapshots, /snapshot/:token)
- Remote Codex sync, push ingest with a hashed token, privacy redaction and
ignored folders (Settings → Data), Cursor sessions (no cost)
- Read-only MCP server, statusline, Grafana/Prometheus files
Also: resizable sidebar, pet run/wave animations, the workspace home keeps a
half-typed prompt, and the pre-commit hook runs only the related tests for a
small commit.
87 lines
3.9 KiB
Markdown
87 lines
3.9 KiB
Markdown
# AgentHub MCP server
|
|
|
|
`mcp/server.js` is a small **read-only** [Model Context Protocol](https://modelcontextprotocol.io)
|
|
server. It lets a Claude Code session (or any MCP client) ask the running
|
|
AgentHub dashboard about sessions, costs, analytics, workspaces and alerts.
|
|
|
|
- Plain Node, no build step and no dependency: JSON-RPC 2.0 over stdio, one JSON
|
|
message per line (`initialize`, `ping`, `tools/list`, `tools/call`).
|
|
- Every tool is ONE `GET` against the dashboard's HTTP API, so its numbers are
|
|
the dashboard's own. It never opens the database and has no write tool.
|
|
- The dashboard must be running (`agenthub start`). A tool called while it is
|
|
down answers an `isError` result saying so.
|
|
|
|
## Enable it
|
|
|
|
The plugin does **not** register the server by itself — every registered MCP
|
|
server adds its tool list to every session's context, so it is opt-in:
|
|
|
|
```bash
|
|
# Plugin install or checkout with `agenthub` on PATH
|
|
claude mcp add agenthub -- agenthub mcp
|
|
|
|
# Checkout without the CLI linked
|
|
claude mcp add agenthub -- node /path/to/AgentHub/mcp/server.js
|
|
```
|
|
|
|
Add `--scope user` to make it available in every project. Remove it with
|
|
`claude mcp remove agenthub`. On a plugin install, `agenthub` is the
|
|
`~/.local/bin/agenthub` launcher the bootstrap keeps pointed at the current
|
|
build, so the registration survives plugin updates.
|
|
|
|
## Which dashboard it talks to
|
|
|
|
| Priority | Source |
|
|
|---|---|
|
|
| 1 | `AGENTHUB_URL` (e.g. `http://127.0.0.1:4821`) |
|
|
| 2 | `CLAUDE_DASHBOARD_PORT` / `DASHBOARD_PORT` |
|
|
| 3 | `~/.claude/.agenthub.json` — the live-dashboard discovery file the CLI uses (`server/lib/dashboard-url.js`) |
|
|
| 4 | `http://127.0.0.1:4820` |
|
|
|
|
When the dashboard sets `DASHBOARD_TOKEN`, give the MCP process the same
|
|
variable (`claude mcp add agenthub -e DASHBOARD_TOKEN=… -- agenthub mcp`); it is
|
|
sent as `Authorization: Bearer`.
|
|
|
|
## Tools
|
|
|
|
Every result is the API's JSON, pretty-printed as text. `tz_offset` is minutes
|
|
from UTC as JavaScript's `getTimezoneOffset()` gives them (UTC+7 → `-420`); when
|
|
left out, the MCP process's own time zone is used.
|
|
|
|
| Tool | Arguments | API |
|
|
|---|---|---|
|
|
| `get_health` | — | `GET /api/health` |
|
|
| `get_info` | — | `GET /api/settings/info` |
|
|
| `get_stats` | `tz_offset`, `tool` | `GET /api/stats` |
|
|
| `get_total_cost` | `tz_offset`, `lane`, `tool` | `GET /api/pricing/cost` |
|
|
| `get_session_cost` | `session_id`*, `tz_offset` | `GET /api/pricing/cost/:id` |
|
|
| `get_lane_cost` | `lane`*, `tz_offset` | `GET /api/pricing/cost?lane=` |
|
|
| `list_sessions` | `q`, `status`, `tool`, `lane`, `limit` | `GET /api/sessions` |
|
|
| `get_session` | `session_id`*, `include_events` | `GET /api/sessions/:id` (`?events=0` unless `include_events`) |
|
|
| `get_session_stats` | `session_id`* | `GET /api/sessions/:id/stats` |
|
|
| `get_analytics` | `tz_offset`, `tool` | `GET /api/analytics` |
|
|
| `get_workflows` | `status`, `tool` | `GET /api/workflows` |
|
|
| `list_alerts` | `unacked`, `limit` | `GET /api/alerts` |
|
|
| `list_lanes` | — | `GET /api/lanes` (workspaces) |
|
|
| `list_pricing` | — | `GET /api/pricing` |
|
|
| `get_budget_status` | — | `GET /api/budgets/status` |
|
|
|
|
`*` = required. `tool` filters by AI CLI (`claude`, `codex`, …) on a dashboard
|
|
that supports the filter and is ignored by one that does not. A route the
|
|
dashboard does not have (`/api/budgets/status` before budgets ship, or any tool
|
|
against an older AgentHub) answers `Not available on this dashboard` — this
|
|
covers both a 404 and the production server's SPA page, which is served with
|
|
200 for any unknown path.
|
|
|
|
## Errors
|
|
|
|
- Dashboard unreachable, an API error (`HTTP 404: Session not found`), a missing
|
|
required argument or an unknown tool → a tool result with `isError: true`.
|
|
- Unknown JSON-RPC method → error `-32601`; a line that is not JSON → `-32700`.
|
|
|
|
## Tests
|
|
|
|
`server/__tests__/mcp-server.test.js` drives the server over stdio against a
|
|
fake API; `server/__tests__/mcp-server-live.test.js` calls every tool against a
|
|
real in-test dashboard, so a tool whose path drifts from the API fails there.
|