@thotischner/observability-mcp 1.7.1 → 3.0.0

package/config/products.yaml.example

@@ -0,0 +1,48 @@
+# MCP Products catalog — copy to products.yaml + set OMCP_PRODUCTS_FILE
+# to its path. See docs/products.md for the field reference.
+#
+# Every entry needs at minimum an id + name. Everything else is
+# optional. The server validates this file at boot via the same
+# parseProductsText pipeline the loader test suite exercises — a
+# typo (e.g. `toolss:` instead of `tools:`) fails the boot loudly
+# rather than silently dropping a grant.
+
+products:
+  - id: ops-bundle
+    name: Operations Bundle
+    description: Incident-response tools for the on-call SRE agent.
+    tools:
+      - query_logs
+      - query_metrics
+      - get_service_health
+    version: "1.0.0"
+    status: published
+    branding:
+      iconUrl: https://example.com/icons/ops.svg
+      color: "#3178c6"
+
+  - id: dev-bundle
+    name: Developer Bundle
+    description: Discovery + topology tools for the coding agent. Read-only.
+    tools:
+      - list_services
+      - get_topology
+    status: published
+
+  - id: experimental-bundle
+    name: Experimental Bundle
+    description: New tools being trialled internally. Hidden from agents.
+    tools:
+      - query_logs
+      - get_topology
+    status: staging                    # admin-only until promoted
+
+  # Multi-tenant example: a product visible only to the "acme" tenant.
+  # Remove the tenant: line (or leave it unset) to land in "default".
+  - id: acme-compliance
+    name: Acme Compliance Read-Only
+    description: Logs query for Acme's compliance team agent.
+    tools:
+      - query_logs
+    status: published
+    tenant: acme

package/dist/analysis/history.d.ts

@@ -0,0 +1,70 @@
+export interface AnomalyRecord {
+    /** ISO-8601 timestamp (the moment the score was computed). */
+    ts: string;
+    service: string;
+    tenant: string;
+    /** Anomaly score, 0..1 typically. Numeric — the sample written to the TSDB. */
+    score: number;
+    /** "mad" | "seasonality" | "correlator" — the method that produced the score. */
+    method: string;
+    /** "info" | "warn" | "critical". */
+    severity: string;
+    /** Optional source label (which signal the score applied to). */
+    signal?: string;
+}
+export interface AnomalyHistoryConfig {
+    /** Remote-write URL. Setting this enables the history sink. */
+    url?: string;
+    /** Comma-separated key=value pairs for extra request headers. */
+    headers?: Record<string, string>;
+    /** Bearer token forwarded as Authorization header. */
+    bearerToken?: string;
+    /** Flush interval in ms. Default 10 000. */
+    flushIntervalMs?: number;
+    /** Max buffer size before a synchronous flush. Default 500. */
+    maxBufferSize?: number;
+    /** Per-request timeout (ms). Default 5 000. */
+    requestTimeoutMs?: number;
+    /** Inject fetch for tests. */
+    fetchImpl?: typeof fetch;
+}
+export declare function fromEnv(env?: NodeJS.ProcessEnv): AnomalyHistoryConfig;
+/**
+ * In-process buffer + remote-write client. Use one instance per
+ * gateway process; `record()` is called from the anomaly detector;
+ * `flush()` runs on the interval AND on SIGTERM.
+ */
+export declare class AnomalyHistory {
+    private readonly url?;
+    private readonly headers;
+    private readonly bearerToken?;
+    private readonly flushIntervalMs;
+    private readonly maxBufferSize;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    private buffer;
+    private timer?;
+    private flushing;
+    constructor(cfg?: AnomalyHistoryConfig);
+    /** Whether the history sink is enabled (URL configured). */
+    isEnabled(): boolean;
+    /** Begin the flush timer. Idempotent. No-op when sink is disabled. */
+    start(): void;
+    /** Stop the flush timer + flush one last time. */
+    stop(): Promise<void>;
+    /** Add one anomaly to the buffer. Silently drops when disabled.
+     *  Triggers a synchronous flush if the buffer crosses maxBufferSize. */
+    record(entry: AnomalyRecord): Promise<void>;
+    /** Send the current buffer to the remote-write endpoint. Drops the
+     *  buffer on success OR failure — history is best-effort. */
+    flush(): Promise<void>;
+    /** Test seam: number of currently-buffered entries. */
+    bufferSize(): number;
+    /** Visible-for-test: format the buffer as a JSON payload mirroring
+     *  the Prometheus remote-write metric shape. Real remote-write uses
+     *  Snappy-compressed protobuf — we ship JSON here as a portable
+     *  baseline that any TSDB-receiving collector can ingest via a tiny
+     *  shim. A protobuf+Snappy fast path is a follow-up. */
+    formatBatch(batch: AnomalyRecord[]): unknown;
+    private sendBatch;
+}

