@confluentinc/mcp-confluent 1.2.2 → 1.3.0

package/dist/env.js

@@ -7,7 +7,7 @@ let envValues = {};
  * Loads and validates environment variables
  * @returns Validated environment object
  */
-export async function loadEnv() {
+function loadEnv() {
     try {
         // Load and validate environment variables with automatic type conversion
         return combinedSchema.parse(process.env);
@@ -20,15 +20,26 @@ export async function loadEnv() {
 /**
  * Initialize environment and save the values
  */
-export async function initEnv() {
+export function initEnv() {
     if (!isInitialized) {
-        envValues = await loadEnv();
+        envValues = loadEnv();
         isInitialized = true;
     }
     return envValues;
 }
-// Create a module to provide access to environment variables
-const env = new Proxy({}, {
+/**
+ * Lazy proxy over the validated environment values. Reading any property
+ * before {@linkcode initEnv} has run throws — this is what catches code that
+ * tries to consult the env outside the bootstrap.
+ *
+ * The default-export shape was retired in #234 to make accidental consumers
+ * visibly fail at the import site, and an ESLint rule slams the door behind
+ * it. The intended pattern is: `main()` calls `initEnv()` once, captures the
+ * returned `Environment` into a local, and passes it explicitly to the few
+ * call sites that need it. No global env consultation lives in handler code,
+ * test infrastructure, or anywhere else.
+ */
+export const env = new Proxy({}, {
     get: (_, property) => {
         if (!isInitialized) {
             throw new Error(`Environment not initialized. Attempted to access ${property} before initialization.`);
@@ -36,5 +47,4 @@ const env = new Proxy({}, {
         return envValues[property];
     },
 });
-export default env;
 //# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAKxC,sCAAsC;AACtC,IAAI,aAAa,GAAG,KAAK,CAAC;AAC1B,IAAI,SAAS,GAAgB,EAAiB,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO;IAC3B,IAAI,CAAC;QACH,yEAAyE;QACzE,OAAO,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,8BAA8B,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO;IAC3B,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,SAAS,GAAG,MAAM,OAAO,EAAE,CAAC;QAC5B,aAAa,GAAG,IAAI,CAAC;IACvB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,6DAA6D;AAC7D,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,EAAiB,EAAE;IACvC,GAAG,EAAE,CAAC,CAAC,EAAE,QAAgB,EAAE,EAAE;QAC3B,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,oDAAoD,QAAQ,yBAAyB,CACtF,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC,QAA6B,CAAC,CAAC;IAClD,CAAC;CACF,CAAC,CAAC;AAEH,eAAe,GAAG,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAKxC,sCAAsC;AACtC,IAAI,aAAa,GAAG,KAAK,CAAC;AAC1B,IAAI,SAAS,GAAgB,EAAiB,CAAC;AAE/C;;;GAGG;AACH,SAAS,OAAO;IACd,IAAI,CAAC;QACH,yEAAyE;QACzE,OAAO,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,8BAA8B,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO;IACrB,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,SAAS,GAAG,OAAO,EAAE,CAAC;QACtB,aAAa,GAAG,IAAI,CAAC;IACvB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,EAAiB,EAAE;IAC9C,GAAG,EAAE,CAAC,CAAC,EAAE,QAAgB,EAAE,EAAE;QAC3B,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,oDAAoD,QAAQ,yBAAyB,CACtF,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC,QAA6B,CAAC,CAAC;IAClD,CAAC;CACF,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,76 @@
 #!/usr/bin/env node
-export {};
+import { CLIOptions } from "./cli.js";
+import { MCPServerConfiguration } from "./config/index.js";
+import { ToolHandler } from "./confluent/tools/base-tools.js";
+import { ToolName } from "./confluent/tools/tool-name.js";
+import { ServerRuntime } from "./server-runtime.js";
+/**
+ * Determine the subset of ToolHandlers to register based on the filtered tool names
+ * and which connections satisfy each tool's service requirements.
+ **/
+export declare function getToolHandlersToRegister(filteredToolNames: ToolName[], runtime: ServerRuntime): Map<ToolName, ToolHandler>;
+/**
+ * Resolve the Segment write key handed to `TelemetryService.initialize`.
+ *
+ * Precedence: an explicit YAML `server.analytics.write_key` wins; otherwise
+ * fall back to `buildConfig.TELEMETRY_WRITE_KEY` (the value `npm pack` injects
+ * at release time). On unpacked / dev builds the build-time value is empty,
+ * so an absent YAML field produces an empty-string fallback that
+ * `TelemetryService` treats as "no key supplied" — analytics stays off.
+ *
+ * Extracted from `main()` so the precedence is unit-testable without booting
+ * the full server.
+ */
+export declare function resolveTelemetryWriteKey(mcpConfig: MCPServerConfiguration): string | undefined;
+export declare function outputApiKey(): void;
+/**
+ * Bootstrap a starter `config.yaml` in the current working directory by
+ * copying one of the bundled example templates, then ensure the new file
+ * is listed in `<cwd>/.gitignore` so credentials filled in later don't
+ * slip into git.
+ *
+ * Resolved relative to `import.meta.url` (the compiled `dist/index.js`)
+ * so this keeps working when invoked via `npx`, where `process.cwd()`
+ * is the user's project but the example file lives next to the install.
+ *
+ * Refuses to overwrite an existing destination so an accidental rerun
+ * cannot wipe credentials the user already filled in. The write uses
+ * `wx` (exclusive create) so the existence check and the create happen
+ * as a single syscall — there is no TOCTOU window where another process
+ * could create the file between a precheck and the write.
+ *
+ * @param oauth When true, copy `config.oauth.example.yaml` (the minimal
+ *   OAuth template); when false, copy `config.example.yaml` (the
+ *   fully-annotated direct/api-key template). The CLI flag in the EEXIST
+ *   error message is selected to match.
+ */
+export declare function outputInitConfig(oauth?: boolean): void;
+export declare function outputToolList(filteredToolNames: ToolName[]): void;
+/**
+ * Result of {@link handleEarlyExits}. Returning a value instead of calling
+ * `process.exit` directly keeps the function pure enough that tests can
+ * assert dispatch behavior by inspecting the result + per-output spies,
+ * without having to stub `process.exit`.
+ */
+export type EarlyExitResult = {
+    handled: false;
+} | {
+    handled: true;
+    exitCode: 0;
+} | {
+    handled: true;
+    exitCode: 1;
+    stderr: string;
+};
+/**
+ * Dispatch the CLI's mutually-exclusive early-exit modes — generate-key,
+ * init-config, init-oauth-config, and list-tools — before the server
+ * bootstrap begins. Returns `{ handled: false }` when none apply, in
+ * which case the caller continues with normal startup.
+ *
+ * On init-config failure, the friendly error message is returned in
+ * `stderr` rather than written here, so the caller controls writing to
+ * stderr and exiting.
+ */
+export declare function handleEarlyExits(cliOptions: CLIOptions): EarlyExitResult;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,UAAU,EAMX,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEjE,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAM7D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD;;;IAGI;AACJ,wBAAgB,yBAAyB,CACvC,iBAAiB,EAAE,QAAQ,EAAE,EAC7B,OAAO,EAAE,aAAa,GACrB,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAiD5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,sBAAsB,GAChC,MAAM,GAAG,SAAS,CAIpB;AAED,wBAAgB,YAAY,IAAI,IAAI,CAQnC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,OAAe,GAAG,IAAI,CAgC7D;AAkCD,wBAAgB,cAAc,CAAC,iBAAiB,EAAE,QAAQ,EAAE,GAAG,IAAI,CAUlE;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,GAClB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,GAC9B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,eAAe,CAqBxE"}

package/dist/index.js

@@ -1,17 +1,75 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { getFilteredToolNames, getPackageVersion, parseCliArgs, } from "./cli.js";
-import { DefaultClientManager } from "./confluent/client-manager.js";
-import { ToolFactory } from "./confluent/tools/tool-factory.js";
-import { ToolName } from "./confluent/tools/tool-name.js";
+import { DisplayedCommandLineUsageError, getFilteredToolNames, getPackageVersion, loadDotEnvFile, parseCliArgs, } from "./cli.js";
+import { buildConfigFromEnvAndCli, loadConfigFromYaml, } from "./config/index.js";
+import { buildConfigTelemetry } from "./confluent/config-telemetry.js";
+import { buildConfig, fs, path } from "./confluent/node-deps.js";
 import { TelemetryEvent, TelemetryService } from "./confluent/telemetry.js";
+import { groupDisabledToolsByReason } from "./confluent/tools/tool-availability.js";
+import { ToolName } from "./confluent/tools/tool-name.js";
+import { ToolHandlerRegistry } from "./confluent/tools/tool-registry.js";
 import { initEnv } from "./env.js";
 import { logger, setLogLevel } from "./logger.js";
 import { generateApiKey, TransportManager } from "./mcp/transports/index.js";
-// Parse command line arguments and load environment variables if --env-file is specified
-const cliOptions = parseCliArgs();
-// Handle --generate-key early (before any other initialization)
-if (cliOptions.generateKey) {
+import { ServerRuntime } from "./server-runtime.js";
+/**
+ * Determine the subset of ToolHandlers to register based on the filtered tool names
+ * and which connections satisfy each tool's service requirements.
+ **/
+export function getToolHandlersToRegister(filteredToolNames, runtime) {
+    const toolHandlers = new Map();
+    const knownIds = new Set(Object.keys(runtime.config.connections));
+    // Pass 1: drop tools excluded by the allow/block list (logged per-tool —
+    // the reason is config-driven, not predicate-driven, so it doesn't fold
+    // into the grouped warning emitted later).
+    const candidates = [];
+    for (const toolName of Object.values(ToolName)) {
+        if (!filteredToolNames.includes(toolName)) {
+            logger.warn(`Tool ${toolName} disabled due to allow/block list rules`);
+            continue;
+        }
+        candidates.push([toolName, ToolHandlerRegistry.getToolHandler(toolName)]);
+    }
+    // Pass 2: register tools that are enabled on at least one connection.
+    for (const [toolName, handler] of candidates) {
+        const enabledIds = handler.enabledConnectionIds(runtime);
+        const unknownIds = enabledIds.filter((id) => !knownIds.has(id));
+        if (unknownIds.length > 0) {
+            throw new Error(`Tool ${toolName}: enabledConnectionIds() returned unknown connection ID(s): ${unknownIds.join(", ")}`);
+        }
+        if (enabledIds.length > 0) {
+            toolHandlers.set(toolName, handler);
+            logger.info(`Tool ${toolName} enabled`);
+        }
+    }
+    // Pass 3: emit one grouped warning per (connectionId, reason) for tools
+    // that are fully disabled — readers see the missing config piece and the
+    // list of all tools blocked by it in a single line, rather than one
+    // line per tool.
+    for (const group of groupDisabledToolsByReason(candidates, runtime)) {
+        logger.warn(`Tools disabled on connection '${group.connectionId}' — ${group.reason}: ${group.toolNames.join(", ")}`);
+    }
+    // Raise an error if no tools are enabled, as the server would be non-functional without any tools.
+    if (toolHandlers.size === 0) {
+        throw new Error("No tools enabled. Please check your configuration and environment variables.");
+    }
+    return toolHandlers;
+}
+/**
+ * Resolve the Segment write key handed to `TelemetryService.initialize`.
+ *
+ * Precedence: an explicit YAML `server.analytics.write_key` wins; otherwise
+ * fall back to `buildConfig.TELEMETRY_WRITE_KEY` (the value `npm pack` injects
+ * at release time). On unpacked / dev builds the build-time value is empty,
+ * so an absent YAML field produces an empty-string fallback that
+ * `TelemetryService` treats as "no key supplied" — analytics stays off.
+ *
+ * Extracted from `main()` so the precedence is unit-testable without booting
+ * the full server.
+ */
+export function resolveTelemetryWriteKey(mcpConfig) {
+    return (mcpConfig.server.analytics?.write_key ?? buildConfig.TELEMETRY_WRITE_KEY);
+}
+export function outputApiKey() {
     const apiKey = generateApiKey();
     console.log("\nGenerated MCP API Key:");
     console.log("=".repeat(64));
@@ -19,176 +77,229 @@ if (cliOptions.generateKey) {
     console.log("=".repeat(64));
     console.log("\nAdd this to your .env file:");
     console.log(`MCP_API_KEY=${apiKey}\n`);
-    process.exit(0);
+}
+/**
+ * Bootstrap a starter `config.yaml` in the current working directory by
+ * copying one of the bundled example templates, then ensure the new file
+ * is listed in `<cwd>/.gitignore` so credentials filled in later don't
+ * slip into git.
+ *
+ * Resolved relative to `import.meta.url` (the compiled `dist/index.js`)
+ * so this keeps working when invoked via `npx`, where `process.cwd()`
+ * is the user's project but the example file lives next to the install.
+ *
+ * Refuses to overwrite an existing destination so an accidental rerun
+ * cannot wipe credentials the user already filled in. The write uses
+ * `wx` (exclusive create) so the existence check and the create happen
+ * as a single syscall — there is no TOCTOU window where another process
+ * could create the file between a precheck and the write.
+ *
+ * @param oauth When true, copy `config.oauth.example.yaml` (the minimal
+ *   OAuth template); when false, copy `config.example.yaml` (the
+ *   fully-annotated direct/api-key template). The CLI flag in the EEXIST
+ *   error message is selected to match.
+ */
+export function outputInitConfig(oauth = false) {
+    const sourceFileName = oauth
+        ? "config.oauth.example.yaml"
+        : "config.example.yaml";
+    const flagName = oauth ? "init-oauth-config" : "init-config";
+    const sourceUrl = new URL(`../${sourceFileName}`, import.meta.url);
+    const destPath = path.resolve("config.yaml");
+    const contents = fs.readFileSync(sourceUrl, "utf-8");
+    try {
+        fs.writeFileSync(destPath, contents, { flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            throw new Error(`config.yaml already exists at ${destPath}. ` +
+                `Remove or rename it before running --${flagName}.`);
+        }
+        throw err;
+    }
+    const gitignoreNote = ensureGitignoreEntry(destPath);
+    console.log(`wrote ./config.yaml (${gitignoreNote})`);
+    // OAuth has no credentials to edit; the bundled template is already
+    // runnable as-is. The api-key template, by contrast, ships placeholder
+    // values the user must fill in before the server can connect.
+    console.log(oauth
+        ? `Next: run with --config ./config.yaml`
+        : `Next: edit credentials in config.yaml and run with --config ./config.yaml`);
+}
+/**
+ * Ensure the basename of `filePath` is listed in `<dirname(filePath)>/.gitignore`.
+ * Creates the gitignore if missing; appends idempotently if present (matching
+ * trimmed lines verbatim — `*.yaml` globs or `/config.yaml` anchors are not
+ * recognized, so a user who already wrote either form will see a duplicate
+ * `config.yaml` entry, which is harmless).
+ *
+ * @returns A short note describing what happened, suitable for the success message.
+ */
+function ensureGitignoreEntry(filePath) {
+    const dir = path.dirname(filePath);
+    const fileName = path.basename(filePath);
+    const gitignorePath = path.join(dir, ".gitignore");
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, `${fileName}\n`);
+        return "added to .gitignore";
+    }
+    const existing = fs.readFileSync(gitignorePath, "utf-8");
+    const alreadyListed = existing
+        .split("\n")
+        .some((line) => line.trim() === fileName);
+    if (alreadyListed) {
+        return ".gitignore already excludes it";
+    }
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    fs.appendFileSync(gitignorePath, `${prefix}${fileName}\n`);
+    return "added to .gitignore";
+}
+export function outputToolList(filteredToolNames) {
+    const MAX_DESC_LENGTH = 120;
+    filteredToolNames.forEach((toolName) => {
+        const config = ToolHandlerRegistry.getToolConfig(toolName);
+        let desc = config.description.replaceAll(/\s+/g, " ").trim();
+        if (desc.length > MAX_DESC_LENGTH) {
+            desc = desc.slice(0, MAX_DESC_LENGTH - 3) + "...";
+        }
+        console.log(`\x1b[32m${config.name}\x1b[0m: ${desc}`);
+    });
+}
+/**
+ * Dispatch the CLI's mutually-exclusive early-exit modes — generate-key,
+ * init-config, init-oauth-config, and list-tools — before the server
+ * bootstrap begins. Returns `{ handled: false }` when none apply, in
+ * which case the caller continues with normal startup.
+ *
+ * On init-config failure, the friendly error message is returned in
+ * `stderr` rather than written here, so the caller controls writing to
+ * stderr and exiting.
+ */
+export function handleEarlyExits(cliOptions) {
+    if (cliOptions.generateKey) {
+        outputApiKey();
+        return { handled: true, exitCode: 0 };
+    }
+    if (cliOptions.initConfig) {
+        return runOutputInitConfig(false);
+    }
+    if (cliOptions.initOauthConfig) {
+        return runOutputInitConfig(true);
+    }
+    if (cliOptions.listTools) {
+        outputToolList(getFilteredToolNames(cliOptions.allowTools ?? [], cliOptions.blockTools ?? []));
+        return { handled: true, exitCode: 0 };
+    }
+    return { handled: false };
+}
+function runOutputInitConfig(oauth) {
+    try {
+        outputInitConfig(oauth);
+        return { handled: true, exitCode: 0 };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        const flag = oauth ? "--init-oauth-config" : "--init-config";
+        return { handled: true, exitCode: 1, stderr: `${flag} failed: ${msg}` };
+    }
 }
 async function main() {
     try {
-        // Initialize environment after CLI args are processed
-        const env = await initEnv();
-        setLogLevel(env.LOG_LEVEL);
-        // Merge environment variables with kafka config from CLI
-        // some additional configurations could be set in the client manager
-        // like separating groupIds by sessionId
-        const kafkaClientConfig = {
-            // Base configuration from environment variables
-            "bootstrap.servers": env.BOOTSTRAP_SERVERS,
-            "client.id": "mcp-confluent",
-            ...(env.KAFKA_API_KEY && env.KAFKA_API_SECRET
-                ? {
-                    "security.protocol": "sasl_ssl",
-                    "sasl.mechanisms": "PLAIN",
-                    "sasl.username": env.KAFKA_API_KEY,
-                    "sasl.password": env.KAFKA_API_SECRET,
-                }
-                : {}),
-            // Merge any additional properties from the kafka config file
-            ...cliOptions.kafkaConfig,
-        };
-        const clientManager = new DefaultClientManager({
-            kafka: kafkaClientConfig,
-            endpoints: {
-                cloud: env.CONFLUENT_CLOUD_REST_ENDPOINT,
-                flink: env.FLINK_REST_ENDPOINT,
-                schemaRegistry: env.SCHEMA_REGISTRY_ENDPOINT,
-                kafka: env.KAFKA_REST_ENDPOINT,
-                telemetry: env.TELEMETRY_ENDPOINT ?? "https://api.telemetry.confluent.cloud",
-            },
-            auth: {
-                cloud: {
-                    apiKey: env.CONFLUENT_CLOUD_API_KEY,
-                    apiSecret: env.CONFLUENT_CLOUD_API_SECRET,
-                },
-                tableflow: {
-                    apiKey: env.TABLEFLOW_API_KEY,
-                    apiSecret: env.TABLEFLOW_API_SECRET,
-                },
-                flink: {
-                    apiKey: env.FLINK_API_KEY,
-                    apiSecret: env.FLINK_API_SECRET,
-                },
-                schemaRegistry: {
-                    apiKey: env.SCHEMA_REGISTRY_API_KEY,
-                    apiSecret: env.SCHEMA_REGISTRY_API_SECRET,
-                },
-                kafka: {
-                    apiKey: env.KAFKA_API_KEY,
-                    apiSecret: env.KAFKA_API_SECRET,
-                },
-                telemetry: {
-                    apiKey: (env.TELEMETRY_API_KEY ?? env.CONFLUENT_CLOUD_API_KEY),
-                    apiSecret: (env.TELEMETRY_API_SECRET ??
-                        env.CONFLUENT_CLOUD_API_SECRET),
-                },
-            },
-        });
-        const filteredToolNames = getFilteredToolNames(cliOptions);
-        // If --list-tools is set, print tool names with descriptions and exit
-        if (cliOptions.listTools) {
-            const MAX_DESC_LENGTH = 120;
-            filteredToolNames.forEach((toolName) => {
-                const config = ToolFactory.getToolConfig(toolName);
-                let desc = config.description.replace(/\s+/g, " ").trim();
-                if (desc.length > MAX_DESC_LENGTH) {
-                    desc = desc.slice(0, MAX_DESC_LENGTH - 3) + "...";
-                }
-                console.log(`\x1b[32m${config.name}\x1b[0m: ${desc}`);
+        // Parse command line arguments.(NO LONGER LOADS ENV VARS FROM -e file!)
+        const cliOptions = parseCliArgs(process.argv);
+        const earlyExit = handleEarlyExits(cliOptions);
+        if (earlyExit.handled) {
+            if (earlyExit.exitCode === 1) {
+                console.error(earlyExit.stderr);
+            }
+            process.exit(earlyExit.exitCode);
+        }
+        const filteredToolNames = getFilteredToolNames(cliOptions.allowTools ?? [], cliOptions.blockTools ?? []);
+        if (cliOptions.envFile) {
+            loadDotEnvFile(cliOptions.envFile);
+        }
+        // Convert our known env vars into a typed Environment obj.
+        const env = initEnv();
+        let mcpConfig;
+        // Load and validate configuration — from YAML file if --config provided, else from env vars + CLI overrides.
+        if (cliOptions.config) {
+            mcpConfig = loadConfigFromYaml(cliOptions.config, process.env);
+        }
+        else {
+            mcpConfig = buildConfigFromEnvAndCli(env, {
+                disableAuth: cliOptions.disableAuth,
+                allowedHosts: cliOptions.allowedHosts,
+                kafkaConfig: cliOptions.kafkaConfig,
+                oauth: cliOptions.oauth,
+                ccloudEnv: cliOptions.ccloudEnv,
             });
-            process.exit(0);
         }
-        const toolHandlers = new Map();
-        // Initialize tools and check their requirements
-        Object.values(ToolName).forEach((toolName) => {
-            if (!filteredToolNames.includes(toolName)) {
-                logger.warn(`Tool ${toolName} disabled due to allow/block list rules`);
-                return;
-            }
-            const handler = ToolFactory.createToolHandler(toolName);
-            // Skip cloud-only tools if disabled by CLI/env
-            if (cliOptions.disableConfluentCloudTools &&
-                handler.isConfluentCloudOnly()) {
-                logger.warn(`Tool ${toolName} disabled due to --disable-confluent-cloud-tools flag or DISABLE_CONFLUENT_CLOUD_TOOLS env var`);
-                return;
-            }
-            const missingVars = handler
-                .getRequiredEnvVars()
-                .filter((varName) => !env[varName]);
-            if (missingVars.length === 0) {
-                toolHandlers.set(toolName, handler);
-                logger.info(`Tool ${toolName} enabled`);
-            }
-            else {
-                logger.warn(`Tool ${toolName} disabled due to missing environment variables: ${missingVars.join(", ")}`);
-            }
+        setLogLevel(mcpConfig.server.log_level);
+        // Transport selection: YAML config is authoritative when --config is used;
+        // CLI flag (or its default) is used on the env-var path.
+        const transports = cliOptions.config
+            ? mcpConfig.server.transports
+            : cliOptions.transports;
+        // DO_NOT_TRACK is a cross-tool user preference (consoledonottrack.com);
+        // the env var acts as a floor so it is honored even when --config is used.
+        TelemetryService.initialize({
+            doNotTrack: mcpConfig.server.do_not_track || env.DO_NOT_TRACK,
+            writeKey: resolveTelemetryWriteKey(mcpConfig),
         });
+        const telemetry = TelemetryService.getInstance();
+        logger.info(`${mcpConfig.getConnectionNames().length} connections loaded successfully`);
+        const runtime = ServerRuntime.fromConfig(mcpConfig);
         const serverVersion = getPackageVersion();
-        const server = new McpServer({
-            name: "confluent",
-            version: serverVersion,
-        });
-        TelemetryService.getInstance().setCommonProperties({
-            serverVersion,
-            transportType: cliOptions.transports.join(","),
-        });
-        // Capture MCP client info when the handshake completes.
-        server.server.oninitialized = () => {
-            const clientInfo = server.server.getClientVersion();
-            TelemetryService.getInstance().setCommonProperties({
-                clientName: clientInfo?.name,
-                clientVersion: clientInfo?.version,
-            });
-        };
-        toolHandlers.forEach((handler, name) => {
-            const config = handler.getToolConfig();
-            server.registerTool(name, {
-                description: config.description,
-                inputSchema: config.inputSchema,
-                annotations: config.annotations,
-            }, async (args, context) => {
-                const sessionId = context?.sessionId;
-                const startTime = Date.now();
-                try {
-                    const result = await handler.handle(clientManager, args, sessionId);
-                    TelemetryService.getInstance().track(TelemetryEvent.TOOL_CALL, {
-                        toolName: name,
-                        durationMs: Date.now() - startTime,
-                        status: result.isError ? "error" : "success",
-                    });
-                    return result;
-                }
-                catch (error) {
-                    TelemetryService.getInstance().track(TelemetryEvent.TOOL_CALL, {
-                        toolName: name,
-                        durationMs: Date.now() - startTime,
-                        status: "error",
-                    });
-                    throw error;
-                }
-            });
-        });
-        // Prepare auth configuration
-        const disableAuth = cliOptions.disableAuth || env.MCP_AUTH_DISABLED;
-        const allowedHosts = cliOptions.allowedHosts || env.MCP_ALLOWED_HOSTS;
-        const apiKey = env.MCP_API_KEY;
+        telemetry.setCommonProperties({ serverVersion });
+        const toolHandlers = getToolHandlersToRegister(filteredToolNames, runtime);
+        logger.info({ enabledTools: [...toolHandlers.keys()] }, `${toolHandlers.size} tool(s) enabled`);
         // Warn if auth is disabled
-        if (disableAuth) {
+        if (mcpConfig.server.auth.disabled) {
             logger.warn("Authentication is DISABLED for HTTP/SSE transports. " +
                 "This should only be used in development environments.");
         }
-        const transportManager = new TransportManager(server, {
-            disableAuth,
-            allowedHosts,
-            apiKey,
+        const transportManager = new TransportManager({
+            disableAuth: mcpConfig.server.auth.disabled,
+            allowedHosts: mcpConfig.server.auth.allowed_hosts,
+            apiKey: mcpConfig.server.auth.api_key,
         });
+        const serverOptions = {
+            serverVersion,
+            toolHandlers,
+            runtime,
+            track: (props) => telemetry.track(TelemetryEvent.TOOL_CALL, {
+                ...props,
+            }),
+        };
         // Start all transports with a single call
-        logger.info(`Starting transports: ${cliOptions.transports.join(", ")}`);
-        await transportManager.start(cliOptions.transports, env.HTTP_PORT, env.HTTP_HOST, env.HTTP_MCP_ENDPOINT_PATH, env.SSE_MCP_ENDPOINT_PATH, env.SSE_MCP_MESSAGE_ENDPOINT_PATH);
+        logger.info(`Starting transports: ${transports.join(", ")}`);
+        await transportManager.start({
+            serverOptions,
+            types: transports,
+            http: {
+                port: mcpConfig.server.http.port,
+                host: mcpConfig.server.http.host,
+                mcpEndpointPath: mcpConfig.server.http.mcp_endpoint,
+                sseEndpointPath: mcpConfig.server.http.sse_endpoint,
+                sseMessageEndpointPath: mcpConfig.server.http.sse_message_endpoint,
+            },
+        });
+        // Boot-time invariants (config source, active transports, connection
+        // types) ride this one-shot event rather than every TOOL_CALL — they
+        // don't change after startup, so duplicating them per tool call buys
+        // nothing. Warehouse queries join SERVER_START to TOOL_CALL on
+        // `serverSessionId` (a common property) when slicing is needed.
+        telemetry.track(TelemetryEvent.SERVER_START, {
+            ...buildConfigTelemetry(cliOptions, mcpConfig, transports),
+        });
         // Set up cleanup handlers
         const performCleanup = async () => {
             logger.info("Shutting down...");
-            await TelemetryService.getInstance().shutdown();
+            await telemetry.shutdown();
             await transportManager.stop();
-            await clientManager.disconnect();
-            await server.close();
+            // shutdown() is race-safe with an in-flight bootstrap.
+            runtime.oauthHolder?.shutdown();
+            await runtime.clientManager.disconnect();
             process.exit(0);
         };
         process.on("SIGINT", performCleanup);
@@ -197,12 +308,14 @@ async function main() {
         process.on("SIGUSR2", performCleanup);
     }
     catch (error) {
+        if (error instanceof DisplayedCommandLineUsageError) {
+            process.exit(0);
+        }
         logger.error({ err: error }, "Error starting server");
         process.exit(1);
     }
 }
-main().catch((error) => {
-    logger.error({ error }, "Error starting server");
-    process.exit(1);
-});
+if (process.env.NODE_ENV !== "test") {
+    await main();
+}
 //# sourceMappingURL=index.js.map