@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/catalog/loader.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Service catalog: an operator-curated map of service name → ownership /
+ * criticality / on-call metadata. Hooked into the existing /api/services
+ * and /api/health responses so the UI (and the agent through the MCP
+ * tools that derive from those endpoints) can see "this is owned by
+ * team-payments, criticality tier-1, on-call URL …" without having to
+ * cross-reference an external CMDB.
+ *
+ * On-disk format: JSON file (commit-friendly, easy to diff in PRs). Path
+ * defaults to `mcp-server/config/catalog.json`; override via
+ * `OMCP_SERVICE_CATALOG_FILE`. Missing or malformed file => no catalog
+ * (the server boots fine, enrichment is a no-op).
+ *
+ * Distinct from the enterprise-gate `OMCP_CATALOG` "product catalog"
+ * which lives behind the entitlement gate and governs MCP-tool grants —
+ * different trust model, different schema.
+ */
+export type CriticalityTier = "tier-1" | "tier-2" | "tier-3" | "tier-4";
+export type DataClassification = "public" | "internal" | "confidential" | "restricted";
+export interface ServiceCatalogEntry {
+    /** Stable short owner identifier — team slug, squad, individual handle. */
+    owner?: string;
+    /** Human-readable description. One sentence. */
+    description?: string;
+    /** Page-the-team URL — Slack channel, on-call rota, runbook index. */
+    onCall?: string;
+    /** Operator-defined criticality bucket. */
+    tier?: CriticalityTier;
+    /** Data classification of what flows through the service. */
+    dataClassification?: DataClassification;
+    /** Free-form SLO label ("99.9% / month" / "99.5%"). Not parsed. */
+    slo?: string;
+    /** Optional list of relevant runbook URLs. */
+    runbooks?: string[];
+    /** Optional list of free-form tags. */
+    tags?: string[];
+    /** Tenant the entry belongs to. Omitted → "default". Used by
+     *  multi-tenant deployments to scope what /api/catalog and the
+     *  list_services / get_service_health tools surface per session. */
+    tenant?: string;
+}
+export interface ServiceCatalog {
+    /** Map service name → entry. Service-name key is the same string
+     * `list_services` returns; no fuzzy matching. */
+    services: Record<string, ServiceCatalogEntry>;
+}
+/** Read + validate a catalog file. Returns the empty catalog on any
+ * problem and (when configured) emits a single warn-level console.error
+ * so the operator notices but the server keeps booting. */
+export declare function readCatalogFile(path: string | undefined): Promise<ServiceCatalog>;
+/** Pure validator — useful in tests and when feeding in-memory data. */
+export declare function validateCatalog(input: unknown): ServiceCatalog;
+/** Lookup wrapper used by the enricher / API handlers. */
+export declare class CatalogStore {
+    private catalog;
+    constructor(catalog?: ServiceCatalog);
+    /** Lookup. When `tenant` is set, returns undefined for entries
+     *  belonging to a different tenant — so a cross-tenant
+     *  enrichment never leaks owner / on-call / SLO bytes. Entries
+     *  without a tenant field are treated as `"default"`. */
+    get(serviceName: string, tenant?: string): ServiceCatalogEntry | undefined;
+    /** Snapshot. When `tenant` is set, filters down to entries in that
+     *  tenant; entries without a tenant field counted as `"default"`. */
+    list(tenant?: string): Record<string, ServiceCatalogEntry>;
+    count(tenant?: string): number;
+    replace(catalog: ServiceCatalog): void;
+}

package/dist/catalog/loader.js

