@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/transport/websocket.js

@@ -0,0 +1,133 @@
+// WebSocket transport for MCP.
+//
+// Implements the @modelcontextprotocol/sdk Transport interface so the
+// existing McpServer can speak JSON-RPC over a single WS connection
+// without duplicating any tool registration code.
+//
+// Wire-format: one JSON-RPC message per WS frame (text). No batching,
+// no framing tricks — the same shape an HTTP POST body carries today.
+//
+// Lifecycle:
+//   - The HTTP upgrade handler authenticates the connection, creates
+//     a WebSocketServerTransport wrapping the accepted socket, then
+//     calls McpServer.connect(transport).
+//   - The transport surfaces incoming messages via onmessage, sends
+//     outgoing messages via ws.send(), and reports closure / errors
+//     through onclose / onerror.
+//   - A heartbeat ping is sent every PING_INTERVAL_MS; if no pong
+//     arrives within PING_TIMEOUT_MS the connection is closed and the
+//     session is reaped (same shape as a normal close).
+import { randomUUID } from "node:crypto";
+export const PING_INTERVAL_MS = 30_000;
+export const PING_TIMEOUT_MS = 90_000;
+/**
+ * Per-WS-connection MCP transport. One instance per accepted socket.
+ */
+export class WebSocketServerTransport {
+    sessionId;
+    onclose;
+    onerror;
+    onmessage;
+    ws;
+    pingTimer;
+    lastPongAt = Date.now();
+    pingIntervalMs;
+    pingTimeoutMs;
+    closed = false;
+    constructor(ws, opts = {}) {
+        this.ws = ws;
+        this.sessionId = opts.sessionId ?? randomUUID();
+        this.pingIntervalMs = opts.pingIntervalMs ?? PING_INTERVAL_MS;
+        this.pingTimeoutMs = opts.pingTimeoutMs ?? PING_TIMEOUT_MS;
+    }
+    async start() {
+        this.ws.on("message", (data, isBinary) => {
+            if (isBinary) {
+                // MCP frames are JSON text. A binary frame is a client bug —
+                // report it but keep the socket open: the SDK contract says
+                // errors are non-fatal unless we explicitly close.
+                this.onerror?.(new Error("WebSocket binary frame rejected (MCP expects text JSON)"));
+                return;
+            }
+            let payload;
+            try {
+                payload = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
+            }
+            catch (err) {
+                this.onerror?.(err instanceof Error
+                    ? err
+                    : new Error(`WebSocket frame parse failed: ${String(err)}`));
+                return;
+            }
+            // Batched frame -> dispatch each entry; matches Streamable HTTP semantics.
+            const items = Array.isArray(payload) ? payload : [payload];
+            for (const item of items) {
+                this.onmessage?.(item);
+            }
+        });
+        this.ws.on("pong", () => {
+            this.lastPongAt = Date.now();
+        });
+        this.ws.on("close", () => this.handleClose());
+        this.ws.on("error", (err) => this.onerror?.(err));
+        // Heartbeat: drives close-on-stale via lack of pongs.
+        this.pingTimer = setInterval(() => {
+            if (this.closed)
+                return;
+            const idleMs = Date.now() - this.lastPongAt;
+            if (idleMs > this.pingTimeoutMs) {
+                // 1001 = going away; matches the "stale connection" semantics
+                // some collectors special-case.
+                try {
+                    this.ws.close(1001, "heartbeat timeout");
+                }
+                catch {
+                    /* socket already gone */
+                }
+                return;
+            }
+            try {
+                this.ws.ping();
+            }
+            catch {
+                /* socket already gone */
+            }
+        }, this.pingIntervalMs).unref();
+    }
+    async send(message, _options) {
+        if (this.closed)
+            return;
+        const text = JSON.stringify(message);
+        await new Promise((resolve, reject) => {
+            this.ws.send(text, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.pingTimer)
+            clearInterval(this.pingTimer);
+        try {
+            // 1000 = normal closure.
+            this.ws.close(1000, "server closing");
+        }
+        catch {
+            /* already gone */
+        }
+        this.onclose?.();
+    }
+    handleClose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.pingTimer)
+            clearInterval(this.pingTimer);
+        this.onclose?.();
+    }
+}

package/dist/transport/websocket.test.d.ts

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

package/dist/transport/websocket.test.js