package/dist/analysis/history.js

@@ -0,0 +1,170 @@
+// Anomaly history — persists per-anomaly scores to an external TSDB
+// via Prometheus remote-write so post-mortems can replay what the
+// gateway saw at a specific time. Opt-in via
+// OMCP_ANOMALY_HISTORY_REMOTE_WRITE; default OFF preserves the
+// pre-F15 "scores live in process memory only" behaviour.
+//
+// Wire format: a single time-series sample per recorded anomaly,
+// labelled with service / tenant / signal / method (mad / seasonality
+// / correlator) / severity. The TSDB-side query then becomes a
+// `omcp_anomaly_score{service="payment"}` PromQL.
+//
+// Buffering: writes are batched on a fixed flush interval so the
+// remote-write side never sees a request per anomaly. Failure to
+// flush logs once and drops the buffer — the gateway must never
+// block on a sick TSDB.
+export function fromEnv(env = process.env) {
+    const url = env.OMCP_ANOMALY_HISTORY_REMOTE_WRITE?.trim();
+    const headers = {};
+    const raw = env.OMCP_ANOMALY_HISTORY_HEADERS;
+    if (raw) {
+        for (const part of raw.split(",")) {
+            const [k, ...rest] = part.split("=");
+            const key = k?.trim();
+            const value = rest.join("=").trim();
+            if (key && value)
+                headers[key] = value;
+        }
+    }
+    return {
+        url: url || undefined,
+        headers: Object.keys(headers).length > 0 ? headers : undefined,
+        bearerToken: env.OMCP_ANOMALY_HISTORY_TOKEN?.trim() || undefined,
+    };
+}
+/**
+ * In-process buffer + remote-write client. Use one instance per
+ * gateway process; `record()` is called from the anomaly detector;
+ * `flush()` runs on the interval AND on SIGTERM.
+ */
+export class AnomalyHistory {
+    url;
+    headers;
+    bearerToken;
+    flushIntervalMs;
+    maxBufferSize;
+    requestTimeoutMs;
+    fetchImpl;
+    buffer = [];
+    timer;
+    flushing = false;
+    constructor(cfg = {}) {
+        this.url = cfg.url;
+        this.headers = cfg.headers ?? {};
+        this.bearerToken = cfg.bearerToken;
+        this.flushIntervalMs = cfg.flushIntervalMs ?? 10_000;
+        this.maxBufferSize = cfg.maxBufferSize ?? 500;
+        this.requestTimeoutMs = cfg.requestTimeoutMs ?? 5_000;
+        this.fetchImpl = cfg.fetchImpl ?? fetch;
+    }
+    /** Whether the history sink is enabled (URL configured). */
+    isEnabled() {
+        return Boolean(this.url);
+    }
+    /** Begin the flush timer. Idempotent. No-op when sink is disabled. */
+    start() {
+        if (!this.isEnabled())
+            return;
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.flush().catch(() => {
+                /* swallow — flush() already logs */
+            });
+        }, this.flushIntervalMs);
+        // unref so the timer doesn't keep the process alive when the
+        // main loop is otherwise idle.
+        this.timer.unref?.();
+    }
+    /** Stop the flush timer + flush one last time. */
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        if (this.isEnabled())
+            await this.flush().catch(() => undefined);
+    }
+    /** Add one anomaly to the buffer. Silently drops when disabled.
+     *  Triggers a synchronous flush if the buffer crosses maxBufferSize. */
+    async record(entry) {
+        if (!this.isEnabled())
+            return;
+        this.buffer.push(entry);
+        if (this.buffer.length >= this.maxBufferSize) {
+            await this.flush().catch(() => undefined);
+        }
+    }
+    /** Send the current buffer to the remote-write endpoint. Drops the
+     *  buffer on success OR failure — history is best-effort. */
+    async flush() {
+        if (!this.isEnabled() || this.buffer.length === 0 || this.flushing)
+            return;
+        this.flushing = true;
+        const batch = this.buffer.splice(0, this.buffer.length);
+        try {
+            await this.sendBatch(batch);
+        }
+        catch (err) {
+            console.warn("AnomalyHistory: flush dropped %d entries (%s). History is best-effort; check the remote-write endpoint.", batch.length, err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /** Test seam: number of currently-buffered entries. */
+    bufferSize() {
+        return this.buffer.length;
+    }
+    /** Visible-for-test: format the buffer as a JSON payload mirroring
+     *  the Prometheus remote-write metric shape. Real remote-write uses
+     *  Snappy-compressed protobuf — we ship JSON here as a portable
+     *  baseline that any TSDB-receiving collector can ingest via a tiny
+     *  shim. A protobuf+Snappy fast path is a follow-up. */
+    formatBatch(batch) {
+        return {
+            // The schema mirrors prometheus.WriteRequest as a JSON object
+            // so collectors that already know "labels + samples" can ingest
+            // it directly.
+            timeseries: batch.map((r) => ({
+                labels: {
+                    __name__: "omcp_anomaly_score",
+                    service: r.service,
+                    tenant: r.tenant,
+                    method: r.method,
+                    severity: r.severity,
+                    ...(r.signal ? { signal: r.signal } : {}),
+                },
+                samples: [{ value: r.score, timestamp: Date.parse(r.ts) }],
+            })),
+        };
+    }
+    async sendBatch(batch) {
+        if (!this.url)
+            return;
+        const body = JSON.stringify(this.formatBatch(batch));
+        const headers = {
+            "content-type": "application/json",
+            ...this.headers,
+        };
+        if (this.bearerToken)
+            headers["authorization"] = `Bearer ${this.bearerToken}`;
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), this.requestTimeoutMs).unref?.();
+        try {
+            const res = await this.fetchImpl(this.url, {
+                method: "POST",
+                headers,
+                body,
+                signal: ctl.signal,
+            });
+            if (!res.ok) {
+                const snippet = (await res.text().catch(() => "")).slice(0, 200);
+                throw new Error(`remote-write returned ${res.status} ${res.statusText}: ${snippet}`);
+            }
+        }
+        finally {
+            if (typeof t === "object" && t)
+                clearTimeout(t);
+        }
+    }
+}