@@ -0,0 +1,122 @@
+/**
+ * Service catalog: an operator-curated map of service name → ownership /
+ * criticality / on-call metadata. Hooked into the existing /api/services
+ * and /api/health responses so the UI (and the agent through the MCP
+ * tools that derive from those endpoints) can see "this is owned by
+ * team-payments, criticality tier-1, on-call URL …" without having to
+ * cross-reference an external CMDB.
+ *
+ * On-disk format: JSON file (commit-friendly, easy to diff in PRs). Path
+ * defaults to `mcp-server/config/catalog.json`; override via
+ * `OMCP_SERVICE_CATALOG_FILE`. Missing or malformed file => no catalog
+ * (the server boots fine, enrichment is a no-op).
+ *
+ * Distinct from the enterprise-gate `OMCP_CATALOG` "product catalog"
+ * which lives behind the entitlement gate and governs MCP-tool grants —
+ * different trust model, different schema.
+ */
+import { promises as fs } from "node:fs";
+const EMPTY_CATALOG = { services: {} };
+const VALID_TIERS = new Set(["tier-1", "tier-2", "tier-3", "tier-4"]);
+const VALID_CLASS = new Set(["public", "internal", "confidential", "restricted"]);
+/** Read + validate a catalog file. Returns the empty catalog on any
+ * problem and (when configured) emits a single warn-level console.error
+ * so the operator notices but the server keeps booting. */
+export async function readCatalogFile(path) {
+    if (!path)
+        return EMPTY_CATALOG;
+    let raw;
+    try {
+        raw = await fs.readFile(path, "utf8");
+    }
+    catch {
+        return EMPTY_CATALOG;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        console.error(`[catalog] OMCP_SERVICE_CATALOG_FILE=${path} is not valid JSON: ${e.message}`);
+        return EMPTY_CATALOG;
+    }
+    return validateCatalog(parsed);
+}
+/** Pure validator — useful in tests and when feeding in-memory data. */
+export function validateCatalog(input) {
+    if (!input || typeof input !== "object")
+        return EMPTY_CATALOG;
+    const obj = input;
+    const rawServices = obj.services;
+    if (!rawServices || typeof rawServices !== "object")
+        return EMPTY_CATALOG;
+    const out = {};
+    for (const [name, value] of Object.entries(rawServices)) {
+        if (!value || typeof value !== "object")
+            continue;
+        const e = value;
+        const entry = {};
+        if (typeof e.owner === "string")
+            entry.owner = e.owner;
+        if (typeof e.description === "string")
+            entry.description = e.description;
+        if (typeof e.onCall === "string")
+            entry.onCall = e.onCall;
+        if (typeof e.tier === "string" && VALID_TIERS.has(e.tier)) {
+            entry.tier = e.tier;
+        }
+        if (typeof e.dataClassification === "string" && VALID_CLASS.has(e.dataClassification)) {
+            entry.dataClassification = e.dataClassification;
+        }
+        if (typeof e.slo === "string")
+            entry.slo = e.slo;
+        if (Array.isArray(e.runbooks)) {
+            entry.runbooks = e.runbooks.filter((x) => typeof x === "string");
+        }
+        if (Array.isArray(e.tags)) {
+            entry.tags = e.tags.filter((x) => typeof x === "string");
+        }
+        if (typeof e.tenant === "string")
+            entry.tenant = e.tenant;
+        out[name] = entry;
+    }
+    return { services: out };
+}
+/** Lookup wrapper used by the enricher / API handlers. */
+export class CatalogStore {
+    catalog;
+    constructor(catalog = EMPTY_CATALOG) {
+        this.catalog = catalog;
+    }
+    /** Lookup. When `tenant` is set, returns undefined for entries
+     *  belonging to a different tenant — so a cross-tenant
+     *  enrichment never leaks owner / on-call / SLO bytes. Entries
+     *  without a tenant field are treated as `"default"`. */
+    get(serviceName, tenant) {
+        const e = this.catalog.services[serviceName];
+        if (!e)
+            return undefined;
+        if (!tenant)
+            return e;
+        const entryTenant = e.tenant || "default";
+        return entryTenant === tenant ? e : undefined;
+    }
+    /** Snapshot. When `tenant` is set, filters down to entries in that
+     *  tenant; entries without a tenant field counted as `"default"`. */
+    list(tenant) {
+        if (!tenant)
+            return this.catalog.services;
+        const out = {};
+        for (const [k, v] of Object.entries(this.catalog.services)) {
+            if ((v.tenant || "default") === tenant)
+                out[k] = v;
+        }
+        return out;
+    }
+    count(tenant) {
+        return Object.keys(this.list(tenant)).length;
+    }
+    replace(catalog) {
+        this.catalog = catalog;
+    }
+}

