@thotischner/observability-mcp 1.3.4 → 1.4.1

package/dist/index.js

@@ -3,9 +3,16 @@ import express from "express";
 import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { loadConfig, saveConfig, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_SETTINGS } from "./config/loader.js";
 import { ConnectorRegistry, getSupportedTypes } from "./connectors/registry.js";
+import { getPluginLoader } from "./connectors/loader.js";
+import { resolveHubCatalogUrl, describeInstalled, mergeCatalog, fetchHubCatalog, } from "./connectors/hub.js";
+import { isValidConnectorName, installTarball } from "./connectors/install.js";
+import { PluginVerificationError } from "./connectors/verify.js";
+import { selfRegistry, withToolMetrics, apiRequests, mcpActiveSessions } from "./metrics/self.js";
+import { buildOpenApiSpec } from "./openapi.js";
 import { listSourcesHandler } from "./tools/list-sources.js";
 import { listServicesHandler } from "./tools/list-services.js";
 import { queryMetricsHandler } from "./tools/query-metrics.js";
@@ -14,7 +21,20 @@ import { getServiceHealthHandler, setHealthThresholds } from "./tools/get-servic
 import { detectAnomaliesHandler } from "./tools/detect-anomalies.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 const __dirname = dirname(fileURLToPath(import.meta.url));
+// Read once at startup; the file is shipped inside the image so this
+// is the source of truth even when the user runs from `npx`.
+const SERVER_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+})();
 function applyConfigToRuntime(config, registry) {
     setHealthThresholds(config.healthThresholds);
 }
@@ -52,8 +72,51 @@ function validateSourceUrl(url) {
         return `Invalid URL: "${url}"`;
     }
 }
