@uptimizr/mcp 1.1.0 → 1.2.0

package/AGENTS.md

@@ -5,13 +5,18 @@
 
 ## What this package is
 
-A **read-only** Model Context Protocol (MCP) server over an Uptimizr collector's query API. It
-lets an agent query a consumer's **own** 3D analytics in natural language. Each tool maps to one
-documented collector read endpoint; the server is a thin wrapper that holds no business logic and
-performs `GET` requests only (ADR 0005, ADR 0017).
+A Model Context Protocol (MCP) server over an Uptimizr collector's API. It lets an agent query a
+consumer's **own** 3D analytics in natural language. Each analytics tool maps to one documented
+collector read endpoint; the server is a thin wrapper that holds no business logic (ADR 0005,
+ADR 0017).
 
-It connects **only to the collector's HTTP query API** (never to the database directly), so the
-collector remains the single gateway that enforces auth, per-project scoping, and privacy.
+**Events are read-only.** Nothing here can write, alter or delete an analytics event, and there is
+no ingestion tool. The one writable surface is **project metadata** — annotations, the glossary,
+saved analyses and pinned dashboard panels — and it is gated: those tools are registered only when
+the configured key holds the `annotate` capability (ADR 0051 §5/§7/§9). See "Metadata tools" below.
+
+It connects **only to the collector's HTTP API** (never to the database directly), so the collector
+remains the single gateway that enforces auth, per-project scoping, and privacy.
 
 ## Run
 
@@ -19,7 +24,44 @@ collector remains the single gateway that enforces auth, per-project scoping, an
 UPTIMIZR_COLLECTOR_URL="https://collect.example.com" UPTIMIZR_API_KEY="utk_…" npx @uptimizr/mcp
 ```
 
-## Tools (read-only)
+## Required key capability
+
+`UPTIMIZR_API_KEY` must hold the **`query`** capability. Mint one with
+`uptimizr new-key <projectId> --capabilities query --label "mcp-agent"` (`query` is the default).
+`GET /api/v1/whoami` reports what a key holds — the server calls it once at start-up for exactly
+this reason — and an authenticated key missing a capability is refused with `403`, not `401`.
+
+Add **`annotate`** only if you want the agent to leave notes, definitions, saved analyses and
+pinned dashboard panels behind (`--capabilities query,annotate`). Without it the server starts
+read-only and never offers those tools; with it, every write is bounded at the collector's edge and
+recorded in the audit log.
+**`query:raw` is optional, and off by default.** Every tool in the default catalog is an aggregate
+read: there is no raw per-session, replay or live-follow tool, so a plain `query` key is all most
+deployments should grant. A key that _does_ hold `query:raw` additionally gets the
+**`session_narrative`** tool — an ordered, bounded account of what one session did — but only when
+the server was told about the capability, and only on a collector running with
+`ENABLE_RAW_SESSION_RETENTION`. `createMcpServer(client, { capabilities })` takes the set that
+`GET /api/v1/whoami` reports; the `uptimizr-mcp` binary looks it up at start-up (best effort — if
+the call fails it serves the `query` surface). Omitting the option serves the `query` surface too,
+so a tool that would always answer `403` is never advertised. `annotate` (metadata writes) and
+`ingest` are never used here. Prefer a dedicated, labelled key with its own `--rate-limit-max` /
+`--rate-limit-window-ms` budget: the collector's agent audit log records activity per key id, which
+is what makes an agent's reads reviewable.
+
+## Transports
+
+`createMcpServer()` is transport-agnostic, and two transports serve the identical catalog,
+resources and prompts:
+
+- **stdio** — what this package's `bin` runs (`npx @uptimizr/mcp`), launched by a desktop client.
+- **Collector-hosted Streamable HTTP** — a collector started with `COLLECTOR_MCP_HTTP=1` serves the
+  same server at `POST`/`GET`/`DELETE` `/mcp` (ADR 0051 §7). A remote client connects with a URL
+  plus `x-api-key` or `Authorization: Bearer <key>` — no local install — and every request is
+  re-authenticated, capped by `COLLECTOR_MCP_MAX_SESSIONS` and charged to the key's rate limit.
+  Tool calls are audited with `surface: "mcp-http"`; this package's own reads are plain HTTP reads
+  and are audited as `http`.
+
+## Analytics tools (read-only)
 
 <!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this table -->
 
@@ -29,22 +71,31 @@ UPTIMIZR_COLLECTOR_URL="https://collect.example.com" UPTIMIZR_API_KEY="utk_…"
 `position_heatmap`, `session_trajectory`, `aggregate_paths`, `scene_coverage`, `camera_distance`,
 `click_rays`, `flow_links`, `top_meshes`, `mesh_sources`, `mesh_trend`, `mesh_dwell`,
 `mesh_blind_spots`, `mesh_interaction_kinds`, `mesh_reachability`, `dead_clicks`, `rage_clicks`,
-`hover_dwell`, `interaction_sources`, `top_input_actions`, `camera_gestures`, `navigation_stats`,
-`backtrack_ratio`, `perf_summary`, `render_scale_truth`, `perf_distribution`, `fps_histogram`,
-`frame_time_percentiles`, `jank_rate`, `perf_churn`, `perf_by_device`, `perf_by_scene`,
-`perf_heatmap`, `compile_stalls`, `resource_summary`, `resource_percentiles`, `stability_counts`,
-`graphics_diagnostics`, `error_heatmap`, `rendering_technology`, `capability_changes`,
-`xr_rotation`, `xr_sources`, `xr_abandonment`, `xr_locomotion`, `xr_tracking_quality`,
-`boundary_heatmap`, `boundary_heatmap_stats`, `xr_boundary_contacts`,
-`ar_placement_time_to_place`, `ar_placement_attempts`, `ar_placement_surfaces`, `funnel`,
-`scene_retention`, `load_bounce_funnel`, `variant_leaderboard`
+`hover_dwell`, `interaction_sources`, `top_input_actions`, `custom_event_vocabulary`,
+`camera_gestures`, `navigation_stats`, `backtrack_ratio`, `perf_summary`, `render_scale_truth`,
+`perf_distribution`, `fps_histogram`, `frame_time_percentiles`, `jank_rate`, `perf_churn`,
+`perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_summary`,
+`resource_percentiles`, `stability_counts`, `graphics_diagnostics`, `error_heatmap`,
+`rendering_technology`, `capability_changes`, `xr_rotation`, `xr_sources`, `xr_abandonment`,
+`xr_locomotion`, `xr_tracking_quality`, `boundary_heatmap`, `boundary_heatmap_stats`,
+`xr_boundary_contacts`, `ar_placement_time_to_place`, `ar_placement_attempts`,
+`ar_placement_surfaces`, `funnel`, `scene_retention`, `load_bounce_funnel`, `variant_leaderboard`,
+`insight_baseline`, `insight_movers`, `insight_anomalies`, `insight_significance`,
+`insight_scene_health`
+
+Only on a key holding `query:raw`, and only when the collector runs with
+`ENABLE_RAW_SESSION_RETENTION` (ADR 0003):
+
+`session_narrative`
 
 <!-- generated:registry-tool-names:end -->
 
-**69 tools, generated** from the `@uptimizr/metrics` semantic metric registry (ADR 0051 §1) — one per
-metric the collector serves on a read endpoint. Names are the registry ids; the full table lives in
-[README.md](./README.md), and `uptimizr://capabilities` enumerates them at runtime with each tool's
-grain, column units and caveats.
+**75 tools, generated** from the `@uptimizr/metrics` semantic metric registry (ADR 0051 §1) — one
+per metric a plain `query` key may read, plus `session_narrative` above for a `query:raw` key. With
+the `query` DSL tool and `list_subscriptions` below, a `query` key sees **77** tools in all. Names
+are the registry ids; the full table lives in [README.md](./README.md), and
+`uptimizr://capabilities` enumerates them at runtime with each tool's grain, column units and
+caveats.
 
 Orientation: `list_sessions`, `list_scenes`, `session_meta`, `scene_representation`, `timeseries`,
 `event_counts`. Attention: the `*_heatmap` family, `mesh_dwell`, `mesh_blind_spots`, `hover_dwell`.
