@cyanmycelium/mcp-broker 1.4.0 → 1.5.0

package/.mcp-broker.example/README.md

@@ -23,6 +23,14 @@ factory deployment. Two consequences.
    use. A missing directory is skipped with a warning; a missing TLS file stops
    startup, with a message naming the two files and the three ways out.
 
+3. **`security.example.json` is the other way to hold `auth`** (broker 1.5.0):
+   a separate security file with one identity and secret per provider and the
+   protected slots, apart from the topology. To use it, rename it
+   `security.json`, add `"securityFile": "security.json"` to `config.json`, and
+   **delete the `auth` block from `config.json`**: the broker refuses to start
+   with `auth` in both files. Each provider's secret comes from the environment
+   variable its entry names, never from the file.
+
 So a straight `cp -r` does not run yet. Do one of these first:
 
 ```sh

package/.mcp-broker.example/security.example.json

@@ -0,0 +1,42 @@
+{
+    "description": "Security settings, kept apart from config.json. Name this file from config.json with \"securityFile\": \"security.json\", or with MCP_BROKER_SECURITY_FILE. No secret is written here: each provider names the environment variable that holds its own.",
+    "auth": {
+        "enabled": true,
+        "publicBaseUrl": "https://broker.example.com",
+        "authorizationServers": ["https://login.example.com"],
+        "jwks": "https://login.example.com/.well-known/jwks.json",
+        "requiredScopes": ["mcp:call"],
+        "subjectMapping": { "userClaim": "sub", "groupClaims": ["groups"], "serviceClaims": ["service"] },
+        "slotResources": {
+            "scada": "/production/site1/scada",
+            "bench-motor01": "/production/site1/bench/motor01"
+        },
+        "roles": {
+            "mcp-caller": { "capabilities": ["mcp.tools.list", "mcp.tools.call"] },
+            "scada-observer": { "inherits": ["mcp-caller"], "capabilities": ["scada.observe"] },
+            "scada-operator": { "inherits": ["scada-observer"], "capabilities": ["scada.acquire", "scada.control"] }
+        },
+        "assignments": [
+            { "id": "line1-operators", "subject": "group:operators-line1", "role": "scada-operator", "resource": "/production/site1/line1/**" },
+            { "id": "scada-service", "subject": "service:mcp-scada", "role": "mcp-caller", "resource": "/production/site1/**" }
+        ]
+    },
+    "providers": [
+        {
+            "id": "mcp-scada",
+            "secretEnv": "SCADA_PROVIDER_SECRET",
+            "subjects": ["service:mcp-scada"],
+            "allowedResources": ["/production/site1/**"]
+        },
+        {
+            "id": "modbus-bench",
+            "secretEnv": "MODBUS_PROVIDER_SECRET",
+            "allowedResources": ["/production/site1/bench/**"]
+        }
+    ],
+    "authorization": {
+        "protectedSlots": {
+            "bench-motor01": { "declaredBy": "mcp-scada", "publishedBy": "modbus-bench" }
+        }
+    }
+}

package/README.md

@@ -79,6 +79,10 @@ the observable signatures are worth knowing:
 
 `broker_diagnose` reports the first as `transport-path-mismatch`.
 
+> **Testing?** `startTestBroker()` from `@cyanmycelium/mcp-broker/testing` runs a
+> real broker in one call, with callers that need no authorization server. See
+> [docs/testing.md](docs/testing.md).
+
 ## Configuration
 
 Two sources, env vars **always win** over the file. The file is the static baseline you ship with the broker; env vars are deploy-specific overrides.
@@ -159,6 +163,8 @@ This table is complete: it lists every `MCP_BROKER_*` variable the CLI reads.
 | `MCP_BROKER_PROVIDER_HEARTBEAT_MS` | `30000` | ws-level ping interval on provider sockets. `0` disables |
 | `MCP_BROKER_PROVIDER_REQUEST_TIMEOUT_MS` | `60000` | How long a provider has to answer one request before it is failed. `0` disables |
 | `MCP_BROKER_PROVIDER_TAKEOVER` | `liveness` | `reject`, `liveness` or `always` when a second provider claims an occupied slot |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | (unset) | Standard OpenTelemetry full traces endpoint. Enables provider telemetry export |
+| `OTEL_EXPORTER_OTLP_HEADERS` | (unset) | Standard comma-separated, percent-encoded OTLP headers |
 | `MCP_BROKER_WWW_DIR` | (unset) | If set, serve this directory at `/` |
 | `MCP_BROKER_BUNDLE_DIR` | (unset) | If set, serve this directory at `/bundle` |
 | `MCP_BROKER_OPEN` | (unset) | `1` opens the broker root on startup; a `/path` or a same-origin absolute URL opens that page. Opens only when a static mount actually covers the resolved path |
@@ -361,6 +367,110 @@ class GaugeAdapter extends McpAdapterBase {
 }
 ```
 
