@thotischner/observability-mcp 3.2.0 → 3.3.0

package/dist/conformance/mcp-2025-11-25.test.js

@@ -245,3 +245,186 @@ test("MCP 2025-11-25: server advertises protocolVersion equal to or newer than 2
     // recognised date-style version string.
     assert.match(r.protocolVersion, /^\d{4}-\d{2}-\d{2}$/, "protocolVersion must be a YYYY-MM-DD date");
 });
+// ---------------------------------------------------------------------------
+// Behavioural tools/call E2E (post-#415 hardening).
+//
+// These run over the REAL /mcp Streamable-HTTP transport against the booted
+// demo stack (integration.yml sets OMCP_CONFORMANCE_URL). They close the gap
+// that let #415 ship: a param can be ADVERTISED in tools/list yet silently
+// stripped by the SDK before it reaches the handler — an advertise-only
+// assertion passes anyway. Here we call the tool and assert the param TAKES
+// EFFECT over the wire. The demo mcp-server runs with OMCP_RAW_QUERY unset and
+// OMCP_IP_ENRICH_FILE unset, so the gate/not-configured assertions are
+// deterministic regardless of backend data.
+// ---------------------------------------------------------------------------
+async function callTool(session, name, args, id = 50) {
+    const { response } = await jsonRpc("tools/call", { name, arguments: args }, { id, session });
+    if (response.error)
+        return { error: response.error };
+    const r = response.result;
+    const text = r?.content?.[0]?.text;
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    return { isError: r?.isError, parsed, text };
+}
+async function discoverService(session) {
+    const r = await callTool(session, "list_services", {}, 40);
+    const list = Array.isArray(r.parsed) ? r.parsed : r.parsed?.services;
+    const name = Array.isArray(list) && list[0] && (list[0].name || list[0].service);
+    return name || "payment-service"; // demo k3s service as fallback
+}
+test("E2E tools/call: query_logs raw_query is refused over the wire when capability off (#415 #3)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "query_logs", { raw_query: '{job="x"}' });
+    // Proves raw_query SURVIVES transport (not stripped) AND the gate fires E2E.
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    assert.match(msg, /raw_query is disabled/i, `expected gate refusal, got ${msg}`);
+});
+test("E2E tools/call: query_metrics raw_query is refused over the wire when capability off (#415 #3)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "query_metrics", { raw_query: "up" });
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    assert.match(msg, /raw_query is disabled/i, `expected gate refusal, got ${msg}`);
+});
+test("E2E tools/call: enrich_ips dispatches and reports not-configured over the wire (Gap B)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "enrich_ips", { ips: ["203.0.113.5"] });
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    // Proves the ips param survives transport and the tool dispatches; demo has
+    // no OMCP_IP_ENRICH_FILE so the deterministic "not configured" path fires.
+    assert.match(msg, /not configured/i, `expected not-configured notice, got ${msg}`);
+});
+test("E2E tools/call: query_logs aggregate takes effect over the wire — grouped result, not raw rows (#415 #2)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "query_logs", {
+        service,
+        aggregate: { op: "count_over_time", step: "15m" },
+        duration: "1h",
+    });
+    // The aggregate result shape (op/mode/series) is structurally distinct from
+    // the raw-rows shape (entries/summary). Asserting the aggregate shape proves
+    // the `aggregate` param survived the SDK input parsing and reached the
+    // connector — even if the series is empty on a sparse demo window.
+    const p = Array.isArray(r.parsed) ? r.parsed[0] : r.parsed;
+    assert.ok(p, `expected an aggregate result, got ${JSON.stringify(r)}`);
+    assert.equal(p.op, "count_over_time", "result must carry the aggregate op");
+    assert.ok("mode" in p && Array.isArray(p.series), "result must be the aggregate shape (mode + series)");
+    assert.ok(!("entries" in p), "aggregate path must NOT return the raw-rows shape");
+});
+test("E2E tools/call: query_metrics labels param is accepted over the wire (#415 #4)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "query_metrics", {
+        service,
+        metric: "cpu",
+        labels: { job: service },
+        duration: "5m",
+    });
+    // Must not be a transport/dispatch error; the labels param must be accepted
+    // (a structured "no data" result is fine — proves it reached the handler).
+    assert.ok(!r.error, `unexpected JSON-RPC error: ${JSON.stringify(r.error)}`);
+    assert.ok(r.parsed !== undefined || r.text !== undefined, "expected a CallToolResult payload");
+});
+test("E2E tools/call: get_anomaly_history dispatches without a PromQL 400 crash (H1 over the wire)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "get_anomaly_history", { service, duration: "1h", method: "mad" });
+    // After the rawQuery fix the emitted PromQL is valid; empty data is a clean
+    // non-error result. The bug produced an invalid-query path that still
+    // returned non-error empty, so we assert the dispatch shape is well-formed.
+    assert.ok(!r.error, `unexpected JSON-RPC error: ${JSON.stringify(r.error)}`);
+    assert.ok(r.parsed !== undefined || r.text !== undefined, "expected a CallToolResult payload");
+});
+test("E2E tools/call: every registered tool dispatches over MCP and returns a CallToolResult", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    // Minimal valid args per tool; tools with required args get discovered/dummy
+    // values. A clean isError result (e.g. query_traces 'no trace backends') is
+    // acceptable — we only require a shape-conformant dispatch, never a -32xxx.
+    const calls = {
+        list_sources: {},
+        list_services: {},
+        query_metrics: { service, metric: "cpu" },
+        query_logs: { service },
+        get_anomaly_history: { service },
+        generate_postmortem: { service },
+        query_traces: { service },
+        get_service_health: { service },
+        detect_anomalies: {},
+        get_topology: {},
+        get_blast_radius: { resource: service },
+        enrich_ips: { ips: ["203.0.113.5"] },
+    };
+    const { response: list } = await jsonRpc("tools/list", {}, { id: 41, session });
+    const names = (list.result?.tools ?? []).map((t) => t.name);
+    assert.ok(names.length >= 12, `expected >=12 tools, got ${names.length}`);
+    let id = 60;
+    for (const name of names) {
+        const args = calls[name] ?? {};
+        const { response } = await jsonRpc("tools/call", { name, arguments: args }, { id: id++, session });
+        if (response.error) {
+            assert.fail(`tool ${name} returned a JSON-RPC dispatch error: ${JSON.stringify(response.error)}`);
+        }
+        const r = response.result;
+        assert.ok(Array.isArray(r.content), `tool ${name} must return content[]`);
+    }
+});
+test("E2E tools/list: every builtin tool advertises ToolAnnotations (readOnlyHint)", opts, async () => {
+    // AX hardening: all 12 builtin tools are read-only; clients (e.g. Claude)
+    // use these hints for auto-approve decisions, so they must be advertised
+    // over the live transport — not just present in the registration source.
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/list", {}, { id: 2, session });
+    const r = response.result;
+    const tools = r.tools ?? [];
+    assert.ok(tools.length >= 12, `expected >=12 tools, got ${tools.length}`);
+    // Federated tools (namespaced `<prefix>.<tool>`) proxy upstream metadata and
+    // may legitimately lack annotations — only the builtin set is asserted.
+    const builtin = tools.filter((t) => t.name && !t.name.includes("."));
+    for (const t of builtin) {
+        assert.equal(t.annotations?.readOnlyHint, true, `tool ${t.name} must advertise annotations.readOnlyHint=true`);
+        assert.ok(t.annotations?.title, `tool ${t.name} must advertise annotations.title`);
+    }
+});
+test("E2E: builtin resource agent-usage-guide is listed and readable", opts, async () => {
+    // AX: the agent usage guide ships as an MCP resource so clients can pull
+    // it into context without a web fetch. Assert list + read over the wire.
+    const session = await newSession();
+    const list = await jsonRpc("resources/list", {}, { id: 10, session });
+    const resources = list.response.result?.resources ?? [];
+    assert.ok(resources.some((r) => r.uri === "omcp://guide/agent-usage"), `agent-usage-guide resource must be listed, got ${JSON.stringify(resources.map((r) => r.uri))}`);
+    const read = await jsonRpc("resources/read", { uri: "omcp://guide/agent-usage" }, { id: 11, session });
+    const contents = read.response.result?.contents ?? [];
+    assert.ok((contents[0]?.text ?? "").includes("Triage recipe"), "guide text must round-trip");
+});
+test("E2E: builtin prompts triage-incident + write-postmortem are listed and resolvable", opts, async () => {
+    const session = await newSession();
+    const list = await jsonRpc("prompts/list", {}, { id: 12, session });
+    const prompts = list.response.result?.prompts ?? [];
+    for (const name of ["triage-incident", "write-postmortem"]) {
+        assert.ok(prompts.some((p) => p.name === name), `prompt ${name} must be listed`);
+    }
+    const got = await jsonRpc("prompts/get", { name: "triage-incident", arguments: { service: "ci-probe" } }, { id: 13, session });
+    const msgs = got.response.result?.messages ?? [];
+    assert.ok((msgs[0]?.content?.text ?? "").includes('"ci-probe"'), "prompt must interpolate the service arg");
+});
+test("E2E: /llms.txt is served and reflects the canonical tool registry", opts, async () => {
+    // llms.txt convention: LLM-readable summary at the server root. Generated
+    // from registry-names.ts, so this also guards against registry drift.
+    const base = URL_ENV.replace(/\/mcp\/?$/, "");
+    const res = await fetch(`${base}/llms.txt`);
+    assert.equal(res.status, 200);
+    assert.match(res.headers.get("content-type") ?? "", /text\/plain/);
+    const text = await res.text();
+    assert.match(text, /^# observability-mcp/, "must start with the llms.txt H1");
+    for (const name of ["query_logs", "query_metrics", "enrich_ips", "get_blast_radius"]) {
+        assert.ok(text.includes(`- ${name} (`), `tool ${name} must be listed`);
+    }
+    assert.ok(text.includes("for-agents"), "must link the for-agents guide");
+});

package/dist/index.js

@@ -393,15 +393,95 @@ async function main() {
             }
             return mcpServer.prompt(name, ...rest);
         });