+// Hard cap for a downloaded/uploaded connector tarball (defence against
+// a hostile or accidental huge artifact OOM-ing the server).
+const MAX_CONNECTOR_TGZ_BYTES = 64 * 1024 * 1024;
+// Dependency-free fixed-window per-client rate limiter for the runtime
+// connector install/upload routes (expensive: fetch + extract + verify +
+// fs write + loader rescan). Bounds abuse even with ENABLE_UI_INSTALL on.
+const installRateState = new Map();
+function installRateLimit(req, res, next) {
+    const WINDOW_MS = 60_000;
+    const MAX = 5;
+    const now = Date.now();
+    if (installRateState.size > 5000) {
+        for (const [k, v] of installRateState)
+            if (v.resetAt < now)
+                installRateState.delete(k);
+    }
+    const key = req.ip || "unknown";
+    let s = installRateState.get(key);
+    if (!s || s.resetAt < now) {
+        s = { count: 0, resetAt: now + WINDOW_MS };
+        installRateState.set(key, s);
+    }
+    s.count++;
+    if (s.count > MAX) {
+        res.setHeader("Retry-After", String(Math.ceil((s.resetAt - now) / 1000)));
+        res.status(429).json({
+            error: "rate limit exceeded — too many connector install attempts, slow down",
+        });
+        return;
+    }
+    next();
+}
 async function main() {
+    // Stdio transport mode (MCP catalogs / desktop clients / Glama's
+    // mcp-proxy spawn a stdio MCP server and read JSON-RPC from stdout).
+    // The protocol stream MUST be the only thing on stdout, so route all
+    // console.log to stderr before anything logs.
+    const STDIO = process.argv.includes("--stdio") ||
+        process.env.MCP_TRANSPORT === "stdio" ||
+        !!process.env.MCP_STDIO;
+    if (STDIO) {
+        console.log = (...a) => console.error(...a);
+    }
     let config = loadConfig();
+    await getPluginLoader().load();
     const registry = new ConnectorRegistry();
     await registry.initialize(config);
     applyConfigToRuntime(config, registry);
@@ -64,49 +127,171 @@ async function main() {
     function createMcpServer() {
         const mcpServer = new McpServer({
             name: "observability-mcp",
-            version: "1.3.0",
+            version: SERVER_VERSION,
         });
         // --- Register tools with Zod schemas ---
-        mcpServer.tool("list_sources", "List all configured observability backends and their connection status. Use this to discover what data sources are available.", {}, async () => listSourcesHandler(registry));
-        mcpServer.tool("list_services", "List all monitored services discovered across all connected backends. Returns service names, their data sources, and signal types (metrics/logs).", { filter: z.string().optional().describe("Optional filter to match service names") }, async (args) => listServicesHandler(registry, args));
+        mcpServer.tool("list_sources", [
+            "List the configured observability backends (Prometheus, Loki, and any connector) and whether each is currently reachable.",
+            "When to use: call this first to learn which source names exist and are healthy before passing `source` to other tools, or to debug why a query returns no data.",
+            "Behavior: read-only, no side effects. Returns one entry per source with its name, type, configured URL, signal types (metrics/logs), and a live up/down status. Never throws for an unreachable backend — the backend is reported as down instead.",
+            "Related: use `list_services` to see what is monitored within these sources.",
+        ].join(" "), {}, async () => withToolMetrics("list_sources", () => listSourcesHandler(registry)));
+        mcpServer.tool("list_services", [
+            "Discover the service names that can be queried, aggregated across every connected backend.",
+            "When to use: call this before `query_metrics`, `query_logs`, or `get_service_health` to obtain the exact, case-sensitive service name those tools require.",
+            "Behavior: read-only, no side effects. Returns one entry per service with the service name, the source(s) it was discovered in, and which signals are available for it (metrics, logs, or both).",
+            "Related: `list_sources` for backend health; `get_service_health` for a per-service overview.",
+        ].join(" "), {
+            filter: z
+                .string()
+                .optional()
+                .describe("Optional case-insensitive substring to narrow the result to matching service names (e.g. 'payment'). Omit to list every discovered service."),
+        }, async (args) => withToolMetrics("list_services", () => listServicesHandler(registry, args)));
         const metricsList = getAvailableMetricNames(registry);
         const metricNames = registry.getBySignal("metrics").flatMap(c => c.getMetrics().map(m => m.name));
         const uniqueNames = [...new Set(metricNames)];
-        mcpServer.tool("query_metrics", `Query a specific metric for a service over a given timeframe. Returns time-series data with pre-computed summary statistics (current, average, min, max, trend). Available metrics: ${metricsList}`, {
-            service: z.string().describe("Service name (e.g. 'api-gateway', 'payment-service')"),
-            metric: z.string().describe(`Metric name. Available: ${uniqueNames.join(", ")}`),
-            duration: z.string().optional().describe("Time range (e.g. '5m', '1h', '24h'). Default: '5m'"),
-            source: z.string().optional().describe("Specific source name. If omitted, queries all metrics backends."),
-            groupBy: z.string().optional().describe("Label to break the result down by, e.g. 'instance', 'pod', 'node'. Returns one series per distinct value in 'groups'."),
-        }, async (args) => queryMetricsHandler(registry, args));
-        mcpServer.tool("query_logs", "Query logs for a service over a given timeframe. Returns log entries with a summary including error/warning counts and top error patterns.", {
-            service: z.string().describe("Service name (e.g. 'payment-service')"),
-            query: z.string().optional().describe("Optional search query to filter log messages (regex supported)"),
-            duration: z.string().optional().describe("Time range (e.g. '5m', '1h', '24h'). Default: '5m'"),
-            level: z.string().optional().describe("Filter by log level: 'error', 'warn', 'info', 'debug'"),
-            limit: z.number().optional().describe("Maximum log entries to return. Default: 100"),
-        }, async (args) => queryLogsHandler(registry, args));
-        mcpServer.tool("get_service_health", "Get an aggregated health overview for a service combining metrics AND logs. Returns health score (0-100), status (healthy/degraded/critical), key metrics, log error summary, anomalies, and cross-signal correlations.", {
-            service: z.string().describe("Service name to check health for"),
-        }, async (args) => getServiceHealthHandler(registry, args));
-        mcpServer.tool("detect_anomalies", "Scan for anomalies across all monitored services (or a specific one). Uses z-score analysis on metrics, checks log error spikes, and correlates signals. Returns anomalies with severity ratings.", {
-            service: z.string().optional().describe("Specific service to scan. If omitted, scans all."),
-            duration: z.string().optional().describe("Time range to analyze (e.g. '5m', '15m', '1h'). Default: '10m'"),
-            sensitivity: z.enum(["low", "medium", "high"]).optional().describe("Detection sensitivity: low (>3σ), medium (>2σ), high (>1.5σ). Default: 'medium'"),
-        }, async (args) => detectAnomaliesHandler(registry, args));
+        mcpServer.tool("query_metrics", [
+            "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.",
+            `Available metrics: ${metricsList}`,
+        ].join(" "), {
+            service: z
+                .string()
+                .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'api-gateway', 'payment-service')."),
+            metric: z
+                .string()
+                .describe(`Required. Exact metric name to query. One of: ${uniqueNames.join(", ")}.`),
+            duration: z
+                .string()
+                .optional()
+                .describe("Optional. Look-back window ending at 'now', written as <number><unit> with unit s|m|h|d (e.g. '5m', '90m', '1h', '24h'). Default: '5m'."),
+            source: z
+                .string()
+                .optional()
+                .describe("Optional. Restrict the query to a single backend by its source name (see `list_sources`). Default: query and merge all metrics backends."),
+            groupBy: z
+                .string()
+                .optional()
+                .describe("Optional. Metric label to break the result down by, e.g. 'instance', 'pod', 'node'. When set, the response contains one series per distinct label value under `groups`. Default: a single aggregated series."),
+        }, async (args) => withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args)));
+        mcpServer.tool("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.",
+            "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(" "), {
+            service: z
+                .string()
+                .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'payment-service')."),
+            query: z
+                .string()
+                .optional()
+                .describe("Optional. Filter expression matched against the log message; regular expressions are supported. Omit to return all entries in the window."),
+            duration: z
+                .string()
+                .optional()
+                .describe("Optional. Look-back window ending at 'now', written as <number><unit> with unit s|m|h|d (e.g. '5m', '1h', '24h'). Default: '5m'."),
+            level: z
+                .enum(["error", "warn", "info", "debug"])
+                .optional()
+                .describe("Optional. Return only entries at this severity. Default: all levels."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Optional. Maximum number of log entries to return (most recent first). Default: 100."),
+        }, async (args) => withToolMetrics("query_logs", () => queryLogsHandler(registry, args)));
+        mcpServer.tool("get_service_health", [
+            "Produce a single aggregated health verdict for ONE service by combining its metrics and logs.",
+            "When to use: the fastest way to answer 'is this service healthy right now and why?'. Use `query_metrics`/`query_logs` to drill into the underlying numbers, or `detect_anomalies` to scan many services at once.",
+            "Prerequisites: get the exact service name from `list_services`.",
+            "Behavior: read-only, no side effects. Returns a weighted health score (0–100), a status of healthy | degraded | critical, the key contributing metrics, a log error summary, detected anomalies, and cross-signal correlations explaining the score. A service with no data yields an explanatory result rather than an exception.",
+        ].join(" "), {
+            service: z
+                .string()
+                .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'payment-service')."),
+        }, async (args) => withToolMetrics("get_service_health", () => getServiceHealthHandler(registry, args)));
+        mcpServer.tool("detect_anomalies", [
+            "Scan one or all monitored services for abnormal behavior and return the findings ranked by severity.",
+            "When to use: the entry point for 'is anything wrong anywhere?' triage. Once a service is flagged, follow up with `get_service_health` for the verdict or `query_metrics`/`query_logs` for the raw evidence.",
+            "Behavior: read-only, no side effects. Applies z-score analysis to metrics, detects log error-rate spikes, and correlates the two. Returns a list of anomalies, each with the affected service, metric/signal, severity, the deviation (e.g. σ and % change), and a short explanation. No anomalies yields an empty list, not an error.",
+            "Related: `get_service_health` (single-service verdict), `query_metrics` (raw series behind a flagged metric).",
+        ].join(" "), {
+            service: z
+                .string()
+                .optional()
+                .describe("Optional. Restrict the scan to one service (exact, case-sensitive name from `list_services`). Default: scan every monitored service."),
+            duration: z
+                .string()
+                .optional()
+                .describe("Optional. Look-back window analyzed for anomalies, written as <number><unit> with unit s|m|h|d (e.g. '5m', '15m', '1h'). Default: '10m'."),
+            sensitivity: z
+                .enum(["low", "medium", "high"])
+                .optional()
+                .describe("Optional. Detection threshold: 'low' flags only strong deviations (>3σ), 'medium' is balanced (>2σ), 'high' is most sensitive and noisier (>1.5σ). Default: 'medium'."),
+        }, async (args) => withToolMetrics("detect_anomalies", () => detectAnomaliesHandler(registry, args)));
         return mcpServer;
     }
     // --- HTTP server ---
     const app = express();
     app.use(express.json({ limit: "1mb" }));
     // Security headers
