@stigmer/mcp-server 3.0.8-dev.20260612122433

package/server.js

@@ -0,0 +1,366 @@
+// Server construction, tool registration, and transport entry points.
+//
+// Mirrors Go internal/server (server.go + http.go) plus the lifecycle helpers
+// from pkg/mcpserver/run.go. The server is stateless: every per-request value
+// (the credential, and thus the gRPC client) is derived from the transport's
+// auth context, so the registration is identical regardless of transport.
+//
+// One structural difference from Go is called out in DD-008: the TS McpServer
+// "assumes ownership" of a single transport, so `both` mode uses one McpServer
+// per transport rather than sharing a single instance across stdio + HTTP.
+import { createServer as createHttpServer } from "node:http";
+import { randomBytes, randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { registerAgentResources } from "./domains/agents/resources.js";
+import { registerAgentTools } from "./domains/agents/tools.js";
+import { registerMcpServerResources } from "./domains/mcpservers/resources.js";
+import { registerMcpServerTools } from "./domains/mcpservers/tools.js";
+import { registerSearchTools } from "./domains/search/tools.js";
+import { registerSkillResources } from "./domains/skills/resources.js";
+import { registerSkillTools } from "./domains/skills/tools.js";
+import { registerWorkflowExecutionTools } from "./domains/workflowexecutions/tools.js";
+import { registerTaskKindTools } from "./domains/workflows/taskkinds.js";
+import { registerWorkflowResources } from "./domains/workflows/resources.js";
+import { registerWorkflowTools } from "./domains/workflows/tools.js";
+import { registerValidateWorkflowYamlTool } from "./domains/workflows/validate.js";
+import { log } from "./logger.js";
+/**
+ * Server version. Overridable at publish/build time; "dev" otherwise, matching
+ * the Go server's ldflags fallback.
+ */
+export const SERVER_VERSION = process.env.STIGMER_MCP_VERSION || "dev";
+/** Grace period for draining in-flight HTTP requests on shutdown. */
+const HTTP_SHUTDOWN_GRACE_MS = 5_000;
+/**
+ * Well-known location (RFC 9728 §3.1) of the OAuth 2.0 Protected Resource
+ * Metadata document. Served only when OAuth discovery is enabled.
+ */
+const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+/**
+ * Build a configured MCP server with every Stigmer tool registered. The backend
+ * target (address + startup credential) is captured in each handler's closure.
+ */
+export function createServer(target) {
+    const server = new McpServer({ name: "mcp-server-stigmer", version: SERVER_VERSION });
+    registerTools(server, target);
+    registerResources(server, target);
+    return server;
+}
+/**
+ * Wire up every domain's tools. Each domain returns the names it registered so
+ * the startup log's count and roster cannot drift from what is actually wired,
+ * matching the Go server's startup log shape.
+ */
+function registerTools(server, target) {
+    const tools = [
+        ...registerSearchTools(server, target),
+        ...registerAgentTools(server, target),
+        ...registerMcpServerTools(server, target),
+        ...registerSkillTools(server, target),
+        ...registerWorkflowTools(server, target),
+        ...registerValidateWorkflowYamlTool(server, target),
+        ...registerTaskKindTools(server, target),
+        ...registerWorkflowExecutionTools(server, target),
+    ];
+    log.info("tools registered", { count: tools.length, tools });
+}
+/**
+ * Wire up every domain's resource templates (the discovery-to-read surface).
+ * Like {@link registerTools}, each domain returns the names it registered so the
+ * startup log stays accurate.
+ */
+function registerResources(server, target) {
+    const resources = [
+        ...registerAgentResources(server, target),
+        ...registerMcpServerResources(server, target),
+        ...registerSkillResources(server, target),
+        ...registerWorkflowResources(server, target),
+    ];
+    log.info("resources registered", { count: resources.length, resources });
+}
+/**
+ * Serve over stdin/stdout until the client disconnects or `signal` aborts.
+ *
+ * Resolves on a clean disconnect (the MCP discovery probe connects, lists
+ * tools/resources, then closes stdin → EOF). Protocol-level errors are logged
+ * but do not terminate the process, mirroring the Go server treating EOF /
+ * broken pipe as a normal shutdown rather than a failure.
+ */
+export async function serveStdio(server, signal) {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    return new Promise((resolve) => {
+        const onAbort = () => void server.close();
+        signal.addEventListener("abort", onAbort, { once: true });
+        // The low-level Server's onclose/onerror are user hooks (not overwritten by
+        // connect), so they are the safe place to observe lifecycle transitions.
+        server.server.onclose = () => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        };
+        server.server.onerror = (err) => log.error("mcp protocol error", { error: err.message });
+    });
+}
+/**
+ * Serve over Streamable HTTP until `signal` aborts.
+ *
+ * Each request carries its own credential via the Authorization header; the
+ * (non-validating) auth layer extracts it onto `req.auth`, which the transport
+ * surfaces to tool handlers as `extra.authInfo`. The application keeps no
+ * per-user state.
+ *
+ * Spike A established the concurrency model: the TS SDK binds one McpServer to
+ * one transport to one MCP session (a second `initialize` on a shared server
+ * fails with "Server already initialized"). Unlike Go — whose SDK multiplexes
+ * sessions over a single shared `*mcp.Server` — the TS server keeps a registry
+ * of `sessionId → transport`, each built from `makeServer` on `initialize`. The
+ * per-request Bearer passthrough is orthogonal and applies on every request.
+ *
+ * Each request is wrapped in access logging (16-hex request id, method, path,
+ * status, duration) and, when OAuth discovery is enabled, RFC 9728 metadata is
+ * served and a WWW-Authenticate challenge is attached to token-less requests.
+ * DNS-rebinding allow-lists are intentionally out of parity scope (the Go server
+ * has none).
+ */
+export async function serveHttp(makeServer, cfg, signal) {
+    const sessions = new Map();
+    const httpServer = createHttpServer((req, res) => {
+        logAccess(req, res);
+        void routeRequest(req, res, sessions, makeServer, cfg);
+    });
+    const addr = `:${cfg.httpPort}`;
+    return new Promise((resolve, reject) => {
+        httpServer.on("error", reject);
+        httpServer.listen(Number(cfg.httpPort), () => {
+            log.info("HTTP transport listening", { addr, auth_enabled: cfg.httpAuthEnabled });
+        });
+        signal.addEventListener("abort", () => {
+            log.info("HTTP server shutting down", { grace_period_ms: HTTP_SHUTDOWN_GRACE_MS });
+            const force = setTimeout(() => httpServer.closeAllConnections?.(), HTTP_SHUTDOWN_GRACE_MS);
+            httpServer.close((err) => {
+                clearTimeout(force);
+                for (const transport of sessions.values())
+                    void transport.close();
+                sessions.clear();
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        }, { once: true });
+    });
+}
+/**
+ * Serve stdio and HTTP concurrently. stdio binds a single server; HTTP builds
+ * one server per session via the factory. The first transport to settle aborts
+ * the other, mirroring Go's serveBoth.
+ */
+export async function serveBoth(target, cfg, signal) {
+    const linked = new AbortController();
+    const onParentAbort = () => linked.abort();
+    signal.addEventListener("abort", onParentAbort, { once: true });
+    const tasks = [
+        serveStdio(createServer(target), linked.signal),
+        serveHttp(() => createServer(target), cfg, linked.signal),
+    ];
+    try {
+        await Promise.race(tasks);
+    }
+    finally {
+        linked.abort();
+        await Promise.allSettled(tasks);
+        signal.removeEventListener("abort", onParentAbort);
+    }
+}
+/**
+ * Route an inbound HTTP request: liveness probe, the non-validating Bearer
+ * extraction, then delegation to the session's MCP transport (reusing an
+ * existing session or creating one for an `initialize` request).
+ *
+ * The token is never validated here — presence is the only check, and it is
+ * forwarded unchanged to stigmer-server which performs validation. This mirrors
+ * the Go authMiddleware exactly (inventory §4.2).
+ */
+async function routeRequest(req, res, sessions, makeServer, cfg) {
+    if (req.method === "GET" && req.url === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(`{"status":"ok"}\n`);
+        return;
+    }
+    // RFC 9728 Protected Resource Metadata — public, unauthenticated, and served
+    // only when OAuth discovery is enabled. CORS-open so browser-based clients
+    // (e.g. Claude Desktop's connector GUI) can discover the authorization server.
+    if (cfg.oauth.enabled && requestPath(req) === PROTECTED_RESOURCE_METADATA_PATH) {
+        serveProtectedResourceMetadata(req, res, cfg);
+        return;
+    }
+    // Non-validating Bearer passthrough, applied to EVERY request so each call's
+    // gRPC client uses that request's own credential.
+    if (cfg.httpAuthEnabled) {
+        const token = extractBearerToken(req);
+        if (token === "") {
+            const headers = { "Content-Type": "text/plain" };
+            // RFC 9728 §5.1: point OAuth-capable clients at the metadata document.
+            if (cfg.oauth.enabled)
+                headers["WWW-Authenticate"] = bearerChallenge(cfg);
+            res.writeHead(401, headers);
+            res.end("missing or malformed Authorization: Bearer header");
+            return;
+        }
+        req.auth = { token, clientId: "stigmer-mcp-passthrough", scopes: [] };
+    }
+    const sessionId = headerValue(req, "mcp-session-id");
+    // Established session → dispatch to its transport.
+    if (sessionId !== undefined) {
+        const transport = sessions.get(sessionId);
+        if (transport === undefined) {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("unknown or expired MCP session");
+            return;
+        }
+        await transport.handleRequest(req, res);
+        return;
+    }
+    // No session → only an initialize POST may open one.
+    if (req.method !== "POST") {
+        res.writeHead(400, { "Content-Type": "text/plain" });
+        res.end("missing Mcp-Session-Id header");
+        return;
+    }
+    const body = await readJsonBody(req);
+    if (!isInitializeRequest(body)) {
+        res.writeHead(400, { "Content-Type": "text/plain" });
+        res.end("Bad Request: an initialize request is required to open a session");
+        return;
+    }
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (id) => {
+            sessions.set(id, transport);
+        },
+        onsessionclosed: (id) => {
+            sessions.delete(id);
+        },
+    });
+    transport.onclose = () => {
+        if (transport.sessionId !== undefined)
+            sessions.delete(transport.sessionId);
+    };
+    await makeServer().connect(transport);
+    await transport.handleRequest(req, res, body);
+}
+/** Return a single header value, collapsing the array form Node may produce. */
+function headerValue(req, name) {
+    const v = req.headers[name];
+    return Array.isArray(v) ? v[0] : v;
+}
+/** Read and JSON-parse a request body (used to classify the initialize POST). */
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            try {
+                resolve(raw === "" ? null : JSON.parse(raw));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        req.on("error", reject);
+    });
+}
+/** Request path without the query string (mirrors Go's r.URL.Path). */
+function requestPath(req) {
+    const url = req.url ?? "/";
+    const q = url.indexOf("?");
+    return q === -1 ? url : url.slice(0, q);
+}
+/**
+ * Attach access logging to a request: on completion, log a 16-hex request id,
+ * method, path, status, and duration. Mirrors Go's requestLogger middleware.
+ */
+function logAccess(req, res) {
+    const start = Date.now();
+    const requestId = randomBytes(8).toString("hex");
+    res.on("finish", () => {
+        log.info("http request", {
+            request_id: requestId,
+            method: req.method,
+            path: requestPath(req),
+            status: res.statusCode,
+            duration_ms: Date.now() - start,
+        });
+    });
+}
+/**
+ * Serve the OAuth 2.0 Protected Resource Metadata document (RFC 9728), answering
+ * the CORS preflight (OPTIONS) and the GET. Mirrors the Go SDK's
+ * ProtectedResourceMetadataHandler output shape.
+ */
+function serveProtectedResourceMetadata(req, res, cfg) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    if (req.method === "OPTIONS") {
+        res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "*");
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    const metadata = {
+        resource: cfg.oauth.resource,
+        authorization_servers: cfg.oauth.authorizationServers,
+        bearer_methods_supported: ["header"],
+        resource_name: "Stigmer MCP Server",
+    };
+    if (cfg.oauth.scopesSupported.length > 0) {
+        metadata.scopes_supported = cfg.oauth.scopesSupported;
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(metadata));
+}
+/**
+ * Build the WWW-Authenticate challenge pointing OAuth clients at this server's
+ * protected-resource-metadata document (RFC 9728 §5.1). Mirrors Go bearerChallenge.
+ */
+function bearerChallenge(cfg) {
+    const metadataURL = cfg.oauth.resource.replace(/\/+$/, "") + PROTECTED_RESOURCE_METADATA_PATH;
+    const params = [`realm="stigmer"`, `resource_metadata="${metadataURL}"`];
+    if (cfg.oauth.scopesSupported.length > 0) {
+        params.push(`scope="${cfg.oauth.scopesSupported.join(" ")}"`);
+    }
+    return "Bearer " + params.join(", ");
+}
+/** Parse the "Authorization: Bearer <token>" header; "" when absent/malformed. */
+function extractBearerToken(req) {
+    const header = req.headers.authorization;
+    if (!header)
+        return "";
+    const prefix = "Bearer ";
+    if (!header.startsWith(prefix))
+        return "";
+    return header.slice(prefix.length).trim();
+}
+/**
+ * Reports whether an error represents a clean client disconnect (EOF / broken
+ * pipe / abort) rather than a genuine failure, so discovery probes that connect
+ * and immediately disconnect do not cause a non-zero exit. Mirrors Go's
+ * isNormalShutdown.
+ */
+export function isNormalShutdown(err) {
+    if (err == null)
+        return true;
+    const name = err.name;
+    if (name === "AbortError")
+        return true;
+    const code = err.code;
+    if (code === "EPIPE" || code === "ABORT_ERR" || code === "ECONNRESET")
+        return true;
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes("EOF") || message.includes("broken pipe");
+}
+//# sourceMappingURL=server.js.map