-        // Suppress unused-warn — kept for the moment registrations land.
-        void registerResource;
-        void registerPrompt;
+        // --- Builtin resources + prompts (agent experience) -------------------
+        // The usage guide is the distilled, agent-validated workflow from issue
+        // #415 — served as an MCP resource so a client can pull it into context
+        // without a web fetch. Prompts compose the existing read-only tools into
+        // the two flows agents run most.
+        registerResource("agent-usage-guide", "omcp://guide/agent-usage", {
+            description: "How to use this gateway effectively as an agent: the proven filter→aggregate→enrich triage recipe, signal-vs-silence behaviours, and the operator flags that unlock optional tools.",
+            mimeType: "text/markdown",
+        }, async (uri) => ({
+            contents: [
+                {
+                    uri: uri.toString(),
+                    mimeType: "text/markdown",
+                    text: [
+                        "# Agent usage guide (observability-mcp)",
+                        "",
+                        "All tools are read-only (`readOnlyHint: true`). The golden rule:",
+                        "**filter and aggregate server-side — ask for numbers, not haystacks.**",
+                        "",
+                        "## Triage recipe (agent-validated, issue #415)",
+                        '1. `query_logs` with `labels` (exact-match field filters, e.g. {"environment":"prod"})',
+                        '   and `aggregate` ({"op":"topk","by":["ip"],"k":10} or {"op":"count_over_time","step":"15m"})',
+                        "   — pushed down to LogQL, returns a handful of numbers instead of thousands of rows.",
+                        "2. `enrich_ips` with the IPs from step 1 — offline geo/ASN/hosting-flag lookup",
+                        "   (bot-vs-human signal). Requires OMCP_IP_ENRICH_FILE on the operator side.",
+                        '3. `query_metrics` with `labels` ({"route":"/checkout"}) and `groupBy` to scope a',
+                        "   curated metric to the slice you care about.",
+                        "",
+                        "## Incident flow",
+                        "`detect_anomalies` (fleet scan) → `get_service_health` (one-service verdict) →",
+                        "`get_blast_radius` (shared-host impact) → `generate_postmortem` (markdown report).",
+                        "",
+                        "## When something is empty or refused",
+                        "The gateway explains itself: no topology connector → explicit note; no trace",
+                        "backend → explicit error; `raw_query` disabled → message naming OMCP_RAW_QUERY=on;",
+                        "redacted values → a `_redacted` count in the result. Relay flag names to your",
+                        "operator verbatim — the messages are written to be forwarded.",
+                        "",
+                        "## Report findings",
+                        "Structured agent reports drive releases here (see issue #415). File one:",
+                        "https://github.com/ThoTischner/observability-mcp/issues/new?template=agent-report.yml",
+                        "Full guide: https://thotischner.github.io/observability-mcp/for-agents/",
+                    ].join("\n"),
+                },
+            ],
+        }));
+        registerPrompt("triage-incident", "Guided incident triage for one service: health verdict, anomaly scan, blast radius, and the log slice that matters.", { service: z.string().describe("Service name as returned by list_services") }, ({ service }) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Triage the service "${service}" using the observability-mcp tools, in this order:`,
+                            `1. get_service_health {"service":"${service}"} — the current verdict and why.`,
+                            `2. detect_anomalies {"service":"${service}","duration":"1h"} — what is statistically off.`,
+                            `3. get_blast_radius {"resource":"${service}"} — who else fails if its host fails.`,
+                            `4. query_logs {"service":"${service}","level":"error","aggregate":{"op":"count_over_time","step":"5m"},"duration":"1h"} — error-volume shape over time; drill into raw rows only for the spike window.`,
+                            "Then summarise: current state, most likely cause, blast radius, and the next diagnostic step. Prefer aggregated queries over raw log dumps.",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }));
+        registerPrompt("write-postmortem", "Generate and refine a post-incident report for one service over a window.", {
+            service: z.string().describe("Service name as returned by list_services"),
+            duration: z.string().optional().describe("Look-back window, e.g. '1h', '6h'. Default '1h'."),
+        }, ({ service, duration }) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Produce a post-mortem for "${service}" over the last ${duration || "1h"}:`,
+                            `1. generate_postmortem {"service":"${service}","duration":"${duration || "1h"}"} — the stitched report (anomaly timeline, blast radius, traces, log highlights).`,
+                            `2. Verify its claims: get_anomaly_history {"service":"${service}","duration":"${duration || "1h"}"} for the score timeline, and query_logs with an aggregate for the error shape.`,
+                            "3. Rewrite the result as a blameless post-mortem: summary, impact, timeline, root-cause hypothesis (with confidence), follow-ups. Mark any section the gateway reported as missing data instead of inventing content.",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }));
         registerTool("list_sources", [
             "List the configured observability backends (Prometheus, Loki, and any connector) and whether each is currently reachable.",
             "When to use: call this first to learn which source names exist and are healthy before passing `source` to other tools, or to debug why a query returns no data.",
-            "Behavior: read-only, no side effects. Returns one entry per source with its name, type, configured URL, signal types (metrics/logs), and a live up/down status. Never throws for an unreachable backend — the backend is reported as down instead.",
+            "Behavior: read-only, no side effects. Returns one entry per source with its name, type, signal types (metrics/logs), and a live up/down status (the backend URL is intentionally not exposed — it may carry embedded credentials). Never throws for an unreachable backend — the backend is reported as down instead.",
             "Related: use `list_services` to see what is monitored within these sources.",
-        ].join(" "), {}, async () => {
+        ].join(" "), {}, { title: "List Sources", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async () => {
             await enforceEntitledAccess(ctx, { tool: "list_sources" });
             return withToolMetrics("list_sources", () => listSourcesHandler(registry, ctx));
         });
@@ -415,7 +495,7 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional case-insensitive substring to narrow the result to matching service names (e.g. 'payment'). Omit to list every discovered service."),
-        }, async (args) => {
+        }, { title: "List Services", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "list_services" });
             const result = await withToolMetrics("list_services", () => listServicesHandler(registry, args, ctx));
             return enrichToolServicesText(result, ctx);