-    app.use((_req, res, next) => {
+    app.use((req, res, next) => {
         res.setHeader("X-Content-Type-Options", "nosniff");
         res.setHeader("X-Frame-Options", "DENY");
         res.setHeader("X-XSS-Protection", "1; mode=block");
         res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
+        // Dynamic API responses must never be served from the browser/proxy
+        // cache: after a mutation (e.g. installing a connector) the UI
+        // re-fetches these GETs immediately, and a heuristically-cached stale
+        // body would make the change "not show up until a page reload".
+        if (req.path.startsWith("/api/")) {
+            res.setHeader("Cache-Control", "no-store");
+        }
+        next();
+    });
+    // API request counter — emitted at response time so the `status` label
+    // is the real outcome. /metrics itself is excluded to avoid self-scrape
+    // amplification.
+    app.use((req, res, next) => {
+        if (req.path === "/metrics")
+            return next();
+        res.on("finish", () => {
+            // Group dynamic segments by the registered Express route when we
+            // have one, otherwise fall back to the literal path. This keeps
+            // label cardinality bounded.
+            const route = req.route?.path ?? req.path;
+            apiRequests.inc({ route, method: req.method, status: String(res.statusCode) });
+        });
         next();
     });
+    // k8s-convention liveness/readiness probes at the root of the path
+    // tree, no /api prefix. Helm chart points its probes here. Cheap
+    // enough to skip the request-counter middleware.
+    let ready = false;
+    app.get("/healthz", (_req, res) => res.type("text").send("ok"));
+    app.get("/readyz", (_req, res) => {
+        if (ready)
+            return res.type("text").send("ok");
+        return res.status(503).type("text").send("starting");
+    });
+    // OpenAPI 3.1 document for the /api/* surface.
+    app.get("/api/openapi.json", (_req, res) => {
+        res.json(buildOpenApiSpec(SERVER_VERSION));
+    });
+    // Self-monitoring — Prometheus scrape endpoint.
+    // Disabled with METRICS_ENABLED=false for environments that prefer
+    // sidecar agents. The Helm chart's ServiceMonitor template targets
+    // this endpoint when enabled.
+    if (process.env.METRICS_ENABLED !== "false") {
+        app.get("/metrics", async (_req, res) => {
+            res.set("Content-Type", selfRegistry.contentType);
+            res.end(await selfRegistry.metrics());
+        });
+    }
     // Serve Web UI
     app.use(express.static(join(__dirname, "ui")));
     // --- API endpoints for Web UI ---
@@ -135,6 +320,170 @@ async function main() {
     app.get("/api/source-types", (_req, res) => {
         res.json(getSupportedTypes());
     });
+    // Server info — version, loaded plugins, MCP protocol version, build metadata.
+    // Used by the Web UI footer and by operators to confirm what's deployed.
+    app.get("/api/info", async (_req, res) => {
+        const loader = getPluginLoader();
+        res.json({
+            name: "observability-mcp",
+            version: SERVER_VERSION,
+            mcpProtocolVersion: "2025-03-26",
+            build: {
+                commit: process.env.GIT_COMMIT || null,
+                date: process.env.BUILD_DATE || null,
+            },
+            runtime: {
+                node: process.version,
+                platform: process.platform,
+                arch: process.arch,
+            },
+            plugins: loader.list().map((p) => ({
+                name: p.name,
+                source: p.source,
+                version: p.manifest?.version ?? null,
+                signalTypes: p.manifest?.signalTypes ?? null,
+            })),
+        });
+    });
+    // Connectors currently loaded into this server (builtin + filesystem
+    // plugins), with manifest metadata — drives the UI "Connectors" page.
+    app.get("/api/connectors", (_req, res) => {
+        res.json({ connectors: describeInstalled(getPluginLoader().list()) });
+    });
+    // Server-side proxy of the connector hub catalog (so the browser
+    // needn't reach the hub directly — works behind a proxy / against a
+    // mirror via HUB_CATALOG_URL). Installed status merged in.
+    app.get("/api/hub/catalog", async (_req, res) => {
+        const url = resolveHubCatalogUrl();
+        try {
+            const catalog = await fetchHubCatalog(url);
+            res.json({
+                url,
+                connectors: mergeCatalog(catalog, describeInstalled(getPluginLoader().list())),
+            });
+        }
+        catch (e) {
+            res.status(502).json({ url, error: e instanceof Error ? e.message : String(e), connectors: [] });
+        }
+    });
+    // Install a connector from the hub into the running server.
+    //
+    // Runtime code-load is powerful, so this is doubly gated:
+    //   1. ENABLE_UI_INSTALL=true must be set (default OFF).
+    //   2. PLUGIN_TRUST_ROOT must be configured — install is ALWAYS
+    //      fail-closed verified (no insecure bypass over HTTP).
+    // Only catalog tarballUrls are fetched (no arbitrary URL in the body)
+    // to avoid SSRF. The connector persists to PLUGINS_DIR (back it with
+    // a PVC on k8s so it survives restarts).
+    app.post("/api/connectors/install", installRateLimit, async (req, res) => {
+        if (process.env.ENABLE_UI_INSTALL !== "true") {
+            return res.status(403).json({
+                error: "UI install is disabled. Set ENABLE_UI_INSTALL=true and PLUGIN_TRUST_ROOT to enable it.",
+            });
+        }
+        const trustRootPath = process.env.PLUGIN_TRUST_ROOT;
+        if (!trustRootPath) {
+            return res.status(412).json({
+                error: "PLUGIN_TRUST_ROOT not configured — refusing to install unverified code.",
+            });
+        }
+        const name = (req.body || {}).name;
+        const version = (req.body || {}).version;
+        if (!isValidConnectorName(name)) {
+            return res.status(400).json({ error: "invalid connector name" });
+        }
+        const pluginsDir = process.env.PLUGINS_DIR ?? "/app/plugins";
+        let work = null;
+        try {
+            const catalog = await fetchHubCatalog(resolveHubCatalogUrl());
+            const entry = catalog.connectors.find((c) => c.name === name);
+            if (!entry)
+                return res.status(404).json({ error: `'${name}' is not in the catalog` });
+            if (entry.builtin)
+                return res.status(409).json({ error: `'${name}' is builtin — no install needed` });
+            const v = version
+                ? entry.versions.find((x) => x.version === version)
+                : entry.versions.find((x) => x.version === (entry.latest ?? entry.versions[0]?.version)) ?? entry.versions[0];
+            if (!v || !v.tarballUrl) {
+                return res.status(422).json({ error: `no tarball for ${name}@${version ?? "latest"}` });
+            }
+            const resp = await fetch(v.tarballUrl);
+            if (!resp.ok)
+                return res.status(502).json({ error: `tarball download HTTP ${resp.status}` });
+            const declared = Number(resp.headers.get("content-length") || 0);
+            if (declared > MAX_CONNECTOR_TGZ_BYTES) {
+                return res.status(413).json({ error: `tarball too large (${declared} bytes)` });
+            }
+            const buf = Buffer.from(await resp.arrayBuffer());
+            if (buf.length > MAX_CONNECTOR_TGZ_BYTES) {
+                return res.status(413).json({ error: `tarball too large (${buf.length} bytes)` });
+            }
+            work = mkdtempSync(join(tmpdir(), "obsmcp-dl-"));
+            const tgz = join(work, "c.tgz");
+            writeFileSync(tgz, buf);
+            const result = installTarball({ tgzPath: tgz, pluginsDir, trustRootPath, expectedName: name });
+            await getPluginLoader().load(); // re-scan so /api/connectors reflects it
+            res.json({
+                ok: true,
+                ...result,
+                note: "installed & persisted to PLUGINS_DIR. Add a source of this type to use it; a server restart is recommended for full availability in existing MCP sessions.",
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            const code = e instanceof PluginVerificationError ? 400 : 500;
+            res.status(code).json({ error: `install failed (fail-closed): ${msg}` });
+        }
+        finally {
+            if (work)
+                rmSync(work, { recursive: true, force: true });
+        }
+    });
+    // Upload a connector bundle (.tgz) and install it into the running
+    // server. Same fail-closed guardrails as /install: the upload is
+    // ALWAYS verified against PLUGIN_TRUST_ROOT (signature + integrity),
+    // so an unsigned/tampered bundle is rejected. Body is the raw tarball
+    // bytes (application/octet-stream). Persists to PLUGINS_DIR.
+    app.post("/api/connectors/upload", installRateLimit, express.raw({ type: "application/octet-stream", limit: "50mb" }), async (req, res) => {
+        if (process.env.ENABLE_UI_INSTALL !== "true") {
+            return res.status(403).json({
+                error: "UI install is disabled. Set ENABLE_UI_INSTALL=true and PLUGIN_TRUST_ROOT to enable it.",
+            });
+        }
+        const trustRootPath = process.env.PLUGIN_TRUST_ROOT;
+        if (!trustRootPath) {
+            return res.status(412).json({
+                error: "PLUGIN_TRUST_ROOT not configured — refusing to install unverified code.",
+            });
+        }
+        const body = req.body;
+        if (!Buffer.isBuffer(body) || body.length === 0) {
+            return res.status(400).json({ error: "empty body — POST the connector .tgz as application/octet-stream" });
+        }
+        const pluginsDir = process.env.PLUGINS_DIR ?? "/app/plugins";
+        let work = null;
+        try {
+            work = mkdtempSync(join(tmpdir(), "obsmcp-up-"));
+            const tgz = join(work, "c.tgz");
+            writeFileSync(tgz, body);
+            const result = installTarball({ tgzPath: tgz, pluginsDir, trustRootPath });
+            await getPluginLoader().load(); // re-scan so /api/connectors reflects it
+            res.json({
+                ok: true,
+                ...result,
+                note: "uploaded, verified & persisted to PLUGINS_DIR. Add a source of this type to use it; a server restart is recommended for full availability in existing MCP sessions.",
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            const code = e instanceof PluginVerificationError ? 400 : 500;
+            res.status(code).json({ error: `upload install failed (fail-closed): ${msg}` });
+        }
+        finally {
+            if (work)
+                rmSync(work, { recursive: true, force: true });
+        }
+    });
     // Add a new source
     app.post("/api/sources", async (req, res) => {
         const { name, type, url, enabled, auth, tls } = req.body;
@@ -352,6 +701,16 @@ async function main() {
         saveConfig(config);
         res.json({ ok: true });
     });
+    // Stdio transport: one server over stdin/stdout, no HTTP listener.
+    if (STDIO) {
+        const server = createMcpServer();
+        await server.connect(new StdioServerTransport());
+        console.error(`observability-mcp running on stdio transport · connectors: ${registry
+            .getAll()
+            .map((c) => c.name)
+            .join(", ")}`);
+        return;
+    }
     // MCP Streamable HTTP transport — stateful sessions
     const transports = new Map();
     const sessionLastActive = new Map();
@@ -366,6 +725,7 @@ async function main() {
                 console.log(`Session ${sid} expired (idle)`);
             }
         }
+        mcpActiveSessions.set(transports.size);
     }, 5 * 60 * 1000);
     app.post("/mcp", async (req, res) => {
         const sessionId = req.headers["mcp-session-id"];
@@ -385,6 +745,7 @@ async function main() {
                         break;
                     }
                 }
+                mcpActiveSessions.set(transports.size);
             };
             const sessionMcpServer = createMcpServer();
             await sessionMcpServer.connect(transport);
@@ -397,6 +758,7 @@ async function main() {
                 transports.set(sid, transport);
             sessionLastActive.set(sid, Date.now());
         }
+        mcpActiveSessions.set(transports.size);
     });
     app.get("/mcp", async (req, res) => {
         const sessionId = req.headers["mcp-session-id"];
@@ -421,6 +783,7 @@ async function main() {
     });
     const PORT = parseInt(process.env.PORT || "3000");
     app.listen(PORT, () => {
+        ready = true;
         console.log(`observability-mcp server running on port ${PORT}`);
         console.log(`  MCP endpoint: http://localhost:${PORT}/mcp`);
         console.log(`  Web UI: http://localhost:${PORT}`);

package/dist/metrics/instrument-connector.d.ts

@@ -0,0 +1,8 @@
+import type { ObservabilityConnector } from "../connectors/interface.js";
+/**
+ * Decorate a connector so every observable backend call increments
+ * obsmcp_connector_calls_total{source,type,operation,outcome}. The
+ * `source` label is filled in on first `connect()` once the config
+ * is known. Keeps connector implementations free of metrics code.
+ */
+export declare function instrumentConnector<T extends ObservabilityConnector>(c: T): T;

package/dist/metrics/instrument-connector.js

@@ -0,0 +1,41 @@
+import { connectorCalls } from "./self.js";
+const OPS = [
+    "healthCheck",
+    "listServices",
+    "queryMetrics",
+    "queryLogs",
+    "listAvailableMetrics",
+];
+/**
+ * Decorate a connector so every observable backend call increments
+ * obsmcp_connector_calls_total{source,type,operation,outcome}. The
+ * `source` label is filled in on first `connect()` once the config
+ * is known. Keeps connector implementations free of metrics code.
+ */
+export function instrumentConnector(c) {
+    let source = "";
+    const type = c.type;
+    const wrappedConnect = c.connect.bind(c);
+    c.connect = async (config) => {
+        source = config.name;
+        return wrappedConnect(config);
+    };
+    for (const op of OPS) {
+        const fn = c[op];
+        if (typeof fn !== "function")
+            continue;
+        const bound = fn.bind(c);
+        c[op] = async (...args) => {
+            try {
+                const r = await bound(...args);
+                connectorCalls.inc({ source: source || "<pending>", type, operation: op, outcome: "ok" });
+                return r;
+            }
+            catch (err) {
+                connectorCalls.inc({ source: source || "<pending>", type, operation: op, outcome: "error" });
+                throw err;
+            }
+        };
+    }
+    return c;
+}

package/dist/metrics/self.d.ts

@@ -0,0 +1,12 @@
+import { Registry, Counter, Histogram, Gauge } from "prom-client";
+export declare const selfRegistry: Registry<"text/plain; version=0.0.4; charset=utf-8">;
+export declare const mcpToolCalls: Counter<"tool" | "outcome">;
+export declare const mcpToolLatency: Histogram<"tool">;
+export declare const connectorCalls: Counter<"type" | "source" | "outcome" | "operation">;
+export declare const apiRequests: Counter<"status" | "route" | "method">;
+export declare const mcpActiveSessions: Gauge<string>;
+/**
+ * Wrap a (potentially async) tool handler to record call count + latency.
+ * Outcome is "ok" or "error" — never throws on its own.
+ */
+export declare function withToolMetrics<T>(tool: string, fn: () => Promise<T>): Promise<T>;

package/dist/metrics/self.js

@@ -0,0 +1,61 @@
+// Server self-metrics exposed at /metrics for Prometheus scraping.
+// Pairs with the Helm chart's ServiceMonitor template.
+//
+// Default Node metrics (CPU, memory, event loop lag, heap) come from
+// prom-client's collectDefaultMetrics. On top of that we ship four
+// product-specific counters/histograms that operators actually need
+// to graph: MCP tool calls, connector backend calls, /api/* requests,
+// active session count.
+import { Registry, collectDefaultMetrics, Counter, Histogram, Gauge, } from "prom-client";
+export const selfRegistry = new Registry();
+selfRegistry.setDefaultLabels({ service: "observability-mcp" });
+collectDefaultMetrics({ register: selfRegistry, prefix: "obsmcp_" });
+export const mcpToolCalls = new Counter({
+    name: "obsmcp_mcp_tool_calls_total",
+    help: "MCP tool invocations by tool and outcome.",
+    labelNames: ["tool", "outcome"],
+    registers: [selfRegistry],
+});
+export const mcpToolLatency = new Histogram({
+    name: "obsmcp_mcp_tool_duration_seconds",
+    help: "MCP tool invocation latency.",
+    labelNames: ["tool"],
+    buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+    registers: [selfRegistry],
+});
+export const connectorCalls = new Counter({
+    name: "obsmcp_connector_calls_total",
+    help: "Calls to a configured connector, by source and outcome.",
+    labelNames: ["source", "type", "operation", "outcome"],
+    registers: [selfRegistry],
+});
+export const apiRequests = new Counter({
+    name: "obsmcp_api_requests_total",
+    help: "Web UI / API request count, by route and status.",
+    labelNames: ["route", "method", "status"],
+    registers: [selfRegistry],
+});
+export const mcpActiveSessions = new Gauge({
+    name: "obsmcp_mcp_active_sessions",
+    help: "Active MCP Streamable HTTP sessions.",
+    registers: [selfRegistry],
+});
+/**
+ * Wrap a (potentially async) tool handler to record call count + latency.
+ * Outcome is "ok" or "error" — never throws on its own.
+ */
+export async function withToolMetrics(tool, fn) {
+    const end = mcpToolLatency.startTimer({ tool });
+    try {
+        const r = await fn();
+        mcpToolCalls.inc({ tool, outcome: "ok" });
+        return r;
+    }
+    catch (err) {
+        mcpToolCalls.inc({ tool, outcome: "error" });
+        throw err;
+    }
+    finally {
+        end();
+    }
+}

package/dist/openapi.d.ts

@@ -0,0 +1,2 @@
+import type { OpenAPIV3_1 } from "openapi-types";
+export declare function buildOpenApiSpec(version: string): OpenAPIV3_1.Document;