feat(ui): maintainer dashboard panel for per-tool MCP usage counts

[galuis116]

Closes #6241

Summary

Part of #6228 (now fully resolved by shipped code — the remote and local PostHog telemetry wrappers, #6355/#6358/#6368, already instrument the MCP tool-dispatch chokepoint on both servers). This is the consumption side: a new McpToolUsageCard maintainer-dashboard panel showing per-tool call counts, success/failure rates, and a local-vs-remote split over a selectable window.

McpToolUsageCard is wired into MaintainerPanel's qualityDashboard.mcpToolUsage (a new, optional field), rendered right after GateOutcomeCard. The backend aggregation that would populate this field from the already-shipped PostHog telemetry is tracked separately and not built here — per the issue's own text, this panel is "buildable and testable against a defined mock data shape even before real production data volume exists." Matching AcceptanceRateCard's own established precedent in this exact codebase, the card assumes mcpToolUsage may be absent from the dashboard payload today and degrades to a "not yet available" empty state (distinct from the "payload exists but zero tools called" empty state) rather than assuming a value or blocking this issue on that aggregation shipping first.

• Uses AnalyticsCardShell for chrome/state handling (loading/empty/ready), matching every other card in this folder.
• The per-tool breakdown table follows activation-preview.tsx's established accessible-table pattern: TableScroll's keyboard-focusable labelled region, a sr-only caption, and scope="col" headers.
• Success rate is successCount / callCount, rendered as — (never divides by zero) when a tool has zero calls.
• No wallet/hotkey/reward/trust-score wording anywhere — this is a private, aggregate-only maintainer surface, same constraint every other card in this folder already follows.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused (UI-only, under apps/loopover-ui/**) and does not mix unrelated backend, MCP, docs, or deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves — Closes feat(ui): maintainer dashboard panel for per-tool MCP usage counts #6241.

Validation

• npm --workspace @loopover/ui run typecheck — clean.
• npm run ui:lint — 0 errors, only pre-existing warnings in unrelated files.
• npm --workspace @loopover/ui run test (full workspace) — 48 files, 300 tests, all passing.
• New mcp-tool-usage-card.test.tsx (6 tests): both empty-state variants (payload absent vs. payload present with zero tools), row rendering + sort order + success-rate math, the zero-calls divide-by-zero guard, the TableScroll a11y wiring, and the forbidden-terms sweep.
• Added 2 new tests to maintainer-panel.test.tsx verifying the real wiring — not just the isolated component: renders the empty state when mcpToolUsage is absent from the dashboard payload, and renders real per-tool rows when it's present. Verified both genuinely fail without the <McpToolUsageCard> render call via git stash on maintainer-panel.tsx, then restored and re-confirmed passing.
• git diff --check
• npm run actionlint
• npm run docs:drift-check / manifest:drift-check / command-reference:check
• npm audit --audit-level=moderate — 0 vulnerabilities.
• Root npm run typecheck / npm run test:coverage — this sandbox's root tsc --noEmit reliably OOMs regardless of diff content (reproduced repeatedly this session); the workspace-scoped @loopover/ui typecheck (clean) plus the full workspace test run (300/300 passing) cover this diff's actual surface. apps/** is excluded from Codecov's coverage.include, so no codecov/patch check applies to this diff, per the issue's own Test Coverage Requirements.

If any required check was skipped, explain why:

• Root typecheck/test:coverage: established OOM pattern in this sandbox, unrelated to diff content; superseded by the scoped checks above.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. — N/A, no such changes; this panel is gated by MaintainerPanel's existing role check, unchanged.
• API/OpenAPI/MCP behavior is updated and tested where needed. — N/A, no new API/MCP surface; mcpToolUsage is a new optional field on an existing response type, with no backend change in this PR (per the issue's own UI-only scope).
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — The card renders from data.qualityDashboard.mcpToolUsage, the real dashboard payload; when the backend hasn't populated that field yet it shows a real, honest "not yet available" empty state (not a fabricated demo value), matching AcceptanceRateCard's identical, already-reviewed pattern.
• Visible UI changes include a UI Evidence section below with screenshots. — See below.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. — CHANGELOG.md untouched.

UI Evidence

A new card titled "MCP tool usage" appears in the maintainer dashboard's quality section, directly after "Gate outcomes." With no data it shows the shared EmptyState ("Not yet available" / a description explaining the field isn't populated yet); with data it shows a 30d window pill and a table of tool name / calls / success rate / local / remote, sorted by call count descending. ui:build couldn't run in this sandbox (a pre-existing, unrelated @scalar/api-reference resolution failure reproduced on clean main) to produce a live screenshot; covered instead by the new render tests asserting the exact rendered rows and empty-state copy.

Notes

The backend aggregation populating qualityDashboard.mcpToolUsage from the already-shipped PostHog telemetry (#6235/#6236/#6358) is a natural follow-up issue, not built here per this issue's explicit UI-only scope.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-16 13:20:49 UTC}

4 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a self-contained McpToolUsageCard maintainer panel wired into MaintainerPanel via a new optional qualityDashboard.mcpToolUsage field, following the existing AcceptanceRateCard/QueueHealthCard pattern of a two-tier empty state (payload absent vs. payload present with zero tools). The success-rate math is null-safe (successRate returns null for callCount 0, formatted as "—"), the table follows the established accessible-table pattern with TableScroll/scope=col/sr-only caption, and tests cover both empty states, sorting, the zero-division case, and the a11y region. Since this is a pure consumption-side UI component with no backend aggregation shipped yet, correctness here is really about rendering logic given a mock shape, which the tests exercise reasonably well.

Nits — 5 non-blocking

• mcp-tool-usage-card.tsx: the sort `[...usage.tools].sort((a, b) => b.callCount - a.callCount)` doesn't tie-break on tool name, so tools with equal callCount may render in a non-deterministic/input-order-dependent sequence across re-renders — consider a secondary sort key.
• The PR description says backend aggregation is 'tracked separately,' but the diff doesn't link to that follow-up issue number, so it's hard to confirm this consumption-only scope has an agreed producer-side counterpart in flight.
• maintainer-panel.tsx is now at ~448 lines per the size-smell note, past the file's own 400-line convention threshold — consider whether MaintainerDashboardView's card list should be split out.
• mcp-tool-usage-card.tsx has no visual indication for the failureCount field defined in McpToolUsageEntry — it's collected but never rendered in the table, which is dead data for this view unless intentional for a future column.
• Add a tie-breaker (e.g. by tool name) to the sort in mcp-tool-usage-card.tsx:36 for deterministic ordering when call counts are equal.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#6241
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 1945 registered-repo PR(s), 1279 merged, 54 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	galuis116; Gittensor profile; 1945 PR(s), 54 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The PR adds a new McpToolUsageCard panel wired into MaintainerPanel showing per-tool call counts, success/failure rate (safe against div-by-zero), and local/remote split over a windowDays value, using AnalyticsCardShell and the accessible-table pattern as requested, with tests mocking the usage-data shape including presence/absence and empty states.

Review context

• Author: galuis116
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 1945 PR(s), 54 issue(s).
• Related work: Titles/paths share 3 meaningful terms. (issue #6504, issue #642)
• Related work: Titles/paths share 3 meaningful terms. (issue #5963, issue #642)
• Related work: Titles/paths share 3 meaningful terms. (issue #642, issue #5229)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Start here: Review top overlaps.
• Then work through the remaining 2 steps in the Signals table above.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop	before /	after /	diff /
/	mobile	before / (mobile)	after / (mobile)	—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy · Diff highlights exactly what changed.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.