@@ -458,7 +538,7 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional escape hatch: a verbatim PromQL expression, run as-is over the range — for ad-hoc queries the curated `metric` catalog can't express (any series, any function, broken down by any label). When set, `metric`/`service`/`groupBy`/`labels` are ignored. DISABLED by default; the operator must enable the raw-query capability (OMCP_RAW_QUERY=on) or the call is refused. Still tenant-scoped and source-allow-listed."),
-        }, async (args) => {
+        }, { title: "Query Metrics", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "query_metrics", source: args?.source, service: args?.service });
             const result = await withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx, { allowRawQuery: RAW_QUERY_ENABLED }));
             return chargeTokenBudget(result, ctx, "query_metrics");
@@ -525,7 +605,7 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional escape hatch: a verbatim LogQL log query, run as-is — for selectors/pipelines the curated params can't express. When set, `service`/`labels`/`level`/`query` are ignored and it is mutually exclusive with `aggregate` (express aggregation in the LogQL itself). DISABLED by default; the operator must enable the raw-query capability (OMCP_RAW_QUERY=on) or the call is refused. Redaction still applies to the returned log lines."),
-        }, async (args) => {
+        }, { title: "Query Logs", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "query_logs", source: args?.source, service: args?.service });
             const result = await withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx, { allowRawQuery: RAW_QUERY_ENABLED }));
             // Redact PII / secrets from the log payload before it crosses the
