@uptimizr/mcp 1.1.1 → 1.2.0

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

package/dist/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE/E,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAErB,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC;IACzB,+BAA+B;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE;QAAE,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;KAAE,CAAC;IAC7E,iDAAiD;IACjD,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;IACnC,mCAAmC;IACnC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC7B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,kFAAkF;IAClF,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IACnD,4EAA4E;IAC5E,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,8BAA8B;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,cAAc,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,EAAE,IAAI,CAAC;IACf,oEAAoE;IACpE,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IACjC,0DAA0D;IAC1D,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC7C,+EAA+E;IAC/E,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC3C;;;OAGG;IACH,OAAO,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC/C,sDAAsD;IACtD,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAmCD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,sBAAsB,CA8C1D"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG/E,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAErB,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC;IACzB,+BAA+B;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;QACjC,UAAU,CAAC,EAAE,gBAAgB,CAAC;KAC/B,CAAC;IACF,iDAAiD;IACjD,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;IACnC,mCAAmC;IACnC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC7B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,kFAAkF;IAClF,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IACnD,4EAA4E;IAC5E,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,8BAA8B;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,cAAc,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,EAAE,IAAI,CAAC;IACf,oEAAoE;IACpE,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IACjC,0DAA0D;IAC1D,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC7C,+EAA+E;IAC/E,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC3C;;;OAGG;IACH,OAAO,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC/C,sDAAsD;IACtD,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AA0DD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,sBAAsB,CAkGhG"}

package/dist/capabilities.js

@@ -1,6 +1,28 @@
 import { EVENT_TYPES, SCHEMA_VERSION } from "@uptimizr/schema";
 import { z } from "zod";
