@thotischner/observability-mcp 1.3.4 → 1.4.0

package/dist/openapi.d.ts

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

package/dist/openapi.js

@@ -0,0 +1,186 @@
+// Hand-written OpenAPI 3.1 spec for the /api/* surface served by
+// mcp-server. The /mcp endpoint follows the MCP Streamable HTTP spec
+// (https://spec.modelcontextprotocol.io/) and is intentionally NOT
+// described here; clients should use the MCP `tools/list` to discover
+// the seven tools exposed there.
+//
+// Keep this lean — operators import it into Insomnia/Postman/OpenAPI
+// codegens. If a path is missing it just won't appear in their UI.
+const SOURCE_SCHEMA = {
+    type: "object",
+    required: ["name", "type", "url"],
+    properties: {
+        name: { type: "string", description: "Unique source name." },
+        type: { type: "string", description: "Connector type id, e.g. 'prometheus'." },
+        url: { type: "string", format: "uri" },
+        enabled: { type: "boolean", default: true },
+        auth: {
+            type: "object",
+            properties: {
+                type: { type: "string", enum: ["none", "basic", "bearer"] },
+            },
+            additionalProperties: true,
+        },
+        tls: { type: "object", additionalProperties: true },
+        signalType: { type: "string", enum: ["metrics", "logs", "traces"] },
+    },
+    additionalProperties: true,
+};
+export function buildOpenApiSpec(version) {
+    // openapi-types' deeply-nested generics make literal path objects fail
+    // structural assignability even when the document is valid OpenAPI. We
+    // build it as a permissive object and cast at the boundary — the shape
+    // is hand-verified and rendered by Swagger/Insomnia downstream.
+    const doc = {
+        openapi: "3.1.0",
+        info: {
+            title: "observability-mcp HTTP API",
+            version,
+            description: "Operator-facing REST API used by the Web UI. The MCP protocol surface lives at /mcp (Streamable HTTP) and is not described here — use MCP's tools/list to discover those.",
+            contact: {
+                name: "observability-mcp",
+                url: "https://github.com/ThoTischner/observability-mcp",
+            },
+            license: { name: "MIT" },
+        },
+        servers: [{ url: "/", description: "Current server" }],
+        tags: [
+            { name: "sources", description: "Observability backend configuration." },
+            { name: "services", description: "Service discovery across all backends." },
+            { name: "health", description: "Aggregated health for discovered services." },
+            { name: "settings", description: "Runtime server configuration." },
+            { name: "metrics-config", description: "Per-source metric definitions." },
+            { name: "self", description: "Server liveness and Prometheus metrics." },
+        ],
+        paths: {
+            "/api/sources": {
+                get: {
+                    tags: ["sources"],
+                    summary: "List configured sources with live health.",
+                    responses: {
+                        "200": {
+                            description: "Sources with status, latency, signal type.",
+                            content: { "application/json": { schema: { type: "array", items: SOURCE_SCHEMA } } },
+                        },
+                    },
+                },
+                post: {
+                    tags: ["sources"],
+                    summary: "Add a new source.",
+                    requestBody: { required: true, content: { "application/json": { schema: SOURCE_SCHEMA } } },
+                    responses: {
+                        "201": { description: "Source created." },
+                        "400": { description: "Validation error." },
+                        "409": { description: "Source with that name already exists." },
+                    },
+                },
+            },
+            "/api/sources/test": {
+                post: {
+                    tags: ["sources"],
+                    summary: "Connection check against a source config without persisting it.",
+                    requestBody: { required: true, content: { "application/json": { schema: SOURCE_SCHEMA } } },
+                    responses: {
+                        "200": {
+                            description: "Reachability report.",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            status: { type: "string", enum: ["up", "down"] },
+                                            latencyMs: { type: "number" },
+                                            message: { type: "string", nullable: true },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            "/api/sources/{name}": {
+                parameters: [{ name: "name", in: "path", required: true, schema: { type: "string" } }],
+                put: {
+                    tags: ["sources"],
+                    summary: "Replace an existing source.",
+                    requestBody: { required: true, content: { "application/json": { schema: SOURCE_SCHEMA } } },
+                    responses: { "200": { description: "Updated." }, "404": { description: "Not found." } },
+                },
+                delete: {
+                    tags: ["sources"],
+                    summary: "Remove a source.",
+                    responses: { "204": { description: "Removed." }, "404": { description: "Not found." } },
+                },
+            },
+            "/api/source-types": {
+                get: {
+                    tags: ["sources"],
+                    summary: "List connector type ids the server can load (builtin + filesystem plugins).",
+                    responses: {
+                        "200": {
+                            description: "Connector type ids.",
+                            content: { "application/json": { schema: { type: "array", items: { type: "string" } } } },
+                        },
+                    },
+                },
+            },
+            "/api/services": {
+                get: {
+                    tags: ["services"],
+                    summary: "List services discovered across all connected backends.",
+                    responses: { "200": { description: "Services." } },
+                },
+            },
+            "/api/health": {
+                get: {
+                    tags: ["health"],
+                    summary: "Aggregated health map: { [service]: ServiceHealth }.",
+                    responses: { "200": { description: "Health map." } },
+                },
+            },
+            "/api/health/{service}": {
+                parameters: [{ name: "service", in: "path", required: true, schema: { type: "string" } }],
+                get: {
+                    tags: ["health"],
+                    summary: "Aggregated health for one service.",
+                    responses: { "200": { description: "ServiceHealth." }, "404": { description: "Not found." } },
+                },
+            },
+            "/api/settings": {
+                get: { tags: ["settings"], summary: "Get runtime settings.", responses: { "200": { description: "Settings." } } },
+                put: { tags: ["settings"], summary: "Update runtime settings.", responses: { "200": { description: "Updated." } } },
+            },
+            "/api/health-thresholds": {
+                get: { tags: ["settings"], summary: "Get health-score thresholds.", responses: { "200": { description: "Thresholds." } } },
+                put: { tags: ["settings"], summary: "Update health-score thresholds.", responses: { "200": { description: "Updated." } } },
+            },
+            "/api/sources/{name}/metrics": {
+                parameters: [{ name: "name", in: "path", required: true, schema: { type: "string" } }],
+                get: { tags: ["metrics-config"], summary: "Get the active metrics list for this source.", responses: { "200": { description: "Metrics." } } },
+                put: { tags: ["metrics-config"], summary: "Replace the active metrics list.", responses: { "200": { description: "Updated." } } },
+                delete: { tags: ["metrics-config"], summary: "Reset to connector defaults.", responses: { "200": { description: "Reset." } } },
+            },
+            "/metrics": {
+                get: {
+                    tags: ["self"],
+                    summary: "Prometheus scrape endpoint. Toggle with METRICS_ENABLED=false.",
+                    responses: {
+                        "200": {
+                            description: "OpenMetrics text exposition.",
+                            content: { "text/plain": { schema: { type: "string" } } },
+                        },
+                    },
+                },
+            },
+            "/api/openapi.json": {
+                get: {
+                    tags: ["self"],
+                    summary: "This document.",
+                    responses: { "200": { description: "OpenAPI 3.1 document." } },
+                },
+            },
+        },
+    };
+    return doc;
+}

package/dist/sdk/index.d.ts

@@ -0,0 +1,46 @@
+export type { ObservabilityConnector } from "../connectors/interface.js";
+export { manifestSchema } from "./manifest-schema.js";
+export type { ValidatedConnectorManifest } from "./manifest-schema.js";
+export type { SignalType, SourceConfig, SourceAuth, SourceTls, ConnectorHealth, ServiceInfo, MetricInfo, MetricQuery, MetricResult, MetricSummary, DataPoint, LogQuery, LogResult, LogEntry, LogSummary, MetricDefinition, } from "../types.js";
+/**
+ * Manifest shape declared in a plugin's `manifest.json`. The server
+ * validates plugin manifests against this at load time.
+ *
+ * @see docs/plugin-architecture.md
+ */
+export interface ConnectorManifest {
+    /** Manifest format version. Always 1 today. */
+    schemaVersion: 1;
+    /** Connector type id, e.g. "prometheus". Used in sources.yaml `type:`. */
+    name: string;
+    /** Human-readable name shown in the Web UI / hub. */
+    displayName: string;
+    /** Semver of this connector build. */
+    version: string;
+    description: string;
+    signalTypes: Array<"metrics" | "logs" | "traces">;
+    homepage?: string;
+    license?: string;
+    logo?: string;
+    /** JSON Schema describing this connector's `SourceConfig` payload. */
+    configSchema?: unknown;
+    capabilities?: {
+        queryMetrics?: boolean;
+        queryLogs?: boolean;
+        listServices?: boolean;
+        listAvailableMetrics?: boolean;
+    };
+    compat?: {
+        /** Semver range of mcp-server versions this connector supports. */
+        serverVersion?: string;
+    };
+}
+/**
+ * The default export shape a connector plugin module must provide.
+ *
+ * @example
+ *   import type { ObservabilityConnector, ConnectorFactory } from "@thotischner/observability-mcp-sdk";
+ *   const create: ConnectorFactory = () => new MyConnector();
+ *   export default create;
+ */
+export type ConnectorFactory = () => import("../connectors/interface.js").ObservabilityConnector | Promise<import("../connectors/interface.js").ObservabilityConnector>;

package/dist/sdk/index.js

@@ -0,0 +1,13 @@
+// Public plugin SDK — the surface a connector author depends on.
+//
+// Plugins should import only from this path so internal refactors of
+// mcp-server stay invisible to them. This file is intentionally a
+// re-export barrel — keep behaviour out of it.
+//
+// Stability: while still on 0.x of the plugin contract, breaking changes
+// may happen. Each release of mcp-server publishes a sibling
+// `@thotischner/observability-mcp-sdk` package mirroring this surface,
+// pinned to the same version. Plugins should declare a peer/range
+// against that package and an `observabilityMcp.compat.serverVersion`
+// constraint in their package.json (see docs/plugin-architecture.md).
+export { manifestSchema } from "./manifest-schema.js";

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

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const manifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    name: z.ZodString;
+    displayName: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    signalTypes: z.ZodArray<z.ZodEnum<{
+        metrics: "metrics";
+        logs: "logs";
+        traces: "traces";
+    }>>;
+    homepage: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
+    logo: z.ZodOptional<z.ZodString>;
+    configSchema: z.ZodOptional<z.ZodUnknown>;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        queryMetrics: z.ZodOptional<z.ZodBoolean>;
+        queryLogs: z.ZodOptional<z.ZodBoolean>;
+        listServices: z.ZodOptional<z.ZodBoolean>;
+        listAvailableMetrics: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    compat: z.ZodOptional<z.ZodObject<{
+        serverVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ValidatedConnectorManifest = z.infer<typeof manifestSchema>;

package/dist/sdk/manifest-schema.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+// Zod schema for connector plugin manifests. Mirror of the TS type in
+// ./index.ts (ConnectorManifest); kept here so both server and plugin
+// authors can import and validate at runtime.
+//
+// Bumping `schemaVersion` is a breaking change for the plugin contract.
+// See docs/plugin-architecture.md for the deprecation policy.
+export const manifestSchema = z.object({
+    schemaVersion: z.literal(1),
+    name: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, {
+        message: "name must be kebab-case lowercase ASCII",
+    }),
+    displayName: z.string().min(1),
+    version: z.string().regex(/^\d+\.\d+\.\d+(-[a-z0-9.-]+)?$/, {
+        message: "version must be semver",
+    }),
+    description: z.string().min(1),
+    signalTypes: z.array(z.enum(["metrics", "logs", "traces"])).min(1),
+    homepage: z.string().url().optional(),
+    license: z.string().optional(),
+    logo: z.string().optional(),
+    configSchema: z.unknown().optional(),
+    capabilities: z
+        .object({
+        queryMetrics: z.boolean().optional(),
+        queryLogs: z.boolean().optional(),
+        listServices: z.boolean().optional(),
+        listAvailableMetrics: z.boolean().optional(),
+    })
+        .optional(),
+    compat: z
+        .object({
+        serverVersion: z.string().optional(),
+    })
+        .optional(),
+});

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

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

package/dist/sdk/manifest-schema.test.js

@@ -0,0 +1,50 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { manifestSchema } from "./manifest-schema.js";
+const minimal = {
+    schemaVersion: 1,
+    name: "prometheus",
+    displayName: "Prometheus",
+    version: "1.0.0",
+    description: "PromQL backend",
+    signalTypes: ["metrics"],
+};
+describe("manifestSchema", () => {
+    it("accepts a minimal valid manifest", () => {
+        const r = manifestSchema.safeParse(minimal);
+        assert.equal(r.success, true);
+    });
+    it("rejects schemaVersion != 1", () => {
+        const r = manifestSchema.safeParse({ ...minimal, schemaVersion: 2 });
+        assert.equal(r.success, false);
+    });
+    it("rejects non-kebab names", () => {
+        const r = manifestSchema.safeParse({ ...minimal, name: "Prometheus_X" });
+        assert.equal(r.success, false);
+    });
+    it("rejects non-semver versions", () => {
+        const r = manifestSchema.safeParse({ ...minimal, version: "v1.0" });
+        assert.equal(r.success, false);
+    });
+    it("requires at least one signalType", () => {
+        const r = manifestSchema.safeParse({ ...minimal, signalTypes: [] });
+        assert.equal(r.success, false);
+    });
+    it("rejects unknown signalType", () => {
+        const r = manifestSchema.safeParse({ ...minimal, signalTypes: ["spans"] });
+        assert.equal(r.success, false);
+    });
+    it("accepts a fully-populated manifest", () => {
+        const full = {
+            ...minimal,
+            homepage: "https://example.com/connector-prom",
+            license: "MIT",
+            logo: "./logo.svg",
+            configSchema: { type: "object" },
+            capabilities: { queryMetrics: true, listServices: true },
+            compat: { serverVersion: ">=1.4.0" },
+        };
+        const r = manifestSchema.safeParse(full);
+        assert.equal(r.success, true);
+    });
+});

package/dist/tools/get-service-health.js

@@ -1,5 +1,6 @@
 import { calculateHealthScore } from "../analysis/health.js";
 import { detectRecentAnomaly } from "../analysis/anomaly.js";
+import { sanitizeForLog } from "../util/sanitize.js";
 let _thresholds = null;
 export function setHealthThresholds(t) {
     _thresholds = t;
@@ -41,7 +42,7 @@ export async function getServiceHealthHandler(registry, args) {
             checkAnomaly(latResult.values.map(v => v.value), "latency_p99", args.service, connector.name, anomalies);
         }
         catch (err) {
-            console.error(`Health check metrics failed for ${args.service}:`, err);
+            console.error("Health check metrics failed for %s:", sanitizeForLog(args.service), err);
         }
     }
     // Gather logs
@@ -64,7 +65,7 @@ export async function getServiceHealthHandler(registry, args) {
             }
         }
         catch (err) {
-            console.error(`Health check logs failed for ${args.service}:`, err);
+            console.error("Health check logs failed for %s:", sanitizeForLog(args.service), err);
         }
     }
     // Calculate health score