package/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/src/cli/mcp-server-stigmer.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// mcp-server-stigmer — the Model Context Protocol server for the Stigmer
+// platform. Mirrors Go cmd/mcp-server-stigmer/main.go.
+//
+// Usage:
+//   mcp-server-stigmer            Transport from STIGMER_MCP_TRANSPORT (default stdio)
+//   mcp-server-stigmer stdio      stdin/stdout JSON-RPC
+//   mcp-server-stigmer http       Streamable HTTP
+//   mcp-server-stigmer both       Both transports simultaneously
+//
+// All other settings are read from STIGMER_-prefixed environment variables;
+// see ./config.ts for the full list.
+
+import { defaultConfig, run, type Transport } from "../index.js";
+
+const VALID_TRANSPORTS: readonly string[] = ["stdio", "http", "both"];
+
+async function main(): Promise<void> {
+  let cfg = defaultConfig();
+
+  // A positional subcommand overrides the env-var-based transport.
+  const sub = process.argv[2];
+  if (sub !== undefined) {
+    if (!VALID_TRANSPORTS.includes(sub)) {
+      process.stderr.write(`unknown subcommand "${sub}" (expected stdio, http, or both)\n`);
+      process.exit(1);
+    }
+    cfg = { ...cfg, transport: sub as Transport };
+  }
+
+  const controller = new AbortController();
+  const shutdown = () => controller.abort();
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+
+  await run(cfg, controller.signal);
+}
+
+main().catch((err: unknown) => {
+  process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/src/config.test.ts

@@ -0,0 +1,88 @@
+import { beforeAll, describe, expect, it } from "vitest";
+
+import { loadConfigFromEnv, validateConfig, type Config } from "./config";
+import { configureLogger } from "./logger";
+
+// Quiet the soft-validation warnings during these tests.
+beforeAll(() => configureLogger({ level: "error", format: "text" }));
+
+/** Build a config from an isolated env (defaults applied; process.env ignored). */
+function fromEnv(env: Record<string, string> = {}): Config {
+  return loadConfigFromEnv(env);
+}
+
+describe("loadConfigFromEnv", () => {
+  it("applies development defaults", () => {
+    const c = fromEnv();
+    expect(c.stigmerServerAddress).toBe("localhost:7234");
+    expect(c.apiKey).toBe("");
+    expect(c.transport).toBe("stdio");
+    expect(c.httpPort).toBe("8080");
+    expect(c.httpAuthEnabled).toBe(true);
+    expect(c.logFormat).toBe("text");
+    expect(c.logLevel).toBe("info");
+    expect(c.oauth.enabled).toBe(false);
+  });
+
+  it("reads overrides and lowercases the transport", () => {
+    const c = fromEnv({
+      STIGMER_MCP_TRANSPORT: "HTTP",
+      STIGMER_API_KEY: "sk_live",
+      STIGMER_MCP_HTTP_AUTH_ENABLED: "false",
+    });
+    expect(c.transport).toBe("http");
+    expect(c.apiKey).toBe("sk_live");
+    expect(c.httpAuthEnabled).toBe(false);
+  });
+
+  it("only the exact string 'true' enables boolean flags (Go parity)", () => {
+    expect(fromEnv({ STIGMER_MCP_HTTP_AUTH_ENABLED: "TRUE" }).httpAuthEnabled).toBe(false);
+    expect(fromEnv({ STIGMER_MCP_OAUTH_ENABLED: "1" }).oauth.enabled).toBe(false);
+  });
+
+  it("parses comma-separated lists, dropping blanks", () => {
+    const c = fromEnv({
+      STIGMER_MCP_OAUTH_ENABLED: "true",
+      STIGMER_MCP_OAUTH_RESOURCE: "https://mcp.stigmer.ai",
+      STIGMER_MCP_OAUTH_AUTHORIZATION_SERVERS: "https://a , , https://b",
+    });
+    expect(c.oauth.authorizationServers).toEqual(["https://a", "https://b"]);
+  });
+});
+
+describe("validateConfig", () => {
+  it("accepts the default config", () => {
+    expect(() => validateConfig(fromEnv())).not.toThrow();
+  });
+
+  it("rejects an invalid transport", () => {
+    expect(() => validateConfig(fromEnv({ STIGMER_MCP_TRANSPORT: "carrier-pigeon" }))).toThrow(
+      /STIGMER_MCP_TRANSPORT/,
+    );
+  });
+
+  it("rejects an empty server address", () => {
+    expect(() => validateConfig({ ...fromEnv(), stigmerServerAddress: "" })).toThrow(
+      /STIGMER_SERVER_ADDRESS/,
+    );
+  });
+
+  it("rejects an invalid log format and level", () => {
+    expect(() => validateConfig(fromEnv({ STIGMER_MCP_LOG_FORMAT: "xml" }))).toThrow(/LOG_FORMAT/);
+    expect(() => validateConfig(fromEnv({ STIGMER_MCP_LOG_LEVEL: "trace" }))).toThrow(/LOG_LEVEL/);
+  });
+
+  it("requires oauth resource and servers when oauth is enabled", () => {
+    expect(() => validateConfig(fromEnv({ STIGMER_MCP_OAUTH_ENABLED: "true" }))).toThrow(
+      /OAUTH_RESOURCE/,
+    );
+    expect(() =>
+      validateConfig(
+        fromEnv({
+          STIGMER_MCP_OAUTH_ENABLED: "true",
+          STIGMER_MCP_OAUTH_RESOURCE: "https://mcp.stigmer.ai",
+        }),
+      ),
+    ).toThrow(/AUTHORIZATION_SERVERS/);
+  });
+});

package/src/config.ts

@@ -0,0 +1,151 @@
+// Environment-variable configuration for mcp-server-stigmer.
+//
+// Every value is read from a STIGMER_-prefixed environment variable with a
+// development-friendly default. This is the embeddable configuration surface
+// (plain types, no internal coupling) and the parity mirror of the Go server's
+// internal/config + pkg/mcpserver Config (inventory §4.4) — the validation
+// reproduces Go's hard-errors AND warnings, not just the defaults.
+
+import { log, type LogFormat, type LogLevel } from "./logger.js";
+
+/** Communication mode between MCP clients and the server. */
+export type Transport = "stdio" | "http" | "both";
+
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728) discovery settings.
+ *
+ * Purely additive: the server stays a stateless Bearer passthrough that never
+ * validates tokens. Issuer values come from deployment config, never code, so
+ * the OSS server is issuer-agnostic. (HTTP discovery wiring itself lands in T02.)
+ */
+export interface OAuthConfig {
+  readonly enabled: boolean;
+  readonly resource: string;
+  readonly authorizationServers: string[];
+  readonly scopesSupported: string[];
+}
+
+/** Runtime configuration for the MCP server. */
+export interface Config {
+  /** gRPC dial target for stigmer-server (e.g. "localhost:7234"). */
+  readonly stigmerServerAddress: string;
+  /**
+   * API key for stigmer-server. Used for stdio/both; in http mode every
+   * request carries its own Bearer token. Empty when targeting an
+   * unauthenticated local backend.
+   */
+  readonly apiKey: string;
+  readonly transport: Transport;
+  readonly httpPort: string;
+  /** Whether HTTP requests require an Authorization: Bearer header. */
+  readonly httpAuthEnabled: boolean;
+  readonly oauth: OAuthConfig;
+  readonly logFormat: LogFormat;
+  readonly logLevel: LogLevel;
+}
+
+const VALID_TRANSPORTS: readonly string[] = ["stdio", "http", "both"];
+const VALID_LOG_FORMATS: readonly string[] = ["text", "json"];
+const VALID_LOG_LEVELS: readonly string[] = ["debug", "info", "warn", "error"];
+
+/** Reads configuration from the process environment, applying defaults. */
+export function loadConfigFromEnv(env: NodeJS.ProcessEnv = process.env): Config {
+  return {
+    stigmerServerAddress: envOr(env, "STIGMER_SERVER_ADDRESS", "localhost:7234"),
+    apiKey: env.STIGMER_API_KEY ?? "",
+    transport: envOr(env, "STIGMER_MCP_TRANSPORT", "stdio").toLowerCase() as Transport,
+    httpPort: envOr(env, "STIGMER_MCP_HTTP_PORT", "8080"),
+    // Go semantics: only the exact string "true" enables auth.
+    httpAuthEnabled: envOr(env, "STIGMER_MCP_HTTP_AUTH_ENABLED", "true") === "true",
+    oauth: {
+      enabled: env.STIGMER_MCP_OAUTH_ENABLED === "true",
+      resource: (env.STIGMER_MCP_OAUTH_RESOURCE ?? "").trim(),
+      authorizationServers: splitList(env.STIGMER_MCP_OAUTH_AUTHORIZATION_SERVERS),
+      scopesSupported: splitList(env.STIGMER_MCP_OAUTH_SCOPES_SUPPORTED),
+    },
+    logFormat: envOr(env, "STIGMER_MCP_LOG_FORMAT", "text").toLowerCase() as LogFormat,
+    logLevel: envOr(env, "STIGMER_MCP_LOG_LEVEL", "info").toLowerCase() as LogLevel,
+  };
+}
+
+/**
+ * Validates invariants that must hold before the server starts. Throws on hard
+ * errors; emits warnings (via the configured logger) for the soft cases the Go
+ * server warns about. Configure the logger before calling this so warnings are
+ * formatted consistently.
+ */
+export function validateConfig(cfg: Config): void {
+  if (!VALID_TRANSPORTS.includes(cfg.transport)) {
+    throw new Error(
+      `invalid STIGMER_MCP_TRANSPORT "${cfg.transport}": must be stdio, http, or both`,
+    );
+  }
+
+  if (cfg.stigmerServerAddress === "") {
+    throw new Error("STIGMER_SERVER_ADDRESS must not be empty");
+  }
+
+  if (cfg.stigmerServerAddress.includes("://")) {
+    log.warn(
+      "STIGMER_SERVER_ADDRESS contains a URL scheme; gRPC targets are host:port — " +
+        "the scheme is informational and TLS is derived from the port",
+      { value: cfg.stigmerServerAddress },
+    );
+  } else if (!hasExplicitPort(cfg.stigmerServerAddress)) {
+    log.warn(
+      "STIGMER_SERVER_ADDRESS has no explicit port; :443 with TLS is assumed for non-loopback addresses",
+      { value: cfg.stigmerServerAddress },
+    );
+  }
+
+  if (!VALID_LOG_FORMATS.includes(cfg.logFormat)) {
+    throw new Error(`invalid STIGMER_MCP_LOG_FORMAT "${cfg.logFormat}": must be text or json`);
+  }
+
+  if (!VALID_LOG_LEVELS.includes(cfg.logLevel)) {
+    throw new Error(
+      `invalid STIGMER_MCP_LOG_LEVEL "${cfg.logLevel}": must be debug, info, warn, or error`,
+    );
+  }
+
+  if (cfg.oauth.enabled) {
+    if (cfg.oauth.resource === "") {
+      throw new Error(
+        "STIGMER_MCP_OAUTH_RESOURCE must be set when STIGMER_MCP_OAUTH_ENABLED is true",
+      );
+    }
+    if (cfg.oauth.authorizationServers.length === 0) {
+      throw new Error(
+        "STIGMER_MCP_OAUTH_AUTHORIZATION_SERVERS must list at least one issuer when STIGMER_MCP_OAUTH_ENABLED is true",
+      );
+    }
+  }
+}
+
+function envOr(env: NodeJS.ProcessEnv, key: string, fallback: string): string {
+  const v = env[key];
+  return v !== undefined && v !== "" ? v : fallback;
+}
+
+/** Parses a comma-separated value into trimmed, non-empty entries. */
+function splitList(raw: string | undefined): string[] {
+  if (!raw || raw.trim() === "") return [];
+  return raw
+    .split(",")
+    .map((p) => p.trim())
+    .filter((p) => p !== "");
+}
+
+/**
+ * Reports whether an authority carries an explicit port. Tolerates bracketed
+ * IPv6 (`[::1]:443`) and treats bare IPv6 (`::1`) as port-less, matching the
+ * intent of Go's net.SplitHostPort in the config warning path.
+ */
+function hasExplicitPort(authority: string): boolean {
+  if (authority.startsWith("[")) {
+    const close = authority.indexOf("]");
+    return close !== -1 && authority.slice(close + 1).startsWith(":");
+  }
+  const lastColon = authority.lastIndexOf(":");
+  return lastColon !== -1 && authority.indexOf(":") === lastColon;
+}