-import { FILTER_TARGETS, allMetrics, isResourceMetric, } from "@uptimizr/metrics";
+import { queryTool } from "@uptimizr/agent-core";
+import { FILTER_TARGETS, allMetrics, isResourceMetric, metricCapability, } from "@uptimizr/metrics";
+import { NON_REGISTRY_READ_TOOLS } from "@uptimizr/agent-core";
+/**
+ * The query DSL's own top-level fields (ADR 0051 §3), for the parameter
+ * glossary. The per-metric tools' parameters are all registry `FilterId`s and
+ * are described by `FILTER_TARGETS`; the `query` tool's are the grammar's, so
+ * they are described here. `limit` and `format` are deliberately absent: they
+ * are filter ids too, and `FILTER_TARGETS` already defines them.
+ */
+const QUERY_DSL_PARAMS = {
+    v: "Grammar version. Always `1`.",
+    metric: "The registry metric to compute — any `id` in `metrics` below.",
+    dimensions: "Group-by dimensions. Must be the metric's own grain, or omitted: each metric is computed " +
+        "at one fixed grain.",
+    filters: "The filters the chosen metric declares, as a JSON object (a metric's `filters` list names " +
+        "them). `since`/`until` live in `range` and `format` is a top-level field.",
+    range: "The time window, `{ since, until }` in epoch milliseconds. Required.",
+    segment: "A named slice to hold fixed. Part of the grammar; not answered yet.",
+    compare: "A second range or segment to compare against. Part of the grammar; not answered yet.",
+    order: "Result ordering. Part of the grammar; not answered yet — each metric has its own order.",
+    explain: "Return the compiled plan instead of the rows. Part of the grammar; not answered yet.",
+};
 /** Every request parameter a metric accepts: its path params, then its filters. */
 function paramsOf(metric) {
     return [...(metric.endpoint?.pathParams ?? []), ...metric.filters];
@@ -37,22 +59,56 @@ function toMetricDescriptor(metric) {
  * schema. Pure and synchronous — it introspects definitions only, never the
  * collector, so it is safe to serve as a static resource.
  */
-export function buildCapabilities() {
+export function buildCapabilities(options = {}) {
+    const granted = new Set(options.capabilities ?? ["query"]);
     const metrics = allMetrics();
-    const served = metrics.filter((metric) => metric.endpoint != null);
-    const tools = served.map((metric) => ({
-        name: metric.id,
-        title: metric.title,
-        description: metric.description,
-        params: paramsOf(metric),
-    }));
+    // `tools` describes what THIS key can call, so a capability-gated metric is
+    // listed only when the key holds its capability (ADR 0051 §7). `metrics` below
+    // still documents the whole registry, each entry carrying the capability its
+    // endpoint needs — the difference between "you cannot call this" and "this
+    // does not exist" is worth keeping.
+    const served = metrics.filter((metric) => metric.endpoint != null && granted.has(metricCapability(metric)));
+    const tools = [
+        ...served.map((metric) => ({
+            name: metric.id,
+            title: metric.title,
+            description: metric.description,
+            params: paramsOf(metric),
+        })),
+        // The descriptor must describe what the server actually registers, and the
+        // server registers `readTools` — which carries a short tail of collector
+        // reads that are configuration rather than measurements and so have no
+        // registry entry (#311). They take no filters, hence the empty `params`.
+        ...NON_REGISTRY_READ_TOOLS.map((tool) => ({
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            params: [],
+        })),
+    ];
+    // The one tool that is not per-metric: the query DSL (ADR 0051 §3). It is
+    // described here too, because this descriptor is what an agent reads to learn
+    // the surface — and the DSL tool's own description sends the agent *back*
+    // here for the metric vocabulary, so leaving it out would close the loop on
+    // nothing.
+    tools.push({
+        name: queryTool.name,
+        title: queryTool.title,
+        description: queryTool.description,
+        params: Object.keys(queryTool.inputSchema),
+    });
     const usedParams = new Set();
     for (const metric of served)
         for (const param of paramsOf(metric))
             usedParams.add(param);
-    const params = [...usedParams]
-        .sort()
-        .map((name) => ({ name, description: FILTER_TARGETS[name].description }));
+    const params = [
+        ...[...usedParams]
+            .sort()
+            .map((name) => ({ name, description: FILTER_TARGETS[name].description })),
+        ...Object.entries(QUERY_DSL_PARAMS)
+            .filter(([name]) => !usedParams.has(name))
+            .map(([name, description]) => ({ name, description })),
+    ];
     return {
         schemaVersion: SCHEMA_VERSION,
         readOnly: true,
@@ -61,8 +117,16 @@ export function buildCapabilities() {
         tools,
         metrics: metrics.map(toMetricDescriptor),
         notes: [
+            "Read the uptimizr://context resource FIRST. It describes the project in front of you — " +
+                "its scene ids and named regions, the custom events this application emits and the props " +
+                "they carry, how fresh the data is, whether raw session retention is on, and which of the " +
+                "metrics below are empty because their capture channel is off. Use the names it gives " +
+                "you; do not infer a scene id, a region id or a custom-event name.",
             "This MCP surface is strictly read-only: aggregate, privacy-preserving queries only. " +
-                "There are no ingestion, mutation, or raw per-session event tools (ADR 0003 / ADR 0017).",
+                "There are no ingestion or mutation tools, and no raw per-session event tools " +
+                "(ADR 0003 / ADR 0017). The one per-session read, `session_narrative`, is a bounded " +
+                "compaction rather than an event stream, and the collector serves it only to a key " +
+                "holding `query:raw` on a deployment with raw-session retention enabled.",
             "`metrics` is the collector's semantic metric registry (ADR 0051 §1): for each metric it " +
                 "gives the result `grain` (what one row is), the `columns` with their units, the JSON " +
                 "Schema of a row, `limits`, how to read it (`interpretation`) and how far to trust it " +
@@ -70,12 +134,19 @@ export function buildCapabilities() {
             "`sourceChannels` names the capture channels (ADR 0012) that feed a metric. If a project " +
                 "has that channel disabled or sampled down, the metric is empty or proportional rather " +
                 "than exact — say so instead of reporting a zero as a finding.",
+            "`query` (the last tool) runs any metric above through the query DSL (ADR 0051 §3): one " +
+                "request naming the `metric`, a required `range`, the filters that metric declares, a " +
+                "`limit` and a `format`. Prefer it when a question needs a filter the per-metric tool " +
+                "does not expose. Its `compare`, `segment`, `order` and `explain` fields are part of the " +
+                "published grammar but are not answered yet — run two queries and subtract instead.",
             "`tools` lists the registry's served read surface and the request parameters of each " +
                 "underlying endpoint. It is exactly the set this server registers, because the tool " +
                 "catalog is generated from the same registry (ADR 0051 §1) — the authoritative input " +
                 "and output schemas of a registered tool are still the ones returned by `tools/list`.",
-            "Enumerate the concrete scene ids for the `scene` parameter with the uptimizr://scenes " +
-                "resource or the list_scenes tool; enumerate sessions with the list_sessions tool.",
+            "Enumerate the concrete scene ids for the `scene` parameter with the uptimizr://context or " +
+                "uptimizr://scenes resource, or the list_scenes tool; enumerate sessions with the " +
+                "list_sessions tool. Custom-event names and their prop keys come from " +
+                "uptimizr://context or the custom_event_vocabulary tool.",
             "All time ranges use epoch-millisecond `since`/`until`. Omit both for all-time.",
             "The same registry drives the collector's OpenAPI document at GET /api/v1/openapi.json, " +
                 "which describes every endpoint below with its parameters and response schema.",

package/dist/capabilities.js.map

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

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { readMcpConfig, type McpConfig } from "./config.js";
-export { createCollectorClient, CollectorError, readTools, type CollectorClient, type CollectorClientConfig, type QueryParams, type ReadTool, type ReadToolRequest, } from "@uptimizr/agent-core";
-export { createMcpServer } from "./server.js";
-export { buildCapabilities, type CapabilitiesDescriptor, type CapabilityToolDescriptor, type CapabilityParamDescriptor, } from "./capabilities.js";
-export { registerResources, CAPABILITIES_URI, SCENES_URI } from "./resources.js";
+export { createCollectorClient, CollectorError, readTools, rawTools, type CollectorClient, type CollectorClientConfig, type QueryParams, type ReadTool, type ReadToolRequest, } from "@uptimizr/agent-core";
+export { writeTools, mutatingWriteTools, type WriteTool } from "@uptimizr/agent-core";
+export { createMcpServer, fetchKeyCapabilities, type CreateMcpServerOptions } from "./server.js";
+export { buildCapabilities, type BuildCapabilitiesOptions, type CapabilitiesDescriptor, type CapabilityToolDescriptor, type CapabilityParamDescriptor, } from "./capabilities.js";
+export { registerResources, CAPABILITIES_URI, SCENES_URI, SKILLS_URI } from "./resources.js";
 export { registerPrompts } from "./prompts.js";
 export { version } from "./version.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACjG,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,8 +1,12 @@
 export { readMcpConfig } from "./config.js";
-export { createCollectorClient, CollectorError, readTools, } from "@uptimizr/agent-core";
-export { createMcpServer } from "./server.js";
+export { createCollectorClient, CollectorError, readTools, rawTools, } from "@uptimizr/agent-core";
+// The metadata write tools (#310) — deliberately a separate export from
+// `readTools` above, so an integration's read-only stance stays inspectable
+// (ADR 0017): events are read-only, metadata writes sit behind `annotate`.
+export { writeTools, mutatingWriteTools } from "@uptimizr/agent-core";
+export { createMcpServer, fetchKeyCapabilities } from "./server.js";
 export { buildCapabilities, } from "./capabilities.js";
-export { registerResources, CAPABILITIES_URI, SCENES_URI } from "./resources.js";
+export { registerResources, CAPABILITIES_URI, SCENES_URI, SKILLS_URI } from "./resources.js";
 export { registerPrompts } from "./prompts.js";
 export { version } from "./version.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,SAAS,GAMV,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,GAIlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,QAAQ,GAMT,MAAM,sBAAsB,CAAC;AAC9B,wEAAwE;AACxE,4EAA4E;AAC5E,2EAA2E;AAC3E,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAkB,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAA+B,MAAM,aAAa,CAAC;AACjG,OAAO,EACL,iBAAiB,GAKlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAuBzE,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAiGvD"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA+BzE,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmBvD"}

package/dist/prompts.js

@@ -1,3 +1,4 @@
+import { AGENT_SKILLS } from "@uptimizr/agent-core";
 import { z } from "zod";
 /**
  * Curated prompt templates for common 3D-analytics investigations (ADR 0050 §7).
@@ -5,92 +6,40 @@ import { z } from "zod";
  * read-only tools in a sensible order — no data is fetched here; the agent runs
  * the tools. Templates are intentionally tool-agnostic about exact arguments so
  * the agent can adapt (e.g. resolve the current epoch-ms range itself).
+ *
+ * The templates themselves are the **agent skills** of `@uptimizr/agent-core`
+ * (`AGENT_SKILLS`). They live there because the headless `uptimizr agent report`
+ * CLI seeds its transcript with the same text (ADR 0051 §6, design sketch §F.4)
+ * and the eval bank asks the same questions; this module is the MCP *binding* —
+ * it turns each skill's argument list into a Zod `argsSchema` and its `render`
+ * into the single user message `prompts/get` returns. Reword a skill once and
+ * every client changes with it.
  */
-const sceneArg = z
-    .string()
-    .optional()
-    .describe("Optional scene id to scope the analysis to (see the uptimizr://scenes resource).");
-const requiredSceneArg = z
-    .string()
-    .describe("The scene id to analyse (see the uptimizr://scenes resource).");
-const forScene = (scene) => scene ? `scene "${scene}"` : "the project (all scenes)";
+/** Build a prompt template's Zod `argsSchema` from a skill's argument list. */
+function argsSchemaFor(skill) {
+    const shape = {};
+    for (const arg of skill.args) {
+        shape[arg.name] = arg.required
+            ? z.string().describe(arg.description)
+            : z.string().optional().describe(arg.description);
+    }
+    return shape;
+}
 /** Register the curated prompt templates on the server. */
 export function registerPrompts(server) {
-    server.registerPrompt("weekly_scene_health", {
-        title: "Weekly scene health",
-        description: "A weekly health check for a scene (or the whole project): traffic, event mix, " +
-            "performance, and the most-interacted meshes.",
-        argsSchema: { scene: sceneArg },
-    }, ({ scene }) => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `Give me a weekly health report for ${forScene(scene)} covering the last 7 days.\n\n` +
-                        "Use these read-only tools and summarise the findings:\n" +
-                        "- `event_counts` for the per-event-type mix" +
-                        (scene ? ` (scene="${scene}")` : "") +
-                        ".\n" +
-                        "- `timeseries` (interval ~86400s) to show the day-by-day event volume and average FPS trend.\n" +
-                        "- `perf_summary` for avg/min/p50 FPS.\n" +
-                        "- `top_meshes` for the most-interacted meshes.\n" +
-                        "- `list_sessions` for how many sessions were recorded.\n\n" +
-                        "Call out anything unusual (traffic spikes/drops, FPS regressions, error events) and " +
-                        "end with 2–3 concrete recommendations.",
-                },
-            },
-        ],
-    }));
-    server.registerPrompt("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, and the objects that draw the most interaction.",
-        argsSchema: { scene: requiredSceneArg },
-    }, ({ scene }) => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `Where does attention concentrate in scene "${scene}"?\n\n` +
-                        'Use these read-only tools (all scoped with scene="' +
-                        scene +
-                        '") and synthesise the result:\n' +
-                        "- `camera_heatmap` for the view-direction distribution (what people look at).\n" +
-                        "- `flow_links` for how gaze flows into clicked meshes.\n" +
-                        "- `click_rays` for view-gated clicks per voxel/mesh.\n" +
-                        "- `top_meshes` for the most-interacted objects.\n\n" +
-                        "Describe the main hot-spots, any ignored/cold areas, and what that implies for the " +
-                        "scene's layout or call-to-action placement.",
-                },
-            },
-        ],
-    }));
-    server.registerPrompt("xr_comfort_review", {
-        title: "XR comfort & drop-off review",
-        description: "Review VR/AR comfort signals for a scene (or the whole project): rapid head rotation, " +
-            "locomotion style, session abandonment, and input-source mix.",
-        argsSchema: { scene: sceneArg },
-    }, ({ scene }) => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `Review XR/immersive comfort and drop-off for ${forScene(scene)}.\n\n` +
-                        "Use these read-only tools" +
-                        (scene ? ` (scene="${scene}")` : "") +
-                        " and correlate the signals:\n" +
-                        "- `xr_rotation` for rapid head/view turns (a motion-sickness proxy).\n" +
-                        "- `xr_locomotion` for the fly/navigate/teleport mix and session span.\n" +
-                        "- `xr_abandonment` for short XR sessions that signal headset drop-off.\n" +
-                        "- `xr_sources` for the hand vs. controller vs. gaze input split.\n\n" +
-                        "Flag likely-uncomfortable patterns (heavy rapid rotation or continuous locomotion " +
-                        "paired with early exits) and suggest comfort mitigations.",
+    for (const skill of AGENT_SKILLS) {
+        server.registerPrompt(skill.name, {
+            title: skill.title,
+            description: skill.description,
+            argsSchema: argsSchemaFor(skill),
+        }, ((args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: { type: "text", text: skill.render(args) },
                 },
-            },
-        ],
-    }));
+            ],
+        })));
+    }
 }
 //# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,MAAM,QAAQ,GAAG,CAAC;KACf,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,kFAAkF,CAAC,CAAC;AAEhG,MAAM,gBAAgB,GAAG,CAAC;KACvB,MAAM,EAAE;KACR,QAAQ,CAAC,+DAA+D,CAAC,CAAC;AAE7E,MAAM,QAAQ,GAAG,CAAC,KAAyB,EAAU,EAAE,CACrD,KAAK,CAAC,CAAC,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC,CAAC,0BAA0B,CAAC;AAE1D,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,MAAM,CAAC,cAAc,CACnB,qBAAqB,EACrB;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,gFAAgF;YAChF,8CAA8C;QAChD,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE;KAChC,EACD,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,sCAAsC,QAAQ,CAAC,KAAK,CAAC,gCAAgC;wBACrF,yDAAyD;wBACzD,6CAA6C;wBAC7C,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;wBACpC,KAAK;wBACL,gGAAgG;wBAChG,yCAAyC;wBACzC,kDAAkD;wBAClD,4DAA4D;wBAC5D,sFAAsF;wBACtF,wCAAwC;iBAC3C;aACF;SACF;KACF,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,cAAc,CACnB,oBAAoB,EACpB;QACE,KAAK,EAAE,iCAAiC;QACxC,WAAW,EACT,+EAA+E;YAC/E,iEAAiE;QACnE,UAAU,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;KACxC,EACD,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,8CAA8C,KAAK,QAAQ;wBAC3D,oDAAoD;wBACpD,KAAK;wBACL,iCAAiC;wBACjC,iFAAiF;wBACjF,0DAA0D;wBAC1D,wDAAwD;wBACxD,qDAAqD;wBACrD,qFAAqF;wBACrF,6CAA6C;iBAChD;aACF;SACF;KACF,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,cAAc,CACnB,mBAAmB,EACnB;QACE,KAAK,EAAE,8BAA8B;QACrC,WAAW,EACT,wFAAwF;YACxF,8DAA8D;QAChE,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE;KAChC,EACD,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,gDAAgD,QAAQ,CAAC,KAAK,CAAC,OAAO;wBACtE,2BAA2B;wBAC3B,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;wBACpC,+BAA+B;wBAC/B,wEAAwE;wBACxE,yEAAyE;wBACzE,0EAA0E;wBAC1E,sEAAsE;wBACtE,oFAAoF;wBACpF,2DAA2D;iBAC9D;aACF;SACF;KACF,CAAC,CACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAmB,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;GAcG;AAEH,+EAA+E;AAC/E,SAAS,aAAa,CAAC,KAAiB;IACtC,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,QAAQ;YAC5B,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC;YACtC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,MAAM,CAAC,cAAc,CACnB,KAAK,CAAC,IAAI,EACV;YACE,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,UAAU,EAAE,aAAa,CAAC,KAAK,CAAU;SAC1C,EACD,CAAC,CAAC,IAAwC,EAAE,EAAE,CAAC,CAAC;YAC9C,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAe;oBACrB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;iBAC7D;aACF;SACF,CAAC,CAAU,CACb,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/resources.d.ts

