@uptimizr/mcp 1.1.0 → 1.2.0

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAsCvE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAqClE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,sBAAsB,CAAC;AAqE9B;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAwBD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAW9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,sBAA2B,GACnC,SAAS,CAiFX"}

package/dist/server.js

@@ -1,12 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { readTools } from "@uptimizr/agent-core";
+import { rawTools, readTools, writeTools, } from "@uptimizr/agent-core";
 import { registerResources } from "./resources.js";
 import { registerPrompts } from "./prompts.js";
 import { version } from "./version.js";
 /**
- * Normalise a collector response into the `{ rows }` envelope every tool's
- * `outputSchema` declares. Aggregate endpoints already return an array; the
+ * Normalise a collector response into the `{ rows }` envelope a `format=full`
+ * result is reported in. Aggregate endpoints already return an array; the
  * single-object reads (a session descriptor, a scene representation, a one-row
  * summary) become a one-element array so a client can treat every tool's
  * structured result the same way. A `204`-style empty body becomes no rows.
@@ -19,8 +18,36 @@ function toRows(data) {
     return [data];
 }
 /**
- * Validate the rows against the tool's registry-derived output schema and
- * return the **parsed** result as the structured payload.
+ * Whether the collector really answered with the envelope the call asked for:
+ * `format=table` with a `meta` block around its rows, `format=summary` with a
+ * `kind`-tagged digest and its `reading`. Both keys are required so a *row* that
+ * happens to have a `kind` column is never mistaken for a digest.
+ */
+function isEnvelope(data, format) {
+    if (data == null || typeof data !== "object" || Array.isArray(data))
+        return false;
+    const payload = data;
+    if (format === "table")
+        return "meta" in payload && "rows" in payload;
+    if (format === "summary")
+        return "kind" in payload && "reading" in payload;
+    return false;
+}
+/**
+ * The structured payload for one tool result: the collector's response in the
+ * envelope the call asked for, validated against the tool's registry-derived
+ * output schema and returned **parsed**.
+ *
+ * `format=table` and `format=summary` are returned as they arrive — the whole
+ * point of those envelopes is the `meta` / `reading` they carry, and stripping
+ * them here is precisely the bug that made the SDK reject the recommended path
+ * with `-32602` (#350). `full` keeps the `{ rows }` wrapping it has always had.
+ * Which envelope to expect is decided by the `format` the request actually
+ * carried — not guessed from the payload — and the payload must then actually
+ * *be* that envelope (`meta` + `rows`, or a `kind`-tagged digest). Anything
+ * else is wrapped as rows, which is what keeps a modern client working against
+ * an **older collector** that does not know `format` and answers a `table`
+ * request with the bare rows (or the bare record) it always returned.
  *
  * The registry's numeric columns are strict `z.number()`: since ADR 0051 §2 the
  * *collector* guarantees numbers, coercing each dialect's wire format
@@ -28,32 +55,106 @@ function toRows(data) {
  * point rows leave its driver. So this is a check, not a repair — the advertised
  * schema describes the API, and normalising here would hide a store regression.
  *
- * If the rows do not match the schema the raw rows are passed through; the SDK's
- * own output validation then reports the offending column by name, which is the
- * honest outcome for a collector that is out of contract.
+ * If the payload does not match the schema it is passed through unchanged; the
+ * SDK's own output validation then reports the offending column by name, which
+ * is the honest outcome for a collector that is out of contract.
+ */
+function structuredResult(tool, data, format) {
+    // A generated per-metric tool returns one metric's rows, so the `format`
+    // envelope above is the default. The `query` tool (ADR 0051 §3) chooses its
+    // own shape — what comes back depends on the `format` that was asked for —
+    // so it supplies the wrapper itself.
+    const payload = tool.structuredContent?.(data) ?? (isEnvelope(data, format) ? data : { rows: toRows(data) });
+    const parsed = tool.outputSchema.safeParse(payload);
+    return parsed.success ? parsed.data : payload;
+}
+/**
+ * Server-level `instructions` for a session whose key capabilities are known.
+ *
+ * Only built when {@link CreateMcpServerOptions.capabilities} is supplied, so
+ * the stdio server's `initialize` result stays byte-for-byte what it has always
+ * been. Capability names are not secret — `GET /api/v1/whoami` returns the same
+ * list to the key's holder — and naming them saves an agent a round of
+ * trial-and-error against tools it could never call.
+ */
+function instructionsFor(capabilities) {
+    const granted = capabilities.length > 0 ? capabilities.join(", ") : "none";
+    return ("Every tool here reads one aggregate metric from the connected Uptimizr collector, " +
+        "always scoped to the project the API key belongs to — no cross-project access, and no " +
+        "personally identifying data. " +
+        `The key this session is bound to holds these capabilities: ${granted}. ` +
+        "Tools outside that set are not registered, and the collector refuses them independently. " +
+        "Read the uptimizr://capabilities resource first: it gives every metric's grain, column " +
+        "units, row limits, interpretation and caveats, so a query can be planned rather than guessed.");
+}
+/**
+ * Ask the collector what the configured key may do (`GET /api/v1/whoami`).
+ *
+ * Never throws: an older collector without the route, an unreachable one, or a
+ * key that cannot even read all yield an empty capability set, and the server
+ * then starts read-only rather than not starting at all. A degraded but useful
+ * server beats no server.
  */
