@uptimizr/mcp 1.1.0 → 1.1.1

package/AGENTS.md

@@ -19,6 +19,20 @@ 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
 ```
 
+## Required key capability
+
+`UPTIMIZR_API_KEY` must hold the **`query`** capability — and only that. 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, so a client can check before it registers tools; an
+authenticated key missing a capability is refused with `403`, not `401`.
+
+**`query:raw` is deliberately not needed.** Every tool here is an aggregate read; the server exposes
+no raw per-session, replay or live-follow tool, so granting its key `query:raw` widens the blast
+radius for nothing. `annotate` (metadata writes) and `ingest` are likewise never used. 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.
+
 ## Tools (read-only)
 
 <!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this table -->
@@ -64,6 +78,45 @@ returns `structuredContent` (`{ rows }`) alongside the JSON text — read the sc
 guessing the row shape, and read the tool description for the metric's caveats before trusting a
 small sample.
 
+## Result formats (`format`)
+
+Every **aggregate** tool takes a `format` argument choosing the envelope its rows arrive in
+(ADR 0051 §2). It filters nothing.
+
+| `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. | **The default choice for an agent.** Always, unless you specifically need the rows. |
+| `table`   | `{ meta, rows }`: the same rows plus the metric, range, applied filters, sample size, row count, a truncation flag and the registry's limits.                                                    | You need every row _and_ the context to judge how far to trust it.                  |
+| `full`    | The bare rows, unchanged. Today's default.                                                                                                                                                       | 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.
+- `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.
+- The catalog's default is still `full` — pass `format` explicitly.
+
+## Resources and prompts
+
+- `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**. Read it first — 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.
+- Prompts: `weekly_scene_health` (optional `scene`), `attention_hotspots` (required `scene`) and
+  `xr_comfort_review` (optional `scene`). Each 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.
+
 ## Rules for agents
 
 - **Read-only and privacy-preserving.** Never add ingestion, mutation, or raw per-session event

package/llms.txt

@@ -32,6 +32,45 @@
 
 <!-- generated:registry-tool-names:end -->
 
+## Result formats (`format`)
+
+Every aggregate tool takes `format` — the envelope its rows arrive in, not a filter (ADR 0051 §2).
+
+- `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` — `{ meta, rows }`: every row plus the metric, range, applied filters, sample size, row
+  count, a truncation flag and the registry limits. Use it when you need the rows *and* the context
+  to judge them.
+- `full` — the bare rows, unchanged. Today's catalog default; pass `format` explicitly.
+
+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. `session_meta` and `scene_representation` are stored records, not
+aggregations, and take no `format`.
+
+## Resources and prompts
+
+- `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 first.
+- `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.
+- Prompts: `weekly_scene_health` (optional `scene`), `attention_hotspots` (required `scene`),
+  `xr_comfort_review` (optional `scene`) — each renders one user message sequencing the read-only
+  tools; they fetch nothing themselves.
+
+## Required key capability
+
+`UPTIMIZR_API_KEY` needs the `query` capability, and only that
+(`uptimizr new-key <projectId> --capabilities query --label "mcp-agent"`; `query` is the default).
+`query:raw` is **deliberately not required** — no tool here reads raw per-session, replay or
+live-follow data. `annotate` and `ingest` are never used either. `GET /api/v1/whoami` reports what a
+key holds; a key missing a required capability is refused with `403`.
+
 ## Key exports
 
 - `createMcpServer(client)` — build the read-only MCP server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "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",
@@ -49,7 +49,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.5.4",
-    "@uptimizr/agent-core": "1.1.0",
+    "@uptimizr/agent-core": "1.1.1",
     "@uptimizr/metrics": "0.1.0",
     "@uptimizr/schema": "1.1.0"
   },