Files

T

nntrivi2001 4aae61297f feat: analytics parity — tool cost, date ranges, budgets, query explorer, replay, snapshots (v2.4.0)

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.

2026-10-06 17:12:28 +07:00

3.9 KiB

Raw Blame History

AgentHub MCP server

mcp/server.js is a small read-only Model Context Protocol 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:

# 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.

3.9 KiB Raw Blame History