@thotischner/observability-mcp 3.2.1 → 3.3.1

package/dist/analysis/health.d.ts

@@ -7,12 +7,22 @@ export interface HealthInputs {
     logErrorRate: number;
 }
 export interface HealthResult {
-    score: number;
-    status: HealthStatus;
+    /** 0-100, or null when no signal had data (status "unknown"). */
+    score: number | null;
+    status: HealthStatus | "unknown";
     details: Record<string, {
         score: number;
         value: number;
         threshold: string;
     }>;
 }
-export declare function calculateHealthScore(inputs: HealthInputs, thresholds: HealthThresholds): HealthResult;
+/** Which signal families actually returned data. Missing/false families are
+ *  excluded from the weighted score and the remaining weights are
+ *  renormalised — so a log-only service is judged on its logs, not on metric
+ *  zeros coerced to "healthy" (issue #453). Omit for the back-compat
+ *  all-signals-present behaviour. */
+export interface SignalCoverage {
+    metrics?: boolean;
+    logs?: boolean;
+}
+export declare function calculateHealthScore(inputs: HealthInputs, thresholds: HealthThresholds, coverage?: SignalCoverage): HealthResult;

package/dist/analysis/health.js

@@ -1,27 +1,43 @@
-export function calculateHealthScore(inputs, thresholds) {
+export function calculateHealthScore(inputs, thresholds, coverage) {
     const w = thresholds.weights;
     const t = thresholds;
+    const hasMetrics = coverage?.metrics !== false; // default: present (back-compat)
+    const hasLogs = coverage?.logs !== false;
     const cpuScore = scoreFromThreshold(inputs.cpu, t.cpu.good, t.cpu.warn, t.cpu.crit);
     const errorRateScore = scoreFromThreshold(inputs.errorRate, t.errorRate.good, t.errorRate.warn, t.errorRate.crit);
     const latencyScore = scoreFromThreshold(inputs.latencyP99, t.latencyP99.good, t.latencyP99.warn, t.latencyP99.crit);
     const logErrorScore = scoreFromThreshold(inputs.logErrorRate, t.logErrors.good, t.logErrors.warn, t.logErrors.crit);
-    const weightedScore = cpuScore * w.cpu +
-        errorRateScore * w.errorRate +
-        latencyScore * w.latency +
-        logErrorScore * w.logErrors;
-    const score = Math.round(Math.max(0, Math.min(100, weightedScore)));
+    // Only count the families that actually reported data; renormalise by the
+    // sum of their weights so a missing family is neither a free "100" nor a
+    // free "0". With full coverage the active weights sum to ~1 and this equals
+    // the previous behaviour.
+    let weighted = 0;
+    let activeWeight = 0;
+    if (hasMetrics) {
+        weighted += cpuScore * w.cpu + errorRateScore * w.errorRate + latencyScore * w.latency;
+        activeWeight += w.cpu + w.errorRate + w.latency;
+    }
+    if (hasLogs) {
+        weighted += logErrorScore * w.logErrors;
+        activeWeight += w.logErrors;
+    }
+    const details = {};
+    if (hasMetrics) {
+        details.cpu = { score: Math.round(cpuScore), value: inputs.cpu, threshold: `warn >${t.cpu.warn}%, crit >${t.cpu.crit}%` };
+        details.errorRate = { score: Math.round(errorRateScore), value: inputs.errorRate, threshold: `warn >${t.errorRate.warn}/s, crit >${t.errorRate.crit}/s` };
+        details.latencyP99 = { score: Math.round(latencyScore), value: inputs.latencyP99, threshold: `warn >${t.latencyP99.warn}s, crit >${t.latencyP99.crit}s` };
+    }
+    if (hasLogs) {
+        details.logErrors = { score: Math.round(logErrorScore), value: inputs.logErrorRate, threshold: `warn >${t.logErrors.warn}/min, crit >${t.logErrors.crit}/min` };
+    }
+    // No family reported data → honestly unknown, not a confident 100/healthy.
+    if (activeWeight === 0) {
+        return { score: null, status: "unknown", details };
+    }
+    const score = Math.round(Math.max(0, Math.min(100, weighted / activeWeight)));
     const status = score > t.statusBoundaries.healthy ? "healthy" :
         score > t.statusBoundaries.degraded ? "degraded" : "critical";
-    return {
-        score,
-        status,
-        details: {
-            cpu: { score: Math.round(cpuScore), value: inputs.cpu, threshold: `warn >${t.cpu.warn}%, crit >${t.cpu.crit}%` },
-            errorRate: { score: Math.round(errorRateScore), value: inputs.errorRate, threshold: `warn >${t.errorRate.warn}/s, crit >${t.errorRate.crit}/s` },
-            latencyP99: { score: Math.round(latencyScore), value: inputs.latencyP99, threshold: `warn >${t.latencyP99.warn}s, crit >${t.latencyP99.crit}s` },
-            logErrors: { score: Math.round(logErrorScore), value: inputs.logErrorRate, threshold: `warn >${t.logErrors.warn}/min, crit >${t.logErrors.crit}/min` },
-        },
-    };
+    return { score, status, details };
 }
 function scoreFromThreshold(value, good, warn, crit) {
     if (value <= good)

package/dist/analysis/health.test.js

@@ -1,6 +1,11 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { calculateHealthScore } from "./health.js";
+// Full-coverage scores are never null; narrow for the existing assertions.
+function num(r) {
+    assert.notEqual(r.score, null, "expected a numeric score");
+    return r.score;
+}
 const defaults = {
     weights: { errorRate: 0.35, latency: 0.25, cpu: 0.20, logErrors: 0.20 },
     cpu: { good: 50, warn: 80, crit: 95 },
@@ -22,21 +27,21 @@ describe("calculateHealthScore", () => {
             cpu: 20, memory: 100_000_000, errorRate: 0.005, latencyP99: 0.3, logErrorRate: 0,
         }, defaults);
         assert.equal(result.status, "healthy");
-        assert.ok(result.score > 80);
+        assert.ok(num(result) > 80);
     });
     it("returns degraded for elevated values", () => {
         const result = calculateHealthScore({
             cpu: 65, memory: 200_000_000, errorRate: 0.05, latencyP99: 0.8, logErrorRate: 3,
         }, defaults);
         assert.equal(result.status, "degraded");
-        assert.ok(result.score > 50 && result.score <= 80, `Expected degraded score 50-80, got ${result.score}`);
+        assert.ok(num(result) > 50 && num(result) <= 80, `Expected degraded score 50-80, got ${result.score}`);
     });
     it("returns critical for extreme values", () => {
         const result = calculateHealthScore({
             cpu: 98, memory: 500_000_000, errorRate: 1.0, latencyP99: 5.0, logErrorRate: 50,
         }, defaults);
         assert.equal(result.status, "critical");
-        assert.ok(result.score <= 50);
+        assert.ok(num(result) <= 50);
     });
     it("score is between 0 and 100", () => {
         for (const cpu of [0, 50, 100]) {
@@ -44,7 +49,7 @@ describe("calculateHealthScore", () => {
                 const result = calculateHealthScore({
                     cpu, memory: 0, errorRate: err, latencyP99: 0, logErrorRate: 0,
                 }, defaults);
-                assert.ok(result.score >= 0 && result.score <= 100, `Score ${result.score} out of range for cpu=${cpu} err=${err}`);
+                assert.ok(num(result) >= 0 && num(result) <= 100, `Score ${result.score} out of range`);
             }
         }
     });
@@ -57,7 +62,7 @@ describe("calculateHealthScore", () => {
             cpu: 25, memory: 0, errorRate: 0, latencyP99: 0, logErrorRate: 0,
         }, strict);
         // CPU 25% with strict thresholds should lower the score
-        assert.ok(result.score < 100);
+        assert.ok(num(result) < 100);
     });
     it("includes detail breakdown", () => {
         const result = calculateHealthScore({
@@ -67,4 +72,25 @@ describe("calculateHealthScore", () => {
         assert.ok("errorRate" in result.details);
         assert.ok(result.details.cpu.score < 100);
     });
+    it("coverage: no signals at all → score null, status unknown (issue #453)", () => {
+        const r = calculateHealthScore({ cpu: 0, memory: 0, errorRate: 0, latencyP99: 0, logErrorRate: 0 }, defaults, { metrics: false, logs: false });
+        assert.equal(r.score, null);
+        assert.equal(r.status, "unknown");
+        assert.deepEqual(r.details, {});
+    });
+    it("coverage: log-only service is judged on logs, not metric zeros (issue #453)", () => {
+        // High log error rate, no metric coverage → must NOT come back healthy.
+        const r = calculateHealthScore({ cpu: 0, memory: 0, errorRate: 0, latencyP99: 0, logErrorRate: 50 }, defaults, { metrics: false, logs: true });
+        assert.notEqual(r.status, "healthy");
+        assert.ok(num(r) < 50, `log-only with 50 errors/min should not be healthy, got ${r.score}`);
+        assert.ok(!("cpu" in r.details), "metric details excluded when metrics absent");
+        assert.ok("logErrors" in r.details);
+    });
+    it("coverage: full coverage (default) is unchanged by the coverage param", () => {
+        const inputs = { cpu: 65, memory: 0, errorRate: 0.05, latencyP99: 0.8, logErrorRate: 3 };
+        const implicit = calculateHealthScore(inputs, defaults);
+        const explicit = calculateHealthScore(inputs, defaults, { metrics: true, logs: true });
+        assert.equal(implicit.score, explicit.score);
+        assert.equal(implicit.status, explicit.status);
+    });
 });

package/dist/analysis/library.test.js

@@ -38,7 +38,7 @@ describe("embeddable analysis library", () => {
             logErrors: { good: 1, warn: 5, crit: 10 },
             statusBoundaries: { healthy: 80, degraded: 50 },
         });
-        assert.ok(r.score >= 0 && r.score <= 100);
+        assert.ok(r.score !== null && r.score >= 0 && r.score <= 100);
         assert.ok(["healthy", "degraded", "critical"].includes(r.status));
     });
 });

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

