@thotischner/observability-mcp 1.3.3 → 1.4.0

package/dist/config/loader.test.js

@@ -1,15 +1,15 @@
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { writeFileSync, mkdtempSync, rmSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { substituteEnv } from "./loader.js";
 // We test the helper functions by importing the module fresh with different env vars.
 // Since the config path is resolved at import time, we use dynamic imports.
-const TMP_DIR = join(tmpdir(), "observability-mcp-test-" + Date.now());
+let TMP_DIR;
 describe("config/loader", () => {
     beforeEach(() => {
-        mkdirSync(TMP_DIR, { recursive: true });
+        TMP_DIR = mkdtempSync(join(tmpdir(), "observability-mcp-test-"));
     });
     afterEach(() => {
         rmSync(TMP_DIR, { recursive: true, force: true });

package/dist/connectors/loader.d.ts

@@ -0,0 +1,43 @@
+import type { ObservabilityConnector } from "./interface.js";
+import type { ConnectorFactory, ConnectorManifest } from "../sdk/index.js";
+export interface LoadedConnector {
+    /** Connector type id, e.g. "prometheus". Matches `source.type` in sources.yaml. */
+    name: string;
+    /** Where this connector came from (debug + UI display). */
+    source: "builtin" | "filesystem" | "config";
+    /** Optional metadata for plugins that ship a manifest.json. */
+    manifest?: ConnectorManifest;
+    factory: ConnectorFactory;
+}
+/**
+ * Resolves which connector implementations the server should know about,
+ * applying three sources in order (later overrides earlier):
+ *   1. builtin shim — Prometheus/Loki bundled with the server
+ *   2. filesystem  — every subdir of PLUGINS_DIR with a valid package.json
+ *   3. config-pinned — `plugins:` block in sources.yaml (not yet wired)
+ *
+ * The legacy `connectorFactories` map in registry.ts can be replaced
+ * with this loader's output without changing observable behaviour.
+ */
+export declare class PluginLoader {
+    private connectors;
+    private pluginsDir;
+    private disabled;
+    constructor(opts?: {
+        pluginsDir?: string;
+        disabled?: string[];
+    });
+    load(): Promise<void>;
+    list(): LoadedConnector[];
+    get(name: string): LoadedConnector | undefined;
+    has(name: string): boolean;
+    supportedTypes(): string[];
+    /** Create a fresh instance of a connector. Returns undefined for unknown types. */
+    create(name: string): ObservabilityConnector | undefined;
+    private loadBuiltins;
+    private loadFilesystem;
+    private loadFilesystemPlugin;
+    private register;
+}
+export declare function getPluginLoader(): PluginLoader;
+export declare function setPluginLoader(loader: PluginLoader): void;

package/dist/connectors/loader.js

@@ -0,0 +1,170 @@
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { manifestSchema } from "../sdk/manifest-schema.js";
+import { PrometheusConnector } from "./prometheus.js";
+import { LokiConnector } from "./loki.js";
+import { sanitizeForLog } from "../util/sanitize.js";
+import { instrumentConnector } from "../metrics/instrument-connector.js";
+/**
+ * Resolves which connector implementations the server should know about,
+ * applying three sources in order (later overrides earlier):
+ *   1. builtin shim — Prometheus/Loki bundled with the server
+ *   2. filesystem  — every subdir of PLUGINS_DIR with a valid package.json
+ *   3. config-pinned — `plugins:` block in sources.yaml (not yet wired)
+ *
+ * The legacy `connectorFactories` map in registry.ts can be replaced
+ * with this loader's output without changing observable behaviour.
+ */
+export class PluginLoader {
+    connectors = new Map();
+    pluginsDir;
+    disabled;
+    constructor(opts = {}) {
+        this.pluginsDir = opts.pluginsDir
+            ?? process.env.PLUGINS_DIR
+            ?? "/app/plugins";
+        // Per-plugin disable via env: PLUGINS_DISABLED="prometheus,loki"
+        const envDisabled = (process.env.PLUGINS_DISABLED ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        this.disabled = new Set([...(opts.disabled ?? []), ...envDisabled]);
+    }
+    async load() {
+        this.loadBuiltins();
+        await this.loadFilesystem();
+    }
+    list() {
+        return Array.from(this.connectors.values());
+    }
+    get(name) {
+        return this.connectors.get(name);
+    }
+    has(name) {
+        return this.connectors.has(name);
+    }
+    supportedTypes() {
+        return Array.from(this.connectors.keys());
+    }
+    /** Create a fresh instance of a connector. Returns undefined for unknown types. */
+    create(name) {
+        const entry = this.connectors.get(name);
+        if (!entry)
+            return undefined;
+        const c = entry.factory();
+        if (c instanceof Promise) {
+            // For now connectors are sync-constructed; if a plugin returns a
+            // Promise we await it lazily in the consumer. Document if/when
+            // this becomes a real pattern.
+            throw new Error(`Connector ${name} returned a Promise; async factories not yet wired`);
+        }
+        return instrumentConnector(c);
+    }
+    loadBuiltins() {
+        this.register({
+            name: "prometheus",
+            source: "builtin",
+            factory: () => new PrometheusConnector(),
+        });
+        this.register({
+            name: "loki",
+            source: "builtin",
+            factory: () => new LokiConnector(),
+        });
+    }
+    async loadFilesystem() {
+        const dir = this.pluginsDir;
+        if (!existsSync(dir))
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const pluginRoot = join(dir, entry);
+            try {
+                if (!statSync(pluginRoot).isDirectory())
+                    continue;
+                await this.loadFilesystemPlugin(pluginRoot);
+            }
+            catch (err) {
+                console.warn("Failed to load plugin %s: %s", sanitizeForLog(entry), sanitizeForLog(String(err)));
+            }
+        }
+    }
+    async loadFilesystemPlugin(pluginRoot) {
+        const pkgPath = join(pluginRoot, "package.json");
+        if (!existsSync(pkgPath))
+            return;
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        const marker = pkg.observabilityMcp;
+        if (!marker || marker.kind !== "connector" || !marker.name)
+            return;
+        let manifest;
+        if (marker.manifest) {
+            const manifestPath = resolve(pluginRoot, marker.manifest);
+            if (existsSync(manifestPath)) {
+                const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+                const parsed = manifestSchema.safeParse(raw);
+                if (!parsed.success) {
+                    const issues = parsed.error.issues
+                        .map((i) => `${i.path.join(".")}: ${i.message}`)
+                        .join("; ");
+                    console.warn("Plugin %s has invalid manifest.json — %s; skipping", sanitizeForLog(marker.name), sanitizeForLog(issues));
+                    return;
+                }
+                manifest = parsed.data;
+                if (manifest.name !== marker.name) {
+                    console.warn("Plugin %s package.json marker name does not match manifest.json (%s); skipping", sanitizeForLog(marker.name), sanitizeForLog(manifest.name));
+                    return;
+                }
+            }
+        }
+        const entryFile = pkg.main || "index.js";
+        const entryPath = resolve(pluginRoot, entryFile);
+        if (!existsSync(entryPath)) {
+            console.warn("Plugin %s missing entry file %s", sanitizeForLog(marker.name), sanitizeForLog(entryFile));
+            return;
+        }
+        const mod = await import(pathToFileURL(entryPath).href);
+        const factory = mod.default ?? mod.createConnector;
+        if (typeof factory !== "function") {
+            console.warn("Plugin %s has no default export factory", sanitizeForLog(marker.name));
+            return;
+        }
+        this.register({
+            name: marker.name,
+            source: "filesystem",
+            manifest,
+            factory,
+        });
+        console.log('Connector plugin "%s" loaded from %s', sanitizeForLog(marker.name), sanitizeForLog(pluginRoot));
+    }
+    register(entry) {
+        if (this.disabled.has(entry.name)) {
+            console.log("Connector %s disabled via PLUGINS_DISABLED; skipping", sanitizeForLog(entry.name));
+            return;
+        }
+        // Later sources override earlier ones; current call order is
+        // builtin → filesystem → config-pinned, matching the design doc.
+        this.connectors.set(entry.name, entry);
+    }
+}
+/**
+ * Singleton loader populated at server startup. The registry consults
+ * this for connector creation. Tests may swap in their own instance
+ * with `setPluginLoader`.
+ */
+let activeLoader = null;
+export function getPluginLoader() {
+    if (!activeLoader)
+        activeLoader = new PluginLoader();
+    return activeLoader;
+}
+export function setPluginLoader(loader) {
+    activeLoader = loader;
+}

package/dist/connectors/loki.js

@@ -200,8 +200,9 @@ export class LokiConnector {
         return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
     }
     escapeLogQLRegex(value) {
-        // Escape backticks which would break the LogQL regex delimiter
-        return value.replace(/`/g, "\\`");
+        // Escape backslash first (so we don't double-escape sequences we add),
+        // then the backtick that delimits LogQL regex literals.
+        return value.replace(/\\/g, "\\\\").replace(/`/g, "\\`");
     }
     buildAuthHeaders() {
         if (!this.auth || this.auth.type === "none")

package/dist/connectors/registry.d.ts

@@ -1,9 +1,12 @@
 import type { ObservabilityConnector } from "./interface.js";
 import type { Config, ConnectorHealth, SignalType, SourceConfig } from "../types.js";
+import { type PluginLoader } from "./loader.js";
 export declare function getSupportedTypes(): string[];
 export declare class ConnectorRegistry {
     private connectors;
     private sourceConfigs;
+    private loader;
+    constructor(loader?: PluginLoader);
     initialize(config: Config): Promise<void>;
     private connectSource;
     addSource(source: SourceConfig): Promise<void>;

package/dist/connectors/registry.js

@@ -1,15 +1,15 @@
-import { PrometheusConnector } from "./prometheus.js";
-import { LokiConnector } from "./loki.js";
-const connectorFactories = {
-    prometheus: () => new PrometheusConnector(),
-    loki: () => new LokiConnector(),
-};
+import { getPluginLoader } from "./loader.js";
+import { sanitizeForLog } from "../util/sanitize.js";
 export function getSupportedTypes() {
-    return Object.keys(connectorFactories);
+    return getPluginLoader().supportedTypes();
 }
 export class ConnectorRegistry {
     connectors = new Map();
     sourceConfigs = new Map();
+    loader;
+    constructor(loader = getPluginLoader()) {
+        this.loader = loader;
+    }
     async initialize(config) {
         for (const source of config.sources) {
             this.sourceConfigs.set(source.name, source);
@@ -19,19 +19,20 @@ export class ConnectorRegistry {
         }
     }
     async connectSource(source) {
-        const factory = connectorFactories[source.type];
-        if (!factory) {
-            console.warn(`Unknown connector type: ${source.type}, skipping ${source.name}`);
+        const connector = this.loader.create(source.type);
+        const safeName = sanitizeForLog(source.name);
+        const safeType = sanitizeForLog(source.type);
+        if (!connector) {
+            console.warn("Unknown connector type: %s, skipping %s", safeType, safeName);
             return;
         }
-        const connector = factory();
         try {
             await connector.connect(source);
             this.connectors.set(source.name, connector);
-            console.log(`Connector "${source.name}" (${source.type}) connected`);
+            console.log('Connector "%s" (%s) connected', safeName, safeType);
         }
         catch (err) {
-            console.error(`Failed to connect "${source.name}":`, err);
+            console.error('Failed to connect "%s":', safeName, err);
         }
     }
     async addSource(source) {
@@ -53,11 +54,10 @@ export class ConnectorRegistry {
         await this.addSource(source);
     }
     async testConnection(source) {
-        const factory = connectorFactories[source.type];
-        if (!factory) {
+        const connector = this.loader.create(source.type);
+        if (!connector) {
             return { status: "down", latencyMs: 0, message: `Unknown type: ${source.type}` };
         }
-        const connector = factory();
         try {
             await connector.connect(source);
             const health = await connector.healthCheck();

package/dist/connectors/tls.test.js

@@ -1,11 +1,11 @@
 import { describe, it, before, after } from "node:test";
 import assert from "node:assert/strict";
 import { Agent } from "node:https";
-import { writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { writeFileSync, mkdtempSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { buildTlsAgent } from "./tls.js";
-const TMP_DIR = join(tmpdir(), "tls-test-" + Date.now());
+let TMP_DIR;
 function makeConfig(overrides = {}) {
     return { name: "test", type: "prometheus", url: "https://localhost:9090", enabled: true, ...overrides };
 }
@@ -38,7 +38,7 @@ describe("buildTlsAgent", () => {
     });
     describe("with certificate files", () => {
         before(() => {
-            mkdirSync(TMP_DIR, { recursive: true });
+            TMP_DIR = mkdtempSync(join(tmpdir(), "tls-test-"));
             writeFileSync(join(TMP_DIR, "ca.pem"), "-----BEGIN CERTIFICATE-----\nfake-ca\n-----END CERTIFICATE-----\n");
             writeFileSync(join(TMP_DIR, "client.pem"), "-----BEGIN CERTIFICATE-----\nfake-client\n-----END CERTIFICATE-----\n");
             writeFileSync(join(TMP_DIR, "client-key.pem"), "-----BEGIN PRIVATE KEY-----\nfake-key\n-----END PRIVATE KEY-----\n");

package/dist/index.js

@@ -6,6 +6,9 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 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 { 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 +17,19 @@ 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";
 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);
 }
@@ -54,6 +69,7 @@ function validateSourceUrl(url) {
 }
 async function main() {
     let config = loadConfig();
+    await getPluginLoader().load();
     const registry = new ConnectorRegistry();
     await registry.initialize(config);
     applyConfigToRuntime(config, registry);
@@ -64,11 +80,11 @@ 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 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)));
         const metricsList = getAvailableMetricNames(registry);
         const metricNames = registry.getBySignal("metrics").flatMap(c => c.getMetrics().map(m => m.name));
         const uniqueNames = [...new Set(metricNames)];
@@ -78,22 +94,22 @@ async function main() {
             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));
+        }, 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) => queryLogsHandler(registry, args));
+        }, 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) => getServiceHealthHandler(registry, args));
+        }, 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) => detectAnomaliesHandler(registry, args));
+        }, async (args) => withToolMetrics("detect_anomalies", () => detectAnomaliesHandler(registry, args)));
         return mcpServer;
     }
     // --- HTTP server ---
@@ -107,6 +123,45 @@ async function main() {
         res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
         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 +190,31 @@ 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,
+            })),
+        });
+    });
     // Add a new source
     app.post("/api/sources", async (req, res) => {
         const { name, type, url, enabled, auth, tls } = req.body;
@@ -366,6 +446,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 +466,7 @@ async function main() {
                         break;
                     }
                 }
+                mcpActiveSessions.set(transports.size);
             };
             const sessionMcpServer = createMcpServer();
             await sessionMcpServer.connect(transport);
@@ -397,6 +479,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 +504,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();
+    }
+}