+## Provider telemetry and OTLP
+
+The complete protocol and deployment contract is in
+[docs/telemetry.md](https://github.com/pandaGaume/mcp-broker/blob/main/docs/telemetry.md).
+
+The optional telemetry extension accepts `broker/telemetry` from any
+provider slot. The broker consumes these notifications itself. It never sends
+them to MCP clients, and it never waits for the exporter while routing requests
+or responses.
+
+The pipeline has explicit bounds. By default it accepts frames up to 64 KiB,
+queues at most 256 spans, exports batches of up to 32, and drops new telemetry
+when the queue is full. `getTelemetryStats()` reports every accepted, exported,
+and dropped span. A trace failure therefore cannot block MCP control traffic.
+
+For the CLI, set the standard OpenTelemetry environment variable:
+
+```sh
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces mcp-broker
+```
+
+`OTEL_EXPORTER_OTLP_HEADERS` carries optional comma-separated, percent-encoded
+headers. The same settings can be kept in `config.json` under `telemetry`:
+
+```json
+{
+    "telemetry": {
+        "otlpHttpEndpoint": "http://otel-collector:4318/v1/traces",
+        "timeoutMs": 5000,
+        "queueCapacity": 256,
+        "batchSize": 32
+    }
+}
+```
+
+Configure the built-in dependency-free OTLP/HTTP JSON exporter:
+
+```ts
+import { WsTunnelBuilder } from "@cyanmycelium/mcp-broker";
+
+const broker = new WsTunnelBuilder()
+    .withPort(3000)
+    .withOtlpHttpTelemetry(
+        {
+            endpoint: "http://otel-collector:4318/v1/traces",
+            headers: { Authorization: `Bearer ${process.env.OTLP_TOKEN}` },
+        },
+        {
+            queueCapacity: 512,
+            batchSize: 32,
+            onExportError: (error) => console.error("telemetry export failed", error),
+        }
+    )
+    .build();
+```
+
+Or pass any sink with `withTelemetry({ exporter })`. This is useful for a file,
+Kafka, an existing OpenTelemetry SDK, or a deterministic test collector.
+
+Provider wire format:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "broker/telemetry",
+    "params": {
+        "version": 1,
+        "signal": "traces",
+        "span": {
+            "traceId": "0123456789abcdef0123456789abcdef",
+            "spanId": "0123456789abcdef",
+            "parentSpanId": "fedcba9876543210",
+            "name": "modbus.read",
+            "kind": 3,
+            "startTimeUnixNano": "1720000000000000000",
+            "endTimeUnixNano": "1720000000001000000",
+            "attributes": {
+                "modbus.function_code": 3,
+                "network.transport": "tcp"
+            },
+            "events": [
+                {
+                    "name": "pdu.rx",
+                    "timeUnixNano": "1720000000000900000",
+                    "attributes": { "bytes": 9 }
+                }
+            ],
+            "status": { "code": 1 }
+        }
+    }
+}
+```
+
+Trace IDs and parent relationships follow W3C Trace Context representation.
+Every routed request carries the context in `params._meta.traceparent`.
+TypeScript providers can continue it with `traceparentOf()`,
+`childTraceparent()` and `withTraceparent()`, then emit with
+`transport.broker.span(span)`. The exporter produces an OTLP
+`ExportTraceServiceRequest`. `service.name` is the authenticated provider
+principal when available, otherwise the slot. `mcp.provider.slot` always keeps
+the slot, and `mcp.provider.principal` records the authenticated identity. Raw
+protocol payloads are not required by the schema. A provider should emit them
+only when its own runtime trace policy explicitly enables that level of detail.
+
 ## Authorization (OAuth 2.1)
 
 By default the broker performs **no** authentication. That is fine behind a

package/dist/bin.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { PACKAGE_NAME, VERSION, loadBrokerConfig, WsTunnelBuilder, loadMcpbBundle, BROKER_AGGREGATE_NAME, BROKER_PROVIDER_NAME, resolveOpenTarget } from './chunk-YTRVLPHP.js';
+import { loadBrokerConfig, loadSecurityConfig, BrokerConfigError, loadMcpbBundle, resolveOpenTarget } from './chunk-BTWLF6KI.js';
+import { PACKAGE_NAME, VERSION, WsTunnelBuilder, BROKER_AGGREGATE_NAME, BROKER_PROVIDER_NAME } from './chunk-K2EQP4RQ.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import open from 'open';
@@ -59,6 +60,10 @@ PROVIDER LIVENESS
   MCP_BROKER_PROVIDER_REQUEST_TIMEOUT_MS Deadline for one provider answer (default 60000, 0 off)
   MCP_BROKER_PROVIDER_TAKEOVER           reject | liveness | always (default liveness)
 
+PROVIDER TELEMETRY (OpenTelemetry, opt-in)
+  OTEL_EXPORTER_OTLP_TRACES_ENDPOINT     Full OTLP/HTTP endpoint, enables trace export
+  OTEL_EXPORTER_OTLP_HEADERS             Comma-separated percent-encoded key=value headers
+
 AUTHORIZATION (OAuth 2.1, opt-in)
   MCP_BROKER_AUTH_ENABLED     "1" to require bearer tokens on client endpoints
   MCP_BROKER_PUBLIC_BASE_URL  Public origin, e.g. https://mcp.example.com
@@ -87,8 +92,20 @@ Full reference: https://github.com/pandaGaume/mcp-broker/tree/main/node
 `
   );
 }