@@ -375,3 +375,67 @@ test("E2E tools/call: every registered tool dispatches over MCP and returns a Ca
         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");
+});
+test("E2E: initialize advertises non-empty instructions pointing at the usage guide (issue #455)", opts, async () => {
+    const { response } = await jsonRpc("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "harness", version: "0" },
+    }, { id: 30 });
+    const r = response.result;
+    assert.ok(r.instructions && r.instructions.length > 0, "initialize.instructions must be populated");
+    assert.match(r.instructions, /omcp:\/\/guide\/agent-usage/, "must point at the usage-guide resource");
+    assert.match(r.instructions, /aggregate/i, "must carry the filter+aggregate golden rule");
+});

package/dist/connectors/loki.js

@@ -68,7 +68,12 @@ export function buildAggregateLogQL(streamPipeline, agg, duration) {
     if (agg.op === "count_over_time") {
         const stepSec = (agg.step && parseDurationSeconds(agg.step)) || defaultBucketSeconds(durSec);
         const inner = `count_over_time(${streamPipeline} [${stepSec}s])`;
-        const logql = byClause ? `sum${byClause} (${inner})` : inner;
+        // Always wrap in sum() — even with no `by`. A bare count_over_time over a
+        // `| json`-piped stream keeps every extracted label (rid/ip/status/…) as
+        // its own series, so the "requests over time" headline case returns a
+        // high-cardinality mess instead of one bucketed total (issue #452). With
+        // no `by` we collapse to a single series; `sum by(...)` for explicit by.
+        const logql = `sum${byClause} (${inner})`;
         return { logql, mode: "range", step: `${stepSec}s` };
     }
     // sum / topk: count over the whole window, then aggregate → instant vector.
@@ -195,6 +200,16 @@ export class LokiConnector {
         const url = `/loki/api/v1/query_range?query=${encodeURIComponent(logql)}` +
             `&start=${start}000000000&end=${end}000000000&limit=${limit}`;
         const data = await this.apiGet(url);
+        // A log query yields resultType "streams". A metric query (e.g. a
+        // raw_query wrapping sum()/count() → vector/matrix) does NOT — and the
+        // streams parser below would dereference undefined `.stream`/`.values`
+        // and crash on `.level` (issue #452). Fail fast with a clear, actionable
+        // message instead of running to timeout on a wrong-shaped result.
+        const resultType = data?.data?.resultType;
+        if (resultType && resultType !== "streams") {
+            throw new Error(`query_logs raw_query returned a '${resultType}' result, but query_logs handles log lines (streams) only. ` +
+                "For counts/sums/top-k use the `aggregate` param on query_logs; for arbitrary vector/matrix LogQL use query_metrics raw_query.");
+        }
         const entries = [];
         for (const stream of data?.data?.result || []) {
             const labels = stream.stream;

package/dist/connectors/loki.test.js

@@ -96,6 +96,34 @@ describe("Q-LOG1: queryLogs LogQL assembly", () => {
         });
         assert.equal(q, '{job="raw"}');
     });
+    it("#452: rawQuery returning a vector/matrix fails fast with a clear message (no .level crash)", async () => {
+        const conn = new LokiConnector();
+        await conn.connect({ name: "loki", type: "loki", url: "http://loki:3100", enabled: true });
+        const orig = globalThis.fetch;
+        globalThis.fetch = (async (url) => {
+            const u = String(url);
+            if (u.includes("/label/") && u.includes("/values"))
+                return jsonRes({ data: ["app"] });
+            // A metric raw_query (sum(count_over_time(...))) returns resultType matrix,
+            // not streams — must not be fed to the streams parser.
+            if (u.includes("/query_range")) {
+                return jsonRes({ data: { resultType: "matrix", result: [{ metric: { url: "/" }, values: [[1000, "5"]] }] } });
+            }
+            return jsonRes({ data: [] });
+        });
+        try {
+            await conn.queryLogs({ rawQuery: "sum(count_over_time({app=\"x\"} | json [6h]))", duration: "6h" });
+            assert.fail("expected a thrown error for a non-streams raw_query result");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            assert.match(msg, /'matrix' result/);
+            assert.match(msg, /aggregate.*param|query_metrics raw_query/);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
 });
 describe("Q-LOG2: parseDurationSeconds / defaultBucketSeconds", () => {
     it("parses m/h/d", () => {
@@ -118,11 +146,14 @@ describe("Q-LOG2: buildAggregateLogQL", () => {
         assert.equal(r.step, "900s");
         assert.equal(r.logql, `sum by (url) (count_over_time(${PIPE} [900s]))`);
     });
-    it("count_over_time without by → bare count_over_time, default step", () => {
+    it("count_over_time without by → sum-wrapped (single series), default step (#452)", () => {
+        // Regression for issue #452: a bare count_over_time over a `| json` stream
+        // keeps every extracted label as its own series. With no `by` we must
+        // collapse to one bucketed total via sum(...).
         const r = buildAggregateLogQL(PIPE, { op: "count_over_time" }, "1h");
         assert.equal(r.mode, "range");
         assert.equal(r.step, "60s");
-        assert.equal(r.logql, `count_over_time(${PIPE} [60s])`);
+        assert.equal(r.logql, `sum (count_over_time(${PIPE} [60s]))`);
     });
     it("sum → instant total per group over the whole window", () => {
         const r = buildAggregateLogQL(PIPE, { op: "sum", by: ["status"] }, "1h");

package/dist/index.js

@@ -342,6 +342,18 @@ async function main() {
         const mcpServer = new McpServer({
             name: "observability-mcp",
             version: SERVER_VERSION,
+        }, {
+            // `instructions` is the one channel the MCP spec auto-injects into the
+            // agent's context on connect (issue #455). Keep it tight: point at the
+            // full guide resource + the single rule that prevents the most common
+            // mistake (dumping raw rows), + the empty-state contract.
+            instructions: "Read MCP resource `omcp://guide/agent-usage` before heavy use. " +
+                "Golden rule: filter + aggregate server-side — use `query_logs`/`query_metrics` " +
+                "`labels` and `query_logs` `aggregate` to ask for numbers, not haystacks (raw log " +
+                "dumps blow past context limits). All tools are read-only. When a result is empty " +
+                "or refused, the message names the operator flag that unlocks it (e.g. OMCP_RAW_QUERY) " +
+                "— relay it verbatim. Prompts `triage-incident` and `write-postmortem` compose the tools. " +
+                "Hit a rough edge? Report it via the agent-report issue template (see the guide).",
         });
         const toolHandlers = new Map();
         // --- Register tools with Zod schemas ---
@@ -393,15 +405,98 @@ 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 & collaborate",
+                        "Structured agent reports drive releases here (see issue #415). File a bug or gap:",
+                        "https://github.com/ThoTischner/observability-mcp/issues/new?template=agent-report.yml",
+                        "For workflows, ideas, or to compare notes with other agents (collaboration welcome):",
+                        "https://github.com/ThoTischner/observability-mcp/discussions",
+                        "Note: posting publicly is an outward-facing action — do it on your operator's behalf, not unprompted.",
+                        "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, 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 +510,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 +553,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");
@@ -466,6 +561,7 @@ async function main() {
         registerTool("query_logs", [
             "Fetch recent log entries for ONE service over a look-back window, with a pre-computed summary (error/warning counts and the most frequent error patterns).",
             "When to use: to inspect what a service actually logged, or to investigate an error spike surfaced by `detect_anomalies` / `get_service_health`. For numeric metrics use `query_metrics` instead.",
+            "Golden rule: filter + aggregate server-side — pass `labels` to scope and `aggregate` (count_over_time/sum/topk) to get numbers, not raw rows. A high-volume window returned raw will blow past your context limit.",
             "Prerequisites: get the exact service name from `list_services` (the service must expose a logs signal).",
             "Behavior: read-only, no side effects. Returns the matching log entries (newest first, capped by `limit`) plus a summary with total/error/warn counts and top recurring error patterns. No matches yields an empty result with a zeroed summary; an unreachable backend yields a structured explanatory error, never an exception.",
         ].join(" "), {
@@ -525,7 +621,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 +661,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 +676,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");
@@ -597,7 +693,7 @@ async function main() {
             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 +707,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 +731,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 +762,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 +775,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 +788,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));
         });
@@ -1195,6 +1291,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/tools/detect-anomalies.js

@@ -40,18 +40,42 @@ export async function detectAnomaliesHandler(registry, args, ctx = defaultContex
     const tenantConnectors = registry.getByTenant(ctx.tenant);
     const metricsConnectors = tenantConnectors.filter((c) => c.signalType === "metrics");
     const logConnectors = tenantConnectors.filter((c) => c.signalType === "logs");
-    let serviceNames = [];
+    // Discover services from BOTH metrics and log connectors, tracking which
+    // signal each service exposes. Previously the fleet scan only enumerated
+    // metrics connectors, so a log-only service was silently dropped from the
+    // scan — and the "all healthy" all-clear never said so (issue #453B). Now
+    // log-only services are scanned (via their log error-rate, as the
+    // description promises) and the per-service coverage is reported.
+    const coverage = new Map();
+    const mark = (name, key) => {
+        const e = coverage.get(name) ?? { metrics: false, logs: false };
+        e[key] = true;
+        coverage.set(name, e);
+    };
+    for (const connector of metricsConnectors) {
+        try {
+            for (const s of await connector.listServices())
+                mark(s.name, "metrics");
+        }
+        catch { /* connector down — skip */ }
+    }
+    for (const connector of logConnectors) {
+        try {
+            for (const s of await connector.listServices())
+                mark(s.name, "logs");
+        }
+        catch { /* connector down — skip */ }
+    }
+    let serviceNames;
     if (args.service) {
         serviceNames = [args.service];
+        if (!coverage.has(args.service)) {
+            // Unknown to listServices — still attempt both signal paths.
+            coverage.set(args.service, { metrics: metricsConnectors.length > 0, logs: logConnectors.length > 0 });
+        }
     }
     else {
-        for (const connector of metricsConnectors) {
-            const services = await connector.listServices();
-            for (const s of services) {
-                if (!serviceNames.includes(s.name))
-                    serviceNames.push(s.name);
-            }
-        }
+        serviceNames = [...coverage.keys()];
     }
     const allAnomalies = [];
     const allCorrelations = [];
@@ -179,14 +203,25 @@ export async function detectAnomaliesHandler(registry, args, ctx = defaultContex
             severity: a.severity,
         })))
         : { ranked: [], summary: "" };
+    // Per-service coverage so an "all healthy" all-clear is verifiable rather
+    // than silently partial: the caller sees exactly which services were
+    // scanned and on which signals (issue #453B).
+    const scanned = serviceNames.map((name) => {
+        const cov = coverage.get(name) ?? { metrics: false, logs: false };
+        const signals = [cov.metrics ? "metrics" : null, cov.logs ? "logs" : null].filter(Boolean);
+        return { service: name, signals };
+    });
+    const metricsCount = scanned.filter((s) => s.signals.includes("metrics")).length;
+    const logsCount = scanned.filter((s) => s.signals.includes("logs")).length;
     const result = {
         scannedServices: serviceNames.length,
+        coverage: { scanned },
         anomalies: allAnomalies,
         correlations: allCorrelations,
         rootCause,
         summary: allAnomalies.length === 0
-            ? "All services healthy — no anomalies detected."
-            : `${allAnomalies.length} anomal${allAnomalies.length === 1 ? "y" : "ies"} detected across ${[...new Set(allAnomalies.map((a) => a.service))].length} service(s).`,
+            ? `No anomalies across ${serviceNames.length} scanned service(s) (${metricsCount} with metrics, ${logsCount} with logs).`
+            : `${allAnomalies.length} anomal${allAnomalies.length === 1 ? "y" : "ies"} detected across ${[...new Set(allAnomalies.map((a) => a.service))].length} of ${serviceNames.length} scanned service(s).`,
     };
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],

package/dist/tools/get-service-health.js

@@ -24,23 +24,38 @@ export async function getServiceHealthHandler(registry, args, ctx = defaultConte
     const tenantConnectors = registry.getByTenant(ctx.tenant);
     const metricsConnectors = tenantConnectors.filter((c) => c.signalType === "metrics");
     const logConnectors = tenantConnectors.filter((c) => c.signalType === "logs");
-    // Gather metrics
+    // Gather metrics. Track whether any series actually returned data —
+    // absent metrics must NOT be coerced to 0 and read as a confident
+    // "healthy" (issue #453).
     let cpu = 0, memory = 0, errorRate = 0, latencyP99 = 0;
+    let metricsHadData = false;
     const anomalies = [];
     for (const connector of metricsConnectors) {
         if (!connector.queryMetrics)
             continue;
         try {
             const cpuResult = await connector.queryMetrics({ service: args.service, metric: "cpu", duration: "5m" });
-            cpu = cpuResult.summary.current;
+            if (cpuResult.values.length > 0) {
+                cpu = cpuResult.summary.current;
+                metricsHadData = true;
+            }
             checkAnomaly(cpuResult.values.map(v => v.value), "cpu", args.service, connector.name, anomalies);
             const memResult = await connector.queryMetrics({ service: args.service, metric: "memory", duration: "5m" });
-            memory = memResult.summary.current / 1_000_000; // Convert to MB for display
+            if (memResult.values.length > 0) {
+                memory = memResult.summary.current / 1_000_000;
+                metricsHadData = true;
+            } // MB for display
             const errResult = await connector.queryMetrics({ service: args.service, metric: "error_rate", duration: "5m" });
-            errorRate = errResult.summary.current;
+            if (errResult.values.length > 0) {
+                errorRate = errResult.summary.current;
+                metricsHadData = true;
+            }
             checkAnomaly(errResult.values.map(v => v.value), "error_rate", args.service, connector.name, anomalies);
             const latResult = await connector.queryMetrics({ service: args.service, metric: "latency_p99", duration: "5m" });
-            latencyP99 = latResult.summary.current;
+            if (latResult.values.length > 0) {
+                latencyP99 = latResult.summary.current;
+                metricsHadData = true;
+            }
             checkAnomaly(latResult.values.map(v => v.value), "latency_p99", args.service, connector.name, anomalies);
         }
         catch (err) {
@@ -50,12 +65,15 @@ export async function getServiceHealthHandler(registry, args, ctx = defaultConte
     // Gather logs
     let logErrorRate = 0;
     let topErrors = [];
+    let logsHadData = false;
     const correlations = [];
     for (const connector of logConnectors) {
         if (!connector.queryLogs)
             continue;
         try {
             const logs = await connector.queryLogs({ service: args.service, duration: "5m", limit: 200 });
+            if (logs.summary.total > 0)
+                logsHadData = true; // real log coverage in the window
             logErrorRate = logs.summary.errorCount; // errors in 5m window
             topErrors = logs.summary.topPatterns;
             // Cross-signal correlation
@@ -70,7 +88,31 @@ export async function getServiceHealthHandler(registry, args, ctx = defaultConte
             console.error("Health check logs failed for %s:", sanitizeForLog(args.service), err);
         }
     }
-    // Calculate health score
+    // Honest signal coverage: judge the service only on the families that
+    // actually returned data, so a log-only (or absent) service is never
+    // coerced to a confident "healthy" from metric zeros (issue #453).
+    const coverage = { metrics: metricsHadData, logs: logsHadData };
+    // No data at all → either the service doesn't exist (typo / decommissioned)
+    // or it isn't monitored. Say so explicitly, like the other tools' empty
+    // states — don't return 100/healthy.
+    if (!metricsHadData && !logsHadData) {
+        const known = await knownServiceNames(tenantConnectors, args.service);
+        const note = known
+            ? `No metric or log data for "${args.service}" in the last 5 minutes — the service exists but has no monitored signals (or was quiet). Health is unknown, not healthy.`
+            : `Service "${args.service}" was not found in any connected source. Check the exact name via list_services. (Not reporting a health score for a service that does not exist.)`;
+        const result = {
+            service: args.service,
+            status: "unknown",
+            score: null,
+            signals: { metrics: null, logs: null },
+            anomalies,
+            correlations,
+            coverage,
+            note,
+        };
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // Calculate health score over the covered signals only.
     const { DEFAULT_HEALTH_THRESHOLDS } = await import("../config/loader.js");
     const health = calculateHealthScore({
         cpu,
@@ -78,22 +120,47 @@ export async function getServiceHealthHandler(registry, args, ctx = defaultConte
         errorRate,
         latencyP99,
         logErrorRate,
-    }, _thresholds || DEFAULT_HEALTH_THRESHOLDS);
+    }, _thresholds || DEFAULT_HEALTH_THRESHOLDS, coverage);
     const result = {
         service: args.service,
         status: health.status,
         score: health.score,
         signals: {
-            metrics: { cpu, memory, errorRate, latencyP99 },
-            logs: { errorRate: logErrorRate, topErrors },
+            metrics: metricsHadData ? { cpu, memory, errorRate, latencyP99 } : null,
+            logs: logsHadData ? { errorRate: logErrorRate, topErrors } : null,
         },
         anomalies,
         correlations,
+        coverage,
+        note: !metricsHadData
+            ? "No metrics signal for this service — score reflects logs only."
+            : !logsHadData
+                ? "No logs signal for this service — score reflects metrics only."
+                : undefined,
     };
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 }
+/** Best-effort: does any connector in the tenant know this service name?
+ *  Used only on the no-data path to distinguish "exists but unmonitored/quiet"
+ *  from "doesn't exist (typo/decommissioned)". A connector that throws is
+ *  treated as "can't confirm" and skipped. */
+async function knownServiceNames(connectors, service) {
+    for (const c of connectors) {
+        if (!c.listServices)
+            continue;
+        try {
+            const svcs = await c.listServices();
+            if (svcs.some((s) => s.name === service))
+                return true;
+        }
+        catch {
+            /* can't confirm via this connector — keep checking */
+        }
+    }
+    return false;
+}
 function checkAnomaly(values, metric, service, source, anomalies) {
     // Robust, metric-type-aware detector (same path as detect_anomalies):
     // latency/error_rate/saturation are one-sided, so a *decrease* (e.g.

package/dist/tools/handlers.test.js

@@ -153,6 +153,38 @@ describe("listServicesHandler", () => {
         assert.equal(data.total, 0);
     });
 });
+describe("detectAnomaliesHandler — fleet coverage (issue #453B)", () => {
+    it("fleet scan includes log-only services and reports per-service coverage", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({
+                name: "prom1", type: "prometheus", signalType: "metrics",
+                listServices: async () => [{ name: "metric-svc", source: "prom1", signalType: "metrics" }],
+                queryMetrics: async () => ({
+                    source: "prom1", service: "metric-svc", metric: "x", unit: "",
+                    values: Array.from({ length: 30 }, (_, i) => ({ timestamp: new Date(Date.now() - (30 - i) * 9000).toISOString(), value: 20 })),
+                    summary: { current: 20, average: 20, min: 20, max: 20, trend: "stable" },
+                }),
+            }),
+            createMockConnector({
+                name: "loki1", type: "loki", signalType: "logs",
+                listServices: async () => [{ name: "log-only-svc", source: "loki1", signalType: "logs" }],
+                queryLogs: async () => ({
+                    source: "loki1", service: "log-only-svc", entries: [],
+                    summary: { total: 10, errorCount: 0, warnCount: 0, topPatterns: [] },
+                }),
+            }),
+        ]);
+        const data = JSON.parse((await detectAnomaliesHandler(reg, {})).content[0].text);
+        // Both services scanned — the log-only one is NOT silently dropped.
+        assert.equal(data.scannedServices, 2);
+        const names = data.coverage.scanned.map((s) => s.service).sort();
+        assert.deepEqual(names, ["log-only-svc", "metric-svc"]);
+        const logOnly = data.coverage.scanned.find((s) => s.service === "log-only-svc");
+        assert.deepEqual(logOnly.signals, ["logs"], "log-only service must be scanned via its logs signal");
+        // All-clear is no longer silently partial — it states the coverage.
+        assert.match(data.summary, /2 scanned service\(s\)/);
+    });
+});
 describe("detectAnomaliesHandler — A5 memory/OOM coverage", () => {
     const flatMemory = () => ({
         source: "prom1", service: "payment-service", metric: "memory", unit: "bytes",
@@ -255,3 +287,57 @@ describe("getServiceHealthHandler — one-sided latency (regression)", () => {
         assert.equal(latAnom, undefined, `latency dropping must not be an anomaly, got: ${JSON.stringify(latAnom)}`);
     });
 });
+describe("getServiceHealthHandler — honest no-data / not-found (issue #453)", () => {
+    const emptySeries = () => ({
+        source: "prom1", service: "x", metric: "x", unit: "",
+        values: [],
+        summary: { current: 0, average: 0, min: 0, max: 0, trend: "stable" },
+    });
+    function metricsConnector(known) {
+        return {
+            connect: async () => { }, disconnect: async () => { },
+            healthCheck: async () => ({ status: "up", latencyMs: 1 }),
+            getDefaultMetrics: () => [], getMetrics: () => [],
+            listServices: async () => known.map((name) => ({ name, source: "prom1", signalType: "metrics" })),
+            name: "prom1", type: "prometheus", signalType: "metrics",
+            queryMetrics: async () => emptySeries(), // no data for any metric
+        };
+    }
+    function regWith(...mocks) {
+        const reg = new ConnectorRegistry();
+        for (const m of mocks) {
+            reg.connectors.set(m.name, m);
+            reg.sourceConfigs.set(m.name, { name: m.name, type: m.type, url: "http://m", enabled: true });
+        }
+        return reg;
+    }
+    it("nonexistent service → status unknown, score null, not-found note (not 100/healthy)", async () => {
+        const reg = regWith(metricsConnector(["payment-service"])); // does NOT know the queried name
+        const data = JSON.parse((await getServiceHealthHandler(reg, { service: "nope-xyz" })).content[0].text);
+        assert.equal(data.status, "unknown");
+        assert.equal(data.score, null);
+        assert.equal(data.signals.metrics, null);
+        assert.match(data.note, /not found/i);
+    });
+    it("log-only service with errors → judged on logs, never 100/healthy from metric zeros", async () => {
+        const logs = {
+            connect: async () => { }, disconnect: async () => { },
+            healthCheck: async () => ({ status: "up", latencyMs: 1 }),
+            getDefaultMetrics: () => [], getMetrics: () => [],
+            listServices: async () => [{ name: "logapp", source: "loki1", signalType: "logs" }],
+            name: "loki1", type: "loki", signalType: "logs",
+            queryLogs: async () => ({
+                source: "loki1", service: "logapp", entries: [],
+                summary: { total: 60, errorCount: 40, warnCount: 0, topPatterns: ["boom"] },
+            }),
+        };
+        const reg = regWith(metricsConnector([]), logs);
+        const data = JSON.parse((await getServiceHealthHandler(reg, { service: "logapp" })).content[0].text);
+        assert.notEqual(data.status, "healthy");
+        assert.notEqual(data.status, "unknown");
+        assert.equal(data.signals.metrics, null, "metrics signal must be null when no metric data");
+        assert.ok(data.signals.logs, "logs signal must be present");
+        assert.deepEqual(data.coverage, { metrics: false, logs: true });
+        assert.ok(data.score !== null && data.score < 50, `40 errors/5min log-only must not be healthy, got ${data.score}`);
+    });
+});

package/dist/types.d.ts

@@ -338,20 +338,31 @@ export interface AnomalyReport {
 }
 export interface ServiceHealth {
     service: string;
-    status: HealthStatus;
-    score: number;
+    /** "unknown" when the service has no data in any signal (or doesn't exist). */
+    status: HealthStatus | "unknown";
+    /** 0-100, or null when status is "unknown" (no signal had data). */
+    score: number | null;
     signals: {
+        /** null when the service exposes no metrics signal / no metric data. */
         metrics: {
             cpu: number;
             memory: number;
             errorRate: number;
             latencyP99: number;
-        };
+        } | null;
+        /** null when the service exposes no logs signal / no log data. */
         logs: {
             errorRate: number;
             topErrors: string[];
-        };
+        } | null;
     };
     anomalies: AnomalyReport[];
     correlations: string[];
+    /** Which signal families actually had data (drives the score weighting). */
+    coverage?: {
+        metrics: boolean;
+        logs: boolean;
+    };
+    /** Operator-facing explanation when status is "unknown" or coverage is partial. */
+    note?: string;
 }

package/package.json

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