@thotischner/observability-mcp 3.3.0 → 3.3.2

package/dist/analysis/correlator.js

@@ -21,7 +21,7 @@ export function correlateSignals(anomalies, logResults, metricResults) {
         for (const metric of serviceMetrics) {
             if (metric.metric === anomaly.metric)
                 continue;
-            if (metric.summary.trend === "rising") {
+            if (metric.summary && metric.summary.trend === "rising") {
                 correlations.push(`${anomaly.service}: ${anomaly.metric} anomaly coincides with rising ${metric.metric} ` +
                     `(current: ${metric.summary.current.toFixed(2)})`);
             }

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

@@ -428,3 +428,14 @@ test("E2E: /llms.txt is served and reflects the canonical tool registry", opts,
     }
     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,31 @@ 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 with a label-filter pipeline + no by → valid sum-wrapped LogQL (#452 leftover #2)", () => {
+        // The reporter saw an intermittent 400 on a label-filtered count_over_time
+        // and wondered if the collapse path emits different LogQL when a filter is
+        // present. It does not: the label filter lives in the streamPipeline
+        // (identical to the sum/topk path, which works), and the count_over_time
+        // branch wraps it verbatim. Assert the emitted LogQL is well-formed —
+        // `sum (count_over_time({sel} | json | environment="prod" [step]))` — so
+        // any future regression in the generated query is caught here.
+        const filtered = '{service_name="app"} | json | environment="prod"';
+        const r = buildAggregateLogQL(filtered, { op: "count_over_time", step: "1h" }, "6h");
+        assert.equal(r.mode, "range");
+        assert.equal(r.step, "3600s");
+        assert.equal(r.logql, `sum (count_over_time(${filtered} [3600s]))`);
+        // Structural sanity: balanced parens, sum-wrapped, single range selector.
+        assert.equal((r.logql.match(/\(/g) || []).length, (r.logql.match(/\)/g) || []).length);
+        assert.match(r.logql, /^sum \(count_over_time\(.*\[\d+s\]\)\)$/);
+    });
+    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/connectors/prometheus.js

@@ -240,6 +240,10 @@ export class PrometheusConnector {
             resolvedSeries: promql,
             resolvedLabel: label,
         };
+        if (!result.summary) {
+            result.note = `No data: no '${params.metric}' series matched "${params.service}" in this window. ` +
+                "The service may expose logs only, or the metric name/label didn't match. Absent ≠ zero — summary is null rather than all-zeros.";
+        }
         if (params.groupBy && groups.length > 1) {
             result.groupBy = params.groupBy;
             result.groups = groups;
@@ -295,6 +299,9 @@ export class PrometheusConnector {
             resolvedSeries: rawQuery,
             resolvedLabel: "",
         };
+        if (!result.summary) {
+            result.note = "No data: the query returned no series in this window. Absent ≠ zero — summary is null rather than all-zeros.";
+        }
         if (groups.length > 1)
             result.groups = groups;
         return result;
@@ -475,7 +482,10 @@ export class PrometheusConnector {
     }
     computeSummary(values) {
         if (values.length === 0) {
-            return { current: 0, average: 0, min: 0, max: 0, trend: "stable" };
+            // No data points → no-data, NOT a confident all-zeros reading. Coercing
+            // an empty series to {current:0,trend:"stable"} is indistinguishable
+            // from a service genuinely idling at 0 (issue #462).
+            return null;
         }
         const current = values[values.length - 1];
         const average = values.reduce((a, b) => a + b, 0) / values.length;

package/dist/connectors/prometheus.test.js

@@ -53,13 +53,9 @@ describe("PrometheusConnector", () => {
         });
     });
     describe("computeSummary", () => {
-        it("returns zeros for empty array", () => {
+        it("returns null for empty array — no-data, not a false all-zeros reading (#462)", () => {
             const s = proto.computeSummary([]);
-            assert.equal(s.current, 0);
-            assert.equal(s.average, 0);
-            assert.equal(s.min, 0);
-            assert.equal(s.max, 0);
-            assert.equal(s.trend, "stable");
+            assert.equal(s, null);
         });
         it("computes correct summary for values", () => {
             const s = proto.computeSummary([10, 20, 30, 40]);
@@ -199,4 +195,34 @@ describe("PrometheusConnector", () => {
             }
         });
     });
+    describe("queryMetrics no-data → null summary, not zero-fill (#462)", () => {
+        const fakeSource = { name: "test", type: "prometheus", url: "http://localhost:9090", enabled: true };
+        it("an empty result set yields values:[], summary:null, and a no-data note", async () => {
+            const connector = new PrometheusConnector();
+            await connector.connect({ ...fakeSource });
+            const orig = globalThis.fetch;
+            // raw_query bypasses the candidate-probe / label-resolve path and runs
+            // query_range directly — here it returns an empty result set (the
+            // no-data case: a logs-only service has no such metric series).
+            globalThis.fetch = (async () => ({
+                ok: true,
+                status: 200,
+                json: async () => ({ data: { result: [] } }),
+            }));
+            try {
+                const result = await connector.queryMetrics({
+                    service: "",
+                    metric: "",
+                    duration: "1h",
+                    rawQuery: "rate(process_cpu_seconds_total{job=\"logs-only-svc\"}[1m]) * 100",
+                });
+                assert.deepEqual(result.values, [], "no data points");
+                assert.equal(result.summary, null, "summary must be null, not {current:0,...}");
+                assert.match(result.note ?? "", /No data/i, "must carry a no-data note");
+            }
+            finally {
+                globalThis.fetch = orig;
+            }
+        });
+    });
 });

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 ---
@@ -431,9 +443,12 @@ async function main() {
                         "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:",
+                        "## 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"),
                 },
@@ -507,7 +522,7 @@ async function main() {
             "Fetch the raw time-series for ONE metric of ONE service over a look-back window, returned together with pre-computed summary statistics.",
             "When to use: when you need the actual numeric values or the trend of a known metric. For a 'is this service OK?' verdict use `get_service_health`; to find which services are misbehaving use `detect_anomalies`.",
             "Prerequisites: get the exact service name from `list_services` and choose a metric from the list at the end of this description.",
-            "Behavior: read-only, no side effects. Returns an ordered array of {timestamp, value} points plus a summary {current, average, min, max, trend}. With `groupBy` set, returns one labelled series per distinct label value under `groups` instead of a single aggregated series. Units depend on the metric (e.g. CPU as %, latency as ms, rates as per-second). An unknown service/metric or an unreachable backend yields a structured explanatory error, never an exception.",
+            "Behavior: read-only, no side effects. Returns an ordered array of {timestamp, value} points plus a summary {current, average, min, max, trend}. When no series matched (e.g. a logs-only service has no such metric), `values` is empty and `summary` is `null` (not all-zeros) with a `note` — absent data is not a real zero reading. With `groupBy` set, returns one labelled series per distinct label value under `groups` instead of a single aggregated series. Units depend on the metric (e.g. CPU as %, latency as ms, rates as per-second). An unknown service/metric or an unreachable backend yields a structured explanatory error, never an exception.",
             `Available metrics: ${metricsList}`,
         ].join(" "), {
             service: z
@@ -546,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(" "), {

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.summary) {
+                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.summary) {
+                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.summary) {
+                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.summary) {
+                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,59 @@ 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: [],
+        // No data → null summary (matches the real connector after #462), so the
+        // health handler treats it as no-coverage, not a real zero reading.
+        summary: null,
+    });
+    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/tools/query-logs-error-shape.test.d.ts

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

package/dist/tools/query-logs-error-shape.test.js

@@ -0,0 +1,32 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ConnectorRegistry } from "../connectors/registry.js";
+import { queryLogsHandler } from "./query-logs.js";
+// Inject a mock connector into the registry's internal maps.
+function regWith(mock) {
+    const reg = new ConnectorRegistry();
+    reg.connectors.set(mock.name, mock);
+    reg.sourceConfigs.set(mock.name, { name: mock.name, type: mock.type, url: "http://mock", enabled: true });
+    return reg;
+}
+describe("queryLogsHandler error response shape (issue #452)", () => {
+    it("a failing query reports `window` (the look-back), not `duration` (read as wall-clock)", async () => {
+        // Mirrors the raw_query fail-fast case: the connector throws, the handler
+        // returns a structured error. The look-back window must be labelled
+        // `window`, never `duration` — an agent reading duration:"5m" on a <1s
+        // failure thinks it hung (the very symptom the fail-fast fix removed).
+        const mock = {
+            connect: async () => { }, disconnect: async () => { },
+            healthCheck: async () => ({ status: "up", latencyMs: 1 }),
+            getDefaultMetrics: () => [], getMetrics: () => [],
+            listServices: async () => [],
+            name: "loki1", type: "loki", signalType: "logs",
+            queryLogs: async () => { throw new Error("query_logs raw_query returned a 'matrix' result, but query_logs handles log lines (streams) only."); },
+        };
+        const result = await queryLogsHandler(regWith(mock), { raw_query: "sum(count_over_time({service_name=\"x\"} | json [1h]))", duration: "1h" }, undefined, { allowRawQuery: true });
+        const data = JSON.parse(result.content[0].text);
+        assert.ok(data.error, "must be an error response");
+        assert.equal(data.window, "1h", "look-back must be reported as `window`");
+        assert.equal("duration" in data, false, "must NOT carry a `duration` field (misread as elapsed time)");
+    });
+});

package/dist/tools/query-logs.js

@@ -119,7 +119,8 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext(), o
         }
         if (aggResults.length === 0) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: aggErrors.length ? `Aggregate failed: ${aggErrors.join("; ")}` : "No data returned", service: args.service, duration }) }],