@@ -1,9 +1,14 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CollectorClient } from "@uptimizr/agent-core";
+import { type CollectorClient } from "@uptimizr/agent-core";
+import { type BuildCapabilitiesOptions } from "./capabilities.js";
 /** URI of the static, machine-readable capabilities/schema descriptor. */
 export declare const CAPABILITIES_URI = "uptimizr://capabilities";
 /** URI of the live list of scenes with recent activity. */
 export declare const SCENES_URI = "uptimizr://scenes";
+/** URI of the live project context document (ADR 0051 §5). */
+export declare const CONTEXT_URI = "uptimizr://context";
+/** URI of the packaged methodology skills catalog (ADR 0051 §7). */
+export declare const SKILLS_URI = "uptimizr://skills";
 /**
  * Register read-only MCP resources so an agent can **self-discover** the surface
  * (ADR 0050 §7):
@@ -11,11 +16,25 @@ export declare const SCENES_URI = "uptimizr://scenes";
  * - `uptimizr://capabilities` — a static descriptor (event types, tool catalog,
  *   parameter semantics) built from the shared catalog + `@uptimizr/schema`. No
  *   collector call; it documents *what can be asked*.
+ * - `uptimizr://context` — the live **project context document** (ADR 0051 §5):
+ *   the scenes and their named regions, the custom-event vocabulary this
+ *   application emits, data freshness and retention flags, and which metrics are
+ *   empty because their capture channel is off. Read it **first**: it is the
+ *   difference between filtering on a real scene id or custom-event name and
+ *   guessing one.
  * - `uptimizr://scenes` — the live set of scene ids with activity, fetched via
  *   the read-only collector client, so the `scene` parameter can be filled in
- *   with real values.
+ *   with real values. A narrower view of what `uptimizr://context` already
+ *   carries; kept for clients that only need the ids.
+ * - `uptimizr://skills` — the packaged **methodology skills** (ADR 0051 §7): the
+ *   same investigations this server offers as prompt templates, listed with what
+ *   each one produces, the tools its method uses and the arguments it takes. A
+ *   client whose UI has no prompt picker can still read the catalog and ask for
+ *   one by name; the full text stays behind `prompts/get`. No collector call.
  *
- * Both are read-only; resources never mutate or expose raw per-session events.
+ * All four are read-only; resources never mutate or expose raw per-session
+ * events. A collector too old to serve `GET /api/v1/context` makes the context
+ * resource fail its read — the other resources and every tool keep working.
  */
