90 lines
4.0 KiB
Markdown
90 lines
4.0 KiB
Markdown
|
# MCP Status Panel — Implementation Plan
|
|||
|
|
|
|||
|
|
Spec: `docs/superpowers/specs/2026-08-03-mcp-status-panel-design.md`
|
|||
|
|
|
|||
|
|
Backend first (tests alongside), then frontend, then verify. Each task is
|
|||
|
|
independently reviewable.
|
|||
|
|
|
|||
|
|
## Task 1 — `app/mcp/stats.py`
|
|||
|
|
|
|||
|
|
- [x] `MCPToolStats` dataclass: `calls: int = 0`, `errors: int = 0`,
|
|||
|
|
`total_duration_ms: float = 0.0`, `last_called_at: datetime | None = None`;
|
|||
|
|
`avg_duration_ms` property returning `None` when `calls == 0`.
|
|||
|
|
- [x] `MCPStatsTracker` with `threading.Lock`, `record(tool, duration_ms, success)`,
|
|||
|
|
`snapshot()` returning a shallow copy.
|
|||
|
|
- [x] `record()` wraps its body in `try/except Exception` → `logger.warning`, never raises.
|
|||
|
|
- [x] `get_mcp_stats_tracker()` with `@lru_cache`.
|
|||
|
|
- [x] Module docstring + at least one `#` comment (AGENTS.md).
|
|||
|
|
|
|||
|
|
## Task 2 — `backend/tests/mcp/test_mcp_stats.py`
|
|||
|
|
|
|||
|
|
- [x] 8 threads × 100 `record()` calls → `calls == 800` exactly.
|
|||
|
|
- [x] `avg_duration_ms` is `None` at zero calls, correct mean afterwards.
|
|||
|
|
- [x] `success=False` increments `errors` and `calls`.
|
|||
|
|
- [x] `record()` with a non-numeric duration logs and does not raise.
|
|||
|
|
|
|||
|
|
## Task 3 — instrument `app/mcp/server.py`
|
|||
|
|
|
|||
|
|
- [x] Wrap `search_regulations` body: `time.perf_counter()` start,
|
|||
|
|
`try/except` records `success=False` and re-raises, `finally` not needed
|
|||
|
|
once both branches record.
|
|||
|
|
- [x] `async def get_mcp_status(public_url: str) -> dict` returning
|
|||
|
|
`{endpoint_url, auth_required, allowed_hosts, tools: [...]}` where each
|
|||
|
|
tool is `{name, description, calls, errors, avg_duration_ms, last_called_at}`.
|
|||
|
|
- [x] `allowed_hosts` parsed from `settings.mcp_allowed_hosts` with the same
|
|||
|
|
split/strip logic `_build_transport_security()` already uses.
|
|||
|
|
- [x] `last_called_at` serialized as ISO-8601 string or `None`.
|
|||
|
|
|
|||
|
|
## Task 4 — `mcp_public_url` setting
|
|||
|
|
|
|||
|
|
- [x] `app/config/settings.py`: `mcp_public_url: str = ""` in the existing `# ── MCP ──` block.
|
|||
|
|
- [x] `.env.example`: documented under the existing MCP section, in Chinese,
|
|||
|
|
with the `http://6.86.80.9:8000/mcp/` example and a note that it is only
|
|||
|
|
needed when a proxy rewrites `Host`.
|
|||
|
|
|
|||
|
|
## Task 5 — `GET /status/mcp`
|
|||
|
|
|
|||
|
|
- [x] Add route to `backend/app/api/routes/status.py`, taking `request: Request`.
|
|||
|
|
- [x] `public_url = settings.mcp_public_url or f"{str(request.base_url).rstrip('/')}/mcp/"`.
|
|||
|
|
- [x] Delegate to `get_mcp_status()`; no MCP internals in the route.
|
|||
|
|
|
|||
|
|
## Task 6 — `backend/tests/mcp/test_mcp_status.py`
|
|||
|
|
|
|||
|
|
- [x] Tool advertised with zeroed stats before any call.
|
|||
|
|
- [x] Stats reflected after `record()`.
|
|||
|
|
- [x] `auth_required` follows a patched `settings.auth_enabled`.
|
|||
|
|
- [x] `public_url` passes through unmodified.
|
|||
|
|
|
|||
|
|
## Task 7 — frontend types + client
|
|||
|
|
|
|||
|
|
- [x] `frontend/src/api/index.ts`: `MCPToolEntry`, `MCPStatusResponse`.
|
|||
|
|
- [x] `frontend/src/api/status.ts`: `getMCPStatus()` + re-export.
|
|||
|
|
|
|||
|
|
## Task 8 — MCP Server card
|
|||
|
|
|
|||
|
|
- [x] Add `getMCPStatus()` to the existing `Promise.allSettled` batch in
|
|||
|
|
`StatusPage.tsx`, with its own `mcpLoading` state.
|
|||
|
|
- [x] Card below "AI Models": endpoint row + one row per tool.
|
|||
|
|
- [x] Copy-config button: builds the `mcpServers` JSON, embeds the
|
|||
|
|
`localStorage` token when `auth_required`, writes via
|
|||
|
|
`navigator.clipboard.writeText`, and reflects success/failure in its label
|
|||
|
|
for ~2s.
|
|||
|
|
- [x] `handleExport()` includes `mcp`.
|
|||
|
|
- [x] Reuse `card` / `card-header` / `service-row` / `StatusIcon`. No new CSS.
|
|||
|
|
|
|||
|
|
## Task 9 — i18n
|
|||
|
|
|
|||
|
|
- [x] `locales/zh.ts` and `locales/en.ts`: `cardMcp`, `mcpEndpoint`,
|
|||
|
|
`mcpAuthRequired`, `mcpAuthDisabled`, `mcpAllowedHosts`, `mcpCopyConfig`,
|
|||
|
|
`mcpCopied`, `mcpCopyFailed`, `mcpCalls`, `mcpErrors`, `mcpAvgDuration`,
|
|||
|
|
`mcpNoTools`, `mcpUnavailable`.
|
|||
|
|
- [x] Both files must stay structurally identical (`en.ts` is typed against `zh.ts`).
|
|||
|
|
|
|||
|
|
## Task 10 — verify
|
|||
|
|
|
|||
|
|
- [x] `python -m pytest backend/tests -q` — all pass.
|
|||
|
|
- [x] `npm --prefix frontend run lint`.
|
|||
|
|
- [x] `npm --prefix frontend run build`.
|
|||
|
|
- [x] Live check: start uvicorn, `GET /api/v1/status/mcp`, confirm the tool is
|
|||
|
|
listed and counters move after a real MCP `tools/call`.
|