feat(mcp): insights_view MCP App — time-series explorer (KLA-402)

[jklaassenjc]

Summary

• Adds `insights_view` MCP App: interactive Directory Insights time-series with filters, top-users sidebar, and event preview
• Introduces `addToolWithMetaTyped[In]` — generic variant of `addToolWithMeta` so parameterized apps get an auto-derived JSON input schema
• Server aggregates into time buckets (size auto-chosen from window); client just renders
• Stacked on top of #18; rebase to main once that lands

UX

Interactive filter form (service / last / event_type / user), stacked bars by time bucket with legend, top-10-users list alongside. Refresh re-runs the query.

Scope

New:

• `internal/mcp/apps_insights.go` — typed args, fetch + aggregate, registration
• `internal/mcp/apps_html/insights.html` — renderer (uses jcApp scaffolding from refactor(mcp): 1-file-per-app pattern for MCP Apps (KLA-401) #18, no duplicated postMessage)
• `internal/mcp/apps_insights_test.go` — 6 tests covering bucketing, window parsing, aggregation, filter, UI metadata, resource injection

Modified:

• `internal/mcp/apps.go` — adds `addToolWithMetaTyped` helper and calls `registerInsightsView` from `registerAppTools`
• `internal/mcp/tools_test.go` — tool count bumps 195 → 196, adds `insights_view` to expected list

Key design choices

• 10k event cap per call. Directory Insights windows can be millions of events; we use `CountEvents` for the true total and `QueryEvents(Limit: 10000)` for the sample, surfacing a warning when truncated so the UI can flag partial data
• Server-side bucketing keeps the UI bundle small and avoids shipping raw events to the browser. Bucket size auto-picked: 5m / 1h / 6h / 1d depending on window span
• Local duration parsing (`parseLastDuration`) instead of `api.ParseTimeRange` for the `Last` argument, so start/end both anchor on the same `nowFunc` and tests stay deterministic
• `addToolWithMetaTyped` is generic on `In any` so each app declares its own typed args struct (KLA-403..406 will use this too)

Test plan

• `go test ./...` clean — 6 new tests, existing count/tools tests updated
• `go vet ./...` clean
• Live validation of the rendering is deferred until fix(mcp): make MCP Apps render in browser clients (basic-host, claude.ai) #17 + refactor(mcp): 1-file-per-app pattern for MCP Apps (KLA-401) #18 merge and we can point basic-host at a clean main build

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds a new MCP App tool that queries and aggregates Directory Insights events (including time-window parsing and sampling limits), which could affect performance/behavior of Insights calls. Also changes the tool-registration helper to support generic typed inputs, potentially impacting how future tools’ schemas/handlers are derived.

Overview
Introduces a new MCP App, insights_view, that serves a ui://jc/insights HTML dashboard and a parameterized tool to fetch/aggregate Directory Insights events into time buckets with top-user rankings, preview events, and truncation warnings (10k event cap).

Refactors app tool registration by adding generic addToolWithMetaTyped[In] (auto-derived JSON input schema) and keeping addToolWithMeta as a no-args wrapper; registerAppTools now registers this typed-input app explicitly. Tests are added/updated to cover window parsing, bucketing/aggregation, UI metadata/resource injection, and the expected tool list/count.

^{Reviewed by Cursor Bugbot for commit daf3c88. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{Reviewed by Cursor Bugbot for commit e8bdee1. Configure here.}

[jklaassenjc]

Addressed both Bugbot findings on this PR in daf3c88:

• Medium — insights.html initialized flag only flips after a successful render now; a thrown parseToolResult or null payload leaves initialized=false so the setTimeout fallback can recover (previously the UI stuck on the loading spinner with no way out).
• Low — addToolWithMeta now delegates to addToolWithMetaTyped[struct{}], dropping ~25 lines of duplicated wrapper logic. Call sites (s.addToolWithMeta(...)) are unchanged.

The base branch was changed.