-export declare function registerResources(server: McpServer, client: CollectorClient): void;
+export declare function registerResources(server: McpServer, client: CollectorClient, options?: BuildCapabilitiesOptions): void;
 //# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAC1D,2DAA2D;AAC3D,eAAO,MAAM,UAAU,sBAAsB,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAuClF"}
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAqB,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAErF,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAC1D,2DAA2D;AAC3D,eAAO,MAAM,UAAU,sBAAsB,CAAC;AAC9C,8DAA8D;AAC9D,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,oEAAoE;AACpE,eAAO,MAAM,UAAU,sBAAsB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,wBAA6B,GACrC,IAAI,CAoGN"}

package/dist/resources.js

@@ -1,8 +1,13 @@
+import { AGENT_SKILLS } from "@uptimizr/agent-core";
 import { buildCapabilities } from "./capabilities.js";
 /** URI of the static, machine-readable capabilities/schema descriptor. */
 export const CAPABILITIES_URI = "uptimizr://capabilities";
 /** URI of the live list of scenes with recent activity. */
 export const SCENES_URI = "uptimizr://scenes";
+/** URI of the live project context document (ADR 0051 §5). */
+export const CONTEXT_URI = "uptimizr://context";
+/** URI of the packaged methodology skills catalog (ADR 0051 §7). */
+export const SKILLS_URI = "uptimizr://skills";
 /**
  * Register read-only MCP resources so an agent can **self-discover** the surface
  * (ADR 0050 §7):
@@ -10,13 +15,27 @@ export const SCENES_URI = "uptimizr://scenes";
  * - `uptimizr://capabilities` — a static descriptor (event types, tool catalog,
  *   parameter semantics) built from the shared catalog + `@uptimizr/schema`. No
  *   collector call; it documents *what can be asked*.
+ * - `uptimizr://context` — the live **project context document** (ADR 0051 §5):
+ *   the scenes and their named regions, the custom-event vocabulary this
+ *   application emits, data freshness and retention flags, and which metrics are
+ *   empty because their capture channel is off. Read it **first**: it is the
+ *   difference between filtering on a real scene id or custom-event name and
+ *   guessing one.
  * - `uptimizr://scenes` — the live set of scene ids with activity, fetched via
  *   the read-only collector client, so the `scene` parameter can be filled in
- *   with real values.
+ *   with real values. A narrower view of what `uptimizr://context` already
+ *   carries; kept for clients that only need the ids.
+ * - `uptimizr://skills` — the packaged **methodology skills** (ADR 0051 §7): the
+ *   same investigations this server offers as prompt templates, listed with what
+ *   each one produces, the tools its method uses and the arguments it takes. A
+ *   client whose UI has no prompt picker can still read the catalog and ask for
+ *   one by name; the full text stays behind `prompts/get`. No collector call.
  *
- * Both are read-only; resources never mutate or expose raw per-session events.
+ * All four are read-only; resources never mutate or expose raw per-session
+ * events. A collector too old to serve `GET /api/v1/context` makes the context
+ * resource fail its read — the other resources and every tool keep working.
  */