@@ -565,7 +645,7 @@ async function main() {
             service: z.string().describe("Service name to filter on."),
             duration: z.string().optional().describe("Rolling window, e.g. '1h', '24h'. Default '1h'."),
             method: z.string().optional().describe("Filter by detector method ('mad' / 'seasonality' / 'correlator'). Optional."),
-        }, async (args) => {
+        }, { title: "Anomaly History", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "get_anomaly_history", service: args?.service });
             const result = await withToolMetrics("get_anomaly_history", () => getAnomalyHistoryHandler(registry, args, ctx));
             return chargeTokenBudget(result, ctx, "get_anomaly_history");
@@ -580,7 +660,7 @@ async function main() {
             service: z.string().describe("Suspected root-cause service."),
             duration: z.string().optional().describe("Window length, e.g. '1h', '6h'. Default '1h'."),
             format: z.enum(["markdown", "json"]).optional().describe("'markdown' (default) or 'json'."),
-        }, async (args) => {
+        }, { title: "Generate Postmortem", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "generate_postmortem", service: args?.service });
             const result = await withToolMetrics("generate_postmortem", () => generatePostmortemHandler(registry, args, ctx));
             return chargeTokenBudget(result, ctx, "generate_postmortem");
@@ -589,15 +669,15 @@ async function main() {
             "Query distributed traces for a service over a given timeframe.",
             "Returns ranked trace summaries (duration, span count, error status) with a p50/p95 aggregate across the returned set.",
             "When to use: investigate tail-latency outliers, walk call chains across services for a specific time window, or pull traces related to an anomaly that the metric/log tools surfaced first.",
-            "Prerequisites: get the exact service name from `list_services`. A Tempo / Jaeger / OTLP connector must be configured.",
-            "Behavior: read-only. `filter` accepts the backend's native query language (TraceQL on Tempo, tag query on Jaeger). When `errorsOnly=true`, only traces with at least one error span are returned. Default limit is 50.",
+            "Prerequisites: get the exact service name from `list_services`. A traces connector (e.g. Tempo, installable from the connector hub) must be configured — none is bundled by default, so without one this returns a clean 'No trace backends configured' result.",
+            "Behavior: read-only. `filter` accepts the backend's native query language (e.g. TraceQL on Tempo). When `errorsOnly=true`, only traces with at least one error span are returned. Default limit is 50.",
         ].join(" "), {
             service: z.string().describe("Service name (e.g. 'payment-service')."),
             duration: z.string().optional().describe("Rolling time window, e.g. '5m', '1h'. Default '15m'."),
             filter: z.string().optional().describe("Backend-native filter (TraceQL on Tempo, tag query on Jaeger). Optional."),
             limit: z.number().int().positive().optional().describe("Soft cap on returned trace summaries. Default 50."),
             errorsOnly: z.boolean().optional().describe("If true, only traces with at least one error span."),
-        }, async (args) => {
+        }, { title: "Query Traces", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "query_traces", service: args?.service });
             const result = await withToolMetrics("query_traces", () => queryTracesHandler(registry, args, ctx));
             return chargeTokenBudget(result, ctx, "query_traces");
