@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/postmortem/synthesizer.js

@@ -0,0 +1,205 @@
+// Auto-post-mortem synthesizer — Phase F19.
+//
+// Stitches together the existing observability primitives — anomaly
+// history (F15), blast-radius (F13/topology), trace summaries (F13),
+// log-derived error patterns (existing query_logs) — into a single
+// markdown report a human (or LLM) can read in one shot.
+//
+// The synthesizer is pure-ish: it accepts the upstream queries as
+// injected functions so the tool layer can compose them without the
+// synthesizer depending on the entire ConnectorRegistry API. Tests
+// inject fake data and don't need a live demo stack.
+/** Synthesise one report from already-fetched primitives. Pure
+ *  compute — no I/O. */
+export function synthesizePostmortem(input) {
+    const timeline = [...input.anomalies]
+        .sort((a, b) => a.ts.localeCompare(b.ts))
+        .map((a) => ({ ts: a.ts, service: a.service, score: a.score, severity: a.severity, method: a.method }));
+    const contributingSignals = aggregateBySignal(input.anomalies);
+    const peakScore = input.anomalies.reduce((m, a) => Math.max(m, a.score), 0);
+    const errorTraces = input.traces.filter((t) => t.hasError).length;
+    const peakNode = input.blastRadius.nodes.find((n) => n.root) ?? input.blastRadius.nodes[0];
+    const blastSize = input.blastRadius.nodes.length;
+    const followUps = inferFollowUps(input, { peakScore, errorTraces, blastSize });
+    const synopsis = synopsisFor(input, peakScore, errorTraces, blastSize);
+    const markdown = renderMarkdown({
+        input,
+        timeline,
+        contributingSignals,
+        peakNode,
+        peakScore,
+        errorTraces,
+        blastSize,
+        followUps,
+        synopsis,
+    });
+    return {
+        service: input.service,
+        window: input.window,
+        fromIso: input.fromIso,
+        toIso: input.toIso,
+        synopsis,
+        markdown,
+        sections: {
+            timeline,
+            blastRadius: { nodes: input.blastRadius.nodes, edgeCount: input.blastRadius.edges.length },
+            topTraces: input.traces.slice(0, 10),
+            contributingSignals,
+            followUps,
+            logHighlights: input.logHighlights ?? [],
+        },
+    };
+}
+function aggregateBySignal(anomalies) {
+    const groups = new Map();
+    for (const a of anomalies) {
+        const sig = a.signal ?? a.method;
+        const prev = groups.get(sig);
+        if (prev)
+            prev.push(a.score);
+        else
+            groups.set(sig, [a.score]);
+    }
+    return [...groups.entries()]
+        .map(([signal, scores]) => ({
+        signal,
+        count: scores.length,
+        meanScore: Math.round((scores.reduce((s, x) => s + x, 0) / scores.length) * 100) / 100,
+    }))
+        .sort((a, b) => b.meanScore - a.meanScore);
+}
+function inferFollowUps(input, ctx) {
+    const out = [];
+    if (input.anomalies.length === 0) {
+        out.push("No anomaly history found for this service in the window — confirm OMCP_ANOMALY_HISTORY_REMOTE_WRITE is wired and Prometheus is scraping the same TSDB.");
+        return out;
+    }
+    if (ctx.peakScore >= 0.9) {
+        out.push(`Peak anomaly score ${ctx.peakScore} is critical — review the detector's threshold for service '${input.service}' and consider whether the chosen method (${dominantMethod(input.anomalies)}) suits this signal's distribution.`);
+    }
+    if (ctx.errorTraces > 0) {
+        out.push(`${ctx.errorTraces} trace(s) carried error spans during the window — drill into the slowest via \`query_traces(service="${input.service}", errorsOnly=true)\`.`);
+    }
+    if (ctx.blastSize > 5) {
+        out.push(`Blast radius spans ${ctx.blastSize} nodes — verify that the dependency edges are still accurate (a stale topology snapshot can blow up the radius and miss the real cause).`);
+    }
+    if ((input.logHighlights ?? []).length > 0) {
+        out.push("Log highlights above point at concrete error patterns — promote the recurring ones to an alert or SLO so the next regression catches itself.");
+    }
+    if (out.length === 0) {
+        out.push("All signals look stable for this window — consider closing the incident as a transient anomaly or expanding the time window.");
+    }
+    return out;
+}
+function dominantMethod(anomalies) {
+    const c = new Map();
+    for (const a of anomalies)
+        c.set(a.method, (c.get(a.method) ?? 0) + 1);
+    return [...c.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "unknown";
+}
+function synopsisFor(input, peakScore, errorTraces, blastSize) {
+    const anomalyCount = input.anomalies.length;
+    if (anomalyCount === 0) {
+        return `No anomalies recorded for service '${input.service}' between ${input.fromIso} and ${input.toIso}. Either the window was clean, or the history sink wasn't writing at the time.`;
+    }
+    return [
+        `Service '${input.service}' produced ${anomalyCount} anomaly sample(s) between ${input.fromIso} and ${input.toIso}, peaking at ${peakScore}.`,
+        `Blast radius at peak covered ${blastSize} node(s); ${errorTraces} trace(s) carried error spans.`,
+    ].join(" ");
+}
+function renderMarkdown(ctx) {
+    const { input, timeline, contributingSignals, peakNode, peakScore, errorTraces, followUps, synopsis } = ctx;
+    const lines = [];
+    lines.push(`# Post-mortem — ${input.service}`);
+    lines.push("");
+    lines.push(`> **Window:** \`${input.fromIso}\` → \`${input.toIso}\` (\`${input.window}\`)  `);
+    lines.push(`> **Tenant:** \`${input.tenant}\`  `);
+    lines.push(`> **Generated by:** observability-mcp \`generate_postmortem\``);
+    lines.push("");
+    lines.push("## Synopsis");
+    lines.push("");
+    lines.push(synopsis);
+    lines.push("");
+    lines.push("## Anomaly timeline");
+    lines.push("");
+    if (timeline.length === 0) {
+        lines.push("_No anomaly samples in this window._");
+    }
+    else {
+        lines.push("| ts | service | score | severity | method |");
+        lines.push("|---|---|---|---|---|");
+        for (const t of timeline.slice(0, 20)) {
+            lines.push(`| \`${t.ts}\` | \`${t.service}\` | ${t.score} | ${t.severity} | ${t.method} |`);
+        }
+        if (timeline.length > 20)
+            lines.push(`| … | _${timeline.length - 20} more rows_ |  |  |  |`);
+    }
+    lines.push("");
+    lines.push("## Blast radius at peak");
+    lines.push("");
+    if (peakNode) {
+        lines.push(`Root node: **\`${peakNode.name}\`** (\`${peakNode.kind}\`).`);
+    }
+    else {
+        lines.push("_Topology snapshot empty._");
+    }
+    lines.push("");
+    if (input.blastRadius.nodes.length > 0) {
+        lines.push("| node | kind |");
+        lines.push("|---|---|");
+        for (const n of input.blastRadius.nodes.slice(0, 30)) {
+            lines.push(`| \`${n.name}\`${n.root ? " *(root)*" : ""} | \`${n.kind}\` |`);
+        }
+    }
+    lines.push("");
+    lines.push(`Edges in radius: **${input.blastRadius.edges.length}**.`);
+    lines.push("");
+    lines.push("## Contributing signals (ranked)");
+    lines.push("");
+    if (contributingSignals.length === 0) {
+        lines.push("_No anomaly samples to rank._");
+    }
+    else {
+        lines.push("| signal | samples | mean score |");
+        lines.push("|---|---|---|");
+        for (const s of contributingSignals.slice(0, 10)) {
+            lines.push(`| \`${s.signal}\` | ${s.count} | ${s.meanScore} |`);
+        }
+    }
+    lines.push("");
+    lines.push("## Related traces");
+    lines.push("");
+    if (input.traces.length === 0) {
+        lines.push("_No traces returned for the window. Configure a Tempo / Jaeger source if traces are expected._");
+    }
+    else {
+        lines.push("| trace | service | duration ms | error |");
+        lines.push("|---|---|---|---|");
+        for (const t of input.traces.slice(0, 10)) {
+            lines.push(`| \`${t.traceId}\` | \`${t.rootService}\` | ${t.durationMs} | ${t.hasError ? "yes" : "no"} |`);
+        }
+        if (errorTraces > 0)
+            lines.push(`\n_${errorTraces} of the returned traces carried error spans._`);
+    }
+    lines.push("");
+    if ((input.logHighlights ?? []).length > 0) {
+        lines.push("## Log highlights");
+        lines.push("");
+        for (const l of input.logHighlights)
+            lines.push(`- ${l}`);
+        lines.push("");
+    }
+    lines.push("## Suggested follow-ups");
+    lines.push("");
+    for (const f of followUps)
+        lines.push(`- ${f}`);
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(`*Generated by observability-mcp \`generate_postmortem\` — see \`docs/postmortems.md\` for the prompt sources.*`);
+    lines.push("");
+    // Bound the chunk to keep memory predictable; the rendered report
+    // is normally a few KB but a pathological 10k-sample timeline
+    // could approach MB without the slice() caps above.
+    return lines.join("\n");
+}

package/dist/postmortem/synthesizer.test.d.ts

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

package/dist/postmortem/synthesizer.test.js

@@ -0,0 +1,141 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { synthesizePostmortem, } from "./synthesizer.js";
+function input(overrides = {}) {
+    return {
+        service: "payment",
+        window: "1h",
+        tenant: "default",
+        fromIso: "2026-06-06T00:00:00.000Z",
+        toIso: "2026-06-06T01:00:00.000Z",
+        anomalies: [],
+        blastRadius: { nodes: [], edges: [] },
+        traces: [],
+        ...overrides,
+    };
+}
+function anomaly(ts, score, method = "mad", severity = "warn", signal) {
+    return { ts, service: "payment", score, method, severity, signal };
+}
+test("synthesizePostmortem: empty input returns synopsis + 'no anomalies' follow-up", () => {
+    const r = synthesizePostmortem(input());
+    assert.match(r.synopsis, /No anomalies recorded/);
+    assert.equal(r.sections.timeline.length, 0);
+    assert.equal(r.sections.followUps.length, 1);
+    assert.match(r.sections.followUps[0], /OMCP_ANOMALY_HISTORY_REMOTE_WRITE/);
+});
+test("synthesizePostmortem: timeline is sorted by ts ascending", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [
+            anomaly("2026-06-06T00:30:00Z", 0.5),
+            anomaly("2026-06-06T00:10:00Z", 0.4),
+            anomaly("2026-06-06T00:50:00Z", 0.9),
+        ],
+    }));
+    assert.deepEqual(r.sections.timeline.map((t) => t.ts), ["2026-06-06T00:10:00Z", "2026-06-06T00:30:00Z", "2026-06-06T00:50:00Z"]);
+});
+test("synthesizePostmortem: contributing signals aggregated by signal label + ranked by mean score desc", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [
+            anomaly("2026-06-06T00:10Z", 0.5, "mad", "warn", "request_latency"),
+            anomaly("2026-06-06T00:20Z", 0.4, "mad", "warn", "request_latency"),
+            anomaly("2026-06-06T00:30Z", 0.95, "seasonality", "critical", "error_rate"),
+        ],
+    }));
+    const sigs = r.sections.contributingSignals;
+    assert.equal(sigs.length, 2);
+    // error_rate (0.95 mean) ranks above request_latency (0.45 mean)
+    assert.equal(sigs[0].signal, "error_rate");
+    assert.equal(sigs[0].count, 1);
+    assert.equal(sigs[0].meanScore, 0.95);
+    assert.equal(sigs[1].signal, "request_latency");
+    assert.equal(sigs[1].count, 2);
+    assert.equal(sigs[1].meanScore, 0.45);
+});
+test("synthesizePostmortem: missing signal label falls back to method", () => {
+    const r = synthesizePostmortem(input({ anomalies: [anomaly("2026-06-06T00:10Z", 0.6, "correlator")] }));
+    assert.equal(r.sections.contributingSignals[0].signal, "correlator");
+});
+test("synthesizePostmortem: critical peak triggers a follow-up mentioning the threshold", () => {
+    const r = synthesizePostmortem(input({ anomalies: [anomaly("2026-06-06T00:30Z", 0.95)] }));
+    assert.ok(r.sections.followUps.some((f) => /Peak anomaly score 0\.95/.test(f)));
+});
+test("synthesizePostmortem: errors-in-traces triggers errorsOnly drill-in suggestion", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.6)],
+        traces: [
+            { traceId: "aaa", rootName: "GET /pay", rootService: "payment", durationMs: 800, hasError: true },
+        ],
+    }));
+    assert.ok(r.sections.followUps.some((f) => /errorsOnly=true/.test(f)));
+});
+test("synthesizePostmortem: large blast radius triggers stale-topology hint", () => {
+    const nodes = Array.from({ length: 7 }, (_, i) => ({ id: `n${i}`, kind: "pod", name: `n${i}`, root: i === 0 }));
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.6)],
+        blastRadius: { nodes, edges: [{ from: "n0", to: "n1", relation: "CALLS" }] },
+    }));
+    assert.ok(r.sections.followUps.some((f) => /7 nodes/.test(f) && /stale topology/i.test(f)));
+});
+test("synthesizePostmortem: clean window returns a 'stable, consider closing' follow-up", () => {
+    // The "all signals stable" branch fires only when:
+    //   anomalies present (not zero)
+    //   peak < 0.9
+    //   no error traces
+    //   blast radius <= 5
+    //   no log highlights
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.3)],
+        blastRadius: { nodes: [{ id: "n0", kind: "pod", name: "n0", root: true }], edges: [] },
+    }));
+    assert.ok(r.sections.followUps.some((f) => /stable for this window/.test(f)));
+});
+test("synthesizePostmortem: markdown contains every section header in order", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.7)],
+        blastRadius: {
+            nodes: [{ id: "p", kind: "deployment", name: "payment", root: true }],
+            edges: [{ from: "p", to: "rds", relation: "READS_FROM" }],
+        },
+        traces: [{ traceId: "t", rootName: "GET /pay", rootService: "payment", durationMs: 200, hasError: false }],
+        logHighlights: ["payment-service: 12 5xx in window"],
+    }));
+    for (const heading of [
+        "# Post-mortem — payment",
+        "## Synopsis",
+        "## Anomaly timeline",
+        "## Blast radius at peak",
+        "## Contributing signals (ranked)",
+        "## Related traces",
+        "## Log highlights",
+        "## Suggested follow-ups",
+    ]) {
+        assert.ok(r.markdown.includes(heading), `markdown missing section: ${heading}`);
+    }
+    // The order check — anomaly timeline should appear before blast radius
+    assert.ok(r.markdown.indexOf("## Anomaly timeline") < r.markdown.indexOf("## Blast radius at peak"));
+});
+test("synthesizePostmortem: timeline > 20 rows is truncated with an ellipsis row", () => {
+    const anomalies = Array.from({ length: 25 }, (_, i) => anomaly(`2026-06-06T00:${String(i).padStart(2, "0")}:00Z`, 0.5 + i * 0.01));
+    const r = synthesizePostmortem(input({ anomalies }));
+    // The structured section has all 25
+    assert.equal(r.sections.timeline.length, 25);
+    // The markdown table is capped at 20 data rows + an ellipsis row
+    // — count rows specifically inside the Anomaly timeline section
+    // (other sections also use | ` ... | tables and would inflate a
+    // global grep).
+    const md = r.markdown;
+    const timelineStart = md.indexOf("## Anomaly timeline");
+    const blastStart = md.indexOf("## Blast radius at peak");
+    const timelineSection = md.slice(timelineStart, blastStart);
+    const tableRows = timelineSection.split("\n").filter((l) => l.startsWith("| `")).length;
+    assert.equal(tableRows, 20);
+    assert.match(timelineSection, /_5 more rows_/);
+});
+test("synthesizePostmortem: report carries the input window + iso bounds back into the structured shape", () => {
+    const r = synthesizePostmortem(input({ window: "6h" }));
+    assert.equal(r.service, "payment");
+    assert.equal(r.window, "6h");
+    assert.equal(r.fromIso, "2026-06-06T00:00:00.000Z");
+    assert.equal(r.toIso, "2026-06-06T01:00:00.000Z");
+});