@@ -59,15 +110,177 @@ Navigation: `aggregate_paths`, `session_trajectory`, `scene_coverage`, `navigati
 `variant_leaderboard`.
 
 Most accept `since`/`until` (epoch ms) plus endpoint-specific filters (`scene`, `session`, `source`,
-`bins`, `cellSize`, `limit`, `cameraMode`, `region`, …). Every tool declares an `outputSchema` and
-returns `structuredContent` (`{ rows }`) alongside the JSON text — read the schema instead of
-guessing the row shape, and read the tool description for the metric's caveats before trusting a
-small sample.
+`bins`, `cellSize`, `limit`, `cameraMode`, `region`, …). Every tool declares an `outputSchema`
+covering all three `format` envelopes and returns the one you asked for as `structuredContent`
+alongside the JSON text — read the schema instead of guessing the row shape, and read the tool
+description for the metric's caveats before trusting a small sample.
+
+## The `query` tool (the query DSL)
+
+One tool is **not** per-metric: `query` (ADR 0051 §3). Its input is the query DSL, so it runs any
+metric in the catalog above with any filter that metric declares:
+
+```jsonc
+{
+  "v": 1,
+  "metric": "mesh_sources",
+  "range": { "since": 1757000000000, "until": 1757600000000 },
+  "filters": { "scene": "lobby", "cameraMode": "first-person" },
+  "limit": 20,
+  "format": "summary",
+}
+```
+
+- **`range` is required** (both ends, epoch ms) — there is no unbounded query.
+- **`format` defaults to `table`** here rather than `full`.
+- The grammar is closed: metrics, dimensions and filters are exactly the vocabulary in the
+  `uptimizr://capabilities` resource. Naming something outside it is a `400` whose
+  `issues[].accepted` lists what would have worked — read it instead of guessing again.
+- `dimensions` may be any subset a metric declares **when** its measure is a portable count —
+  event counts, mesh and interaction tallies, input actions, camera gestures. A spatial heatmap or a
+  percentile is computed at one fixed grain and refuses anything else, naming the grain it supports.
+- **`compare`** — another `{ range }` or `{ segment }`; the result comes back joined on the
+  dimension key as `{ current, previous, delta, deltaPct }`, with a significance test where the
+  measure is a count and both windows clear the metric's minimum. Never subtract two results by hand.
+- **`explain: true`** — the compiled plan instead of the rows: the tier, the SQL with its parameters
+  left unbound, `params` by name and type (never value), `rowsScanned`, and `warnings` (a capture
+  channel that produced nothing, a sample below the metric's minimum, a truncated result).
+- **`drillQuery`** — every row of a `summary` carries the whole query narrowed to that row, ready to
+  send straight back.
+- `order` takes a measure column, and only where the result is a ranked list.
+
+Its `structuredContent` is `{ result }` rather than `{ rows }`, because what comes back depends on
+the `format` asked for.
+
+## Non-metric reads
+
+Alongside the generated per-metric tools, the server registers `list_subscriptions` (ADR 0051
+§6): the project's standing conditional subscriptions, what each watches for, and how each last
+went. It takes no arguments. It is read-only like everything else here — creating or deleting a
+subscription needs the `annotate` capability and is done over plain HTTP, not through MCP.
+
+## Result formats (`format`)
+
+Every **aggregate** tool takes a `format` argument choosing the envelope its rows arrive in
+(ADR 0051 §2). It filters nothing. **Omit it and you get `table`** — the tools' own default,
+sent explicitly, so the HTTP endpoints still default to `full` for every other client.
+
+| `format`  | Returns                                                                                                                                                                                          | Use it when                                                                                  |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `summary` | A bounded digest — `ranked` top rows, a `series` trend, merged spatial `clusters`, or a single `record` — with shares, a sample size, the metric's `caveats` and a templated `reading` sentence. | **Ask for it.** Whenever you do not need every row — always, for a heatmap or a leaderboard. |
+| `table`   | `{ meta, rows }`: the same rows plus the metric, range, applied filters, sample size, row count, a truncation flag and the registry's limits.                                                    | **What you get if you name no format.** Every row _and_ the context to judge it.             |
+| `full`    | The bare rows, unchanged, with no envelope at all.                                                                                                                                               | You are post-processing the rows yourself and already know the sample is adequate.           |
+
+- `summary` is capped at the metric's `limits.maxSummaryRows`, so a 500-bin heatmap costs the same
+  as a 5-bin one. That is the whole point: a heatmap, voxel cloud or long leaderboard returned as
+  `full` can fill a context window on its own.
+- `reading` and `caveats` are templated from the registry's column semantics by pure code — no model
+  is involved, so identical rows always produce identical words. Quote them; don't re-derive them.
+- Shares appear only where the measure can honestly be summed. A metric in FPS or a ratio reports
+  `total: null` and no shares — do not compute a percentage from those rows.
+- Cluster coordinates are **grid indices**: multiply by the effective `cellSize` for world space.
+  When the scene has a registered proxy and named regions, each cluster of a world-space heatmap is
+  also **labelled** — `region` (the smallest containing region), `regions[]` (all of them),
+  `nearestMesh`, and `distance` in world units (`0` when the mesh box contains the hotspot) — and
+  `drill.region` becomes that region **id**, ready to pass straight back as the `region` argument.
+  Say the label, not the coordinate. A `null` means the scene registered nothing that could answer
+  and the `caveats` name which; inventing a landmark instead is a hallucination.
+- `session_meta` and `scene_representation` are single stored records, not aggregations, and take no
+  `format`. Raw `/api/v1/sessions/:id/events` has an unrelated `format=json|ndjson`, and this server
+  exposes no tool for it.
+- `table` is only self-_describing_, not bounded: its `meta` costs a fixed ~200 characters and the
+  rows are still all of them. When the answer could be large, ask for `summary`.
+
+## Metadata tools (`annotate` only)
+
+Registered **only** when `GET /api/v1/whoami` reports the `annotate` capability, so a read-only key
+yields a read-only server. They write project metadata and nothing else — no event is touched.
+
+| Tool               | What it does                                                                                               |
+| ------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `annotate`         | Pin a note to the project, a scene, a mesh, a region, a metric or a period of time (`targetKind`, `text`). |
+| `define_term`      | Record what a name means in this project (`term`, `meaning`). Idempotent — redefining replaces.            |
+| `save_analysis`    | Store a titled question plus its conclusion (`title`, `query`, `conclusion?`).                             |
+| `list_annotations` | Read the notes already left. Call it **before** explaining a spike someone may already have explained.     |
+| `list_glossary`    | Read the project's vocabulary before interpreting mesh names, scene ids or custom events.                  |
+| `list_analyses`    | Read questions this project has asked before, and what they concluded.                                     |
+| `pin_panel`        | Keep a question on the project's dashboard (`title`, `query`, `chart`, `encoding?`, `span?`, `note?`).     |
+| `unpin_panel`      | Remove one pinned panel by its `id`. It goes for **everyone** on the project, not just you.                |
+| `list_panels`      | Read the panels already pinned, oldest first. Call it **before** pinning, so you extend the grid.          |
+
+Bounds are enforced by the collector: `text` ≤ 2 000 characters, `meaning` ≤ 500, `title` ≤ 120,
+`conclusion` ≤ 4 000, a panel `note` ≤ 500, and per project at most 500 annotations, 200 terms,
+200 analyses and 50 pinned panels (a write past a cap answers `409`). Stored rows record that an
+**agent** wrote them; the collector decides that from the calling client, never from the payload.
+
+`pin_panel` stores a **spec**, not code: a metric id, a chart name and some column names, which the
+dashboard draws with panel components it already ships. Pass the same `query` document the `query`
+tool takes, with `range` set to `"inherit"` so the panel follows the dashboard's own time filter
+instead of freezing the window you asked in, and a `chart` the metric's grain supports —
+`line`/`area` need a time-bucketed metric, `heatmap2d` a binned one, `world3d` a voxelised one,
+`stat` a single-record one, `bar` a ranking, `table` anything. A spec that does not fit is a `400`
+naming the charts that would have worked.
+
+Use them at the end of an investigation, not for scratch state: a note that says what was concluded
+and why is worth keeping, a note per query is noise.
+
+## Resources and prompts
+
+- `uptimizr://context` (`application/json`) — the **live project context document**
+  (`GET /api/v1/context`, ADR 0051 §5). **Read this first, before capabilities.** It describes the
+  project in front of you rather than the API: the scene ids with their labels and named region ids,
+  the custom events the application emits with the `props` keys and coarse types they carry, the top
+  meshes and bound input actions, data freshness (`lastEventAt`, `sessions24h`), whether raw session
+  retention is on, the store engine and collector version, the project glossary and recent
+  annotations, and `metrics.disabledByCapture` — the metrics that WILL return empty because every
+  capture channel feeding them is off. Bounded (<16 KB) and cached per project for ~30 s. Use the ids
+  and names it gives you; never infer a scene id, a region id or a custom-event name.
+- `uptimizr://capabilities` (`application/json`) — the machine-readable descriptor: schema version,
+  the canonical event types, the tool catalog, the parameter-semantics glossary, and `metrics`, the
+  whole registry with each metric's grain, column units, row JSON Schema, filters, limits,
+  interpretation, caveats, source channels and related metrics. Served from the package; **no
+  collector call**. The companion to the context: it is how to plan a query without trial and error.
+- `uptimizr://scenes` (`application/json`) — the **live** list of scene ids with recent activity,
+  fetched through the read-only query API. These are the valid values for the `scene` parameter, so
+  resolve a user's scene name against it instead of guessing a string.
+- `uptimizr://skills` (`application/json`) — the packaged methodology skills below: name, title,
+  description, the tools each method relies on, the capabilities it needs and the arguments it
+  takes. Served from the package; **no collector call**. Use it when the client has no prompt
+  picker; the method itself comes from `prompts/get`.
+- Prompts: one per packaged skill, listed below. Each opens by telling the agent to read
+  `uptimizr://context` first, then renders one user message that sequences the existing read-only
+  tools; they fetch nothing themselves and name no exact arguments, so the agent still resolves the
+  epoch-ms range and the filters.
+
+## Packaged methodology skills (ADR 0051 §7)
+
+A prompt names tools; a **skill** carries the method. Each is an Agent Skills file,
+`skills/<name>/SKILL.md`, shipped in this tarball (authored in `@uptimizr/agent-core`) and
+registered here as a prompt template. The body is the investigation as numbered steps: orient on
+`uptimizr://context`, start from the score, test a change before calling it real, date it, and end
+with recommendations. Read one before improvising: `skills/weekly-scene-health/SKILL.md`.
+
+<!-- generated:registry-skill-names:start — generated by `pnpm gen:docs`; edit the SKILL.md files, not this list -->
+
+- `attention_hotspots` (scene (required), range) — Find where visitors look and click in a scene: view-direction concentration, gaze→mesh flow, the objects that draw the most interaction, and the ones nobody ever notices. USE FOR: deciding where to put a call to action, finding ignored or invisible content, explaining why an object gets no clicks, laying out a scene around what people actually look at.
+  Method: `skills/attention-hotspots/SKILL.md`. Tools: `camera_heatmap`, `flow_links`, `click_rays`, `top_meshes`, `mesh_dwell`, `mesh_blind_spots`, `query`.
+- `conversion_investigation` (scene, range) — Find out where a funnel loses people and whether the loss is real: step-by-step drop-off, the bounce that happens before the funnel even starts, scene-to-scene retention, variant performance, and the interaction failures (dead clicks, rage clicks, unreachable meshes) that explain a stalled step. USE FOR: a funnel that converts worse than expected, an A/B variant comparison, "where do people drop off", diagnosing a step nobody completes.
+  Method: `skills/conversion-investigation/SKILL.md`. Tools: `funnel`, `load_bounce_funnel`, `scene_retention`, `variant_leaderboard`, `dead_clicks`, `rage_clicks`, `mesh_reachability`, `flow_links`, `insight_significance`, `insight_movers`, `query`.
+- `performance_regression_triage` (scene, range) — Triage a frame-rate or stability regression: confirm it moved, date it, locate it (which scene, device class, place in the scene), and name the mechanism — jank, shader compile stalls, memory pressure, a render-scale change or a rendering-technology shift. USE FOR: "the app got slower", a FPS drop after a release, stutter reports, deciding whether a regression is real or noise.
+  Method: `skills/performance-regression-triage/SKILL.md`. Tools: `insight_movers`, `insight_anomalies`, `insight_significance`, `insight_baseline`, `perf_summary`, `perf_distribution`, `frame_time_percentiles`, `jank_rate`, `perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_percentiles`, `render_scale_truth`, `rendering_technology`, `query`.
+- `weekly_scene_health` (scene, range) — A weekly health check for a scene (or the whole project): a weighted health score with every factor traced back to the metric behind it, what changed against last week, traffic, event mix, performance, and the most-interacted meshes. USE FOR: the recurring "how is the scene doing?" review, a scheduled weekly or monthly report, a first look at a project you do not know yet, deciding which scene to investigate next.
+  Method: `skills/weekly-scene-health/SKILL.md`. Tools: `insight_scene_health`, `insight_movers`, `insight_baseline`, `insight_significance`, `insight_anomalies`, `event_counts`, `timeseries`, `perf_summary`, `top_meshes`, `list_sessions`, `query`.
+- `xr_comfort_audit` (scene, range) — Audit VR/AR comfort for a scene (or the whole project): rapid head rotation, locomotion style, tracking quality, guardian/boundary contacts, input-source mix, and the short sessions that mean someone took the headset off. USE FOR: motion-sickness complaints, immersive sessions that end early, choosing a locomotion scheme, checking whether a play space is big enough.
+  Method: `skills/xr-comfort-audit/SKILL.md`. Tools: `xr_rotation`, `xr_locomotion`, `xr_abandonment`, `xr_sources`, `xr_tracking_quality`, `xr_boundary_contacts`, `boundary_heatmap_stats`, `insight_scene_health`, `insight_movers`, `query`.
+
+<!-- generated:registry-skill-names:end -->
 
 ## Rules for agents
 
-- **Read-only and privacy-preserving.** Never add ingestion, mutation, or raw per-session event
-  tools here. No data leaves the consumer's infrastructure (ADR 0003).
+- **Events are read-only; privacy-preserving throughout.** Never add an ingestion tool, an
+  event-mutating tool, or a raw per-session event tool here. The only writes are the `annotate`-gated
+  metadata tools above, and they must stay a separate `writeTools` export from `readTools` so the
+  read-only stance remains inspectable. No data leaves the consumer's infrastructure (ADR 0003).
 - The server talks only to the configured collector with the consumer's `x-api-key`; never hardcode
   or log credentials.
 - Keep it a thin wrapper: the `readTools` catalog (defined in `@uptimizr/agent-core`) is
@@ -77,13 +290,37 @@ small sample.
 - **No database driver, ever.** This server talks to a collector over HTTP; it must stay installable
   with `npx`. Never add `@uptimizr/db` (or any package with a native/optional binary dependency) to
   `dependencies` — `src/__tests__/dependencies.test.ts` fails if you do.
+- **Start from an insight primitive on an open-ended question.** "How are things?" does not mean
+  "call thirty tools": `insight_scene_health` says _which scene_ to look at (six weighted factors,
+  each naming the metric, raw value and project baseline behind it; 50 is the project norm, not a
+  pass mark), `insight_movers` compares every comparable metric with the previous equal window and
+  ranks the changes by how unusual each is, and `insight_baseline` says whether a level is outside
+  normal for that scene. Two fields decide whether a mover is reportable: `direction` is the
+  registry's opinion of what a _rise_ means (so a rise in a `down` metric is a regression, not an
+  improvement), and `aboveMinSample: false` means the delta is arithmetic but not evidence — those
+  rows are returned rather than dropped, and must never be reported as findings.
+- **Then `insight_anomalies` to put a date on it.** `insight_movers` compares two windows you
+  chose; `insight_anomalies` walks one metric's whole series and names the buckets that do not
+  belong — `spike` / `drop` for a single bucket far from the ones before it, and `shift` at the
+  bucket where the level moved and _stayed_ moved, which is the shape a release regression has and
+  the one no per-bucket threshold can see. Quote `bucketStart`, and read `contributor`: where the
+  metric declares a dimension it can be split by, the row names the mesh, source, input action,
+  event type or scene holding the largest share of the excess. Its `z` is in standard deviations
+  while `insight_movers`' is the same ratio unscaled, so the two columns are not comparable.
+- **Call `insight_significance` before calling a single change real.** It reports the effect, a 95%
+  interval and a p-value for one metric across two windows, with the test chosen from what the
+  measure is. Read `ci95` before `p` — an interval straddling 0 means you cannot tell yet — and
+  read `powerNote`, which distinguishes "no effect" from "not enough data". It compares two
+  _windows_, not two segments.
 - Tool definitions are pure (`buildRequest`) and must stay unit-testable without a live collector.
 
 ## Programmatic API
 