-function structuredRows(outputSchema, data) {
-    const rows = toRows(data);
-    const parsed = z.object(outputSchema).safeParse({ rows });
-    return parsed.success ? parsed.data : { rows };
+export async function fetchKeyCapabilities(client) {
+    try {
+        const whoami = (await client.get("/api/v1/whoami"));
+        return Array.isArray(whoami?.capabilities)
+            ? whoami.capabilities.filter((capability) => typeof capability === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
 }
 /**
- * Build the Uptimizr MCP server: a read-only `McpServer` whose tools each wrap
- * one collector query endpoint via the injected `CollectorClient`. The server
- * holds no business logic — it forwards validated arguments and returns the
- * collector's JSON (ADR 0005 / ADR 0017). Alongside the tools it exposes
+ * Build the Uptimizr MCP server: an `McpServer` whose tools each wrap one
+ * collector endpoint via the injected `CollectorClient`. The server holds no
+ * business logic — it forwards validated arguments and returns the collector's
+ * JSON (ADR 0005 / ADR 0017). Alongside the tools it exposes
  * capability-discovery **resources** and curated analysis **prompts** so agents
  * can self-orient (ADR 0050 §7).
  *
- * The tool catalog is generated from the `@uptimizr/db` metric registry
+ * The **analytics** tool catalog is generated from the metric registry
  * (ADR 0051 §1), so `tools/list` covers every metric the collector serves on an
  * endpoint. Each tool advertises the registry-derived `outputSchema` and returns
- * both `structuredContent` (the typed `{ rows }` envelope) and the `content`
- * text a client without structured-output support still reads.
+ * both `structuredContent` — the `format` envelope the call asked for, which
+ * since #336 is `{ meta, rows }` by default — and the `content` text a client
+ * without structured-output support still reads. That catalog is entirely
+ * read-only: **events cannot be written, altered or deleted through this
+ * server** (ADR 0051 §9).
+ *
+ * `options.capabilities` is what the **key** behind `client` is allowed to do
+ * (`GET /api/v1/whoami`). Tools whose endpoint needs more than the ordinary
+ * `query` capability are registered only when the key really holds it, so
+ * `tools/list` describes what this session can actually do rather than what the
+ * collector could do for somebody else: the raw-session tools of #314 behind
+ * `query:raw`, the **metadata** tools of #310 — annotations, glossary, saved
+ * analyses — behind `annotate`. Omit it and only the `query` surface is served,
+ * the safe default for a caller that has not looked the key up.
+ *
+ * The factory is **transport-agnostic**: `bin.ts` connects it to stdio, and the
+ * collector connects one instance per authenticated Streamable HTTP session at
+ * `/mcp` (ADR 0051 §7), passing that session's key capabilities through
+ * `options`. Both get the same tools, resources and prompts from this one place.
  */
-export function createMcpServer(client) {
-    const server = new McpServer({ name: "uptimizr-mcp", version }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
-    for (const tool of readTools) {
+export function createMcpServer(client, options = {}) {
+    // The default is the ordinary read surface, never "nothing": a caller that has
+    // not looked the key up still gets every `query` tool, exactly as before.
+    // `instructions`, by contrast, keys off the *supplied* set, so a stdio server
+    // built without one keeps the `initialize` result it has always had.
+    const capabilities = options.capabilities ?? ["query"];
+    const server = new McpServer({ name: "uptimizr-mcp", version }, {
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        ...(options.capabilities ? { instructions: instructionsFor(options.capabilities) } : {}),
+    });
+    const tools = [
+        ...readTools,
+        // `query:raw` additionally requires `ENABLE_RAW_SESSION_RETENTION` on the
+        // collector (ADR 0003), which this process cannot see — a narrative tool on
+        // a retention-disabled collector still answers 403, and says so.
+        ...(capabilities.includes("query:raw") ? rawTools : []),
+    ];
+    for (const tool of tools) {
         server.registerTool(tool.name, {
             title: tool.title,
             description: tool.description,
@@ -68,7 +169,7 @@ export function createMcpServer(client) {
                     return { content: [{ type: "text", text }] };
                 return {
                     content: [{ type: "text", text }],
-                    structuredContent: structuredRows(tool.outputSchema, data),
+                    structuredContent: structuredResult(tool, data, params.format),
                 };
             }
             catch (err) {
@@ -77,7 +178,31 @@ export function createMcpServer(client) {
             }
         });
     }
-    registerResources(server, client);
+    // Metadata tools (#310, ADR 0051 §5): annotations, glossary, saved analyses.
+    //
+    // They appear in `tools/list` only for a key that holds `annotate`. That is a
+    // usability decision, not the security boundary — the collector refuses the
+    // write either way with a 403 — but offering an agent a tool it will always
+    // be refused for wastes its context and its patience.
+    //
+    // Nothing here can write, alter or delete an event: the tools call the three
+    // metadata endpoints and nothing else, and every call is audited by the
+    // collector (ADR 0051 §7/§9).
+    if (capabilities.includes("annotate")) {
+        for (const tool of writeTools) {
+            server.registerTool(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.inputSchema }, async (args) => {
+                try {
+                    const data = await tool.execute(client, args);
+                    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+                }
+            });
+        }
+    }
+    registerResources(server, client, { capabilities });
     registerPrompts(server);
     return server;
 }

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -1,7 +1,9 @@
 # @uptimizr/mcp
 
-> A read-only Model Context Protocol server over an Uptimizr collector's query API. Lets an agent
-> query a consumer's own 3D analytics; thin wrapper, GET-only, no data egress.
+> A Model Context Protocol server over an Uptimizr collector's API. Lets an agent query a consumer's
+> own 3D analytics; thin wrapper, no data egress. Events are read-only; project-metadata writes
+> (annotations, glossary, saved analyses, pinned panels) are registered only for a key holding
+> `annotate`.
 
 ## Docs
 
@@ -10,7 +12,7 @@
 - [Integration & API reference](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md): the underlying query endpoints.
 - [Architecture Decision Records](https://github.com/RaananW/Uptimizr/tree/main/docs/adr): privacy model (0003), thin backends (0005), consumer-facing agents (0017).
 
-## Tools (read-only)
+## Analytics tools (read-only)
 
 <!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this list -->
 
@@ -20,23 +22,196 @@
 `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 -->
 
+## Insight primitives (ADR 0051 §4)
+
+Five of the tools are readings *about* the other metrics, and they are the right first call on an
+open-ended question — "how are things?" does not mean "call thirty tools".
+
+- `insight_scene_health` — one 0-100 score per scene over six weighted factors (perf stability,
+  jank, errors, dead clicks, coverage, XR abandonment), least healthy first. The right *unscoped*
+  starting point: it answers which scene to open. Every factor carries the `metric` id behind it,
+  its `raw` value and the project `baseline` it was compared with, so the next call and the
+  sentence to write are both already in the row. **50 is the project norm, not a pass mark** — the
+  score compares a scene with the rest of the project's recent past — and a factor with
+  `score: null` was not counted (its `note` says why).
+- `insight_movers` — what changed against a reference window (the previous equal one by default),
+  for every comparable metric in scope, ranked by a robust z-score: the change divided by how much
+  that metric normally swings, so a noisy metric must move much further than a steady one to reach
+  the top. Bounded: at most 24 metrics are scanned per request.
+- `insight_baseline` — what is normal for one metric in one scene: `median` and `mad`, the
+  `p10`..`p90` band, and the drift `slope`. Call it on whatever moved, to say whether the new level
+  is actually outside normal rather than merely different.
+- `insight_anomalies` — *when* one metric went wrong. One row per bucket that does not belong in
+  the series: `kind: "spike" | "drop"` for a bucket more than `sensitivity` (default 3) standard
+  deviations from the trailing window, and `kind: "shift"` at the bucket where the level moved and
+  stayed moved. Where the metric declares a dimension it can be split by, `contributor` names the
+  mesh, source, input action, event type or scene holding the largest `share` of the excess.
+  Bounded: one scan for the series plus at most three attribution scans per request.
+- `insight_significance` — whether a difference between two windows could be chance: `effect`,
+  `ci95`, `p`, and the `test` that produced them (a two-proportion z with Wilson intervals for a
+  declared rate, Welch's t over the per-bucket values for a level, an exact Poisson rate test for a
+  bare count — picked from the measure, not from you). **Read `ci95` before `p`**: an interval that
+  straddles 0 means you cannot tell yet, and `powerNote` says what this much data could have
+  detected at all. Welch's `n` is the number of **buckets**, not events. It compares two *windows*,
+  not two segments: a variant-versus-variant question is a `400`, not a wrong answer.
+
+Read `insight_anomalies`' `z` as standard deviations and `insight_movers`' as the same ratio
+unscaled — they differ by a constant factor (1.4826) and must not be compared directly. A sustained
+level change is reported both as a `shift` and, for the days right after it, as `drop`/`spike`
+rows: two true statements about one event.
+
+Two fields decide whether a mover is worth reporting, and both are easy to misread:
+
+- `direction` is the registry's opinion of what a **rise** in that metric means — `up` (good),
+  `down` (bad) or `neutral`. It is *not* the direction of the move: read it with the sign of
+  `delta`, so a rise in a `down` metric (errors, dead clicks, jank) is a regression.
+- `aboveMinSample: false` means the delta is real arithmetic but the denominator is below the
+  metric's declared minimum. Such rows are returned rather than dropped — "we cannot tell" and
+  "nothing changed" are different answers — and must never be reported as findings.
+
+Statistics are computed in pure TypeScript over portable day/hour buckets, so the same data yields
+the same answer on every storage engine. Only `comparable` metrics with a faithful per-bucket form
+participate; asking for one that has none returns `400` naming every id that does.
+
+## Result formats (`format`)
+
+Every aggregate tool takes `format` — the envelope its rows arrive in, not a filter (ADR 0051 §2).
+Omit it and you get `table`: the tools' own default, sent explicitly, so the HTTP endpoints still
+default to `full` for every other client. All three validate against the tool's `outputSchema`.
+
+- `summary` — **prefer this.** 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. Capped at the metric's `limits.maxSummaryRows`, so a 500-bin heatmap
+  costs the same as a 5-bin one. `reading` and `caveats` are templated by pure code — no model —
+  so identical rows always produce identical words.
+- `table` — **the default.** `{ meta, rows }`: every row plus the metric, range, applied filters,
+  sample size, row count, a truncation flag and the registry limits. Self-describing, but not
+  bounded — the rows are still all of them, so ask for `summary` when the answer could be large.
+- `full` — the bare rows, unchanged, with no envelope at all.
+
+Shares appear only where the measure can honestly be summed (an FPS or ratio metric reports
+`total: null` and no shares). Cluster coordinates are grid indices — multiply by the effective
+`cellSize` for world space. When the scene has a registered proxy and named regions, a world-space
+cluster is also labelled with `region` (the smallest containing region), `regions[]` (all containing
+ids), `nearestMesh` and `distance` (world units, `0` when the mesh box contains it), and
+`drill.region` becomes that region id — pass it straight back as the `region` argument. Quote the
+label rather than the coordinate; a `null` means the scene registered nothing that could answer (the
+`caveats` say which), so do not invent a landmark. `session_meta` and `scene_representation` are
+stored records, not aggregations, and take no `format`.
+
+## Resources and prompts
+
+- `uptimizr://context` (`application/json`) — the live project context document
+  (`GET /api/v1/context`, ADR 0051 §5): scene ids + labels + named region ids, the custom-event
+  vocabulary with its `props` keys and coarse types, top meshes, bound input actions, data freshness,
+  retention flags, store engine, glossary, recent annotations, and `metrics.disabledByCapture` —
+  metrics that return empty because their capture channel is off. Bounded and cached per project.
+  **Read it first**, and use the ids and names it gives you instead of inferring your own.
+- `uptimizr://capabilities` (`application/json`) — static descriptor: schema version, canonical
+  event types, the tool catalog, the parameter-semantics glossary, and `metrics` (the whole registry
+  with grain, column units, row JSON Schema, filters, limits, interpretation, caveats, source
+  channels). No collector call. Read it after the context.
+- `uptimizr://scenes` (`application/json`) — the live scene ids with recent activity, i.e. the valid
+  values for the `scene` parameter. Fetched through the read-only query API.
+- `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.
+- Prompts: one per packaged skill (`attention_hotspots`, `conversion_investigation`,
+  `performance_regression_triage`, `weekly_scene_health`, `xr_comfort_audit`) — each opens by
+  telling the agent to read `uptimizr://context` first, then renders one user message sequencing
+  the read-only tools; they fetch nothing themselves.
+
+## Packaged methodology skills (ADR 0051 §7)
+
+Every prompt template is a packaged skill: an Agent Skills file under `skills/<name>/SKILL.md` in
+this tarball, whose body is the investigation as numbered steps. The catalog is also the
+`uptimizr://skills` resource; `prompts/get` returns the rendered method.
+
+<!-- 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 -->
+
+## Transports
+
+Two transports, one server: `createMcpServer()` is transport-agnostic.
+
+- **stdio** — `npx @uptimizr/mcp`, launched by a desktop client. What this package's `bin` does.
+- **Collector-hosted Streamable HTTP** — the collector serves the same server at `POST/GET/DELETE
+  /mcp` when it is started with `COLLECTOR_MCP_HTTP=1` (ADR 0051 §7). A remote client connects with
+  a URL plus `x-api-key` (or `Authorization: Bearer <key>`); tool calls are audited with
+  `surface: "mcp-http"`. The catalog, resources and prompts are identical to stdio's.
+
+## Required key capability
+
+`UPTIMIZR_API_KEY` needs the `query` capability
+(`uptimizr new-key <projectId> --capabilities query --label "mcp-agent"`; `query` is the default).
+Add `annotate` only to let the agent write project metadata — the server calls
+`GET /api/v1/whoami` once at start-up and registers the metadata tools only when the key holds it.
+`query:raw` is **optional and off by default**: the default catalog is aggregate reads only, and a
+key that holds it gains exactly one more tool, `session_narrative` (see below). `ingest` is never
+used. A key missing a required capability is refused with `403`.
+
 ## Key exports
 
-- `createMcpServer(client)` — build the read-only MCP server.
+- `createMcpServer(client, options?)` — build the MCP server. `options.capabilities` is the bound
+  key's capability set, passed by the collector-hosted transport (or read from `/api/v1/whoami` by
+  the stdio bin) so a session's surface matches its key: metadata write tools are registered only
+  when it includes `annotate`, and omitting it registers the read catalog alone.
+- `fetchKeyCapabilities(client)` — ask `GET /api/v1/whoami` what the key holds (never throws).
 - `createCollectorClient(config)` — the thin GET-only collector client.
 - `readMcpConfig()` — read `UPTIMIZR_COLLECTOR_URL` + `UPTIMIZR_API_KEY` from the environment.
 - `readTools` — the read-only tool catalog (one entry per query endpoint), generated from the
-  `@uptimizr/metrics` metric registry: 69 tools, each with an input schema, an MCP `outputSchema` and the
-  metric's interpretation notes and caveats in its description (ADR 0051).
+  `@uptimizr/metrics` metric registry plus `query` and `list_subscriptions`: 77 tools, each with an
+  input schema, an MCP `outputSchema` covering all three `format` envelopes, and the metric's
+  interpretation notes and caveats in its description (ADR 0051).
+- `writeTools` — the project-metadata tools (`annotate`, `define_term`, `save_analysis`,
+  `pin_panel`, `unpin_panel`, `list_annotations`, `list_glossary`, `list_analyses`,
+  `list_panels`). A separate export from `readTools` on
+  purpose, so an integration's read-only stance stays inspectable. They write metadata only — no
+  event can be written, altered or deleted through them. `pin_panel` stores a panel **spec** — a
+  metric id, a chart name, some column names — that the dashboard draws with panels it already
+  ships; send the `query` document with `range: "inherit"` and a chart the metric's grain supports,
+  or it is a `400` naming the charts that would have worked. `unpin_panel` removes a panel for
+  everyone on the project. At most 50 pinned panels per project (`409` past the cap).
+
+## Capability-gated tools (ADR 0051 §7)
+
+- The default catalog is the `query` surface: aggregate reads only, no raw per-session tool.
+- `createMcpServer(client, { capabilities })` takes the key's capability set (from `GET /api/v1/whoami`). When it includes `query:raw`, the server also registers `session_narrative` — an ordered, bounded account of what one session did, gated on the collector also running with `ENABLE_RAW_SESSION_RETENTION`. Omit the option and only the `query` surface is served.
+- The `uptimizr-mcp` binary discovers the capability set at start-up (best effort; a failure falls back to the `query` surface).
+
+## Non-metric reads
+
+- `list_subscriptions` — the project's conditional subscriptions (ADR 0051 §6): what the
+  collector is watching for and how each one last went. No arguments. Read-only; creating or
+  deleting one needs `annotate` and is not exposed as a tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Read-only Model Context Protocol (MCP) server over an Uptimizr collector's query API — let an agent ask questions of your own 3D analytics, on your own infrastructure.",
   "keywords": [
     "uptimizr",
@@ -40,6 +40,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE",
     "AGENTS.md",
@@ -48,27 +49,27 @@
   "sideEffects": false,
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^4.5.4",
-    "@uptimizr/agent-core": "1.1.0",
-    "@uptimizr/metrics": "0.1.0",
-    "@uptimizr/schema": "1.1.0"
+    "zod": "^4.6.5",
+    "@uptimizr/agent-core": "1.2.0",
+    "@uptimizr/metrics": "0.2.0",
+    "@uptimizr/schema": "1.2.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
-    "tsx": "^4.23.13",
-    "vitest": "^4.1.11"
+    "@types/node": "^26.6.2",
+    "tsx": "^4.23.15",
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node ../../../scripts/copy-dir.mjs ../agent-core/skills skills",
     "dev": "tsc -p tsconfig.json --watch",
     "serve": "tsx src/bin.ts",
     "start": "node dist/bin.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "lint": "eslint .",
-    "clean": "rimraf -g dist *.tsbuildinfo"
+    "clean": "rimraf -g dist skills *.tsbuildinfo"
   }
 }

package/skills/attention-hotspots/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: attention_hotspots
+title: Attention hot-spots for a scene
+description: >-
+  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. Trigger phrases: what do people
+  look at, attention hotspots, where do visitors click, which meshes get ignored, blind spots,
+  gaze heatmap, is anyone seeing this object.
+tools:
+  - camera_heatmap
+  - flow_links
+  - click_rays
+  - top_meshes
+  - mesh_dwell
+  - mesh_blind_spots
+  - query
+capabilities:
+  - query
+args:
+  - name: scene
+    required: true
+    description: The scene id to analyse (see the uptimizr://scenes resource).
+  - name: range
+    required: false
+    default: the last 7 days
+    description: The window to analyse, in words — e.g. "the last 7 days", "since launch".
+---
+
+Where does attention concentrate in scene "{{scene}}" over {{range}}?
+
+Work through the method below with the read-only tools it names — all of them scoped with
+`scene="{{scene}}"` — and synthesise one answer.
+
+1. **Orient before you ask anything.** Read the `uptimizr://context` resource first: it gives the
+   real scene ids, the scene's **named regions** and the custom-event names this project emits, and
+   it tells you which metrics are empty because their capture channel is off. Name regions the way
+   the project names them — "the checkout counter", not "the cluster at x≈3".
+
+2. **Where do they look?** `camera_heatmap` (`scene="{{scene}}"`) gives the view-direction
+   distribution — what people point the camera at, whether or not they ever click it. Ask for
+   `format: "summary"`: the digest merges neighbouring cells into a handful of clusters with a
+   share each and a plain-language `reading`, which is what you want here; the raw grid is
+   thousands of cells you cannot describe.
+
+3. **Does looking turn into touching?** `flow_links` (`scene="{{scene}}"`) links where the gaze was
+   to the mesh that was then clicked. A strong link is a working call to action; a heavy look with
+   no outgoing link is content that draws the eye and then disappoints.
+
+4. **Where do the clicks land?** `click_rays` (`scene="{{scene}}"`) gives view-gated clicks per
+   voxel and mesh — clicks attributed to what the visitor could actually see, not to whatever the
+   ray happened to pass through.
+
+5. **Rank the objects.** `top_meshes` (`scene="{{scene}}"`) for the most-interacted meshes, and
+   `mesh_dwell` (`scene="{{scene}}"`) for how long attention rests on each one. Dwell without
+   interaction is hesitation, and it usually means the object looks clickable and is not, or is
+   clickable and does not look it.
+
+6. **Name the cold half.** `mesh_blind_spots` (`scene="{{scene}}"`) lists the meshes that are
+   present and essentially never noticed. A hot-spot report that only names hot spots tells you
+   nothing about the content you paid to build.
+
+7. **Narrow it with the DSL.** For anything the canned tools do not expose, use the single `query`
+   tool: pick the `metric`, bound it with `range`, filter it, and set `format: "summary"` for a
+   bounded digest — each summary row carries a `drillQuery` you can send straight back instead of
+   rebuilding the filter. Set `compare: { range: <previous window> }` to see whether a hot spot is
+   new, and `explain: true` when a result looks wrong or empty: the plan names the capture channel,
+   the sample size and the row cap behind it.
+
+## What to report
+
+- The two or three real hot-spots, named with the project's own region and mesh names, each with
+  its share of attention.
+- The cold areas and the meshes nobody notices.
+- Where gaze fails to convert into interaction, and what that implies for layout and
+  call-to-action placement.
+
+Carry the caveats: heatmaps are gated on the view/pointer capture channels and are sampled
+(ADR 0012), so a share is a share _of the sampled events_; say so, and say when a result was
+truncated (`meta.truncated`) or sits below the metric's own minimum sample. Do not turn a voxel
+cluster into a claim about one object unless `click_rays` or `flow_links` attributes it to that
+mesh.
+
+End with 2–3 concrete layout or content recommendations. If an `annotate` tool is available, leave
+a note on the region you want revisited — a region-scoped annotation is what makes the next report
+open where this one ended. If a `pin_panel` tool is available, pin the heatmap panel you reasoned
+from.