+                // `window` = the requested look-back, not elapsed time (issue #452).
+                content: [{ type: "text", text: JSON.stringify({ error: aggErrors.length ? `Aggregate failed: ${aggErrors.join("; ")}` : "No data returned", service: args.service, window: duration }) }],
                 isError: aggErrors.length > 0,
             };
         }
@@ -160,7 +161,9 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext(), o
                     text: JSON.stringify({
                         error: errors.length > 0 ? `Query failed: ${errors.join("; ")}` : "No logs returned",
                         service: args.service,
-                        duration,
+                        // The requested look-back window, NOT elapsed wall-clock time. Named
+                        // `window` so a fast failure isn't misread as a 5-minute hang (#452).
+                        window: duration,
                     }),
                 },
             ],

package/dist/types.d.ts

@@ -182,7 +182,8 @@ export interface MetricSummary {
 export interface MetricGroup {
     key: string;
     values: DataPoint[];
-    summary: MetricSummary;
+    /** null when this group has no data points — absent ≠ a real zero reading. */
+    summary: MetricSummary | null;
 }
 export interface MetricResult {
     source: string;
@@ -190,12 +191,15 @@ export interface MetricResult {
     metric: string;
     unit: string;
     values: DataPoint[];
-    summary: MetricSummary;
+    /** null when `values` is empty (no series matched this service/metric) — a
+     *  no-data signal, not a confident all-zeros reading (issue #462). */
+    summary: MetricSummary | null;
     resolvedSeries?: string;
     resolvedLabel?: string;
     groupBy?: string;
     groups?: MetricGroup[];
     hint?: string;
+    note?: string;
 }
 export interface LogEntry {
     timestamp: string;
@@ -338,20 +342,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.3.0",
+  "version": "3.3.2",
   "description": "Unified observability gateway for AI agents — one MCP server for Prometheus, Loki, and any backend",
   "type": "module",
   "license": "Apache-2.0",