feat(analytics): track MCP compatibility adoption

[oktofeesh1]

Summary

Closes #139.

Adds privacy-safe MCP compatibility adoption tracking across the CLI/MCP request path, private analytics APIs, and the operator dashboard.

What changed

• Added bounded MCP package/client/protocol telemetry parsing with unsafe header rejection.
• Sent static MCP package/client/version headers from the CLI API client.
• Recorded MCP telemetry on MCP success and error paths, including compatibility status.
• Added aggregate MCP compatibility adoption summaries for private operator/API analytics.
• Surfaced stale/incompatible MCP client counts and version buckets in the analytics dashboard.
• Regenerated the app OpenAPI snapshot for the new private analytics endpoint.
• Added regression tests for no-leak invariants, endpoint clamps, summary aggregation, CLI headers, and MCP error telemetry.

Why

MCP adoption needs version distribution and stale/incompatible client visibility without storing tokens, local paths, source contents, or raw actor/session identifiers in product analytics.

Validation

• npm run test:unit -- test/unit/mcp-compatibility.test.ts test/unit/product-usage-mcp-adoption.test.ts
• npm run test:unit -- test/unit/mcp-server-telemetry.test.ts
• npm run test:unit -- test/unit/mcp-cli.test.ts
• npm run test:integration -- test/integration/api.test.ts
• npm run test:ci
• Codex Security diff scan: no reportable findings; every final-diff worklist row completed and the markdown/HTML report rendered locally.

Notes

• This branch is stacked after feat(analytics): add privacy-safe usage event spine #182 and feat(analytics): add daily activation rollups #183; it should be reviewed after those analytics foundations land.
• Public output remains aggregate-only and does not expose tokens, local paths, raw actor names, raw session IDs, source contents, wallet/hotkey data, or private scoring context.

[superagent-security]

Superagent found 1 security concern(s).

[superagent-security]

Superagent found 1 security concern(s).

[superagent-security]

Superagent found 1 security concern(s).

P1: New private analytics endpoints lack operator role authorization

Private analytics endpoints omit operator role checks.

Add requireAppRole(c, ["operator"]) guards to both analytics routes before serving data.

AI prompt

Check if this security scanner issue is valid. If so, understand the root cause and fix it. If appropriate, update or add tests. Keep the change focused and preserve intended behavior.

<file name="src/api/routes.ts">
<violation number="1" location="src/api/routes.ts:810">
<priority>P1</priority>
<title>New private analytics endpoints lack operator role authorization</title>
<evidence>The new handlers `GET /v1/app/analytics/mcp-compatibility` and `GET /v1/app/analytics/daily-rollups` are registered without any `requireAppRole` or identity check, while the adjacent `/v1/app/operator-dashboard` explicitly enforces `requireAppRole(c, ["operator"])`. This leaves aggregate adoption data and daily rollups accessible without the intended operator authorization.</evidence>
<recommendation>Add `const forbidden = await requireAppRole(c, ["operator"]); if (forbidden) return forbidden;` at the top of both new analytics route handlers, consistent with the existing operator-dashboard pattern.</recommendation>
</violation>
</file>

[JSONbored]

@oktofeesh1 This is ready from my side. The MCP compatibility adoption tracking is now green and merge-clean against current main.

A few notes:

• The API/OpenAPI/MCP surfaces are updated together.
• CLI telemetry, compatibility service behavior, MCP server telemetry, and adoption aggregation all have targeted tests.
• This should be merged after the rollup foundation if we are keeping the analytics stack ordered cleanly.