-export function registerResources(server, client) {
+export function registerResources(server, client, options = {}) {
     server.registerResource("capabilities", CAPABILITIES_URI, {
         title: "Uptimizr capabilities",
         description: "Machine-readable descriptor of the read-only analytics surface: event types, the tool " +
@@ -27,10 +46,23 @@ export function registerResources(server, client) {
             {
                 uri: uri.href,
                 mimeType: "application/json",
-                text: JSON.stringify(buildCapabilities(), null, 2),
+                text: JSON.stringify(buildCapabilities(options), null, 2),
             },
         ],
     }));
+    server.registerResource("context", CONTEXT_URI, {
+        title: "Project context",
+        description: "Read this first. The live description of THIS project: scenes and their named regions, " +
+            "the custom events the application emits and the props they carry, data freshness and " +
+            "retention flags, the store engine, and which metrics will be empty because their capture " +
+            "channel is off. Use the ids and names it gives you instead of inferring your own.",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const data = await client.get("api/v1/context", {});
+        return {
+            contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(data) }],
+        };
+    });
     server.registerResource("scenes", SCENES_URI, {
         title: "Active scenes",
         description: "Live list of developer-assigned scene ids with recent activity — the valid values for " +
@@ -42,5 +74,35 @@ export function registerResources(server, client) {
             contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(data) }],
         };
     });
