@thotischner/observability-mcp 1.4.0 → 1.4.1

package/dist/connectors/verify.d.ts

@@ -0,0 +1,19 @@
+import { type KeyObject } from "node:crypto";
+export declare class PluginVerificationError extends Error {
+}
+/** Parse a PEM public key into a KeyObject. Throws PluginVerificationError. */
+export declare function loadTrustRoot(pemPath: string): KeyObject;
+/** "sha256-<base64>" digest of a buffer, matching the manifest `integrity` form. */
+export declare function sha256Integrity(data: Buffer): string;
+/**
+ * Constant-time-ish compare of the entry file against the manifest's
+ * declared integrity digest. Throws on mismatch.
+ */
+export declare function verifyIntegrity(entryPath: string, integrity: string | undefined): void;
+/**
+ * Verify a detached signature over the raw manifest bytes against the
+ * trust root. Signature is read as base64 (whitespace tolerated, e.g. a
+ * `manifest.json.sig` produced by `openssl dgst -sign ... | base64`).
+ * Throws PluginVerificationError if the signature does not verify.
+ */
+export declare function verifyManifestSignature(manifestBytes: Buffer, signatureBytes: Buffer, trustRoot: KeyObject): void;

package/dist/connectors/verify.js

@@ -0,0 +1,87 @@
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { readFileSync } from "node:fs";
+// Airgapped-friendly plugin verification.
+//
+// No network, no external binary (no cosign): a plugin is trusted when
+//   1. its entry file hashes to the manifest's `integrity` digest, and
+//   2. the manifest bytes carry a detached signature that verifies
+//      against a locally-configured trust-root public key.
+//
+// Ed25519 and RSA/EC (PKCS#8 / SPKI PEM) trust roots are supported.
+export class PluginVerificationError extends Error {
+}
+/** Parse a PEM public key into a KeyObject. Throws PluginVerificationError. */
+export function loadTrustRoot(pemPath) {
+    let pem;
+    try {
+        pem = readFileSync(pemPath, "utf8");
+    }
+    catch (err) {
+        throw new PluginVerificationError(`trust root unreadable at ${pemPath}: ${String(err)}`);
+    }
+    try {
+        return createPublicKey(pem);
+    }
+    catch (err) {
+        throw new PluginVerificationError(`trust root is not a valid PEM public key: ${String(err)}`);
+    }
+}
+/** "sha256-<base64>" digest of a buffer, matching the manifest `integrity` form. */
+export function sha256Integrity(data) {
+    return "sha256-" + createHash("sha256").update(data).digest("base64");
+}
+/**
+ * Constant-time-ish compare of the entry file against the manifest's
+ * declared integrity digest. Throws on mismatch.
+ */
+export function verifyIntegrity(entryPath, integrity) {
+    if (!integrity) {
+        throw new PluginVerificationError("manifest has no integrity digest");
+    }
+    let bytes;
+    try {
+        bytes = readFileSync(entryPath);
+    }
+    catch (err) {
+        throw new PluginVerificationError(`entry file unreadable: ${String(err)}`);
+    }
+    const actual = sha256Integrity(bytes);
+    if (actual.length !== integrity.length || actual !== integrity) {
+        throw new PluginVerificationError(`entry file integrity mismatch (manifest=${integrity} actual=${actual})`);
+    }
+}
+/**
+ * Verify a detached signature over the raw manifest bytes against the
+ * trust root. Signature is read as base64 (whitespace tolerated, e.g. a
+ * `manifest.json.sig` produced by `openssl dgst -sign ... | base64`).
+ * Throws PluginVerificationError if the signature does not verify.
+ */
+export function verifyManifestSignature(manifestBytes, signatureBytes, trustRoot) {
+    const sig = decodeSignature(signatureBytes);
+    // Ed25519/Ed448 take algorithm=null; RSA/EC sign over a SHA-256 digest.
+    const keyType = trustRoot.asymmetricKeyType;
+    const algorithm = keyType === "ed25519" || keyType === "ed448" ? null : "sha256";
+    let ok = false;
+    try {
+        ok = cryptoVerify(algorithm, manifestBytes, trustRoot, sig);
+    }
+    catch (err) {
+        throw new PluginVerificationError(`signature verification errored: ${String(err)}`);
+    }
+    if (!ok) {
+        throw new PluginVerificationError("manifest signature does not match trust root");
+    }
+}
+// Accept either raw DER bytes or a base64/armored .sig file.
+function decodeSignature(raw) {
+    const text = raw.toString("utf8").trim();
+    if (/^[A-Za-z0-9+/\s=]+$/.test(text) && text.length > 0) {
+        const compact = text.replace(/\s+/g, "");
+        const b = Buffer.from(compact, "base64");
+        // Round-trip check: if it re-encodes cleanly it was really base64.
+        if (b.length > 0 && b.toString("base64").replace(/=+$/, "") === compact.replace(/=+$/, "")) {
+            return b;
+        }
+    }
+    return raw;
+}