package/dist/analysis/history.test.d.ts

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

package/dist/analysis/history.test.js

@@ -0,0 +1,141 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { AnomalyHistory, fromEnv } from "./history.js";
+function entry(overrides = {}) {
+    return {
+        ts: "2026-06-06T00:00:00.000Z",
+        service: "payment",
+        tenant: "default",
+        score: 0.87,
+        method: "mad",
+        severity: "warn",
+        ...overrides,
+    };
+}
+function captureFetch(captureBody) {
+    const f = (async (_url, init) => {
+        if (captureBody) {
+            captureBody.body = JSON.parse(init.body);
+            captureBody.headers = init.headers;
+        }
+        return { ok: true, status: 200, statusText: "OK", text: async () => "" };
+    });
+    return f;
+}
+test("fromEnv: missing URL → disabled config", () => {
+    assert.equal(fromEnv({}).url, undefined);
+});
+test("fromEnv: parses URL + headers + token", () => {
+    const cfg = fromEnv({
+        OMCP_ANOMALY_HISTORY_REMOTE_WRITE: "https://tsdb/api/v1/write",
+        OMCP_ANOMALY_HISTORY_HEADERS: "x-scope=tenant-a,x-extra=foo=bar",
+        OMCP_ANOMALY_HISTORY_TOKEN: "secret-token",
+    });
+    assert.equal(cfg.url, "https://tsdb/api/v1/write");
+    assert.deepEqual(cfg.headers, { "x-scope": "tenant-a", "x-extra": "foo=bar" });
+    assert.equal(cfg.bearerToken, "secret-token");
+});
+test("isEnabled: false without url, true with url", () => {
+    assert.equal(new AnomalyHistory({}).isEnabled(), false);
+    assert.equal(new AnomalyHistory({ url: "https://x" }).isEnabled(), true);
+});
+test("record: disabled instance silently drops, buffer stays empty", async () => {
+    const h = new AnomalyHistory({});
+    await h.record(entry());
+    assert.equal(h.bufferSize(), 0);
+});
+test("record + flush: posts the buffer as a remote-write-shaped JSON", async () => {
+    const captured = {};
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: captureFetch(captured),
+    });
+    await h.record(entry({ score: 0.9 }));
+    await h.record(entry({ service: "orders", score: 0.42 }));
+    await h.flush();
+    const body = captured.body;
+    assert.equal(body.timeseries.length, 2);
+    assert.equal(body.timeseries[0].labels.__name__, "omcp_anomaly_score");
+    assert.equal(body.timeseries[0].labels.service, "payment");
+    assert.equal(body.timeseries[0].samples[0].value, 0.9);
+    assert.equal(body.timeseries[1].labels.service, "orders");
+});
+test("flush: bearer token forwarded as Authorization header", async () => {
+    const captured = {};
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        bearerToken: "tok-abc",
+        fetchImpl: captureFetch(captured),
+    });
+    await h.record(entry());
+    await h.flush();
+    assert.equal(captured.headers["authorization"], "Bearer tok-abc");
+});
+test("flush: clears the buffer on success", async () => {
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: captureFetch(),
+    });
+    await h.record(entry());
+    await h.record(entry());
+    assert.equal(h.bufferSize(), 2);
+    await h.flush();
+    assert.equal(h.bufferSize(), 0);
+});
+test("flush: HTTP error logs + drops buffer (does NOT retry)", async () => {
+    const f = (async () => ({
+        ok: false,
+        status: 503,
+        statusText: "Service Unavailable",
+        text: async () => "tsdb overloaded",
+    }));
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: f,
+    });
+    await h.record(entry());
+    await h.flush();
+    // Best-effort policy: buffer cleared even on error.
+    assert.equal(h.bufferSize(), 0);
+});
+test("flush: empty buffer is a no-op (no fetch call)", async () => {
+    let called = 0;
+    const f = (async () => {
+        called++;
+        return { ok: true, status: 200, statusText: "OK", text: async () => "" };
+    });
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: f,
+    });
+    await h.flush();
+    assert.equal(called, 0);
+});
+test("record: synchronous auto-flush triggers when buffer crosses maxBufferSize", async () => {
+    let calls = 0;
+    const f = (async () => {
+        calls++;
+        return { ok: true, status: 200, statusText: "OK", text: async () => "" };
+    });
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: f,
+        maxBufferSize: 3,
+    });
+    await h.record(entry());
+    await h.record(entry());
+    assert.equal(calls, 0);
+    await h.record(entry()); // crosses threshold → auto-flush
+    assert.equal(calls, 1);
+    assert.equal(h.bufferSize(), 0);
+});
+test("formatBatch: omits empty optional signal label", async () => {
+    const h = new AnomalyHistory({ url: "https://x" });
+    const out = h.formatBatch([entry({ signal: "" })]);
+    assert.equal("signal" in out.timeseries[0].labels, false);
+});
+test("formatBatch: includes signal label when set", () => {
+    const h = new AnomalyHistory({ url: "https://x" });
+    const out = h.formatBatch([entry({ signal: "request_latency" })]);
+    assert.equal(out.timeseries[0].labels.signal, "request_latency");
+});

