@thotischner/observability-mcp 1.8.1 → 3.0.0

package/dist/auth/policy/loader.js

@@ -27,6 +27,7 @@ import { BuiltinPolicyEngine } from "./engine.js";
 export const VALID_RESOURCES = new Set([
     "sources", "services", "health", "topology", "settings",
     "connectors", "audit", "catalog", "users", "redaction",
+    "products",
 ]);
 export const VALID_ACTIONS = new Set(["read", "write", "delete", "bypass"]);
 export class PolicyLoadError extends Error {
@@ -98,3 +99,39 @@ export function loadPolicyFromFile(path) {
     }
     return loadPolicyFromString(text, `file:${path}`);
 }
+/** Render a policy map into the YAML/JSON shape the loader reads.
+ *  Pure helper — separated from the file-write step so a future
+ *  PolicyEngine implementation that doesn't speak the file format
+ *  can compose differently. */
+export function serializePolicy(policy) {
+    // Lock in the field order so a round-trip-through-this-function
+    // is stable diffs in a version-controlled file. Roles sorted
+    // alphabetically; grants sorted by (resource, action) inside
+    // each role.
+    const rolesOut = {};
+    for (const role of Object.keys(policy).sort()) {
+        const grants = policy[role] || [];
+        const sorted = grants
+            .slice()
+            .sort((a, b) => (a.resource + ":" + a.action).localeCompare(b.resource + ":" + b.action))
+            .map((g) => ({ resource: g.resource, action: g.action }));
+        rolesOut[role] = sorted;
+    }
+    return yaml.dump({ roles: rolesOut }, { sortKeys: false, lineWidth: 100 });
+}
+/** Atomic write of the policy file. Same tmp+rename pattern used by
+ *  products + users — a crash mid-write leaves the previous file
+ *  intact. mode 0o600 so the on-disk RBAC catalogue isn't
+ *  world-readable on multi-tenant hosts. */
+export async function writePolicyFile(path, policy) {
+    // Validate via the parse path before writing — a bad input
+    // shape would otherwise produce a file the boot loader then
+    // rejects (fail-closed reboot). Validate-then-write keeps the
+    // good-policy invariant.
+    loadPolicyFromString(serializePolicy(policy), "(in-memory)");
+    const { writeFile, rename } = await import("node:fs/promises");
+    const text = serializePolicy(policy);
+    const tmp = path + ".tmp";
+    await writeFile(tmp, text, { encoding: "utf8", mode: 0o600 });
+    await rename(tmp, path);
+}

package/dist/auth/policy/loader.test.d.ts

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

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

@@ -0,0 +1,86 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { writePolicyFile, loadPolicyFromFile, loadPolicyFromString, serializePolicy, VALID_RESOURCES } from "./loader.js";
+import { BuiltinPolicyEngine } from "./engine.js";
+test("VALID_RESOURCES — includes products (closes a pre-existing inconsistency vs rbac.ts)", () => {
+    assert.ok(VALID_RESOURCES.has("products"), "products must be a recognised resource for file-loaded policies");
+});
+test("serializePolicy — round-trips through the parser cleanly", () => {
+    const text = serializePolicy({
+        admin: [
+            { resource: "sources", action: "delete" },
+            { resource: "users", action: "delete" },
+        ],
+        viewer: [{ resource: "sources", action: "read" }],
+    });
+    // Parsing the serialised text via loadPolicyFromString must yield
+    // an engine with the same role grants — round-trip is stable.
+    const e = loadPolicyFromString(text, "test");
+    assert.deepEqual(e.roles().sort(), ["admin", "viewer"]);
+    const admin = e.list(["admin"]).map((p) => p.resource + ":" + p.action).sort();
+    assert.deepEqual(admin, ["sources:delete", "users:delete"]);
+});
+test("serializePolicy — deterministic ordering (roles + grants both sorted)", () => {
+    const a = serializePolicy({
+        z: [{ resource: "sources", action: "write" }, { resource: "audit", action: "read" }],
+        a: [{ resource: "users", action: "read" }],
+    });
+    const b = serializePolicy({
+        a: [{ resource: "users", action: "read" }],
+        z: [{ resource: "audit", action: "read" }, { resource: "sources", action: "write" }],
+    });
+    // Same logical policy → byte-identical text. Important for git-diff sanity.
+    assert.equal(a, b);
+});
+test("writePolicyFile — atomic round-trip preserves shape", async () => {
+    const { mkdtemp, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-policy-"));
+    try {
+        const path = join(dir, "policy.yaml");
+        await writePolicyFile(path, {
+            admin: [{ resource: "sources", action: "delete" }],
+            operator: [{ resource: "sources", action: "write" }],
+        });
+        const engine = loadPolicyFromFile(path);
+        assert.deepEqual(engine.roles().sort(), ["admin", "operator"]);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("writePolicyFile — rejects an invalid resource before writing the file", async () => {
+    const { mkdtemp, rm, readdir } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-policy-reject-"));
+    try {
+        const path = join(dir, "policy.yaml");
+        await assert.rejects(writePolicyFile(path, {
+            admin: [{ resource: "nope", action: "read" }],
+        }), /unknown/i);
+        // No file (or tmp) was created — validate-then-write held.
+        const entries = await readdir(dir);
+        assert.deepEqual(entries, []);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("BuiltinPolicyEngine.replace — mutates the inner map in place (gate closures see the new policy)", () => {
+    const engine = new BuiltinPolicyEngine({
+        admin: [{ resource: "sources", action: "delete" }],
+    });
+    // Capture a reference to the raw map BEFORE replace — verify the
+    // reference is preserved (hot-swap, not reassign).
+    const before = engine.raw();
+    engine.replace({
+        admin: [{ resource: "sources", action: "delete" }, { resource: "audit", action: "read" }],
+        viewer: [{ resource: "sources", action: "read" }],
+    });
+    assert.equal(before, engine.raw(), "raw() must return the same object reference after replace()");
+    assert.deepEqual(engine.roles().sort(), ["admin", "viewer"]);
+    assert.equal(engine.evaluate(["admin"], "audit", "read").allowed, true);
+    assert.equal(engine.evaluate(["viewer"], "sources", "read").allowed, true);
+});

package/dist/auth/policy/opa.d.ts

@@ -27,7 +27,7 @@
  * for auth/oidc/, and OPA traffic stays inside the cluster).
  */
 import type { Permission, Resource, Action } from "../rbac.js";
-import type { PolicyEngine, EvalResult } from "./engine.js";
+import type { PolicyEngine, EvalResult, EvalContext } from "./engine.js";
 export type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
 export interface OpaConfig {
     /** Base URL, e.g. http://opa:8181 (no trailing slash). */
@@ -57,13 +57,13 @@ export declare class OpaPolicyEngine implements PolicyEngine {
     private cacheKey;
     private now;
     private query;
-    evaluate(roles: string[] | undefined, resource: Resource, action: Action): EvalResult;
+    evaluate(roles: string[] | undefined, resource: Resource, action: Action, ctx?: EvalContext): EvalResult;
     /** 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. */
-    warmEvaluate(roles: string[], resource: string, action: string): Promise<EvalResult>;
-    list(roles: string[] | undefined): Permission[];
-    warmList(roles: string[]): Promise<Permission[]>;
+    warmEvaluate(roles: string[], resource: string, action: string, tenant?: string): Promise<EvalResult>;
+    list(roles: string[] | undefined, ctx?: EvalContext): Permission[];
+    warmList(roles: string[], tenant?: string): Promise<Permission[]>;
     roles(): string[];
     kind(): string;
 }

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