@thotischner/observability-mcp 1.4.0 → 1.5.1

package/dist/index.js

@@ -1,12 +1,19 @@
 #!/usr/bin/env node
 import express from "express";
+import rateLimit from "express-rate-limit";
 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 { defaultContext, principalContext } from "./context.js";
+import { loadCredentials, credentialsConfigured, extractToken, resolveToken, } from "./auth/credentials.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";
@@ -17,7 +24,8 @@ 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 } from "node:fs";
+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`.
@@ -67,7 +75,32 @@ 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;
+// Per-client rate limiter for the expensive runtime routes (connector
+// install/upload: fetch + extract + verify + fs write + loader rescan;
+// add/test source: outbound backend connect). Uses express-rate-limit
+// so the control is explicit and well-tested. Bounds abuse even with
+// ENABLE_UI_INSTALL on.
+const installRateLimit = rateLimit({
+    windowMs: 60_000,
+    limit: 5,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: "rate limit exceeded — too many attempts, slow down" },
+});
 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();
@@ -77,50 +110,133 @@ async function main() {
     // so we cannot share a single McpServer across HTTP sessions. Each new
     // session needs its own server. The factory captures the live registry
     // by reference so tool handlers always see the current configuration.
-    function createMcpServer() {
+    function createMcpServer(ctx) {
         const mcpServer = new McpServer({
             name: "observability-mcp",
             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 () => withToolMetrics("list_sources", () => 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) => withToolMetrics("list_services", () => 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, ctx)));
+        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, ctx)));
         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) => withToolMetrics("query_metrics", () => 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) => withToolMetrics("query_logs", () => 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) => withToolMetrics("get_service_health", () => 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) => withToolMetrics("detect_anomalies", () => 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, ctx)));
+        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, ctx)));
+        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, ctx)));
+        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, ctx)));
         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
@@ -215,8 +331,147 @@ async function main() {
             })),
         });
     });
+    // 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) => {
+    app.post("/api/sources", installRateLimit, async (req, res) => {
         const { name, type, url, enabled, auth, tls } = req.body;
         if (!name || !type || !url) {
             res.status(400).json({ error: "name, type, and url are required" });
@@ -279,7 +534,7 @@ async function main() {
         res.json({ ok: true });
     });
     // Test a source connection (without saving)
-    app.post("/api/sources/test", async (req, res) => {
+    app.post("/api/sources/test", installRateLimit, async (req, res) => {
         const { name, type, url, enabled, auth, tls } = req.body;
         if (!type || !url) {
             res.status(400).json({ error: "type and url are required" });
@@ -325,7 +580,7 @@ async function main() {
     // List discovered services
     app.get("/api/services", async (_req, res) => {
         try {
-            const result = await listServicesHandler(registry, {});
+            const result = await listServicesHandler(registry, {}, defaultContext());
             res.json(parseToolResult(result));
         }
         catch {
@@ -335,7 +590,7 @@ async function main() {
     // Health endpoint for UI dashboard
     app.get("/api/health/:service", async (req, res) => {
         try {
-            const result = await getServiceHealthHandler(registry, { service: req.params.service });
+            const result = await getServiceHealthHandler(registry, { service: req.params.service }, defaultContext());
             res.json(parseToolResult(result));
         }
         catch {
@@ -345,13 +600,13 @@ async function main() {
     // Health for all services
     app.get("/api/health", async (_req, res) => {
         try {
-            const servicesResult = await listServicesHandler(registry, {});
+            const servicesResult = await listServicesHandler(registry, {}, defaultContext());
             const parsed = parseToolResult(servicesResult);
             const services = parsed?.services || [];
             const health = {};
             for (const svc of services) {
                 try {
-                    const result = await getServiceHealthHandler(registry, { service: svc.name });
+                    const result = await getServiceHealthHandler(registry, { service: svc.name }, defaultContext());
                     health[svc.name] = parseToolResult(result);
                 }
                 catch {
@@ -432,6 +687,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(defaultContext());
+        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();
@@ -448,7 +713,26 @@ async function main() {
         }
         mcpActiveSessions.set(transports.size);
     }, 5 * 60 * 1000);
+    // Single-tenant auth gate. No credentials configured → anonymous (current
+    // behaviour, fully backward compatible). Configured → require a valid
+    // Bearer/X-API-Key on every /mcp request; resolve the principal + its
+    // coarse source allow-list into the RequestContext.
+    function gateCtx(req, res) {
+        if (!credentialsConfigured())
+            return defaultContext();
+        const cred = resolveToken(extractToken(req.headers), loadCredentials());
+        if (!cred) {
+            res
+                .status(401)
+                .json({ error: "unauthorized: valid Bearer token or X-API-Key required" });
+            return null;
+        }
+        return principalContext(cred.name, cred.allowedSources);
+    }
     app.post("/mcp", async (req, res) => {
+        const ctx = gateCtx(req, res);
+        if (!ctx)
+            return;
         const sessionId = req.headers["mcp-session-id"];
         let transport;
         if (sessionId && transports.has(sessionId)) {
@@ -468,7 +752,7 @@ async function main() {
                 }
                 mcpActiveSessions.set(transports.size);
             };
-            const sessionMcpServer = createMcpServer();
+            const sessionMcpServer = createMcpServer(ctx);
             await sessionMcpServer.connect(transport);
         }
         await transport.handleRequest(req, res, req.body);
@@ -482,6 +766,8 @@ async function main() {
         mcpActiveSessions.set(transports.size);
     });
     app.get("/mcp", async (req, res) => {
+        if (!gateCtx(req, res))
+            return;
         const sessionId = req.headers["mcp-session-id"];
         const transport = transports.get(sessionId);
         if (!transport) {
@@ -491,6 +777,8 @@ async function main() {
         await transport.handleRequest(req, res);
     });
     app.delete("/mcp", async (req, res) => {
+        if (!gateCtx(req, res))
+            return;
         const sessionId = req.headers["mcp-session-id"];
         const transport = transports.get(sessionId);
         if (transport) {

package/dist/net/egress-policy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Verifiable offline mode — egress policy.
+ *
+ * The server performs **no telemetry, analytics, phone-home, or update
+ * checks**. The only outbound network calls it ever makes are to backends
+ * the operator explicitly configures (Prometheus/Loki/... source URLs) or to
+ * an artifact URL the operator/registry explicitly asks it to install.
+ *
+ * This module is the machine-checkable statement of that guarantee:
+ * `egress-policy.test.ts` fails CI if any source file outside the allowlist
+ * introduces an outbound call — so the "no data egress" property cannot
+ * silently regress.
+ */
+export declare const OFFLINE_STATEMENT: string;
+/** Regex of outbound-call shapes the guard scans for. */
+export declare const OUTBOUND_PATTERN: RegExp;
+/**
+ * Files/prefixes permitted to make outbound calls, each with the reason.
+ * Anything matching OUTBOUND_PATTERN outside these paths is a policy breach
+ * (e.g. a newly added analytics/telemetry module).
+ */
+export declare const EGRESS_ALLOWLIST: ReadonlyArray<{
+    prefix: string;
+    reason: string;
+}>;
+/**
+ * Hard-blocked analytics/telemetry SDKs — matches an *import/require of the
+ * package*, not the word in prose, so comments/policy text don't false-positive.
+ */
+export declare const FORBIDDEN_TELEMETRY: RegExp;
+export declare function isEgressAllowed(relPath: string): boolean;

package/dist/net/egress-policy.js

@@ -0,0 +1,37 @@
+/**
+ * Verifiable offline mode — egress policy.
+ *
+ * The server performs **no telemetry, analytics, phone-home, or update
+ * checks**. The only outbound network calls it ever makes are to backends
+ * the operator explicitly configures (Prometheus/Loki/... source URLs) or to
+ * an artifact URL the operator/registry explicitly asks it to install.
+ *
+ * This module is the machine-checkable statement of that guarantee:
+ * `egress-policy.test.ts` fails CI if any source file outside the allowlist
+ * introduces an outbound call — so the "no data egress" property cannot
+ * silently regress.
+ */
+export const OFFLINE_STATEMENT = "observability-mcp makes no telemetry/analytics/phone-home/update calls. " +
+    "Outbound traffic goes only to operator-configured source backends and " +
+    "operator/registry-requested plugin artifacts. It runs fully air-gapped.";
+/** Regex of outbound-call shapes the guard scans for. */
+export const OUTBOUND_PATTERN = /\b(fetch\s*\(|https?\.request\s*\(|new\s+WebSocket\s*\(|import\s*\(\s*['"]https?:)/;
+/**
+ * Files/prefixes permitted to make outbound calls, each with the reason.
+ * Anything matching OUTBOUND_PATTERN outside these paths is a policy breach
+ * (e.g. a newly added analytics/telemetry module).
+ */
+export const EGRESS_ALLOWLIST = [
+    { prefix: "connectors/", reason: "connectors query operator-configured source backends" },
+    { prefix: "cli/index.ts", reason: "CLI fetches a source location the operator passed explicitly" },
+    { prefix: "index.ts", reason: "connector-hub plugin install of an operator/registry-requested tarball URL" },
+];
+/**
+ * Hard-blocked analytics/telemetry SDKs — matches an *import/require of the
+ * package*, not the word in prose, so comments/policy text don't false-positive.
+ */
+export const FORBIDDEN_TELEMETRY = /(?:from\s*['"]|require\(\s*['"])[^'"]*(sentry|posthog|mixpanel|amplitude|@segment|datadog-rum|analytics-node|google-analytics)/i;
+export function isEgressAllowed(relPath) {
+    const p = relPath.replace(/\\/g, "/");
+    return EGRESS_ALLOWLIST.some((a) => p === a.prefix || p.startsWith(a.prefix));
+}

package/dist/net/egress-policy.test.d.ts

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

package/dist/net/egress-policy.test.js

@@ -0,0 +1,52 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, relative } from "node:path";
+import { OUTBOUND_PATTERN, FORBIDDEN_TELEMETRY, isEgressAllowed, EGRESS_ALLOWLIST, } from "./egress-policy.js";
+// Verifiable offline mode: static guard so the "no data egress" guarantee
+// cannot silently regress. Any new outbound call outside the documented
+// allowlist, or any analytics/telemetry SDK anywhere, fails CI here.
+const srcRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+function walk(dir) {
+    const out = [];
+    for (const e of readdirSync(dir)) {
+        const p = join(dir, e);
+        if (statSync(p).isDirectory())
+            out.push(...walk(p));
+        else if (e.endsWith(".ts") && !e.endsWith(".test.ts"))
+            out.push(p);
+    }
+    return out;
+}
+describe("verifiable offline mode — egress policy", () => {
+    const files = walk(srcRoot)
+        .map((f) => ({
+        rel: relative(srcRoot, f).replace(/\\/g, "/"),
+        src: readFileSync(f, "utf8"),
+    }))
+        // The policy module itself names these tokens by design.
+        .filter((f) => f.rel !== "net/egress-policy.ts");
+    it("scans a non-trivial number of source files", () => {
+        assert.ok(files.length > 20, `only scanned ${files.length} files`);
+    });
+    it("no outbound call outside the egress allowlist", () => {
+        const breaches = files
+            .filter((f) => OUTBOUND_PATTERN.test(f.src) && !isEgressAllowed(f.rel))
+            .map((f) => f.rel);
+        assert.deepEqual(breaches, [], `outbound calls found outside allowlist (${EGRESS_ALLOWLIST.map((a) => a.prefix).join(", ")}): ` +
+            `${breaches.join(", ")} — telemetry/phone-home is forbidden; if legitimate, extend EGRESS_ALLOWLIST with a reason`);
+    });
+    it("no analytics/telemetry SDK anywhere in source", () => {
+        const hits = files
+            .filter((f) => FORBIDDEN_TELEMETRY.test(f.src))
+            .map((f) => f.rel);
+        assert.deepEqual(hits, [], `forbidden telemetry/analytics identifiers in: ${hits.join(", ")}`);
+    });
+    it("allowlisted files are still present (allowlist not stale)", () => {
+        for (const { prefix } of EGRESS_ALLOWLIST) {
+            const covered = files.some((f) => f.rel === prefix || f.rel.startsWith(prefix));
+            assert.ok(covered, `allowlist entry "${prefix}" matches no source file — prune it`);
+        }
+    });
+});

package/dist/sdk/index.d.ts

@@ -34,6 +34,12 @@ export interface ConnectorManifest {
         /** Semver range of mcp-server versions this connector supports. */
         serverVersion?: string;
     };
+    /**
+     * Subresource-integrity-style digest of the entry file
+     * ("sha256-<base64>"). Required (and signature-checked) when the
+     * server runs with VERIFY_PLUGINS=true. See docs/plugin-architecture.md.
+     */
+    integrity?: string;
 }
 /**
  * The default export shape a connector plugin module must provide.

package/dist/sdk/manifest-schema.d.ts

@@ -23,5 +23,6 @@ export declare const manifestSchema: z.ZodObject<{
     compat: z.ZodOptional<z.ZodObject<{
         serverVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    integrity: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ValidatedConnectorManifest = z.infer<typeof manifestSchema>;