@@ -0,0 +1,124 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { WebSocketServerTransport } from "./websocket.js";
+// Minimal fake ws that satisfies the methods + events
+// WebSocketServerTransport actually touches. Avoids pulling the real
+// `ws` module into the unit-test runner (which is npm install + a TCP
+// socket pair away).
+class FakeWS extends EventEmitter {
+    sent = [];
+    closed;
+    pingCount = 0;
+    send(text, cb) {
+        this.sent.push(text);
+        cb();
+    }
+    close(code, reason) {
+        this.closed = { code, reason };
+        this.emit("close");
+    }
+    ping() {
+        this.pingCount++;
+    }
+}
+function rpc(method, id) {
+    return { jsonrpc: "2.0", id, method };
+}
+test("WebSocketServerTransport: parses one JSON message per text frame", async () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws);
+    const received = [];
+    t.onmessage = (m) => received.push(m);
+    await t.start();
+    ws.emit("message", JSON.stringify(rpc("tools/list", 1)), false);
+    ws.emit("message", JSON.stringify(rpc("tools/call", 2)), false);
+    assert.equal(received.length, 2);
+    assert.equal(received[0].method, "tools/list");
+    assert.equal(received[1].method, "tools/call");
+    await t.close();
+});
+test("WebSocketServerTransport: batched JSON arrays fan out", async () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws);
+    const received = [];
+    t.onmessage = (m) => received.push(m);
+    await t.start();
+    ws.emit("message", JSON.stringify([rpc("a", 1), rpc("b", 2), rpc("c", 3)]), false);
+    assert.equal(received.length, 3);
+    await t.close();
+});
+test("WebSocketServerTransport: malformed JSON surfaces onerror, socket stays open", async () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws);
+    const errs = [];
+    t.onerror = (e) => errs.push(e);
+    await t.start();
+    ws.emit("message", "not-json{", false);
+    assert.equal(errs.length, 1);
+    assert.equal(ws.closed, undefined, "socket must NOT be closed on parse error");
+    await t.close();
+});
+test("WebSocketServerTransport: binary frame rejected with onerror, socket stays open", async () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws);
+    const errs = [];
+    t.onerror = (e) => errs.push(e);
+    await t.start();
+    ws.emit("message", Buffer.from([0x01, 0x02]), true);
+    assert.equal(errs.length, 1);
+    assert.match(errs[0]?.message ?? "", /binary frame/i);
+    assert.equal(ws.closed, undefined);
+    await t.close();
+});
+test("WebSocketServerTransport: send() writes serialized message", async () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws);
+    await t.start();
+    await t.send({ jsonrpc: "2.0", id: 1, result: { ok: true } });
+    assert.equal(ws.sent.length, 1);
+    assert.match(ws.sent[0] ?? "", /"result":\{"ok":true\}/);
+    await t.close();
+});
+test("WebSocketServerTransport: ws-close triggers onclose", async () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws);
+    let closed = false;
+    t.onclose = () => {
+        closed = true;
+    };
+    await t.start();
+    ws.emit("close");
+    assert.equal(closed, true);
+    // Subsequent send must be a no-op (not throw).
+    await t.send({ jsonrpc: "2.0", id: 99, result: {} });
+});
+test("WebSocketServerTransport: heartbeat pings the socket on its interval", async () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws, { pingIntervalMs: 20, pingTimeoutMs: 10_000 });
+    await t.start();
+    await new Promise((r) => setTimeout(r, 65));
+    assert.ok(ws.pingCount >= 2, `expected >=2 pings, got ${ws.pingCount}`);
+    await t.close();
+});
+test("WebSocketServerTransport: stale connection (no pong) gets closed with 1001", async () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws, { pingIntervalMs: 10, pingTimeoutMs: 25 });
+    await t.start();
+    await new Promise((r) => setTimeout(r, 60));
+    assert.equal(ws.closed?.code, 1001);
+    assert.match(ws.closed?.reason ?? "", /heartbeat/);
+});
+test("WebSocketServerTransport: generates a sessionId by default", () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws);
+    assert.ok(t.sessionId, "sessionId must be set");
+    assert.match(t.sessionId, /^[0-9a-f-]{36}$/);
+});
+test("WebSocketServerTransport: sessionId override is honored", () => {
+    const ws = new FakeWS();
+    const t = new WebSocketServerTransport(ws, {
+        sessionId: "test-session",
+    });
+    assert.equal(t.sessionId, "test-session");
+});

package/dist/types.d.ts

@@ -31,6 +31,12 @@ export interface SourceConfig {
     /** @deprecated Use tls.skipVerify instead */
     tlsSkipVerify?: boolean;
     metrics?: MetricDefinition[];
+    /** Tenant this source belongs to. When set, only requests in that
+     *  tenant see / can target the source — cross-tenant access returns
+     *  the same not-found posture as the rest of the tenancy layer.
+     *  Unset = global source, available to every tenant (preserves
+     *  pre-E7 single-tenant behaviour as the default). */
+    tenant?: string;
 }
 export interface GeneralSettings {
     checkIntervalMs: number;
@@ -151,6 +157,51 @@ export interface LogResult {
     entries: LogEntry[];
     summary: LogSummary;
 }
+export interface TraceQuery {
+    /** Service name to filter by — required. */
+    service: string;
+    /** Rolling time window, same shape as MetricQuery.duration ("5m", "1h", "24h"). */
+    duration: string;
+    /** Free-form filter pattern interpreted by the backend (TraceQL,
+     *  Jaeger tag query, etc.). Optional. */
+    filter?: string;
+    /** Soft cap on the number of trace summaries returned. Default 50. */
+    limit?: number;
+    /** Only return spans tagged as errors (`status: error` / span status 2). */
+    errorsOnly?: boolean;
+}
+export interface TraceSpanSummary {
+    /** Stable trace id (hex). */
+    traceId: string;
+    /** Root or first span name. */
+    rootName: string;
+    /** Service that emitted the root span. */
+    rootService: string;
+    /** Total trace duration in milliseconds. */
+    durationMs: number;
+    /** Span count. */
+    spanCount: number;
+    /** Whether any span in this trace has an error status. */
+    hasError: boolean;
+    /** Span start timestamp (RFC-3339). */
+    startTs: string;
+    /** Optional backend-specific link to the trace view. */
+    url?: string;
+}
+export interface TraceSummary {
+    total: number;
+    errorCount: number;
+    /** Median trace duration (ms) across the returned set. */
+    p50DurationMs: number;
+    /** 95th-percentile trace duration (ms). */
+    p95DurationMs: number;
+}
+export interface TraceResult {
+    source: string;
+    service: string;
+    traces: TraceSpanSummary[];
+    summary: TraceSummary;
+}
 /**
  * A discrete infrastructure entity discovered by a topology-aware connector.
  *