-`readMcpConfig()`, `createMcpServer(client)`, and the shared building blocks re-exported from
+`readMcpConfig()`, `createMcpServer(client, options?)` (`options.capabilities` is the key’s
+capability set from `/api/v1/whoami`; it gates the `query:raw` and `annotate` tools),
+`buildCapabilities(options?)`, and the shared building blocks re-exported from
 [`@uptimizr/agent-core`](https://www.npmjs.com/package/@uptimizr/agent-core):
-`createCollectorClient(config)` and `readTools`.
+`createCollectorClient(config)`, `readTools`, `rawTools` and `writeTools`.
 
 ## More
 

package/README.md

@@ -1,14 +1,23 @@
 # @uptimizr/mcp
 
-A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server over an
-Uptimizr collector's query API. It lets an AI agent ask natural-language questions about your
+A [Model Context Protocol](https://modelcontextprotocol.io) server over an Uptimizr
+collector's API. It lets an AI agent ask natural-language questions about your
 3D analytics ("what was the most-clicked mesh this week?") and have them answered by querying
 **your own** collector — nothing is sent to any third party.
 
-The server is a thin wrapper: each tool maps one-to-one to a documented collector query endpoint
-(see [integration docs](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md)). It
-performs `GET` requests only — there are **no ingestion, mutation, or raw per-session event
-tools**.
+The server is a thin wrapper: each analytics tool maps one-to-one to a documented collector query
+endpoint (see
+[integration docs](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md)) and performs
+`GET` requests only. There is **no ingestion tool**, and nothing here can write, alter or delete an
+analytics event — **events are read-only**. A key holding `query:raw` additionally gets
+`session_narrative`, the compacted account of one session, on a collector running with
+`ENABLE_RAW_SESSION_RETENTION`.
+
+The one exception is gated: when the configured key holds the `annotate` capability the server also
+registers the **project-metadata** tools `annotate`, `define_term` and `save_analysis` (plus
+`list_annotations`, `list_glossary`, `list_analyses`), which leave notes, definitions and saved
+analyses behind. The server asks `GET /api/v1/whoami` once at start-up, so a read-only key yields a
+read-only server, and every metadata write is recorded in the project's agent audit log.
 
 ## How it connects
 
@@ -28,10 +37,10 @@ UPTIMIZR_API_KEY="utk_…" \
 npx @uptimizr/mcp
 ```
 
-| Environment variable     | Required | Notes                                              |
-| ------------------------ | -------- | -------------------------------------------------- |
-| `UPTIMIZR_COLLECTOR_URL` | yes      | Base URL of **your** collector.                    |
-| `UPTIMIZR_API_KEY`       | yes      | Your project API key (`x-api-key`), read-only use. |
+| Environment variable     | Required | Notes                                                                                           |
+| ------------------------ | -------- | ----------------------------------------------------------------------------------------------- |
+| `UPTIMIZR_COLLECTOR_URL` | yes      | Base URL of **your** collector.                                                                 |
+| `UPTIMIZR_API_KEY`       | yes      | Your project API key (`x-api-key`). `query` reads; add `annotate` to enable the metadata tools. |
 
 ### Configure an MCP client
 
@@ -76,14 +85,14 @@ For **GitHub Copilot CLI**, put the same entry in `~/.copilot/mcp-config.json` w
 ## Tools
 
 The catalog is **generated from the semantic metric registry** in `@uptimizr/metrics` (ADR 0051 §1):
-every aggregation the collector serves on a read endpoint is a tool — **69** of them. Each tool's
+every metric the collector serves on a read endpoint is a tool — **76** of them, one table row
+each, of which a plain `query` key sees 75 (`session_narrative` needs `query:raw`). Each tool's
 description carries the metric's interpretation notes and caveats, and each declares an MCP
-`outputSchema` for the rows it returns (results come back as both `content` text and
-`structuredContent`).
-
-The table is **generated** from the collector's semantic metric registry (ADR 0051) — one row per
-registered read metric. Read `uptimizr://capabilities` for each one's result grain, column units,
-row schema and caveats; the same registry drives the collector's `GET /api/v1/openapi.json`.
+`outputSchema` covering every `format` envelope it can answer with — the rows, the `table`
+envelope around them (the tools' default), or a `summary` digest. Results come back as both
+`content` text and `structuredContent`. Read `uptimizr://capabilities` for each tool's result
+grain, column units, row schema and caveats; the same registry drives the collector's
+`GET /api/v1/openapi.json`.
 
 Most tools accept an optional time range (`since` / `until`, epoch ms) and the filters the
 underlying endpoint supports (`scene`, `session`, `source`, `bins`, `cellSize`, `interval`, `type`,
@@ -96,6 +105,7 @@ underlying endpoint supports (`scene`, `session`, `source`, `bins`, `cellSize`,
 | ---------------------------- | ---------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `list_sessions`              | `/api/v1/sessions`                       | Recent sessions                     | `since`, `until`, `bins`, `limit`, `cameraMode`, `format`                                                                 |
 | `session_meta`               | `/api/v1/sessions/:id/meta`              | Session descriptor                  | `session`                                                                                                                 |
+| `session_narrative`          | `/api/v1/sessions/:id/narrative`         | Session narrative                   | `session`, `minDwellMs`, `fpsThreshold`, `maxEntries`, `format`                                                           |
 | `scene_representation`       | `/api/v1/scenes/:sceneId/representation` | Scene representation                | `scene`                                                                                                                   |
 | `list_scenes`                | `/api/v1/scenes`                         | Active scenes                       | `since`, `until`, `limit`, `format`                                                                                       |
 | `timeseries`                 | `/api/v1/timeseries`                     | Event volume over time              | `since`, `until`, `interval`, `scene`, `type`, `format`                                                                   |
@@ -127,6 +137,7 @@ underlying endpoint supports (`scene`, `session`, `source`, `bins`, `cellSize`,
 | `hover_dwell`                | `/api/v1/hover/dwell`                    | Hover hesitation per object         | `since`, `until`, `bins`, `limit`, `scene`, `session`, `source`, `cameraMode`, `format`                                   |
 | `interaction_sources`        | `/api/v1/interactions/sources`           | Interactions by input source        | `since`, `until`, `bins`, `limit`, `scene`, `session`, `source`, `cameraMode`, `format`                                   |
 | `top_input_actions`          | `/api/v1/input-actions/top`              | Most-used shortcuts and actions     | `since`, `until`, `bins`, `limit`, `scene`, `session`, `source`, `cameraMode`, `format`                                   |
+| `custom_event_vocabulary`    | `/api/v1/vocabulary/custom-events`       | Discovered custom-event vocabulary  | `since`, `until`, `scene`, `limit`, `format`                                                                              |
 | `camera_gestures`            | `/api/v1/camera-gestures`                | Camera navigation gestures          | `since`, `until`, `bins`, `limit`, `scene`, `session`, `source`, `cameraMode`, `format`                                   |
 | `navigation_stats`           | `/api/v1/navigation`                     | Navigation effort per session       | `since`, `until`, `moveThreshold`, `limit`, `scene`, `session`, `format`                                                  |
 | `backtrack_ratio`            | `/api/v1/backtrack`                      | Path retrace / backtracking         | `since`, `until`, `cellSize`, `limit`, `scene`, `session`, `format`                                                       |
@@ -163,6 +174,11 @@ underlying endpoint supports (`scene`, `session`, `source`, `bins`, `cellSize`,
 | `scene_retention`            | `/api/v1/scene-retention`                | Scene-to-scene retention            | `since`, `until`, `limit`, `format`                                                                                       |
 | `load_bounce_funnel`         | `/api/v1/load-bounce`                    | Load → bounce funnel                | `since`, `until`, `scene`, `bands`, `format`                                                                              |
 | `variant_leaderboard`        | `/api/v1/variant-leaderboard`            | Variant → conversion leaderboard    | `since`, `until`, `scene`, `cameraMode`, `variant`, `conversion`, `limit`, `format`                                       |
+| `insight_baseline`           | `/api/v1/insights/baseline`              | Metric baseline                     | `metric`, `scene`, `window`, `bucket`, `since`, `until`, `format`                                                         |
+| `insight_movers`             | `/api/v1/insights/movers`                | What changed                        | `scene`, `metrics`, `bucket`, `limit`, `since`, `until`, `refSince`, `refUntil`, `format`                                 |
+| `insight_anomalies`          | `/api/v1/insights/anomalies`             | Anomalous buckets                   | `metric`, `scene`, `window`, `bucket`, `sensitivity`, `since`, `until`, `format`                                          |
+| `insight_significance`       | `/api/v1/insights/significance`          | Statistical significance            | `metric`, `scene`, `bucket`, `since`, `until`, `refSince`, `refUntil`, `format`                                           |
+| `insight_scene_health`       | `/api/v1/insights/scene-health`          | Scene health score                  | `scene`, `window`, `since`, `until`, `bucket`, `limit`, `weights`, `format`                                               |
 
 <!-- generated:registry-tools:end -->
 
@@ -172,11 +188,59 @@ The server also exposes read-only **resources** for self-discovery — `uptimizr
 (a machine-readable descriptor of event types, the tool catalog, parameter semantics, and
 `metrics`: the collector's whole semantic metric registry, with each metric's result grain, column
 units, row JSON Schema, row limits, interpretation and caveats — ADR 0051) and
-`uptimizr://scenes` (live scene ids) — and curated **prompts** (`weekly_scene_health`,
-`attention_hotspots`, `xr_comfort_review`) that drive the tools above. A remote Streamable HTTP
-transport is a deferred, auth-gated follow-up (ADR 0050 §7). See the
+`uptimizr://context` (the live project context document), `uptimizr://scenes` (live scene ids) and
+`uptimizr://skills` (the methodology catalog below) — plus one curated **prompt per packaged
+skill**, listed in the table below, that drives the tools above. See the
 [MCP guide](https://uptimizr.com/docs/guides/mcp/) for details.
 
+## Methodology skills
+
+Each prompt template is a packaged **skill** — an Agent Skills file, `skills/<name>/SKILL.md`,
+shipped in this package — so the method an agent follows is readable, forkable and identical to the
+one `uptimizr agent report --skill` runs on your collector. The catalog is also served as the
+`uptimizr://skills` resource. `*` marks a required argument.
+
+<!-- generated:registry-skills:start — generated by `pnpm gen:docs`; edit the SKILL.md files, not this list -->
+
+| Skill                           | Arguments          | What it produces, and when to use it                                                                                                                                                                                                                                                                                                                                                                                                                     | Tools its method names                                                                                                                                                                                                                                                                                            |
+| ------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `attention_hotspots`            | `scene*`, `range?` | Find where visitors look and click in a scene: view-direction concentration, gaze→mesh flow, the objects that draw the most interaction, and the ones nobody ever notices. USE FOR: deciding where to put a call to action, finding ignored or invisible content, explaining why an object gets no clicks, laying out a scene around what people actually look at.                                                                                       | `camera_heatmap`, `flow_links`, `click_rays`, `top_meshes`, `mesh_dwell`, `mesh_blind_spots`, `query`                                                                                                                                                                                                             |
+| `conversion_investigation`      | `scene?`, `range?` | Find out where a funnel loses people and whether the loss is real: step-by-step drop-off, the bounce that happens before the funnel even starts, scene-to-scene retention, variant performance, and the interaction failures (dead clicks, rage clicks, unreachable meshes) that explain a stalled step. USE FOR: a funnel that converts worse than expected, an A/B variant comparison, "where do people drop off", diagnosing a step nobody completes. | `funnel`, `load_bounce_funnel`, `scene_retention`, `variant_leaderboard`, `dead_clicks`, `rage_clicks`, `mesh_reachability`, `flow_links`, `insight_significance`, `insight_movers`, `query`                                                                                                                      |
+| `performance_regression_triage` | `scene?`, `range?` | Triage a frame-rate or stability regression: confirm it moved, date it, locate it (which scene, device class, place in the scene), and name the mechanism — jank, shader compile stalls, memory pressure, a render-scale change or a rendering-technology shift. USE FOR: "the app got slower", a FPS drop after a release, stutter reports, deciding whether a regression is real or noise.                                                             | `insight_movers`, `insight_anomalies`, `insight_significance`, `insight_baseline`, `perf_summary`, `perf_distribution`, `frame_time_percentiles`, `jank_rate`, `perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_percentiles`, `render_scale_truth`, `rendering_technology`, `query` |
+| `weekly_scene_health`           | `scene?`, `range?` | A weekly health check for a scene (or the whole project): a weighted health score with every factor traced back to the metric behind it, what changed against last week, traffic, event mix, performance, and the most-interacted meshes. USE FOR: the recurring "how is the scene doing?" review, a scheduled weekly or monthly report, a first look at a project you do not know yet, deciding which scene to investigate next.                        | `insight_scene_health`, `insight_movers`, `insight_baseline`, `insight_significance`, `insight_anomalies`, `event_counts`, `timeseries`, `perf_summary`, `top_meshes`, `list_sessions`, `query`                                                                                                                   |
+| `xr_comfort_audit`              | `scene?`, `range?` | Audit VR/AR comfort for a scene (or the whole project): rapid head rotation, locomotion style, tracking quality, guardian/boundary contacts, input-source mix, and the short sessions that mean someone took the headset off. USE FOR: motion-sickness complaints, immersive sessions that end early, choosing a locomotion scheme, checking whether a play space is big enough.                                                                         | `xr_rotation`, `xr_locomotion`, `xr_abandonment`, `xr_sources`, `xr_tracking_quality`, `xr_boundary_contacts`, `boundary_heatmap_stats`, `insight_scene_health`, `insight_movers`, `query`                                                                                                                        |
+
+<!-- generated:registry-skills:end -->
+
+```bash
+cat node_modules/@uptimizr/mcp/skills/weekly-scene-health/SKILL.md
+```
+
+## Hosted transport (Streamable HTTP)
+
+The collector can serve **this same server** itself, over MCP's Streamable HTTP transport, so a
+remote agent connects with a URL and a key instead of launching this package locally (ADR 0051 §7).
+Start the collector with `COLLECTOR_MCP_HTTP=1` and point a client at `/mcp`:
+
+```jsonc
+{
+  "mcpServers": {
+    "uptimizr": {
+      "type": "http",
+      "url": "https://collect.example.com/mcp",
+      "headers": { "Authorization": "Bearer utk_…" },
+    },
+  },
+}
+```
+
+`x-api-key` works in place of the bearer header, the key still needs only `query`, and the tools,
+resources and prompts are identical — both transports are built by the same `createMcpServer()`
+below. Tool calls made that way are recorded in the collector's audit log with
+`surface: "mcp-http"`; calls from this package over stdio are ordinary HTTP reads, recorded as
+`http`. See the
+[hosted transport guide](https://uptimizr.com/docs/guides/mcp/#hosted-transport-streamable-http).
+
 ## Programmatic use
 
 ```ts
@@ -188,8 +252,14 @@ const server = createMcpServer(client);
 await server.connect(new StdioServerTransport());
 ```
 
-The package also exports `readTools`, `CollectorError`, `version`, and the related public types.
-The read-only tool catalog (`readTools`) and the `GET`-only collector client are defined in the
+`createMcpServer(client, options?)` takes an optional `options.capabilities` — the capability set of
+the API key the server instance is bound to. The collector-hosted transport passes the key it
+resolved, so a session's surface can only narrow to what its key may do; omitting it (as the stdio
+entry point does) registers the whole read catalog and leaves enforcement to the collector.
+
+The package also exports `readTools`, `rawTools`, `writeTools`, `CollectorError`, `version`, and the
+related public types. The read-only analytics catalog (`readTools`), the `annotate`-gated
+`writeTools`, and the collector client are defined in the
 framework-agnostic [`@uptimizr/agent-core`](../agent-core/README.md) package and re-exported here,
 so the agent tool surface is defined once and shared across the MCP server, the dashboard assistant,
 and the demo assistant (ADR 0050). Building a non-MCP agent? Depend on `@uptimizr/agent-core`

package/dist/bin.js

@@ -2,7 +2,7 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createCollectorClient } from "@uptimizr/agent-core";
 import { readMcpConfig } from "./config.js";
-import { createMcpServer } from "./server.js";
+import { createMcpServer, fetchKeyCapabilities } from "./server.js";
 /**
  * Entry point: read configuration from the environment, build a read-only
  * collector client and MCP server, and serve over stdio (the transport MCP
@@ -11,7 +11,14 @@ import { createMcpServer } from "./server.js";
 async function main() {
     const config = readMcpConfig();
     const client = createCollectorClient(config);
-    const server = createMcpServer(client);
+    // Ask the collector what this key may do before building the server, so the
+    // capability-gated tools match the key: the raw-session tools of #314 only for
+    // `query:raw`, the metadata write tools of #310 only for `annotate`. Best
+    // effort — a collector older than `/api/v1/whoami`, an offline start or a
+    // transient failure yields "no extra capabilities", which serves the ordinary
+    // `query` surface this binary has always served.
+    const capabilities = await fetchKeyCapabilities(client);
+    const server = createMcpServer(client, { capabilities });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,OAAO,IAAI,CAAC,CAAC;IACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;GAIG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,+EAA+E;IAC/E,0EAA0E;IAC1E,0EAA0E;IAC1E,8EAA8E;IAC9E,iDAAiD;IACjD,MAAM,YAAY,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,OAAO,IAAI,CAAC,CAAC;IACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/capabilities.d.ts

@@ -1,5 +1,5 @@
 import { type EventType } from "@uptimizr/schema";
-import { type ColumnSemantics, type DimensionId, type FilterId, type MetricCategory, type MetricComparison, type MetricGrain } from "@uptimizr/metrics";
+import { type ColumnSemantics, type DimensionId, type FilterId, type MetricCapability, type MetricCategory, type MetricComparison, type MetricGrain } from "@uptimizr/metrics";
 /**
  * One tool the server exposes, described for self-discovery: its name, a human
  * title, what it returns, and the parameter names it accepts.
@@ -34,11 +34,17 @@ export interface CapabilityMetricDescriptor {
     category: MetricCategory;
     /** What one row represents. */
     grain: MetricGrain;
-    /** The collector route it is served on, when it has one. */
+    /**
+     * The collector route it is served on, when it has one. `capability` names the
+     * API-key capability the route requires; it is absent for the ordinary
+     * `query` surface and `"query:raw"` for a metric gated behind raw-session
+     * retention (ADR 0051 §7).
+     */
     endpoint?: {
         method: "GET";
         path: string;
         pathParams?: readonly FilterId[];
+        capability?: MetricCapability;
     };
     /** Group-by dimensions the rows are keyed by. */
     dimensions: readonly DimensionId[];
@@ -93,10 +99,22 @@ export interface CapabilitiesDescriptor {
     /** Human-oriented notes about scope and discovery. */
     notes: readonly string[];
 }
+/**
+ * What the descriptor should describe.
+ */
+export interface BuildCapabilitiesOptions {
+    /**
+     * The capability set of the key this descriptor is being built for, as
+     * `GET /api/v1/whoami` reports it. Defaults to `["query"]` — the ordinary
+     * aggregate read surface, and the safe answer for a caller that has not
+     * looked the key up.
+     */
+    capabilities?: readonly string[];
+}
 /**
  * Build the capabilities descriptor from the metric registry and the event
  * schema. Pure and synchronous — it introspects definitions only, never the
  * collector, so it is safe to serve as a static resource.
  */
-export declare function buildCapabilities(): CapabilitiesDescriptor;
+export declare function buildCapabilities(options?: BuildCapabilitiesOptions): CapabilitiesDescriptor;
 //# sourceMappingURL=capabilities.d.ts.map