package/dist/catalog/loader.test.d.ts

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

package/dist/catalog/loader.test.js

@@ -0,0 +1,108 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readCatalogFile, validateCatalog, CatalogStore } from "./loader.js";
+test("readCatalogFile — missing path returns empty catalog", async () => {
+    const c = await readCatalogFile(undefined);
+    assert.deepEqual(c, { services: {} });
+});
+test("readCatalogFile — missing file returns empty catalog (no crash)", async () => {
+    const c = await readCatalogFile("/tmp/definitely-does-not-exist-omcp.json");
+    assert.deepEqual(c, { services: {} });
+});
+test("readCatalogFile — malformed JSON returns empty catalog", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-catalog-"));
+    try {
+        const file = join(dir, "catalog.json");
+        await writeFile(file, "{this is not json", "utf8");
+        const c = await readCatalogFile(file);
+        assert.deepEqual(c, { services: {} });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("readCatalogFile — valid file returns parsed catalog", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-catalog-"));
+    try {
+        const file = join(dir, "catalog.json");
+        await writeFile(file, JSON.stringify({
+            services: {
+                "payment-service": {
+                    owner: "team-payments",
+                    tier: "tier-1",
+                    dataClassification: "confidential",
+                    slo: "99.9%",
+                    runbooks: ["https://runbooks.example/payments"],
+                    tags: ["pci", "regulated"],
+                },
+            },
+        }), "utf8");
+        const c = await readCatalogFile(file);
+        assert.equal(c.services["payment-service"].owner, "team-payments");
+        assert.equal(c.services["payment-service"].tier, "tier-1");
+        assert.deepEqual(c.services["payment-service"].tags, ["pci", "regulated"]);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("validateCatalog — rejects invalid tier values", () => {
+    const c = validateCatalog({ services: { svc: { tier: "tier-9" } } });
+    assert.equal(c.services.svc.tier, undefined);
+});
+test("validateCatalog — rejects invalid data classification", () => {
+    const c = validateCatalog({ services: { svc: { dataClassification: "ultra-secret" } } });
+    assert.equal(c.services.svc.dataClassification, undefined);
+});
+test("validateCatalog — strips non-string entries from runbooks / tags", () => {
+    const c = validateCatalog({
+        services: { svc: { runbooks: ["a", 1, "b", null], tags: [{}, "tag1"] } },
+    });
+    assert.deepEqual(c.services.svc.runbooks, ["a", "b"]);
+    assert.deepEqual(c.services.svc.tags, ["tag1"]);
+});
+test("validateCatalog — skips non-object service entries", () => {
+    const c = validateCatalog({ services: { svc1: "string", svc2: null, svc3: { owner: "team" } } });
+    assert.equal(c.services.svc1, undefined);
+    assert.equal(c.services.svc2, undefined);
+    assert.equal(c.services.svc3.owner, "team");
+});
+test("CatalogStore — get / list / count / replace", () => {
+    const store = new CatalogStore({
+        services: {
+            a: { owner: "team-a" },
+            b: { owner: "team-b" },
+        },
+    });
+    assert.equal(store.count(), 2);
+    assert.equal(store.get("a")?.owner, "team-a");
+    assert.equal(store.get("nope"), undefined);
+    assert.equal(Object.keys(store.list()).length, 2);
+    store.replace({ services: { x: { owner: "team-x" } } });
+    assert.equal(store.count(), 1);
+    assert.equal(store.get("x")?.owner, "team-x");
+});
+test("CatalogStore — tenant filter scopes get / list / count", () => {
+    const store = new CatalogStore({
+        services: {
+            "acme-payments": { owner: "team-a", tenant: "acme" },
+            "bigco-payments": { owner: "team-b", tenant: "bigco" },
+            "shared-cdn": { owner: "team-c" }, // no tenant → "default"
+        },
+    });
+    // No tenant filter → see everything (admin-style read)
+    assert.equal(store.count(), 3);
+    // Tenant-scoped: each sees its own entries + nothing else
+    assert.equal(store.count("acme"), 1);
+    assert.equal(store.get("acme-payments", "acme")?.owner, "team-a");
+    assert.equal(store.get("bigco-payments", "acme"), undefined, "cross-tenant get must return undefined");
+    assert.equal(Object.keys(store.list("acme"))[0], "acme-payments");
+    // Default tenant includes entries with no tenant field
+    assert.equal(store.count("default"), 1);
+    assert.equal(store.get("shared-cdn", "default")?.owner, "team-c");
+    // Unknown tenant → empty
+    assert.equal(store.count("unknown"), 0);
+});

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { parseArgs, pickFreePort, composeOverride, resolveCatalogSource, formatPluginList, formatPluginInfo, resolveInstall, splitPassthrough, helmReleaseArgs, HELM_REPO_NAME, HELM_REPO_URL, HELP, } from "./lib.js";
 import { loadTrustRoot, verifyIntegrity, verifyManifestSignature, PluginVerificationError, } from "../connectors/verify.js";
+import { inspectorConfigCommand } from "./inspector-config.js";
 function pkgVersion() {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
@@ -363,6 +364,8 @@ async function main() {
             return plugin(sub, positionals, flags);
         case "helm":
             return helm(sub, positionals[0] ?? "observability-mcp", passthrough);
+        case "inspector-config":
+            return inspectorConfigCommand();
         default:
             fail(`unknown command: ${command}\n\n${HELP}`);
     }

package/dist/cli/inspector-config.d.ts

@@ -0,0 +1,9 @@
+export interface InspectorConfig {
+    mcpServers: Record<string, {
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+}
+export declare function buildInspectorConfig(env?: NodeJS.ProcessEnv): InspectorConfig;
+/** CLI entrypoint. Prints JSON to stdout; exits 0 on success. */
+export declare function inspectorConfigCommand(): void;

package/dist/cli/inspector-config.js

@@ -0,0 +1,28 @@
+// `omcp inspector-config` — emit a config JSON the official MCP
+// Inspector can consume. Reads OMCP_BASE_URL (default
+// http://localhost:3000) and optionally OMCP_INSPECTOR_TOKEN to put
+// in the Authorization header.
+//
+// Pipe straight into Inspector:
+//   npx @modelcontextprotocol/inspector --config <(omcp inspector-config)
+//
+// Or write to a file:
+//   omcp inspector-config > inspector.json
+//   npx @modelcontextprotocol/inspector --config inspector.json
+export function buildInspectorConfig(env = process.env) {
+    const baseRaw = env.OMCP_BASE_URL?.trim() || "http://localhost:3000";
+    const base = baseRaw.replace(/\/$/, "");
+    const url = `${base}/mcp`;
+    const token = env.OMCP_INSPECTOR_TOKEN?.trim();
+    const name = env.OMCP_INSPECTOR_SERVER_NAME?.trim() || "observability-mcp";
+    const server = { url };
+    if (token) {
+        server.headers = { Authorization: `Bearer ${token}` };
+    }
+    return { mcpServers: { [name]: server } };
+}
+/** CLI entrypoint. Prints JSON to stdout; exits 0 on success. */
+export function inspectorConfigCommand() {
+    const cfg = buildInspectorConfig();
+    process.stdout.write(JSON.stringify(cfg, null, 2) + "\n");
+}

package/dist/cli/inspector-config.test.d.ts

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

package/dist/cli/inspector-config.test.js

@@ -0,0 +1,33 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildInspectorConfig } from "./inspector-config.js";
+test("buildInspectorConfig: defaults to localhost:3000/mcp, no headers, observability-mcp server name", () => {
+    const cfg = buildInspectorConfig({});
+    assert.deepEqual(cfg, {
+        mcpServers: {
+            "observability-mcp": {
+                url: "http://localhost:3000/mcp",
+            },
+        },
+    });
+});
+test("buildInspectorConfig: trims trailing slash from base URL", () => {
+    const cfg = buildInspectorConfig({ OMCP_BASE_URL: "https://gw.example.com/" });
+    assert.equal(cfg.mcpServers["observability-mcp"].url, "https://gw.example.com/mcp");
+});
+test("buildInspectorConfig: token populates Authorization Bearer", () => {
+    const cfg = buildInspectorConfig({
+        OMCP_INSPECTOR_TOKEN: "tok-abc",
+    });
+    assert.equal(cfg.mcpServers["observability-mcp"].headers?.Authorization, "Bearer tok-abc");
+});
+test("buildInspectorConfig: custom server name", () => {
+    const cfg = buildInspectorConfig({
+        OMCP_INSPECTOR_SERVER_NAME: "my-gateway",
+    });
+    assert.ok("my-gateway" in cfg.mcpServers);
+});
+test("buildInspectorConfig: empty token trimmed → no headers key", () => {
+    const cfg = buildInspectorConfig({ OMCP_INSPECTOR_TOKEN: "   " });
+    assert.equal(cfg.mcpServers["observability-mcp"].headers, undefined);
+});

package/dist/cli/lib.d.ts

@@ -92,4 +92,4 @@ export declare function splitPassthrough(argv: string[]): {
 };
 /** The helm argv for the install/upgrade step (repo add/update are fixed). */
 export declare function helmReleaseArgs(action: "install" | "upgrade", release: string, passthrough: string[]): string[];
-export declare const HELP = "omcp \u2014 observability-mcp control CLI\n\nUsage:\n  omcp version                 Print CLI + server package version\n  omcp doctor                  Check the local toolchain (docker, compose, helm, node)\n  omcp demo up                 Start the full demo stack (auto-picks free host ports)\n  omcp demo down               Stop and remove the demo stack\n  omcp demo status             Show demo container status\n  omcp plugin list             List connectors from the hub catalog\n  omcp plugin info <name>      Show one connector's versions + verification info\n  omcp plugin install <ref>    Install name[@version]: download, verify, extract\n  omcp plugin verify <dir>     Verify an installed plugin dir against a trust root\n  omcp helm install [release]  helm repo add+update, then install the signed chart\n  omcp helm upgrade [release]  Same, as 'helm upgrade --install'\n  omcp help                    Show this help\n\nPass extra helm flags after a literal --, e.g.:\n  omcp helm upgrade obs -- -n monitoring --set sources.prometheusUrl=http://prom:9090\n\nFlags:\n  --json                       Machine-readable output (doctor, status, plugin)\n  --from <url|path>            Catalog source (default: local checkout or the public hub)\n  --offline-dir <dir>          Airgapped: read <name>-<ver>.tgz[.sig] + manifest from <dir>\n  --trust-root <pem>           Verify signature+integrity against this PEM (fail-closed)\n  --insecure                   Skip verification (NOT recommended; explicit opt-out)\n  --dest <dir>                 Install target (default: $PLUGINS_DIR or ./plugins)\n  --force                      Overwrite an existing install dir\n";
+export declare const HELP = "omcp \u2014 observability-mcp control CLI\n\nUsage:\n  omcp version                 Print CLI + server package version\n  omcp doctor                  Check the local toolchain (docker, compose, helm, node)\n  omcp demo up                 Start the full demo stack (auto-picks free host ports)\n  omcp demo down               Stop and remove the demo stack\n  omcp demo status             Show demo container status\n  omcp plugin list             List connectors from the hub catalog\n  omcp plugin info <name>      Show one connector's versions + verification info\n  omcp plugin install <ref>    Install name[@version]: download, verify, extract\n  omcp plugin verify <dir>     Verify an installed plugin dir against a trust root\n  omcp helm install [release]  helm repo add+update, then install the signed chart\n  omcp helm upgrade [release]  Same, as 'helm upgrade --install'\n  omcp inspector-config        Print an MCP Inspector config JSON pointing at the local gateway\n  omcp help                    Show this help\n\nPass extra helm flags after a literal --, e.g.:\n  omcp helm upgrade obs -- -n monitoring --set sources.prometheusUrl=http://prom:9090\n\nFlags:\n  --json                       Machine-readable output (doctor, status, plugin)\n  --from <url|path>            Catalog source (default: local checkout or the public hub)\n  --offline-dir <dir>          Airgapped: read <name>-<ver>.tgz[.sig] + manifest from <dir>\n  --trust-root <pem>           Verify signature+integrity against this PEM (fail-closed)\n  --insecure                   Skip verification (NOT recommended; explicit opt-out)\n  --dest <dir>                 Install target (default: $PLUGINS_DIR or ./plugins)\n  --force                      Overwrite an existing install dir\n";

package/dist/cli/lib.js

@@ -169,6 +169,7 @@ Usage:
   omcp plugin verify <dir>     Verify an installed plugin dir against a trust root
   omcp helm install [release]  helm repo add+update, then install the signed chart
   omcp helm upgrade [release]  Same, as 'helm upgrade --install'
+  omcp inspector-config        Print an MCP Inspector config JSON pointing at the local gateway
   omcp help                    Show this help
 
 Pass extra helm flags after a literal --, e.g.:

package/dist/conformance/mcp-2025-11-25.test.d.ts

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

package/dist/conformance/mcp-2025-11-25.test.js

@@ -0,0 +1,206 @@
+// MCP 2025-11-25 conformance harness.
+//
+// Run against a running gateway by setting OMCP_CONFORMANCE_URL to
+// its Streamable HTTP endpoint (default http://localhost:3000/mcp).
+// When the env var is unset, every test skips — this lets the suite
+// live in `find src -name "*.test.ts"` without requiring a server
+// during a plain unit-test run.
+//
+//   OMCP_CONFORMANCE_URL=http://localhost:3000/mcp \
+//   npx tsx --test src/conformance/mcp-2025-11-25.test.ts
+//
+// The `make conformance` target boots the demo stack, waits for
+// /healthz, then runs this file with the URL pointed at the live
+// server.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+const URL_ENV = process.env.OMCP_CONFORMANCE_URL;
+const PROTOCOL_VERSION = "2025-11-25";
+const skip = !URL_ENV;
+const opts = skip ? { skip: "OMCP_CONFORMANCE_URL not set" } : {};
+async function jsonRpc(method, params, opts = {}) {
+    if (!URL_ENV)
+        throw new Error("OMCP_CONFORMANCE_URL not set");
+    const reqHeaders = {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+    };
+    if (opts.session)
+        reqHeaders["mcp-session-id"] = opts.session;
+    const body = {
+        jsonrpc: "2.0",
+        id: opts.id ?? 1,
+        method,
+        params: params ?? {},
+    };
+    const res = await fetch(URL_ENV, {
+        method: "POST",
+        headers: reqHeaders,
+        body: JSON.stringify(body),
+    });
+    const headers = {};
+    res.headers.forEach((v, k) => {
+        headers[k] = v;
+    });
+    // Streamable HTTP may answer with either JSON or SSE; both carry a
+    // single JSON-RPC envelope for unary calls. Strip the SSE framing
+    // if present so the test only deals with the JSON shape.
+    const text = await res.text();
+    let response;
+    if (text.startsWith("event:") || text.includes("data: ")) {
+        const match = text.match(/^data:\s*(.+)$/m);
+        response = match ? JSON.parse(match[1]) : {};
+    }
+    else if (text.trim().startsWith("{")) {
+        response = JSON.parse(text);
+    }
+    else {
+        response = {};
+    }
+    return { response, headers, status: res.status };
+}
+async function notify(method, session) {
+    if (!URL_ENV)
+        return;
+    await fetch(URL_ENV, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json, text/event-stream",
+            "mcp-session-id": session,
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", method, params: {} }),
+    });
+}
+async function newSession() {
+    const { headers, response } = await jsonRpc("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "conformance-harness", version: "0" },
+    }, { id: 1 });
+    assert.ok(response.result, "initialize must return a result");
+    const session = headers["mcp-session-id"];
+    assert.ok(session, "server must issue mcp-session-id on initialize");
+    await notify("notifications/initialized", session);
+    return session;
+}
+test("MCP 2025-11-25: initialize returns spec-compliant InitializeResult", opts, async () => {
+    const { response, headers } = await jsonRpc("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "harness", version: "0" },
+    });
+    assert.equal(response.jsonrpc, "2.0");
+    assert.equal(response.id, 1);
+    assert.ok(response.result && typeof response.result === "object");
+    const r = response.result;
+    assert.ok(r.protocolVersion, "InitializeResult must include protocolVersion");
+    assert.ok(r.capabilities && typeof r.capabilities === "object", "capabilities object required");
+    assert.ok(r.serverInfo && typeof r.serverInfo === "object", "serverInfo required");
+    assert.ok(r.serverInfo?.name, "serverInfo.name required");
+    assert.ok(r.serverInfo?.version, "serverInfo.version required");
+    assert.ok(headers["mcp-session-id"], "Mcp-Session-Id header required on initialize response");
+});
+test("MCP 2025-11-25: tools/list returns a Tool[] each with name + inputSchema", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/list", {}, { id: 2, session });
+    assert.ok(response.result, JSON.stringify(response.error ?? {}));
+    const r = response.result;
+    assert.ok(Array.isArray(r.tools), "tools must be an array");
+    assert.ok(r.tools && r.tools.length > 0, "gateway must expose at least one tool");
+    for (const t of r.tools) {
+        assert.ok(t.name && typeof t.name === "string", `tool name required, got ${JSON.stringify(t)}`);
+        assert.ok(t.inputSchema && typeof t.inputSchema === "object", `tool ${t.name} missing inputSchema`);
+    }
+});
+test("MCP 2025-11-25: tools/call dispatches and returns CallToolResult", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/call", { name: "list_sources", arguments: {} }, { id: 3, session });
+    // Either a result (success path) or a JSON-RPC error — both are
+    // spec-compliant; we just verify shape.
+    if (response.error) {
+        assert.equal(typeof response.error.code, "number");
+        assert.equal(typeof response.error.message, "string");
+    }
+    else {
+        const r = response.result;
+        assert.ok(Array.isArray(r.content), "CallToolResult.content must be an array");
+    }
+});
+test("MCP 2025-11-25: unknown method returns -32601 Method not found", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("this/method/does/not/exist", {}, { id: 99, session });
+    assert.ok(response.error, "expected an error envelope");
+    assert.equal(response.error?.code, -32601, "spec-mandated error code for unknown method");
+});
+test("MCP 2025-11-25: ping returns an empty result", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("ping", {}, { id: 4, session });
+    assert.ok(response.result !== undefined, "ping must return a result (may be empty object)");
+});
+test("MCP 2025-11-25: resources/list returns Resource[] or method-not-found", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("resources/list", {}, { id: 5, session });
+    if (response.error) {
+        assert.equal(response.error.code, -32601, "if not supported, must be -32601");
+    }
+    else {
+        const r = response.result;
+        assert.ok(Array.isArray(r.resources), "resources must be an array");
+    }
+});
+test("MCP 2025-11-25: prompts/list returns Prompt[] or method-not-found", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("prompts/list", {}, { id: 6, session });
+    if (response.error) {
+        assert.equal(response.error.code, -32601, "if not supported, must be -32601");
+    }
+    else {
+        const r = response.result;
+        assert.ok(Array.isArray(r.prompts), "prompts must be an array");
+    }
+});
+test("MCP 2025-11-25: logging/setLevel accepts spec levels or method-not-found", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("logging/setLevel", { level: "info" }, { id: 7, session });
+    if (response.error) {
+        assert.equal(response.error.code, -32601, "if not supported, must be -32601");
+    }
+    else {
+        // Spec says the result is `EmptyResult` — we don't enforce
+        // strictly empty (some implementations include diagnostics) but
+        // it must be a JSON object.
+        assert.ok(typeof response.result === "object");
+    }
+});
+test("MCP 2025-11-25: tools/call with invalid params returns -32602 or isError result", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/call", { name: "list_sources", arguments: { __invalid_arg: { nested: 1 } } }, { id: 8, session });
+    // The spec allows either a JSON-RPC error or an isError CallToolResult.
+    // We accept either; reject only on a successful non-error result for
+    // input that should not validate.
+    if (response.error) {
+        assert.ok([-32602, -32600].includes(response.error.code) || response.error.code <= -32000);
+    }
+    else {
+        const r = response.result;
+        // list_sources happens to ignore unknown args — that's fine, the
+        // spec doesn't require strict input rejection for tools that opt
+        // out. Just confirm we got a shape-conformant CallToolResult.
+        assert.ok(Array.isArray(r.content));
+    }
+});
+test("MCP 2025-11-25: server advertises protocolVersion equal to or newer than 2025-11-25", opts, async () => {
+    const { response } = await jsonRpc("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "harness", version: "0" },
+    }, { id: 100 });
+    const r = response.result;
+    assert.ok(r.protocolVersion, "protocolVersion must be present in InitializeResult");
+    // Spec contract: the server picks the highest version it supports
+    // that the client also offered, OR returns the highest it knows
+    // about and lets the client decide. We just require it's a
+    // recognised date-style version string.
+    assert.match(r.protocolVersion, /^\d{4}-\d{2}-\d{2}$/, "protocolVersion must be a YYYY-MM-DD date");
+});

