@confluentinc/mcp-confluent 1.2.1 → 1.3.0

package/dist/mcp/transports/server.js

@@ -1,8 +1,8 @@
 import fastifySwagger from "@fastify/swagger";
 import fastifySwaggerUi from "@fastify/swagger-ui";
-import env from "../../env.js";
 import { logger } from "../../logger.js";
-import { createAuthHook } from "../../mcp/transports/auth.js";
+import { CFLT_MCP_API_KEY_HEADER, createAuthHook, } from "../../mcp/transports/auth.js";
+import { pingHandler, pingRequestSchema, pingResponseSchema, } from "../../mcp/transports/ping.js";
 import { default as Fastify, } from "fastify";
 export class HttpServer {
     fastify;
@@ -18,7 +18,7 @@ export class HttpServer {
             this.authConfig = config.auth;
         }
     }
-    async prepare() {
+    async prepare(config) {
         if (this.isSwaggerConfigured) {
             return;
         }
@@ -37,7 +37,7 @@ export class HttpServer {
                 },
                 servers: [
                     {
-                        url: `http://${env.HTTP_HOST}:${env.HTTP_PORT}`,
+                        url: `http://${config.host}:${config.port}`,
                         description: "Local development server",
                     },
                 ],
@@ -45,7 +45,7 @@ export class HttpServer {
                     securitySchemes: {
                         apiKey: {
                             type: "apiKey",
-                            name: "cflt-mcp-api-Key",
+                            name: CFLT_MCP_API_KEY_HEADER,
                             in: "header",
                         },
                     },
@@ -64,6 +64,18 @@ export class HttpServer {
             },
             staticCSP: true,
         });
+        // Register /ping at the server level (not per-transport) so HTTP+SSE configurations
+        // don't fail at startup with a duplicate-route error
+        this.fastify.post("/ping", {
+            schema: {
+                tags: ["mcp"],
+                summary: "JSON-RPC 2.0 ping endpoint",
+                body: pingRequestSchema,
+                response: {
+                    200: pingResponseSchema,
+                },
+            },
+        }, pingHandler());
         this.isSwaggerConfigured = true;
     }
     getInstance() {

package/dist/mcp/transports/server.js.map

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

package/dist/mcp/transports/session-registry.d.ts

@@ -0,0 +1,33 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Transport as SdkTransport } from "@modelcontextprotocol/sdk/shared/transport.js";
+/** Paired SDK transport + {@link McpServer} representing one MCP session. */
+export interface SessionEntry<T extends SdkTransport = SdkTransport> {
+    readonly transport: T;
+    readonly server: McpServer;
+}
+/**
+ * Registry of {@link SessionEntry} pairs keyed by MCP session id. Multi-client transports need
+ * one {@link McpServer} per session because the SDK binds each server to a single transport.
+ *
+ * {@see https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts}
+ * {@see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management}
+ */
+export declare class SessionRegistry<T extends SdkTransport = SdkTransport> {
+    private readonly sessions;
+    set(sessionId: string, entry: SessionEntry<T>): void;
+    get(sessionId: string): SessionEntry<T> | undefined;
+    /**
+     * Connects {@linkcode server} to {@linkcode transport}; closes both on rejection. The pair
+     * is not in the registry yet at this point (the SDK's {@linkcode T.onsessioninitialized}
+     * callback fires later, during {@linkcode T.handleRequest}), so failure here is an orphan
+     * cleanup, not a registry mutation.
+     */
+    bindServer(server: McpServer, transport: T): Promise<void>;
+    /** Closes the {@link SessionEntry} for {@linkcode sessionId} (if any) and removes it. */
+    closeAndRemove(sessionId: string): Promise<void>;
+    /** Closes every registered transport + server pair and clears the registry. */
+    closeAll(): Promise<void>;
+    /** Closes both halves of {@linkcode entry}, logging (not propagating) any failures. */
+    private closeEntry;
+}
+//# sourceMappingURL=session-registry.d.ts.map

package/dist/mcp/transports/session-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../../../src/mcp/transports/session-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,IAAI,YAAY,EAAE,MAAM,+CAA+C,CAAC;AAG/F,6EAA6E;AAC7E,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IACjE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IAChE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAE/D,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAIpD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS;IAInD;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE,yFAAyF;IACnF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtD,+EAA+E;IACzE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ/B,uFAAuF;YACzE,UAAU;CAYzB"}