package/dist/products/loader.d.ts

@@ -0,0 +1,112 @@
+/**
+ * MCP Products — curated, agent-facing collections of tools.
+ *
+ * A Product is a named bundle that ships with branding metadata
+ * (icon, description, version) plus a list of allowed MCP tools.
+ * The agent calling /mcp can be told which Product it belongs to
+ * (via a future header / arg, slice 2+), and the server can filter
+ * tools/list and tools/call responses accordingly.
+ *
+ * Today's surface (slice 1):
+ *   - In-memory ProductsStore loaded from OMCP_PRODUCTS_FILE
+ *     (YAML or JSON). Missing/empty file → empty catalog.
+ *   - Strict validation: unknown action / unknown resource /
+ *     unexpected keys reject loudly.
+ *   - Mtime-poll hot-reload: callers (e.g. each /api/products
+ *     handler) `await store.maybeReload()` before reading. If the
+ *     file mtime advanced since the last load, the store re-parses
+ *     and atomically swaps the in-memory file; parse errors keep
+ *     the previous good state and log loudly. One `stat()` call per
+ *     reload-aware request — too cheap to matter vs. the network
+ *     round-trip, no FSWatcher platform fragility (WSL / NFS).
+ */
+export interface Product {
+    /** Stable identifier — used in URLs, audit entries, /api/products/{id}. */
+    id: string;
+    /** Display name shown in the UI / agent dropdown. */
+    name: string;
+    /** One-sentence description. */
+    description?: string;
+    /** Allowed MCP tool names. Empty / undefined → all tools allowed. */
+    tools?: string[];
+    /** Operator-defined version label, e.g. "1.0.0" or "preview". */
+    version?: string;
+    /** Free-form branding metadata for the UI — icon URL, theme colour, etc. */
+    branding?: {
+        iconUrl?: string;
+        color?: string;
+    };
+    /** Lifecycle stage: published = visible to agents; staging = admin-only. */
+    status?: "published" | "staging";
+    /** Tenant this product belongs to. Omitted → "default". */
+    tenant?: string;
+}
+export interface ProductsFile {
+    products: Product[];
+}
+export declare class ProductsLoadError extends Error {
+    constructor(msg: string);
+}
+export declare function readProductsFile(path: string | undefined): Promise<ProductsFile>;
+export declare function parseProductsText(text: string, origin: string): ProductsFile;
+/** In-memory store with tenant- and status-aware queries. */
+export declare class ProductsStore {
+    private file;
+    /** Optional source file path. When set, `maybeReload()` polls its
+     *  mtime and re-parses on change. Mutations via upsert/delete update
+     *  `lastMtimeMs` after the caller persists, so the store does not
+     *  reload its own writes. */
+    private path?;
+    private lastMtimeMs;
+    constructor(file?: ProductsFile, opts?: {
+        path?: string;
+        initialMtimeMs?: number;
+    });
+    /** Re-read the source file if its mtime has advanced since the last
+     *  load. No-op when no path was supplied at construction. Parse or
+     *  IO errors are logged and the previous good state is kept — the
+     *  invariant is "the store always reflects a valid catalogue", so a
+     *  broken edit on disk never takes the running server down. */
+    maybeReload(): Promise<{
+        reloaded: boolean;
+    }>;
+    /** Re-stat the source file and pin the mtime cursor to its current
+     *  value. Call this after a successful write so the store does not
+     *  treat its own change as an external reload trigger. Best-effort:
+     *  if the stat fails, the next maybeReload() will simply reload the
+     *  file once and find it identical. */
+    pinMtimeAfterWrite(): Promise<void>;
+    /** Return the product list. When `tenant` is set, filters to that
+     *  tenant (entries without a tenant field treated as "default").
+     *  When `includeStaging` is false (default), staging products are
+     *  hidden from the result — admins should pass true. */
+    list(opts?: {
+        tenant?: string;
+        includeStaging?: boolean;
+    }): Product[];
+    /** Lookup by id. Cross-tenant gets return undefined when `tenant` set. */
+    get(id: string, tenant?: string): Product | undefined;
+    count(tenant?: string): number;
+    replace(file: ProductsFile): void;
+    /** Upsert (replace if id exists, else append). Returns the new
+     *  ProductsFile so the caller can persist it. */
+    upsert(product: Product): ProductsFile;
+    /** Remove by id. Returns true when the product existed, false
+     *  otherwise. Caller persists the resulting file. */
+    delete(id: string): {
+        removed: boolean;
+        file: ProductsFile;
+    };
+    /** Snapshot of the current file (for tests / persistence). */
+    snapshot(): ProductsFile;
+}
+/** Validate a single product entry by routing it through the same
+ *  parser as the file format. Throws ProductsLoadError on any
+ *  shape problem. Used by PUT /api/products/:id so a typo / wrong
+ *  type / unknown key gets the same loud rejection a malformed
+ *  file would. */
+export declare function validateProduct(input: unknown, origin?: string): Product;
+/** Atomic write of the products file. Same tmp+rename pattern as
+ *  the audit-chain + token-budget snapshot, so a crash mid-write
+ *  leaves the previous file intact. */
+export declare function writeProductsFile(path: string, file: ProductsFile): Promise<void>;