package/dist/audit/log.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Append-only audit log for the management plane.
+ *
+ * Distinct from the enterprise-gate audit (`enterprise/audit/`) which
+ * records every gated MCP tool call. This one records every mutating
+ * `/api/*` request (sources/settings/health-thresholds/connectors)
+ * so an operator can answer "who changed what, when".
+ *
+ * On-disk format is JSONL with one entry per line. Each line includes
+ * `prevHash` and `hash` (SHA-256 over the canonical JSON of the entry
+ * without the hash field itself, plus the previous hash) — a
+ * tamper-evident chain that `scripts/verify-audit.mjs` can walk.
+ *
+ * In-memory mode (no `OMCP_MGMT_AUDIT_FILE`) keeps the last
+ * `inMemoryCap` entries in a ring buffer so the UI's audit tab still
+ * shows something even without persistence configured. This is the
+ * default in the demo / single-user case.
+ */
+import type { AuditSink } from "./sinks/types.js";
+export interface AuditEntry {
+    /** RFC-3339 UTC timestamp. */
+    ts: string;
+    /** Monotonically-increasing per-process sequence number. */
+    seq: number;
+    /** Identity that triggered the change. "anonymous" when auth is off. */
+    actor: {
+        sub: string;
+        name?: string;
+    };
+    /** Tenant the actor belonged to at the time of the action.
+     *  Omitted on pre-E7 entries; readers default to "default". */
+    tenant?: string;
+    /** Logical resource + action, mirrors the RBAC vocabulary. */
+    resource: string;
+    action: string;
+    /** Full request method + path for easy reading in the UI. */
+    method: string;
+    path: string;
+    /** HTTP status code emitted by the gated handler. */
+    status: number;
+    /** Source IP, best-effort (honours X-Forwarded-For when trust-proxy is set). */
+    ip?: string;
+    /** Optional resource identifier extracted from the path (`:name` param). */
+    target?: string;
+    /** Tamper-evident chain. */
+    prevHash: string;
+    hash: string;
+}
+export interface AuditLogConfig {
+    /** Absolute path to a JSONL file. When undefined, the log lives in
+     * memory only. */
+    file?: string;
+    /** How many recent entries to keep in memory regardless of file mode. */
+    inMemoryCap?: number;
+    /** Mirror every chained entry to one or more external sinks
+     * (Splunk/SIEM webhook, S3 archive, ...). The on-disk JSONL chain
+     * stays the authoritative master — sinks are best-effort mirrors
+     * and never block record(). */
+    sinks?: AuditSink[];
+}
+export declare const DEFAULT_IN_MEMORY_CAP = 500;
+export declare class AuditLog {
+    private readonly cap;
+    private readonly file;
+    private readonly sinks;
+    private ring;
+    private lastHash;
+    private seq;
+    private writeQueue;
+    private bootstrapped;
+    constructor(cfg?: AuditLogConfig);
+    /**
+     * If a file is configured, replay it to recover seq + lastHash so a
+     * server restart picks up the chain exactly where it left off.
+     * Safe to call multiple times — bootstraps once and caches.
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Record an event. Returns the canonical entry (with chain fields)
+     * once enqueued; persistence to disk completes asynchronously.
+     */
+    record(input: Omit<AuditEntry, "ts" | "seq" | "prevHash" | "hash">): Promise<AuditEntry>;
+    /** Flush every configured sink. Called from SIGTERM and tests. */
+    flushSinks(): Promise<void>;
+    /** Snapshot of the in-memory ring (most recent last). */
+    list(opts?: {
+        from?: string;
+        to?: string;
+        actor?: string;
+        action?: string;
+        limit?: number;
+        tenant?: string;
+    }): AuditEntry[];
+    /** For verification scripts. */
+    get tipHash(): string;
+    get nextSeq(): number;
+}
+/** Stable hash of an entry-without-hash, against `prevHash` already present. */
+export declare function chainHash(entryWithoutHash: Omit<AuditEntry, "hash">): string;
+/** Walk a JSONL file end-to-end and confirm every entry's hash matches
+ * the chain. Used by the offline verifier CLI. */
+export declare function verifyChain(entries: AuditEntry[]): {
+    ok: true;
+} | {
+    ok: false;
+    brokenAt: number;
+    reason: string;
+};