@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/auth/policy/opa.js

@@ -44,10 +44,13 @@ export class OpaPolicyEngine {
         this.cfg = { timeoutMs: 1500, ...cfg };
         this.fetcher = cfg.fetcher ?? ((u, i) => fetch(u, i));
     }
-    cacheKey(roles, resource, action) {
+    cacheKey(roles, resource, action, tenant) {
         // NUL-delimited so role names containing "," / "|" can't alias
         // across role sets ({"a,b"} would otherwise collide with {"a","b"}).
-        return roles.slice().sort().join("\x00") + "\x01" + resource + "\x01" + action;
+        // Tenant is part of the key so cross-tenant decisions don't share
+        // cache slots — required once we thread tenant into the OPA input.
+        const tk = tenant || "";
+        return roles.slice().sort().join("\x00") + "\x01" + resource + "\x01" + action + "\x01" + tk;
     }
     now() {
         return Date.now();
@@ -74,14 +77,15 @@ export class OpaPolicyEngine {
             clearTimeout(timer);
         }
     }
-    evaluate(roles, resource, action) {
+    evaluate(roles, resource, action, ctx) {
         const rs = roles && roles.length > 0 ? roles : [];
+        const tenant = ctx?.tenant;
         // The PolicyEngine.evaluate contract is sync to keep the hot
         // gate path off the await stack, so we serve from the cache
         // synchronously and warm the cache lazily on miss. Misses fall
         // back to a conservative deny + the cache will be populated for
         // next time.
-        const key = this.cacheKey(rs, resource, action);
+        const key = this.cacheKey(rs, resource, action, tenant);
         const cached = this.cache.get(key);
         if (cached && this.now() - cached.at < this.cacheTtlMs)
             return cached.result;
@@ -89,16 +93,22 @@ export class OpaPolicyEngine {
         // first miss (deny while warming) but the next call within the
         // TTL returns the real verdict. For sync-required contracts we
         // accept that trade-off vs. blocking every request handler.
-        void this.warmEvaluate(rs, resource, action);
+        void this.warmEvaluate(rs, resource, action, tenant);
         return { allowed: false, reason: "OPA decision pending (warming cache); request again" };
     }
     /** Async warm of the evaluate cache. Public so a long-running
      *  caller can `await engine.warmEvaluate(...)` before the gate
      *  check if it cannot tolerate the warming-deny window. */
-    async warmEvaluate(roles, resource, action) {
-        const key = this.cacheKey(roles, resource, action);
+    async warmEvaluate(roles, resource, action, tenant) {
+        const key = this.cacheKey(roles, resource, action, tenant);
         try {
-            const out = await this.query({ input: { roles, resource, action } });
+            // input.tenant is always included (undefined → null in JSON
+            // serialisation, omitted by JSON.stringify default) so Rego
+            // authors can write `input.tenant == "acme"` rules without
+            // tripping on missing-field. When the caller didn't supply
+            // tenant we still include the key with `undefined` value;
+            // JSON.stringify drops it cleanly.
+            const out = await this.query({ input: { roles, resource, action, tenant } });
             const raw = out.result;
             let result;
             if (raw === true || raw === false) {
@@ -124,20 +134,21 @@ export class OpaPolicyEngine {
             return result;
         }
     }
-    list(roles) {
+    list(roles, ctx) {
         if (!roles || roles.length === 0)
             return [];
-        const key = roles.slice().sort().join("\x00");
+        const tenant = ctx?.tenant || "";
+        const key = roles.slice().sort().join("\x00") + "\x01" + tenant;
         const cached = this.listCache.get(key);
         if (cached && this.now() - cached.at < this.listCacheTtlMs)
             return cached.perms;
-        void this.warmList(roles);
+        void this.warmList(roles, ctx?.tenant);
         return [];
     }
-    async warmList(roles) {
-        const key = roles.slice().sort().join("\x00");
+    async warmList(roles, tenant) {
+        const key = roles.slice().sort().join("\x00") + "\x01" + (tenant || "");
         try {
-            const out = await this.query({ input: { roles, list: true } });
+            const out = await this.query({ input: { roles, list: true, tenant } });
             const raw = out.result;
             let perms = [];
             if (raw && typeof raw === "object" && Array.isArray(raw.permissions)) {

package/dist/auth/policy/opa.test.js

@@ -141,6 +141,54 @@ test("OpaPolicyEngine — cache key delimiter prevents role-name collision (\"a,
     assert.equal(r2.allowed, false);
     assert.equal(calls.length, 2, "the two role-sets must not collide on the cache key");
 });
+test("OpaPolicyEngine — tenant flows into the OPA input shape on evaluate", async () => {
+    let seenBody = null;
+    const fetcher = (async (_url, init) => {
+        seenBody = init?.body ? JSON.parse(String(init.body)) : null;
+        return new Response(JSON.stringify({ result: true }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    await e.warmEvaluate(["admin"], "sources", "write", "acme");
+    const body = seenBody;
+    assert.equal(body?.input?.tenant, "acme", "tenant must reach the Rego input as input.tenant");
+    assert.equal(body?.input?.resource, "sources");
+    assert.equal(body?.input?.action, "write");
+});
+test("OpaPolicyEngine — tenant flows into the OPA input shape on list", async () => {
+    let seenBody = null;
+    const fetcher = (async (_url, init) => {
+        seenBody = init?.body ? JSON.parse(String(init.body)) : null;
+        return new Response(JSON.stringify({ result: { permissions: [] } }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    await e.warmList(["admin"], "acme");
+    const body = seenBody;
+    assert.equal(body?.input?.tenant, "acme");
+    assert.equal(body?.input?.list, true);
+});
+test("OpaPolicyEngine — cache key isolates tenants (same roles+resource+action, different tenants → two OPA calls)", async () => {
+    let calls = 0;
+    const fetcher = (async (_url, init) => {
+        calls++;
+        const body = init?.body ? JSON.parse(String(init.body)) : null;
+        // Return a different verdict per tenant so a cache mix-up would
+        // surface as a wrong allowed value, not just an extra call.
+        const allowed = body?.input?.tenant === "acme";
+        return new Response(JSON.stringify({ result: allowed }), { status: 200 });
+    });
+    const e = new OpaPolicyEngine({ url: "http://opa.test", packagePath: "p", fetcher });
+    const acme = await e.warmEvaluate(["admin"], "sources", "read", "acme");
+    const bigco = await e.warmEvaluate(["admin"], "sources", "read", "bigco");
+    assert.equal(acme.allowed, true);
+    assert.equal(bigco.allowed, false);
+    assert.equal(calls, 2, "tenants must not share cache slots");
+    // Repeat — both come from cache, no extra OPA hits.
+    const acme2 = e.evaluate(["admin"], "sources", "read", { tenant: "acme" });
+    const bigco2 = e.evaluate(["admin"], "sources", "read", { tenant: "bigco" });
+    assert.equal(acme2.allowed, true);
+    assert.equal(bigco2.allowed, false);
+    assert.equal(calls, 2);
+});
 test("OpaPolicyEngine — sort-stable cache key (role-set order doesn't matter)", async () => {
     let calls = 0;
     const fetcher = (async (_u) => {

package/dist/auth/rbac.d.ts

@@ -16,13 +16,18 @@
  */
 import type { RequestHandler } from "express";
 import type { AuthRuntime } from "./middleware.js";
+import type { PolicyEngine } from "./policy/engine.js";
 export type Action = "read" | "write" | "delete" | "bypass";
 export type Resource = "sources" | "services" | "health" | "topology" | "settings" | "connectors" | "audit" | "catalog" | "users" | "redaction" | "products";
 export interface Permission {
     resource: Resource;
     action: Action;
 }
-/** Built-in default policy. Operators can replace this via OMCP_RBAC_POLICY in a follow-up. */
+/** Built-in default policy. Operators replace this via OMCP_RBAC_POLICY_FILE
+ *  (YAML/JSON file → BuiltinPolicyEngine) or OMCP_OPA_URL (external
+ *  OPA → OpaPolicyEngine). The gate consumes whichever via
+ *  `buildRequirePermissionFromEngine` so tenant-conditional Rego
+ *  rules can fire. */
 export declare const DEFAULT_POLICY: Record<string, Permission[]>;
 /** Resolve whether the given role set grants the requested permission. */
 export declare function hasPermission(roles: string[] | undefined, resource: Resource, action: Action, policy?: Record<string, Permission[]>): boolean;
@@ -34,6 +39,23 @@ export declare function hasPermission(roles: string[] | undefined, resource: Res
  * with no session means anonymous mode is active.
  */
 export declare function buildRequirePermission(runtime: AuthRuntime, resource: Resource, action: Action, policy?: Record<string, Permission[]>): RequestHandler;
+/**
+ * Engine-aware variant of `buildRequirePermission`. Prefer this when an
+ * external policy engine (OPA, custom Rego) is in play — the legacy
+ * `(roles, resource, action) → boolean` map cannot carry the active
+ * tenant, so a Rego rule like `allow { input.tenant == "acme" }` can
+ * never fire if you go through the map. This variant calls
+ * `engine.evaluate(roles, resource, action, { tenant: session.tenant })`
+ * so tenant-conditional rules see the input they need.
+ *
+ * Anonymous mode stays a no-op — same as the map variant.
+ *
+ * Performance: `evaluate` is sync by contract. OPA hits its cache; on
+ * first miss it returns a conservative deny and warms in the
+ * background — the second request inside the TTL gets the real
+ * verdict. Documented in opa.ts.
+ */
+export declare function buildRequirePermissionFromEngine(runtime: AuthRuntime, resource: Resource, action: Action, engine: PolicyEngine): RequestHandler;
 /** Convenience snapshot for `/api/me` — list every permission the
  * given role set unlocks. Used by the UI to hide write controls the
  * current user can't trigger anyway. */

package/dist/auth/rbac.js

@@ -14,7 +14,11 @@
  * Basic mode runs every mutating /api/* request through `requirePermission`
  * middleware (mounted in index.ts alongside `requireSession`).
  */
-/** Built-in default policy. Operators can replace this via OMCP_RBAC_POLICY in a follow-up. */
+/** Built-in default policy. Operators replace this via OMCP_RBAC_POLICY_FILE
+ *  (YAML/JSON file → BuiltinPolicyEngine) or OMCP_OPA_URL (external
+ *  OPA → OpaPolicyEngine). The gate consumes whichever via
+ *  `buildRequirePermissionFromEngine` so tenant-conditional Rego
+ *  rules can fire. */
 export const DEFAULT_POLICY = {
     viewer: [
         { resource: "sources", action: "read" },
@@ -96,6 +100,44 @@ export function buildRequirePermission(runtime, resource, action, policy = DEFAU
         });
     };
 }
+/**
+ * Engine-aware variant of `buildRequirePermission`. Prefer this when an
+ * external policy engine (OPA, custom Rego) is in play — the legacy
+ * `(roles, resource, action) → boolean` map cannot carry the active
+ * tenant, so a Rego rule like `allow { input.tenant == "acme" }` can
+ * never fire if you go through the map. This variant calls
+ * `engine.evaluate(roles, resource, action, { tenant: session.tenant })`
+ * so tenant-conditional rules see the input they need.
+ *
+ * Anonymous mode stays a no-op — same as the map variant.
+ *
+ * Performance: `evaluate` is sync by contract. OPA hits its cache; on
+ * first miss it returns a conservative deny and warms in the
+ * background — the second request inside the TTL gets the real
+ * verdict. Documented in opa.ts.
+ */
+export function buildRequirePermissionFromEngine(runtime, resource, action, engine) {
+    if (runtime.mode === "anonymous") {
+        return function rbacNoop(_req, _res, next) {
+            next();
+        };
+    }
+    return function rbacGateEngine(req, res, next) {
+        const sess = req.session;
+        const verdict = engine.evaluate(sess?.roles, resource, action, { tenant: sess?.tenant });
+        if (verdict.allowed) {
+            next();
+            return;
+        }
+        res.status(403).json({
+            error: "permission denied",
+            code: "OMCP_PERMISSION_DENIED",
+            required: { resource, action },
+            have: sess?.roles ?? [],
+            reason: verdict.reason,
+        });
+    };
+}
 /** Convenience snapshot for `/api/me` — list every permission the
  * given role set unlocks. Used by the UI to hide write controls the
  * current user can't trigger anyway. */

package/dist/auth/rbac.test.js

@@ -119,3 +119,65 @@ test("DEFAULT_POLICY shape — has the three built-in roles", () => {
     assert.ok(DEFAULT_POLICY.operator);
     assert.ok(DEFAULT_POLICY.admin);
 });
+import { buildRequirePermissionFromEngine } from "./rbac.js";
+import { BuiltinPolicyEngine } from "./policy/engine.js";
+test("buildRequirePermissionFromEngine — anonymous always allows (no-op middleware)", () => {
+    const engine = new BuiltinPolicyEngine(DEFAULT_POLICY);
+    const mw = buildRequirePermissionFromEngine({ mode: "anonymous" }, "sources", "write", engine);
+    const res = mkRes();
+    let called = false;
+    mw(mkReq(), res, () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(res.statusCode, 0);
+});
+test("buildRequirePermissionFromEngine — engine.evaluate verdict is surfaced verbatim in the 403 body", () => {
+    // Spy engine returns a custom reason so we can prove the gate forwards it.
+    const engine = {
+        evaluate: () => ({ allowed: false, reason: "test deny reason from engine" }),
+        list: () => [],
+        roles: () => [],
+        kind: () => "test",
+    };
+    const runtime = { mode: "basic", session: { secret: "x".repeat(48) } };
+    const mw = buildRequirePermissionFromEngine(runtime, "sources", "write", engine);
+    const res = mkRes();
+    mw(mkReq(["viewer"]), res, () => undefined);
+    assert.equal(res.statusCode, 403);
+    const body = res.body;
+    assert.equal(body.code, "OMCP_PERMISSION_DENIED");
+    assert.equal(body.reason, "test deny reason from engine");
+});
+test("buildRequirePermissionFromEngine — passes session.tenant into engine.evaluate's EvalContext (load-bearing for OPA tenant rules)", () => {
+    // This is the property the OPA-input-tenant refine relies on:
+    // the gate MUST pass session.tenant to engine.evaluate so a Rego
+    // rule like `allow { input.tenant == "acme" }` can fire. Capture
+    // the ctx and assert it carries the tenant verbatim.
+    let seenCtx;
+    const engine = {
+        evaluate: (_roles, _r, _a, ctx) => {
+            seenCtx = ctx;
+            return { allowed: true, reason: "ok" };
+        },
+        list: () => [],
+        roles: () => [],
+        kind: () => "spy",
+    };
+    const runtime = { mode: "basic", session: { secret: "x".repeat(48) } };
+    const mw = buildRequirePermissionFromEngine(runtime, "sources", "read", engine);
+    const res = mkRes();
+    const req = {
+        session: { sub: "u", name: "u", roles: ["viewer"], tenant: "acme", iat: 0, exp: Date.now() / 1000 + 60 },
+    };
+    mw(req, res, () => undefined);
+    assert.equal(seenCtx?.tenant, "acme", "tenant from session must flow into engine.evaluate ctx");
+});
+test("buildRequirePermissionFromEngine — sessionless basic-mode request denies via engine (roles undefined → no permission)", () => {
+    const engine = new BuiltinPolicyEngine(DEFAULT_POLICY);
+    const runtime = { mode: "basic", session: { secret: "x".repeat(48) } };
+    const mw = buildRequirePermissionFromEngine(runtime, "sources", "read", engine);
+    const res = mkRes();
+    let called = false;
+    mw(mkReq(), res, () => { called = true; });
+    assert.equal(called, false);
+    assert.equal(res.statusCode, 403);
+});

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");
+});