@@ -611,7 +691,7 @@ async function main() {
             service: z
                 .string()
                 .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'payment-service')."),
-        }, async (args) => {
+        }, { title: "Service Health", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "get_service_health", service: args?.service });
             const result = await withToolMetrics("get_service_health", () => getServiceHealthHandler(registry, args, ctx));
             const enriched = enrichToolHealthText(result, String(args?.service ?? ""), ctx);
@@ -635,7 +715,7 @@ async function main() {
                 .enum(["low", "medium", "high"])
                 .optional()
                 .describe("Optional. Detection threshold: 'low' flags only strong deviations (>3σ), 'medium' is balanced (>2σ), 'high' is most sensitive and noisier (>1.5σ). Default: 'medium'."),
-        }, async (args) => {
+        }, { title: "Detect Anomalies", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "detect_anomalies", source: args?.source, service: args?.service });
             // P1: pass the anomaly-history sink so detected scores flow
             // into the TSDB and `get_anomaly_history` returns real data.
@@ -666,7 +746,7 @@ async function main() {
                 .max(5000)
                 .optional()
                 .describe("Optional. Maximum resources to return; edges are trimmed to the kept set. Default 500, max 5000."),
-        }, async (args) => {
+        }, { title: "Topology Graph", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "get_topology", source: args?.source });
             return withToolMetrics("get_topology", () => getTopologyHandler(registry, args, ctx));
         });
@@ -679,7 +759,7 @@ async function main() {
             resource: z
                 .string()
                 .describe("Required. Resource to evaluate. Accepts the canonical id (e.g. 'k8s:pod:default/checkout-7f89d'), the exact resource name (e.g. 'checkout-7f89d'), or a unique substring of either."),
-        }, async (args) => {
+        }, { title: "Blast Radius", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "get_blast_radius" });
             return withToolMetrics("get_blast_radius", () => getBlastRadiusHandler(registry, args, ctx));
         });
@@ -692,7 +772,7 @@ async function main() {
             ips: z
                 .array(z.string())
                 .describe("Required. IPv4 address strings to enrich (e.g. ['203.0.113.5','198.51.100.9']). Max 1000 per call; invalid entries are returned with found=false rather than failing the batch."),
-        }, async (args) => {
+        }, { title: "Enrich IPs", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "enrich_ips" });
             return withToolMetrics("enrich_ips", async () => enrichIpsHandler(ipEnrichment, args, ctx));
         });