package/dist/connectors/interface.d.ts

@@ -1,4 +1,4 @@
-import type { SignalType, ConnectorHealth, ServiceInfo, MetricInfo, MetricQuery, MetricResult, LogQuery, LogResult, SourceConfig, MetricDefinition, Resource, Edge, TopologySnapshot, TopologyChangeListener } from "../types.js";
+import type { SignalType, ConnectorHealth, ServiceInfo, MetricInfo, MetricQuery, MetricResult, LogQuery, LogResult, TraceQuery, TraceResult, SourceConfig, MetricDefinition, Resource, Edge, TopologySnapshot, TopologyChangeListener } from "../types.js";
 export interface ObservabilityConnector {
     readonly name: string;
     readonly type: string;
@@ -14,6 +14,10 @@ export interface ObservabilityConnector {
     listAvailableMetrics?(service: string): Promise<MetricInfo[]>;
     queryMetrics?(params: MetricQuery): Promise<MetricResult>;
     queryLogs?(params: LogQuery): Promise<LogResult>;
+    /** Optional traces capability — Tempo / Jaeger / OTLP backends
+     *  implement this. The MCP `query_traces` tool fans out to every
+     *  connector that has it. */
+    queryTraces?(params: TraceQuery): Promise<TraceResult>;
     /** Current in-memory resource list. Should be O(1) — backed by the watch cache. */
     listResources?(): Promise<Resource[]>;
     /** Current in-memory edge list. Should be O(1) — backed by the watch cache. */