+    server.registerResource("skills", SKILLS_URI, {
+        title: "Methodology skills",
+        description: "The packaged investigation methodologies this server also offers as prompt templates: " +
+            "what each one produces, when to use it, the tools its method relies on, the API-key " +
+            "capabilities it needs and the arguments it takes. Ask for one by name with " +
+            "`prompts/get` to receive the method itself. No collector call.",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                // The body is deliberately left out: it is a template, and rendering it
+                // needs the arguments `prompts/get` collects. Listing it here would put
+                // an unrendered `{{scene}}` in front of a model as if it were the method.
+                text: JSON.stringify({
+                    skills: AGENT_SKILLS.map((skill) => ({
+                        name: skill.name,
+                        title: skill.title,
+                        description: skill.description,
+                        tools: skill.tools,
+                        capabilities: skill.capabilities,
+                        args: skill.args,
+                        prompt: skill.name,
+                        file: `skills/${skill.id}/SKILL.md`,
+                    })),
+                }, null, 2),
+            },
+        ],
+    }));
 }
 //# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAC1D,2DAA2D;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAiB,EAAE,MAAuB;IAC1E,MAAM,CAAC,gBAAgB,CACrB,cAAc,EACd,gBAAgB,EAChB;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EACT,wFAAwF;YACxF,8EAA8E;QAChF,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,GAAG,CAAC,IAAI;gBACb,QAAQ,EAAE,kBAAkB;gBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;aACnD;SACF;KACF,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,gBAAgB,CACrB,QAAQ,EACR,UAAU,EACV;QACE,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,wFAAwF;YACxF,yCAAyC;QAC3C,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE;QACZ,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO;YACL,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;SACxF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}