package/dist/connectors/verify.test.d.ts

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

package/dist/connectors/verify.test.js

@@ -0,0 +1,63 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPairSync, sign as cryptoSign, createPublicKey } from "node:crypto";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sha256Integrity, verifyIntegrity, verifyManifestSignature, loadTrustRoot, PluginVerificationError, } from "./verify.js";
+function tmp() {
+    return mkdtempSync(join(tmpdir(), "verify-"));
+}
+test("sha256Integrity produces sha256-<base64> and round-trips", () => {
+    const digest = sha256Integrity(Buffer.from("hello"));
+    assert.match(digest, /^sha256-[A-Za-z0-9+/]+=*$/);
+    assert.equal(sha256Integrity(Buffer.from("hello")), digest);
+    assert.notEqual(sha256Integrity(Buffer.from("hellp")), digest);
+});
+test("verifyIntegrity passes on match, throws on mismatch and missing", () => {
+    const dir = tmp();
+    const entry = join(dir, "index.js");
+    writeFileSync(entry, "export default () => ({});\n");
+    const good = sha256Integrity(Buffer.from("export default () => ({});\n"));
+    assert.doesNotThrow(() => verifyIntegrity(entry, good));
+    assert.throws(() => verifyIntegrity(entry, "sha256-AAAA"), PluginVerificationError);
+    assert.throws(() => verifyIntegrity(entry, undefined), PluginVerificationError);
+    assert.throws(() => verifyIntegrity(join(dir, "nope.js"), good), PluginVerificationError);
+});
+test("Ed25519: valid signature verifies, tampered manifest is rejected", () => {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const manifest = Buffer.from('{"name":"prometheus","schemaVersion":1}');
+    const sig = cryptoSign(null, manifest, privateKey);
+    assert.doesNotThrow(() => verifyManifestSignature(manifest, sig, publicKey));
+    // base64-armored signature (the form `openssl ... | base64` emits)
+    const armored = Buffer.from(sig.toString("base64"));
+    assert.doesNotThrow(() => verifyManifestSignature(manifest, armored, publicKey));
+    // tampered bytes
+    assert.throws(() => verifyManifestSignature(Buffer.from('{"name":"evil"}'), sig, publicKey), PluginVerificationError);
+});
+test("RSA trust root path (algorithm=sha256) verifies", () => {
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+    const manifest = Buffer.from('{"name":"loki"}');
+    const sig = cryptoSign("sha256", manifest, privateKey);
+    assert.doesNotThrow(() => verifyManifestSignature(manifest, sig, publicKey));
+});
+test("signature from a different key is rejected", () => {
+    const a = generateKeyPairSync("ed25519");
+    const b = generateKeyPairSync("ed25519");
+    const manifest = Buffer.from("payload");
+    const sig = cryptoSign(null, manifest, a.privateKey);
+    assert.throws(() => verifyManifestSignature(manifest, sig, b.publicKey), PluginVerificationError);
+});
+test("loadTrustRoot parses PEM and rejects garbage", () => {
+    const dir = tmp();
+    const { publicKey } = generateKeyPairSync("ed25519");
+    const pem = publicKey.export({ type: "spki", format: "pem" });
+    const p = join(dir, "trust.pem");
+    writeFileSync(p, pem);
+    const loaded = loadTrustRoot(p);
+    assert.equal(loaded.export({ type: "spki", format: "pem" }), createPublicKey(pem).export({ type: "spki", format: "pem" }));
+    const bad = join(dir, "bad.pem");
+    writeFileSync(bad, "not a key");
+    assert.throws(() => loadTrustRoot(bad), PluginVerificationError);
+    assert.throws(() => loadTrustRoot(join(dir, "missing.pem")), PluginVerificationError);
+});

package/dist/index.js

@@ -3,10 +3,14 @@ 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";
@@ -17,7 +21,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 +72,49 @@ 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();
@@ -83,32 +130,108 @@ async function main() {
             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)));
+        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'."),
+        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", "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"),
+        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", "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"),
+        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 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'"),
+        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;
     }
@@ -116,11 +239,18 @@ async function main() {
     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,6 +345,145 @@ 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) => {
         const { name, type, url, enabled, auth, tls } = req.body;
@@ -432,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();

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>;

package/dist/sdk/manifest-schema.js

@@ -33,4 +33,15 @@ export const manifestSchema = z.object({
         serverVersion: z.string().optional(),
     })
         .optional(),
+    // Subresource-integrity-style digest of the plugin entry file
+    // ("sha256-<base64>"). When the server runs with VERIFY_PLUGINS=true
+    // this MUST be present and match the on-disk entry, and the manifest
+    // itself MUST carry a valid detached signature. Airgapped-friendly:
+    // verification is fully offline against a local trust-root key.
+    integrity: z
+        .string()
+        .regex(/^sha256-[A-Za-z0-9+/]+=*$/, {
+        message: 'integrity must be "sha256-<base64>"',
+    })
+        .optional(),
 });