-var { config, baseDir } = loadBrokerConfig();
+function loadConfigOrExit() {
+  try {
+    const loaded = loadBrokerConfig();
+    return { ...loaded, security: loadSecurityConfig(loaded) };
+  } catch (error) {
+    if (!(error instanceof BrokerConfigError)) throw error;
+    process.stderr.write(`${error.message}
+`);
+    process.exit(1);
+  }
+}
+var { config, baseDir, security } = loadConfigOrExit();
 var cwd = process.cwd();
+var authConfig = security?.security.auth ?? config.auth;
 function envFromConfig(envName, configValue) {
   if (configValue === void 0 || configValue === null) return;
   if (process.env[envName] !== void 0 && process.env[envName] !== "") return;
@@ -112,11 +129,11 @@ envFromConfig("MCP_BROKER_MAX_SUBSCRIPTIONS_PER_SLOT", config.resourceSubscripti
 envFromConfig("MCP_BROKER_MAX_RESOURCE_URI_LENGTH", config.resourceSubscriptions?.maxResourceUriLength);
 envFromConfig("MCP_BROKER_PROVIDER_TAKEOVER", config.providerTakeover);
 envFromConfig("MCP_BROKER_OPEN", config.www?.open === true ? "1" : typeof config.www?.open === "string" ? config.www.open : void 0);
-envFromConfig("MCP_BROKER_AUTH_ENABLED", config.auth?.enabled === true ? "1" : void 0);
-envFromConfig("MCP_BROKER_PUBLIC_BASE_URL", config.auth?.publicBaseUrl);
-envFromConfig("MCP_BROKER_JWKS", config.auth?.jwks);
-envFromConfig("MCP_BROKER_ISSUER", config.auth?.issuer);
-envFromConfig("MCP_BROKER_PROVIDER_SECRET", config.auth?.providerSecret);
+envFromConfig("MCP_BROKER_AUTH_ENABLED", authConfig?.enabled === true ? "1" : void 0);
+envFromConfig("MCP_BROKER_PUBLIC_BASE_URL", authConfig?.publicBaseUrl);
+envFromConfig("MCP_BROKER_JWKS", authConfig?.jwks);
+envFromConfig("MCP_BROKER_ISSUER", authConfig?.issuer);
+envFromConfig("MCP_BROKER_PROVIDER_SECRET", authConfig?.providerSecret);
 var stdioProvider = process.env["MCP_BROKER_STDIO_PROVIDER"];
 if (stdioProvider) {
   const toStderr = (...args) => process.stderr.write(args.join(" ") + "\n");
@@ -133,6 +150,27 @@ var clientPath = process.env["MCP_BROKER_CLIENT_PATH"] ?? "/";
 var mcpPath = process.env["MCP_BROKER_MCP_PATH"] ?? "/mcp";
 var ssePath = process.env["MCP_BROKER_SSE_PATH"] ?? "/sse";
 var messagesPath = process.env["MCP_BROKER_MESSAGES_PATH"] ?? "/messages";
+var otlpTracesEndpoint = process.env["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] ?? config.telemetry?.otlpHttpEndpoint;
+function otlpHeadersFromEnv(raw) {
+  const headers = {};
+  if (!raw) return headers;
+  for (const field of raw.split(",")) {
+    const separator = field.indexOf("=");
+    if (separator <= 0) {
+      console.warn(`[mcp-broker] Ignoring malformed OTEL_EXPORTER_OTLP_HEADERS field: ${JSON.stringify(field)}.`);
+      continue;
+    }
+    try {
+      const key = decodeURIComponent(field.slice(0, separator).trim());
+      const value = decodeURIComponent(field.slice(separator + 1).trim());
+      if (key) headers[key] = value;
+    } catch {
+      console.warn(`[mcp-broker] Ignoring malformed percent encoding in OTEL_EXPORTER_OTLP_HEADERS field: ${JSON.stringify(field)}.`);
+    }
+  }
+  return headers;
+}
+var otlpHeaders = { ...config.telemetry?.headers ?? {}, ...otlpHeadersFromEnv(process.env["OTEL_EXPORTER_OTLP_HEADERS"]) };
 var tlsCertPath = process.env["MCP_BROKER_TLS_CERT"] ? path.resolve(cwd, process.env["MCP_BROKER_TLS_CERT"]) : config.tls?.cert ? path.resolve(baseDir, config.tls.cert) : null;
 var tlsKeyPath = process.env["MCP_BROKER_TLS_KEY"] ? path.resolve(cwd, process.env["MCP_BROKER_TLS_KEY"]) : config.tls?.key ? path.resolve(baseDir, config.tls.key) : null;
 var protocolOverride = process.env["MCP_BROKER_PROTOCOL"]?.toLowerCase();
@@ -215,6 +253,34 @@ function warnIfStdioTargetUnknown(target) {
     `[mcp-broker] MCP_BROKER_STDIO_PROVIDER="${target}" names a slot this broker does not host. Nothing answers on it until a WebSocket provider connects to ${providerPath}/${target} (or announces "${target}" on ${providersPath}), and until then every request from the MCP host, including the initial handshake, fails with 'Provider "${target}" not connected'. An MCP host that starts before that provider is up, which is always the case for a provider hosted in a browser page, will therefore never connect. Prefer MCP_BROKER_STDIO_PROVIDER="${BROKER_AGGREGATE_NAME}": it exists from startup, answers the handshake itself, unions every opted-in provider, and pushes notifications/tools/list_changed as providers join, so a page opened later appears live. Slots this broker hosts right now: ${hosted.length > 0 ? hosted.map((n) => `"${n}"`).join(", ") + `, plus the reserved "${BROKER_AGGREGATE_NAME}" and "${BROKER_PROVIDER_NAME}"` : `the reserved "${BROKER_AGGREGATE_NAME}" and "${BROKER_PROVIDER_NAME}" only`}.`
   );
 }
+function telemetryExportLogger(intervalMs = 6e4) {
+  let failures = 0;
+  let suppressed = 0;
+  let lastReport = 0;
+  return {
+    error(error) {
+      failures++;
+      const now = Date.now();
+      if (lastReport === 0 || now - lastReport >= intervalMs) {
+        const suffix = suppressed > 0 ? ` (${suppressed} repeated failure(s) suppressed)` : "";
+        console.error(`[mcp-broker] telemetry export failed: ${error.message}${suffix}`);
+        lastReport = now;
+        suppressed = 0;
+      } else {
+        suppressed++;
+      }
+    },
+    success(recordCount) {
+      if (failures === 0) return;
+      console.info(
+        `[mcp-broker] telemetry export recovered after ${failures} failed batch(es)${suppressed > 0 ? `, ${suppressed} repeated log line(s) suppressed` : ""}; exported ${recordCount} span(s).`
+      );
+      failures = 0;
+      suppressed = 0;
+      lastReport = 0;
+    }
+  };
+}
 async function main() {
   const localGrammarsDir = path.join(baseDir, "grammars");
   const hasLocalGrammars = fs.existsSync(localGrammarsDir);
@@ -235,6 +301,26 @@ async function main() {
   if (providerTakeover) {
     builder.withProviderTakeover(providerTakeover);
   }
+  if (otlpTracesEndpoint) {
+    const exportLog = telemetryExportLogger();
+    builder.withOtlpHttpTelemetry(
+      {
+        endpoint: otlpTracesEndpoint,
+        headers: otlpHeaders,
+        timeoutMs: config.telemetry?.timeoutMs,
+        serviceNamespace: config.telemetry?.serviceNamespace
+      },
+      {
+        maxFrameBytes: config.telemetry?.maxFrameBytes,
+        queueCapacity: config.telemetry?.queueCapacity,
+        batchSize: config.telemetry?.batchSize,
+        maxAttributes: config.telemetry?.maxAttributes,
+        maxEvents: config.telemetry?.maxEvents,
+        onExportError: exportLog.error,
+        onExportSuccess: exportLog.success
+      }
+    );
+  }
   if (useTls) {
     try {
       builder.withTlsFiles(tlsCertPath, tlsKeyPath);
@@ -306,7 +392,7 @@ async function main() {
     const publicBaseUrl = process.env["MCP_BROKER_PUBLIC_BASE_URL"];
     const jwks = process.env["MCP_BROKER_JWKS"];
     const issuer = process.env["MCP_BROKER_ISSUER"];
-    const authorizationServers = config.auth?.authorizationServers ?? (issuer ? [issuer] : []);
+    const authorizationServers = authConfig?.authorizationServers ?? (issuer ? [issuer] : []);
     if (!publicBaseUrl || !jwks || authorizationServers.length === 0) {
       console.error(
         "[mcp-broker] auth.enabled requires publicBaseUrl, jwks, and at least one authorizationServers entry (or issuer). Set them via config.auth or MCP_BROKER_PUBLIC_BASE_URL / MCP_BROKER_JWKS / MCP_BROKER_ISSUER."
@@ -318,25 +404,37 @@ async function main() {
       authorizationServers,
       jwksUri: jwks,
       issuer,
-      scopesSupported: config.auth?.scopesSupported,
-      requiredScopes: config.auth?.requiredScopes,
-      perSlotScopes: config.auth?.perSlotScopes,
-      providerScopes: config.auth?.providerScopes,
-      subjectMapping: config.auth?.subjectMapping,
-      roles: config.auth?.roles,
-      assignments: config.auth?.assignments,
-      denies: config.auth?.denies,
-      slotResources: config.auth?.slotResources,
-      toolCapabilities: config.auth?.toolCapabilities,
-      providerToolCapabilities: config.auth?.providerToolCapabilities,
-      audit: config.auth?.audit
+      scopesSupported: authConfig?.scopesSupported,
+      requiredScopes: authConfig?.requiredScopes,
+      perSlotScopes: authConfig?.perSlotScopes,
+      providerScopes: authConfig?.providerScopes,
+      subjectMapping: authConfig?.subjectMapping,
+      roles: authConfig?.roles,
+      assignments: authConfig?.assignments,
+      denies: authConfig?.denies,
+      slotResources: authConfig?.slotResources,
+      toolCapabilities: authConfig?.toolCapabilities,
+      providerToolCapabilities: authConfig?.providerToolCapabilities,
+      audit: authConfig?.audit
     });
   }
   const providerSecret = process.env["MCP_BROKER_PROVIDER_SECRET"];
   if (providerSecret) {
     builder.withProviderSecret(providerSecret);
   }
-  const tunnel = builder.build();
+  let tunnel;
+  try {
+    if (security) {
+      if (security.credentials.length > 0) builder.withProviderPrincipals(security.credentials);
+      const protectedSlots = security.security.authorization?.protectedSlots;
+      if (protectedSlots && Object.keys(protectedSlots).length > 0) builder.withProtectedSlots(protectedSlots);
+      builder.withSecurityVersion(security.version);
+    }
+    tunnel = builder.build();
+  } catch (error) {
+    console.error(`[mcp-broker] ${error.message}`);
+    process.exit(1);
+  }
   await tunnel.start();
   const httpScheme = useTls ? "https" : "http";
   const wsScheme = useTls ? "wss" : "ws";
@@ -365,12 +463,20 @@ async function main() {
     console.log(`\u{1F310}  Local grammars        ${localGrammarsDir}`);
   }
   console.log(`\u{1F510}  Authorization         ${authEnabled ? "OAuth 2.1 (Bearer required)" : "disabled (trusted network only)"}`);
-  console.log(`\u{1F6E1}\uFE0F   Provider auth         ${providerSecret ? "shared secret required" : "disabled"}`);
+  const providerIdentities = security?.credentials.length ?? 0;
+  console.log(
+    `\u{1F6E1}\uFE0F   Provider auth         ${providerIdentities > 0 ? `${providerIdentities} provider identit${providerIdentities === 1 ? "y" : "ies"}${providerSecret ? " + shared secret" : ""}` : providerSecret ? "shared secret required" : "disabled"}`
+  );
+  if (security) {
+    const protectedCount = Object.keys(security.security.authorization?.protectedSlots ?? {}).length;
+    console.log(`\u{1F50F}  Security file         ${security.sourcePath} (version ${security.version}${protectedCount > 0 ? `, ${protectedCount} protected slot(s)` : ""})`);
+  }
   console.log(`\u{1F30D}  Browser origins       ${describeAllowedOrigins()}`);
   console.log(`                          enforced on /<name>/${mcpSuffix}, /<name>/${sseSuffix} and /<name>/${messagesSuffix}`);
   if (!allowedOrigins) {
     console.log(`                          a page this broker serves is refused too, list its origin to admit it`);
   }
+  console.log(`\u{1F4C8}  Provider telemetry    ${otlpTracesEndpoint ? `OTLP/HTTP to ${otlpTracesEndpoint}` : "disabled"}`);
   console.log(hr);
   console.log(`   New here? Call broker_guide on the ${BROKER_PROVIDER_NAME} slot: ${localhost}/${BROKER_PROVIDER_NAME}/${mcpSuffix}`);
   console.log(`   Press Ctrl+C to stop.`);