@@ -1117,11 +1197,11 @@ async function main() {
     // get_anomaly_history queries them back via any Prometheus source
     // pointed at the same TSDB.
     //
-    // The detector-side hook that actually records per-anomaly scores
-    // is plumbed in F15b (it requires passing this instance into the
-    // detectAnomaliesHandler — minor surgery deferred). The
-    // infrastructure ships now so externally-written omcp_anomaly_score
-    // metrics are already queryable end-to-end.
+    // The detector-side hook that records per-anomaly scores is wired:
+    // this instance is passed into detectAnomaliesHandler at the
+    // detect_anomalies tool registration below, so every scan records its
+    // scores. Externally-written omcp_anomaly_score metrics are queryable
+    // end-to-end too.
     const anomalyHistory = new AnomalyHistory(anomalyHistoryFromEnv());
     anomalyHistory.start();
     if (anomalyHistory.isEnabled()) {
@@ -1195,6 +1275,41 @@ async function main() {
     // enough to skip the request-counter middleware.
     let ready = false;
     app.get("/healthz", (_req, res) => res.type("text").send("ok"));
+    // /llms.txt — the llms.txt convention (llmstxt.org): a plain-text,
+    // LLM-friendly summary of what this server is and how to use it. The
+    // primary audience of this gateway IS an LLM agent, so the gateway
+    // serves its own. Tool list is generated from the canonical registry
+    // (registry-names.ts) so it can't drift from the real surface.
+    const LLMS_TXT = [
+        "# observability-mcp",
+        "",
+        `> Unified observability gateway for AI agents (v${SERVER_VERSION}). One MCP server`,
+        "> for Prometheus, Loki, and any backend via pluggable connectors — with",
+        "> server-side filtering/aggregation so agents get numbers, not haystacks.",
+        "",
+        "MCP endpoint: POST /mcp (Streamable HTTP) · also stdio (--stdio) and WebSocket (/mcp/ws).",
+        "All tools are read-only and advertise MCP ToolAnnotations (readOnlyHint: true).",
+        "MCP resource omcp://guide/agent-usage carries the agent usage guide;",
+        "prompts triage-incident and write-postmortem compose the tools into workflows.",
+        "",
+        "## Tools",
+        "",
+        ...REGISTERED_TOOLS.map((t) => `- ${t.name} (${t.category}): ${t.summary}`),
+        "",
+        "## Connect",
+        "",
+        "    claude mcp add observability --transport http http://localhost:3000/mcp",
+        "",
+        "## Docs",
+        "",
+        "- For agents (start here): https://thotischner.github.io/observability-mcp/for-agents/",
+        "- Documentation site: https://thotischner.github.io/observability-mcp/",
+        "- Report a finding (agent-report template): https://github.com/ThoTischner/observability-mcp/issues/new?template=agent-report.yml",
+        "- Discussions (agent collaboration welcome): https://github.com/ThoTischner/observability-mcp/discussions",
+        "- Source: https://github.com/ThoTischner/observability-mcp",
+        "",
+    ].join("\n");
+    app.get("/llms.txt", (_req, res) => res.type("text/plain; charset=utf-8").send(LLMS_TXT));
     // Procurement-time probe: the MCP spec revisions and transports the
     // gateway supports. Static today — kept as a separate endpoint so a
     // discovery tool / RFP probe / catalog scanner can resolve our

package/dist/sdk/manifest-schema.d.ts

@@ -18,8 +18,14 @@ export declare const manifestSchema: z.ZodObject<{
     capabilities: z.ZodOptional<z.ZodObject<{
         queryMetrics: z.ZodOptional<z.ZodBoolean>;
         queryLogs: z.ZodOptional<z.ZodBoolean>;
+        queryLogAggregate: z.ZodOptional<z.ZodBoolean>;
+        queryTraces: z.ZodOptional<z.ZodBoolean>;
         listServices: z.ZodOptional<z.ZodBoolean>;
         listAvailableMetrics: z.ZodOptional<z.ZodBoolean>;
+        listResources: z.ZodOptional<z.ZodBoolean>;
+        listEdges: z.ZodOptional<z.ZodBoolean>;
+        getTopologySnapshot: z.ZodOptional<z.ZodBoolean>;
+        watchTopology: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     compat: z.ZodOptional<z.ZodObject<{
         serverVersion: z.ZodOptional<z.ZodString>;

package/dist/sdk/manifest-schema.js

@@ -24,8 +24,15 @@ export const manifestSchema = z.object({
         .object({
         queryMetrics: z.boolean().optional(),
         queryLogs: z.boolean().optional(),
+        queryLogAggregate: z.boolean().optional(),
+        queryTraces: z.boolean().optional(),
         listServices: z.boolean().optional(),
         listAvailableMetrics: z.boolean().optional(),
+        // Topology-provider capabilities (e.g. the Kubernetes connector).
+        listResources: z.boolean().optional(),
+        listEdges: z.boolean().optional(),
+        getTopologySnapshot: z.boolean().optional(),
+        watchTopology: z.boolean().optional(),
     })
         .optional(),
     compat: z

package/dist/tools/get-anomaly-history.js

@@ -67,13 +67,20 @@ export async function getAnomalyHistoryHandler(registry, args, ctx = defaultCont
         labelFilters.push(`method="${escLabel(args.method)}"`);
     const metric = `omcp_anomaly_score{${labelFilters.join(",")}}`;
     // Fan out across every metrics connector; first non-empty answer wins.
+    // CRITICAL: pass the hand-built selector via `rawQuery`, NOT `metric`.
+    // The connector's curated path wraps a bare `metric` in `{ {{selector}} }`,
+    // which for our already-complete selector produces invalid double-brace
+    // PromQL (`omcp_anomaly_score{service="x"}{ job="x" }`) → 400 → the catch
+    // below swallowed it and the tool always reported "no history". rawQuery is
+    // sent verbatim to /api/v1/query_range (the R4 passthrough).
     for (const c of candidates) {
         if (!c.queryMetrics)
             continue;
         try {
             const r = await c.queryMetrics({
                 service: args.service,
-                metric,
+                metric: "omcp_anomaly_score",
+                rawQuery: metric,
                 duration,
             });
             if (r && Array.isArray(r.values) && r.values.length > 0) {

package/dist/tools/get-anomaly-history.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/get-anomaly-history.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { getAnomalyHistoryHandler } from "./get-anomaly-history.js";
+// Regression guard for the wired-but-dead bug found in the v3.2 audit:
+// get_anomaly_history hand-builds a complete PromQL selector
+// (`omcp_anomaly_score{service="x",method="mad"}`) and must pass it via
+// `rawQuery` (verbatim passthrough), NOT via `metric`. The curated `metric`
+// path wraps the value in `{ {{selector}} }`, which for an already-complete
+// selector yields invalid double-brace PromQL → Prometheus 400 → the handler
+// swallowed it and always returned "no history". This test pins that the
+// connector receives a verbatim rawQuery and never the manglable metric path.
+function fakeRegistry(capture, result) {
+    const conn = {
+        name: "prom",
+        type: "prometheus",
+        signalType: "metrics",
+        async queryMetrics(q) {
+            capture(q);
+            if (!result)
+                throw new Error("no data");
+            return result;
+        },
+    };
+    return { getByTenant: () => [conn] };
+}
+function parse(r) {
+    return JSON.parse(r.content[0].text);
+}
+describe("get_anomaly_history — rawQuery wiring (audit regression)", () => {
+    it("routes the omcp_anomaly_score selector via rawQuery, not metric", async () => {
+        let captured;
+        const reg = fakeRegistry((q) => (captured = q), {
+            source: "prom",
+            service: "payment",
+            metric: "omcp_anomaly_score",
+            unit: "",
+            values: [{ timestamp: "2026-06-09T00:00:00.000Z", value: 0.7 }],
+            summary: { current: 0.7, average: 0.7, min: 0.7, max: 0.7, trend: "stable" },
+        });
+        const out = parse(await getAnomalyHistoryHandler(reg, { service: "payment", method: "mad", duration: "1h" }));
+        assert.ok(captured, "connector.queryMetrics must be called");
+        // The fix: rawQuery carries the verbatim selector.
+        assert.equal(captured.rawQuery, 'omcp_anomaly_score{service="payment",method="mad"}');
+        // And it must NOT be smuggled through the curated `metric` path (which would
+        // double-brace it). metric may be a bare name placeholder, but never the selector.
+        assert.doesNotMatch(String(captured.metric ?? ""), /\{/, "metric must not carry the brace selector");
+        // Sanity: the verbatim query has exactly one brace block (no double-brace).
+        assert.equal((captured.rawQuery.match(/\{/g) || []).length, 1);
+        assert.equal(out.isError, undefined);
+        assert.equal(out.values.length, 1);
+    });
+    it("omits the method filter when not given", async () => {
+        let captured;
+        const reg = fakeRegistry((q) => (captured = q), {
+            source: "prom", service: "api", metric: "omcp_anomaly_score", unit: "",
+            values: [{ timestamp: "2026-06-09T00:00:00.000Z", value: 1 }],
+            summary: { current: 1, average: 1, min: 1, max: 1, trend: "stable" },
+        });
+        await getAnomalyHistoryHandler(reg, { service: "api" });
+        assert.equal(captured.rawQuery, 'omcp_anomaly_score{service="api"}');
+    });
+});

package/dist/tools/handlers.test.js

@@ -90,6 +90,21 @@ describe("listServicesHandler", () => {
         assert.deepEqual(apiGw.sources.sort(), ["loki1", "prom1"]);
         assert.deepEqual(apiGw.signalTypes.sort(), ["logs", "metrics"]);
     });
+    it("carries per-service labels (e.g. discoveredVia) through the merge (audit: docs/loki.md)", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({
+                name: "loki1", type: "loki", signalType: "logs",
+                listServices: async () => [
+                    { name: "payment-service", source: "loki1", signalType: "logs", labels: { discoveredVia: "service_name" } },
+                ],
+            }),
+        ]);
+        const result = await listServicesHandler(reg, {});
+        const data = JSON.parse(result.content[0].text);
+        const svc = data.services.find((s) => s.name === "payment-service");
+        assert.ok(svc, "service must be present");
+        assert.equal(svc.labels?.discoveredVia, "service_name", "discoveredVia must surface in the tool output");
+    });
     it("filters services case-insensitively", async () => {
         const reg = createRegistryWithMocks([
             createMockConnector({

package/dist/tools/list-services.js

@@ -25,7 +25,10 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
             console.error(`Failed to list services from ${connector.name}:`, err);
         }
     }
-    // Deduplicate by name, merge signal types
+    // Deduplicate by name, merge signal types. Carry per-service `labels`
+    // (e.g. the Loki connector's `discoveredVia`, documented in docs/loki.md)
+    // through the merge so discovery metadata actually surfaces in the tool
+    // output; first source to set a given label key wins.
     const merged = new Map();
     for (const svc of allServices) {
         const existing = merged.get(svc.name);
@@ -34,12 +37,15 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
                 existing.sources.push(svc.source);
             if (!existing.signalTypes.includes(svc.signalType))
                 existing.signalTypes.push(svc.signalType);
+            if (svc.labels)
+                existing.labels = { ...svc.labels, ...(existing.labels ?? {}) };
         }
         else {
             merged.set(svc.name, {
                 name: svc.name,
                 sources: [svc.source],
                 signalTypes: [svc.signalType],
+                labels: svc.labels ? { ...svc.labels } : undefined,
             });
         }
     }

package/dist/tools/query-traces.js

@@ -6,10 +6,12 @@
 // summaries, and recomputes a global p50/p95 over the merged set
 // (rather than blindly averaging per-source summaries).
 //
-// Backend support today: a Tempo connector + a Jaeger shim ship as
-// filesystem plugins. Any connector that implements queryTraces
-// participates automatically — no changes needed in the tool layer
-// when a new backend lands.
+// Backend support: no traces backend is bundled by default. The Tempo
+// connector ships in the connector hub (install it to enable traces);
+// there is no Jaeger connector today. Any connector that implements the
+// optional queryTraces capability participates automatically — so on a
+// stack without one the tool returns a clean "No trace backends
+// configured" result rather than failing.
 import { defaultContext } from "../context.js";
 import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
 export const queryTracesDefinition = {
@@ -18,7 +20,7 @@ export const queryTracesDefinition = {
         "Query distributed traces for a service over a given timeframe.",
         "Returns ranked trace summaries with duration, error status, and span count, plus a p50/p95 duration aggregate across the returned set.",
         "When to use: investigating tail-latency outliers, walking call chains across services for a known time window, or pulling related traces for an anomaly the metric/log tools surfaced first.",
-        "Behavior: read-only; results may be capped via `limit` (default 50). `filter` accepts the backend's native query language (TraceQL on Tempo, tag query on Jaeger). When `errorsOnly=true`, only traces with at least one error span are returned.",
+        "Behavior: read-only; results may be capped via `limit` (default 50). `filter` accepts the backend's native query language (e.g. TraceQL on Tempo). When `errorsOnly=true`, only traces with at least one error span are returned.",
         "Related: `query_metrics` for the per-service latency series; `get_blast_radius` for the topology a trace traverses.",
     ].join(" "),
     inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thotischner/observability-mcp",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Unified observability gateway for AI agents — one MCP server for Prometheus, Loki, and any backend",
   "type": "module",
   "license": "Apache-2.0",