package/dist/mcp/transports/session-registry.js

@@ -0,0 +1,65 @@
+import { logger } from "../../logger.js";
+/**
+ * Registry of {@link SessionEntry} pairs keyed by MCP session id. Multi-client transports need
+ * one {@link McpServer} per session because the SDK binds each server to a single transport.
+ *
+ * {@see https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts}
+ * {@see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management}
+ */
+export class SessionRegistry {
+    sessions = new Map();
+    set(sessionId, entry) {
+        this.sessions.set(sessionId, entry);
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    /**
+     * Connects {@linkcode server} to {@linkcode transport}; closes both on rejection. The pair
+     * is not in the registry yet at this point (the SDK's {@linkcode T.onsessioninitialized}
+     * callback fires later, during {@linkcode T.handleRequest}), so failure here is an orphan
+     * cleanup, not a registry mutation.
+     */
+    async bindServer(server, transport) {
+        try {
+            await server.connect(transport);
+        }
+        catch (err) {
+            await this.closeEntry({ transport, server });
+            throw err;
+        }
+    }
+    /** Closes the {@link SessionEntry} for {@linkcode sessionId} (if any) and removes it. */
+    async closeAndRemove(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return;
+        // delete first so a re-entrant call from `transport.onclose` is a no-op
+        this.sessions.delete(sessionId);
+        await this.closeEntry(entry);
+    }
+    /** Closes every registered transport + server pair and clears the registry. */
+    async closeAll() {
+        const entries = [...this.sessions.values()];
+        this.sessions.clear();
+        for (const entry of entries) {
+            await this.closeEntry(entry);
+        }
+    }
+    /** Closes both halves of {@linkcode entry}, logging (not propagating) any failures. */
+    async closeEntry(entry) {
+        try {
+            await entry.transport.close();
+        }
+        catch (err) {
+            logger.error({ err }, "transport.close() failed during session cleanup");
+        }
+        try {
+            await entry.server.close();
+        }
+        catch (err) {
+            logger.error({ err }, "server.close() failed during session cleanup");
+        }
+    }
+}
+//# sourceMappingURL=session-registry.js.map

package/dist/mcp/transports/session-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry.js","sourceRoot":"","sources":["../../../src/mcp/transports/session-registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAQxC;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IACT,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE/D,GAAG,CAAC,SAAiB,EAAE,KAAsB;QAC3C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,MAAiB,EAAE,SAAY;QAC9C,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;YAC7C,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,cAAc,CAAC,SAAiB;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,wEAAwE;QACxE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAChC,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,QAAQ;QACZ,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,uFAAuF;IAC/E,KAAK,CAAC,UAAU,CAAC,KAAsB;QAC7C,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,iDAAiD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,8CAA8C,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;CACF"}

package/dist/mcp/transports/sse.d.ts

@@ -2,13 +2,24 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { HttpServer } from "../../mcp/transports/server.js";
 import { Transport } from "../../mcp/transports/types.js";
 export declare class SseTransport implements Transport {
-    private server;
+    private serverFactory;
     private httpServer;
     private sseMcpEndpointPath;
     private sseMcpMessageEndpointPath;
     private sessions;
-    constructor(server: McpServer, httpServer: HttpServer, sseMcpEndpointPath?: string, sseMcpMessageEndpointPath?: string);
+    constructor(serverFactory: () => McpServer, httpServer: HttpServer, sseMcpEndpointPath?: string, sseMcpMessageEndpointPath?: string);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
+    /**
+     * Mints a per-session {@link McpServer} + {@link SSEServerTransport} pair, wires
+     * lifecycle callbacks, registers the session, then binds the server. Streamable HTTP gets
+     * the sessionId asynchronously via the SDK's {@linkcode onsessioninitialized} callback (which
+     * fires inside {@linkcode StreamableHTTPServerTransport.handleRequest}), so it can register
+     * lazily and a failed bind leaves no entry. SSE has no such callback — sessionId is known at
+     * construction — so we register first and roll back on bind rejection. Without the rollback
+     * a fast client could see {@linkcode SSEServerTransport.start}'s endpoint event, POST to
+     * {@linkcode sseMcpMessageEndpointPath} and race the {@linkcode sessions.set} call.
+     */
+    private createSession;
 }
 //# sourceMappingURL=sse.d.ts.map

package/dist/mcp/transports/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/mcp/transports/sse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQpE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAiBzD,qBAAa,YAAa,YAAW,SAAS;IAI1C,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,kBAAkB;IAC1B,OAAO,CAAC,yBAAyB;IANnC,OAAO,CAAC,QAAQ,CAA0C;gBAGhD,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,UAAU,EACtB,kBAAkB,GAAE,MAAe,EACnC,yBAAyB,GAAE,MAAoB;IAGnD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+HxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAWlC"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/mcp/transports/sse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAkBzD,qBAAa,YAAa,YAAW,SAAS;IAI1C,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,kBAAkB;IAC1B,OAAO,CAAC,yBAAyB;IANnC,OAAO,CAAC,QAAQ,CAA6C;gBAGnD,aAAa,EAAE,MAAM,SAAS,EAC9B,UAAU,EAAE,UAAU,EACtB,kBAAkB,GAAE,MAAe,EACnC,yBAAyB,GAAE,MAAoB;IAGnD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmFxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC;;;;;;;;;OASG;YACW,aAAa;CA+C5B"}

package/dist/mcp/transports/sse.js

@@ -1,6 +1,6 @@
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { sdkTransports } from "../../confluent/node-deps.js";
 import { logger } from "../../logger.js";
-import { pingHandler, pingRequestSchema, pingResponseSchema, } from "../../mcp/transports/ping.js";
+import { SessionRegistry } from "../../mcp/transports/session-registry.js";
 const sseErrorSchema = {
     type: "object",
     properties: {
@@ -8,13 +8,13 @@ const sseErrorSchema = {
     },
 };
 export class SseTransport {
-    server;
+    serverFactory;
     httpServer;
     sseMcpEndpointPath;
     sseMcpMessageEndpointPath;
-    sessions = {};
-    constructor(server, httpServer, sseMcpEndpointPath = "/sse", sseMcpMessageEndpointPath = "/messages") {
-        this.server = server;
+    sessions = new SessionRegistry();
+    constructor(serverFactory, httpServer, sseMcpEndpointPath = "/sse", sseMcpMessageEndpointPath = "/messages") {
+        this.serverFactory = serverFactory;
         this.httpServer = httpServer;
         this.sseMcpEndpointPath = sseMcpEndpointPath;
         this.sseMcpMessageEndpointPath = sseMcpMessageEndpointPath;
@@ -30,25 +30,9 @@ export class SseTransport {
                     400: sseErrorSchema,
                 },
             },
-        }, async (request, reply) => {
+        }, async (_request, reply) => {
             try {
-                // Create transport with the correct message endpoint
-                const transport = new SSEServerTransport(this.sseMcpMessageEndpointPath, reply.raw);
-                // Get the session ID from the transport
-                const sessionId = transport.sessionId;
-                if (!sessionId) {
-                    throw new Error("Failed to get session ID from transport");
-                }
-                // Store the session before connecting to ensure it's available for messages
-                this.sessions[sessionId] = transport;
-                // Set up cleanup on connection close
-                reply.raw.on("close", () => {
-                    logger.info(`SSE connection closed for session ${sessionId}`);
-                    delete this.sessions[sessionId];
-                });
-                // Connect the transport to the server
-                await this.server.connect(transport);
-                logger.info(`New SSE connection established for session ${sessionId}`);
+                await this.createSession(reply.raw);
             }
             catch (error) {
                 logger.error({ error }, "Failed to establish SSE connection");
@@ -82,14 +66,13 @@ export class SseTransport {
         }, async (request, reply) => {
             try {
                 const sessionId = request.query.sessionId;
-                logger.info(`Received message for sessionId ${sessionId}`);
-                const transport = this.sessions[sessionId];
-                if (!transport) {
+                const entry = this.sessions.get(sessionId);
+                if (!entry) {
                     logger.warn(`No transport found for sessionId: ${sessionId}`);
                     reply.code(400).send({ error: "No transport found for sessionId" });
                     return;
                 }
-                await transport.handlePostMessage(request.raw, reply.raw, request.body);
+                await entry.transport.handlePostMessage(request.raw, reply.raw, request.body);
             }
             catch (error) {
                 logger.error({ error }, "Failed to process SSE message");
@@ -98,29 +81,58 @@ export class SseTransport {
                 }
             }
         });
-        // POST ping endpoint for health checks
-        fastify.post("/ping", {
-            schema: {
-                tags: ["mcp"],
-                summary: "JSON-RPC 2.0 ping endpoint",
-                body: pingRequestSchema,
-                response: {
-                    200: pingResponseSchema,
-                },
-            },
-        }, pingHandler());
         logger.info("SSE transport routes registered");
     }
     async disconnect() {
         logger.info("Cleaning up SSE transport sessions...");
-        // Clean up all active sessions
-        Object.values(this.sessions).forEach((transport) => {
-            const sessionId = transport.sessionId;
-            if (sessionId) {
-                delete this.sessions[sessionId];
-            }
-            transport.close();
+        await this.sessions.closeAll();
+    }
+    /**
+     * Mints a per-session {@link McpServer} + {@link SSEServerTransport} pair, wires
+     * lifecycle callbacks, registers the session, then binds the server. Streamable HTTP gets
+     * the sessionId asynchronously via the SDK's {@linkcode onsessioninitialized} callback (which
+     * fires inside {@linkcode StreamableHTTPServerTransport.handleRequest}), so it can register
+     * lazily and a failed bind leaves no entry. SSE has no such callback — sessionId is known at
+     * construction — so we register first and roll back on bind rejection. Without the rollback
+     * a fast client could see {@linkcode SSEServerTransport.start}'s endpoint event, POST to
+     * {@linkcode sseMcpMessageEndpointPath} and race the {@linkcode sessions.set} call.
+     */
+    async createSession(rawResponse) {
+        const perSessionServer = this.serverFactory();
+        const transport = new sdkTransports.SSEServerTransport(this.sseMcpMessageEndpointPath, rawResponse);
+        const sessionId = transport.sessionId;
+        if (!sessionId) {
+            // SDK's SSEServerTransport always assigns a sessionId in its constructor; this branch is
+            // defensive. Close the just-created pair before throwing so we don't leak the McpServer
+            // and the SSE response stays detached.
+            await transport.close();
+            await perSessionServer.close();
+            throw new Error("Failed to get session ID from transport");
+        }
+        // fires on every close path (network drop, server-initiated, etc.) so abandoned sessions
+        // don't leak; closeAndRemove is idempotent against the not-yet-registered case
+        transport.onclose = () => {
+            this.sessions.closeAndRemove(sessionId).catch((err) => {
+                logger.error({ err, sessionId }, "Failed to close SSE session on transport.onclose");
+            });
+        };
+        this.sessions.set(sessionId, {
+            transport,
+            server: perSessionServer,
         });
+        try {
+            await this.sessions.bindServer(perSessionServer, transport);
+        }
+        catch (err) {
+            // bindServer already closed both halves via its internal closeEntry; we still call
+            // closeAndRemove here because bindServer doesn't know the registry key and the entry
+            // is what makes the session reachable to incoming POSTs. The duplicate close is safe:
+            // SDK transport.close() and McpServer.close() are both idempotent.
+            await this.sessions.closeAndRemove(sessionId);
+            throw err;
+        }
+        logger.info(`New SSE connection established for session ${sessionId}`);
+        return transport;
     }
 }
 //# sourceMappingURL=sse.js.map

package/dist/mcp/transports/sse.js.map

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

package/dist/server-runtime.d.ts

@@ -0,0 +1,28 @@
+import { MCPServerConfiguration } from "./config/index.js";
+import { BaseClientManager } from "./confluent/base-client-manager.js";
+import { OAuthHolder } from "./confluent/oauth/oauth-holder.js";
+/**
+ * Aggregate of all runtime state threaded through the server.
+ *
+ * Carries config and per-connection client managers.
+ */
+export declare class ServerRuntime {
+    readonly config: MCPServerConfiguration;
+    readonly clientManagers: Record<string, BaseClientManager>;
+    /**
+     * The active OAuth holder when any connection in the config has `type === "oauth"`.
+     * Constructed by {@link ServerRuntime.fromConfig}; `undefined` on api_key paths.
+     * Construction is side-effect-free — PKCE runs lazily on the first
+     * `holder.ensureLoggedIn()` call, which the MCP tool-call wrapper invokes
+     * before any handler that needs Confluent access.
+     */
+    readonly oauthHolder: OAuthHolder | undefined;
+    constructor(config: MCPServerConfiguration, clientManagers: Record<string, BaseClientManager>, oauthHolder?: OAuthHolder | undefined);
+    /**
+     * Convenience accessor for the single-connection period.
+     * Remove (or make multi-connection-aware) when issue #151 lands.
+     */
+    get clientManager(): BaseClientManager;
+    static fromConfig(config: MCPServerConfiguration): ServerRuntime;
+}
+//# sourceMappingURL=server-runtime.d.ts.map

package/dist/server-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-runtime.d.ts","sourceRoot":"","sources":["../src/server-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG1E,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAEnE;;;;GAIG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3D;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC;gBAG5C,MAAM,EAAE,sBAAsB,EAC9B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACjD,WAAW,GAAE,WAAW,GAAG,SAAqB;IAOlD;;;OAGG;IACH,IAAI,aAAa,IAAI,iBAAiB,CAarC;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,sBAAsB,GAAG,aAAa;CA4CjE"}

package/dist/server-runtime.js

@@ -0,0 +1,73 @@
+import { constructDirectClientManager } from "./confluent/direct-client-manager.js";
+import { OAuthClientManager } from "./confluent/oauth-client-manager.js";
+import { OAuthHolder } from "./confluent/oauth/oauth-holder.js";
+/**
+ * Aggregate of all runtime state threaded through the server.
+ *
+ * Carries config and per-connection client managers.
+ */
+export class ServerRuntime {
+    config;
+    clientManagers;
+    /**
+     * The active OAuth holder when any connection in the config has `type === "oauth"`.
+     * Constructed by {@link ServerRuntime.fromConfig}; `undefined` on api_key paths.
+     * Construction is side-effect-free — PKCE runs lazily on the first
+     * `holder.ensureLoggedIn()` call, which the MCP tool-call wrapper invokes
+     * before any handler that needs Confluent access.
+     */
+    oauthHolder;
+    constructor(config, clientManagers, oauthHolder = undefined) {
+        this.config = config;
+        this.clientManagers = clientManagers;
+        this.oauthHolder = oauthHolder;
+    }
+    /**
+     * Convenience accessor for the single-connection period.
+     * Remove (or make multi-connection-aware) when issue #151 lands.
+     */
+    get clientManager() {
+        const managers = Object.values(this.clientManagers);
+        if (managers.length === 0) {
+            throw new Error("ServerRuntime has no client managers");
+        }
+        if (managers.length > 1) {
+            // enforceSingleConnectionOnly() in config/models.ts should prevent this at parse time;
+            // this guard is the runtime mirror of that constraint.
+            throw new Error("ServerRuntime has multiple client managers; use clientManagers[id] directly");
+        }
+        return managers[0];
+    }
+    static fromConfig(config) {
+        const oauthConns = Object.values(config.connections).filter((c) => c.type === "oauth");
+        if (oauthConns.length > 1) {
+            // `enforceSingleConnectionOnly()` already prevents this today; keep the
+            // defensive check so that when multi-connection support lands (#151),
+            // multi-OAuth is rejected explicitly rather than silently picking one.
+            throw new Error(`Multiple OAuth connections defined in configuration; only one is supported`);
+        }
+        const oauthConn = oauthConns[0];
+        const oauthHolder = oauthConn
+            ? new OAuthHolder(oauthConn.ccloud_env)
+            : undefined;
+        // Construct a client manager for each connection in the config.
+        // (although currently there will only be one, see `enforceSingleConnectionOnly()`)
+        // When OAuth is in play, every connection's manager is bearer-auth-backed by
+        // the shared holder; otherwise, fall back to the per-connection direct factory.
+        const clientManagers = Object.fromEntries(Object.entries(config.connections).map(([id, conn]) => {
+            if (oauthHolder && oauthConn) {
+                return [
+                    id,
+                    new OAuthClientManager(oauthHolder, oauthConn.ccloud_env, oauthConn.kafka_debug),
+                ];
+            }
+            // No OAuth connection found, so every connection is direct.
+            if (conn.type !== "direct") {
+                throw new Error(`Internal error: connection ${id} is not direct but no OAuth holder was constructed`);
+            }
+            return [id, constructDirectClientManager(conn)];
+        }));
+        return new ServerRuntime(config, clientManagers, oauthHolder);
+    }
+}
+//# sourceMappingURL=server-runtime.js.map

package/dist/server-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-runtime.js","sourceRoot":"","sources":["../src/server-runtime.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,4BAA4B,EAAE,MAAM,yCAAyC,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAEnE;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACf,MAAM,CAAyB;IAC/B,cAAc,CAAoC;IAC3D;;;;;;OAMG;IACM,WAAW,CAA0B;IAE9C,YACE,MAA8B,EAC9B,cAAiD,EACjD,cAAuC,SAAS;QAEhD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,IAAI,aAAa;QACf,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACpD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,uFAAuF;YACvF,uDAAuD;YACvD,MAAM,IAAI,KAAK,CACb,6EAA6E,CAC9E,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC,CAAC,CAAE,CAAC;IACtB,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,MAA8B;QAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CACzD,CAAC,CAAC,EAA8B,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CACtD,CAAC;QACF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,wEAAwE;YACxE,sEAAsE;YACtE,uEAAuE;YACvE,MAAM,IAAI,KAAK,CACb,4EAA4E,CAC7E,CAAC;QACJ,CAAC;QACD,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,WAAW,GAAG,SAAS;YAC3B,CAAC,CAAC,IAAI,WAAW,CAAC,SAAS,CAAC,UAAU,CAAC;YACvC,CAAC,CAAC,SAAS,CAAC;QAEd,gEAAgE;QAChE,mFAAmF;QACnF,6EAA6E;QAC7E,gFAAgF;QAChF,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CACvC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE;YACpD,IAAI,WAAW,IAAI,SAAS,EAAE,CAAC;gBAC7B,OAAO;oBACL,EAAE;oBACF,IAAI,kBAAkB,CACpB,WAAW,EACX,SAAS,CAAC,UAAU,EACpB,SAAS,CAAC,WAAW,CACtB;iBACO,CAAC;YACb,CAAC;YACD,4DAA4D;YAC5D,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CACb,8BAA8B,EAAE,oDAAoD,CACrF,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,EAAE,EAAE,4BAA4B,CAAC,IAAI,CAAC,CAAU,CAAC;QAC3D,CAAC,CAAC,CACH,CAAC;QACF,OAAO,IAAI,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IAChE,CAAC;CACF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@confluentinc/mcp-confluent",
   "description": "Confluent MCP Server",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "author": "Confluent Inc.",
   "license": "MIT",
   "repository": {
@@ -25,10 +25,15 @@
   "homepage": "https://www.confluent.io/blog/ai-agents-using-anthropic-mcp/",
   "scripts": {
     "dev": "concurrently \"tsc -p tsconfig.build.json --watch\" \"tsc-alias -p tsconfig.build.json --watch\"",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest",
-    "test:ts": "tsc --noEmit",
+    "test": "npm run build && vitest run",
+    "test:coverage": "npm run test -- --coverage",
+    "test:unit": "vitest run --project unit --outputFile.junit=TEST-unit.xml",
+    "test:unit:coverage": "npm run test:unit -- --coverage",
+    "test:unit:watch": "vitest --project unit",
+    "test:integration": "npm run build && vitest run --project integration --outputFile.junit=TEST-integration.xml",
+    "test:integration:coverage": "npm run test:integration -- --coverage",
+    "test:harness": "vitest run --project harness --reporter=verbose",
+    "typecheck": "tsc --noEmit",
     "start": "node dist/index.js --env-file .env",
     "start:http": "node dist/index.js --env-file .env --transport http",
     "start:sse": "node dist/index.js --env-file .env --transport sse",
@@ -38,8 +43,10 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write \"**/*.+(js|ts|json)\"",
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "generate:openapi-types": "openapi-typescript ./openapi.json -o ./src/confluent/openapi-schema.d.ts --empty-objects-unknown",
     "print:schema": "node dist/print-md-schema.js",
     "inspector": "npx @modelcontextprotocol/inspector node dist/index.js --env-file .env",
+    "inspector:yaml": "node scripts/inspector-yaml.mjs",
     "prepare": "husky",
     "prepack": "npm run build && node scripts/inject-build-config.mjs"
   },
@@ -48,7 +55,7 @@
     "@types/content-type": "^1.1.9",
     "@types/eslint__js": "^8.42.3",
     "@types/node": "^24.0.4",
-    "@types/sinon": "^21.0.0",
+    "@types/turndown": "^5.0.6",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.35.0",
     "@typescript-eslint/parser": "^8.35.0",
@@ -57,11 +64,12 @@
     "eslint": "^9.29.0",
     "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-prettier": "^5.5.1",
+    "eslint-plugin-unused-imports": "^4.4.1",
     "globals": "^16.2.0",
     "husky": "^9.1.7",
     "openapi-typescript": "^7.8.0",
     "prettier": "3.6.1",
-    "sinon": "^21.0.2",
+    "prettier-plugin-organize-imports": "^4.3.0",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.35.0",
@@ -75,18 +83,26 @@
     "@fastify/swagger-ui": "^5.2.3",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@segment/analytics-node": "^3.0.0",
+    "cheerio": "^1.2.0",
     "commander": "^14.0.0",
     "dotenv": "^16.5.0",
     "fastify": "^5.7.3",
+    "open": "^10.2.0",
     "openapi-fetch": "^0.14.0",
     "pino": "^10.1.0",
-    "properties-file": "^3.5.12"
+    "pino-pretty": "^13.1.3",
+    "properties-file": "^3.5.12",
+    "turndown": "^7.2.4",
+    "yaml": "^2.8.3"
   },
   "overrides": {
     "zod": "^4.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "config.example.yaml",
+    "config.oauth.example.yaml",
+    "assets/oauth-templates"
   ],
   "engines": {
     "node": ">=22"

package/dist/confluent/helpers.d.ts

@@ -1,11 +0,0 @@
-import { Environment } from "../env.js";
-/**
- * Ensures a parameter exists either from the provided value or environment variable. Favor the provided param over the environment variable when truthy.
- * @param envVarName - The name of the environment variable to check
- * @param errorMessage - The error message to throw if neither parameter nor environment variable exists
- * @param param - Optional parameter value to use instead of environment variable
- * @returns The parameter value or environment variable value with its original type
- * @throws {Error} When neither parameter nor environment variable exists
- */
-export declare const getEnsuredParam: <T extends Environment[keyof Environment]>(envVarName: keyof Environment, errorMessage: string, param?: T) => T;
-//# sourceMappingURL=helpers.d.ts.map

package/dist/confluent/helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/confluent/helpers.ts"],"names":[],"mappings":"AAAA,OAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,WAAW,CAAC,MAAM,WAAW,CAAC,EACtE,YAAY,MAAM,WAAW,EAC7B,cAAc,MAAM,EACpB,QAAQ,CAAC,KACR,CAMF,CAAC"}

package/dist/confluent/helpers.js

@@ -1,17 +0,0 @@
-import env from "../env.js";
-/**
- * Ensures a parameter exists either from the provided value or environment variable. Favor the provided param over the environment variable when truthy.
- * @param envVarName - The name of the environment variable to check
- * @param errorMessage - The error message to throw if neither parameter nor environment variable exists
- * @param param - Optional parameter value to use instead of environment variable
- * @returns The parameter value or environment variable value with its original type
- * @throws {Error} When neither parameter nor environment variable exists
- */
-export const getEnsuredParam = (envVarName, errorMessage, param) => {
-    const finalParam = param || env[envVarName];
-    if (!finalParam) {
-        throw new Error(`${errorMessage}`);
-    }
-    return finalParam;
-};
-//# sourceMappingURL=helpers.js.map

package/dist/confluent/helpers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/confluent/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,GAAoB,MAAM,aAAa,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,UAA6B,EAC7B,YAAoB,EACpB,KAAS,EACN,EAAE;IACL,MAAM,UAAU,GAAG,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,UAAe,CAAC;AACzB,CAAC,CAAC"}