@confluentinc/mcp-confluent 1.4.0 → 1.6.0

package/README.md

@@ -6,9 +6,17 @@
 An open-source [MCP server](https://modelcontextprotocol.io/) that enables AI assistants to interact with Confluent Cloud, Confluent Platform, and standalone Apache Kafka deployments through natural language.
 It provides 50+ tools across Kafka, Flink SQL, Schema Registry, Connectors, Tableflow, and more -- usable from any MCP-compatible client including Claude Desktop, Claude Code, Cursor, VS Code, Goose, and Gemini CLI.
 
+> [!TIP]
+> **Already a Confluent Cloud customer?**
+> Confluent offers a [fully managed MCP server](https://docs.confluent.io/cloud/current/ai/ai-tools/managed-mcp-server.html) with no local server to run and no dependencies to install.
+> It provides access to your Confluent Cloud resources with AI-powered connector diagnostics, governed by your existing RBAC permissions.
+> Use this open-source server if you need Confluent Platform / self-managed Kafka support, or want to customize and extend the toolset.
+> 
+> **NOTE:** The open-source MCP server is a community-supported project. Confluent doesn’t provide dedicated support for it, and support is best-effort only, with no service level commitments. If you run into an issue or want to contribute, open an issue or pull request directly in this repository.
+
 ## Quick Start
 
-> **Prerequisites:** [Node.js 22+](https://nodejs.org/).
+> **Prerequisites:** [Node.js 22.19.0+](https://nodejs.org/).
 > If you want to interact with [Confluent Cloud](https://confluent.cloud/), you need to create an account first.
 
 1. Generate a quick `config.yaml` file in your project root:
@@ -56,10 +64,10 @@ npx -y @confluentinc/mcp-confluent --list-tools
 
 These tools need no service blocks or authentication — they're enabled even on a bare config, regardless of which deployment the rest of your config targets.
 
-| Category          | Tools                                         | Description                                               |
-| ----------------- | --------------------------------------------- | --------------------------------------------------------- |
-| **Documentation** | `search-product-docs`, `get-product-doc-page` | Search Confluent product docs and fetch full page content |
-| **Diagnostics**   | `explain-disabled-tools`                      | Explain why specific tools are absent from `tools/list`   |
+| Category          | Tools                                                                                                    | Description                                                                                                                                                                                     |
+| ----------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Documentation** | `search-product-docs`, `get-product-doc-page`                                                            | Search Confluent product docs and fetch full page content                                                                                                                                       |
+| **Diagnostics**   | `explain-disabled-tools`, `list-configured-connections`, `config-help`, `describe-configured-connection` | Explain why tools are absent, list configured connections and the tools enabled on each, suggest the YAML to enable a specific tool, and describe one connection's config and tool availability |
 
 ### Available Tools for Confluent Cloud
 
@@ -67,24 +75,26 @@ These tools require endpoints and authentication against specific Confluent Clou
 Refer to [`config.example.yaml`](config.example.yaml) for the full set of configuration variables.
 Categories marked with ¹ also work with [OAuth authentication](#oauth-authentication-for-confluent-cloud) — sign in via your browser instead of provisioning API keys.
 
-| Category                                     | Tools                                                                                                                                                                                                                                                                                                                                        | Description                                                                                |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| **Kafka** ¹                                  | `list-topics`, `create-topics`, `delete-topics`, `produce-message`, `consume-messages`, `list-consumer-groups`, `describe-consumer-group`, `get-consumer-group-lag`, `alter-topic-config`, `get-topic-config`                                                                                                                                | Manage topics, produce/consume messages, inspect consumer groups, configure topic settings |
-| **Flink SQL**                                | `create-flink-statement`, `list-flink-statements`, `read-flink-statement`, `delete-flink-statements`, `get-flink-statement-exceptions`                                                                                                                                                                                                       | Create and manage Flink SQL statements                                                     |
-| **Flink Catalog**                            | `list-flink-catalogs`, `list-flink-databases`, `list-flink-tables`, `describe-flink-table`, `get-flink-table-info`                                                                                                                                                                                                                           | Explore Flink catalogs, databases, and table schemas                                       |
-| **Flink Diagnostics**                        | `check-flink-statement-health`, `detect-flink-statement-issues`, `get-flink-statement-profile`                                                                                                                                                                                                                                               | Health checks, issue detection, and query profiling                                        |
-| **Connectors**                               | `list-connectors`, `get-connector-config`, `get-connector-offsets`, `get-connector-status`, `get-connector-tasks`, `get-connector-error-summary`, `get-connector-error-recommendations`, `get-connector-logs`, `create-connector`, `delete-connector`, `pause-connector`, `resume-connector`, `restart-connector`, `update-connector-config` | Inspect and manage Kafka Connect connectors                                                |
-| **Schema Registry** ¹                        | `list-schemas`, `delete-schema`                                                                                                                                                                                                                                                                                                              | List, inspect, and delete data schemas                                                     |
-| **Catalog & Tags**                           | `search-topics-by-tag`, `search-topics-by-name`, `create-topic-tags`, `delete-tag`, `remove-tag-from-entity`, `add-tags-to-topic`, `list-tags`                                                                                                                                                                                               | Organize and search topics using tags                                                      |
-| **Organizations, Environments & Clusters** ¹ | `list-organizations`, `list-environments`, `read-environment`, `list-clusters`                                                                                                                                                                                                                                                               | Discover Confluent Cloud resources                                                         |
-| **Tableflow**                                | `create-tableflow-topic`, `list-tableflow-topics`, `read-tableflow-topic`, `update-tableflow-topic`, `delete-tableflow-topic`, `list-tableflow-regions`                                                                                                                                                                                      | Manage Tableflow-enabled topics                                                            |
-| **Tableflow Catalog**                        | `create-tableflow-catalog-integration`, `list-tableflow-catalog-integrations`, `read-tableflow-catalog-integration`, `update-tableflow-catalog-integration`, `delete-tableflow-catalog-integration`                                                                                                                                          | Manage Tableflow catalog integrations (e.g., AWS Glue)                                     |
-| **Metrics**                                  | `list-available-metrics`, `query-metrics`                                                                                                                                                                                                                                                                                                    | Discover and query Confluent Cloud operational metrics                                     |
-| **Billing** ¹                                | `list-billing-costs`                                                                                                                                                                                                                                                                                                                         | Query billing and cost data                                                                |
+| Category                                     | Tools                                                                                                                                                                                                                                                                                                                                          | Description                                                                                |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **Kafka** ¹                                  | `list-topics`, `create-topics`, `delete-topics`, `produce-message`, `consume-messages`, `list-consumer-groups`, `describe-consumer-group`, `get-consumer-group-lag`, `alter-topic-config`, `get-topic-config`                                                                                                                                  | Manage topics, produce/consume messages, inspect consumer groups, configure topic settings |
+| **Flink SQL** ¹                              | `create-flink-statement`, `list-flink-statements`, `get-flink-statement-results`, `delete-flink-statements`, `get-flink-statement-exceptions`, `list-compute-pools`                                                                                                                                                                            | Create and manage Flink SQL statements; discover Flink compute pools                       |
+| **Flink Catalog** ¹                          | `list-flink-catalogs`, `list-flink-databases`, `list-flink-tables`, `describe-flink-table`, `get-flink-table-info`                                                                                                                                                                                                                             | Explore Flink catalogs, databases, and table schemas                                       |
+| **Flink Diagnostics** ¹                      | `check-flink-statement-health`, `detect-flink-statement-issues`, `get-flink-statement-profile`                                                                                                                                                                                                                                                 | Health checks, issue detection, and query profiling                                        |
+| **Connectors** ¹                             | `list-connectors`, `get-connector-config`, `get-connector-offsets`, `get-connector-status`, `get-connector-tasks`, `get-connector-error-summary`, `get-connector-error-recommendations`, `get-connector-logs`, `create-connector` ², `delete-connector`, `pause-connector`, `resume-connector`, `restart-connector`, `update-connector-config` | Inspect and manage Kafka Connect connectors                                                |
+| **Schema Registry** ¹                        | `list-schemas`, `create-schema`, `delete-schema`                                                                                                                                                                                                                                                                                               | List, inspect, create, and delete data schemas                                             |
+| **Catalog & Tags** ¹                         | `search-topics-by-tag`, `search-topics-by-name`, `create-topic-tags`, `delete-tag`, `remove-tag-from-entity`, `add-tags-to-topic`, `list-tags`                                                                                                                                                                                                 | Organize and search topics using tags                                                      |
+| **Organizations, Environments & Clusters** ¹ | `list-organizations`, `list-environments`, `read-environment`, `list-clusters`                                                                                                                                                                                                                                                                 | Discover Confluent Cloud resources                                                         |
+| **Tableflow** ¹                              | `create-tableflow-topic`, `list-tableflow-topics`, `read-tableflow-topic`, `update-tableflow-topic`, `delete-tableflow-topic`, `list-tableflow-regions`                                                                                                                                                                                        | Manage Tableflow-enabled topics                                                            |
+| **Tableflow Catalog** ¹                      | `create-tableflow-catalog-integration`, `list-tableflow-catalog-integrations`, `read-tableflow-catalog-integration`, `update-tableflow-catalog-integration`, `delete-tableflow-catalog-integration`                                                                                                                                            | Manage Tableflow catalog integrations (e.g., AWS Glue)                                     |
+| **Metrics** ¹                                | `list-available-metrics`, `query-metrics`                                                                                                                                                                                                                                                                                                      | Discover and query Confluent Cloud operational metrics                                     |
+| **Billing** ¹                                | `list-billing-costs`                                                                                                                                                                                                                                                                                                                           | Query billing and cost data                                                                |
 
 ¹ Also available under OAuth — see [OAuth Authentication for Confluent Cloud](#oauth-authentication-for-confluent-cloud) for setup and caveats.
 Categories not marked currently require a `direct` connection with static API keys; OAuth migration is in progress.
 
+² Individual tool not available under OAuth; requires a `direct` connection with static API keys.
+
 ### Available Tools for local deployments
 
 These tools only require Kafka or Schema Registry endpoints - no Confluent Cloud API key/secret is needed.
@@ -106,7 +116,7 @@ Ready-to-use variants live in [`sample_configs/`](sample_configs/).
 | Category            | Tools                                                                                                                                                               | Description                                                      |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
 | **Kafka**           | `list-topics`, `create-topics`, `delete-topics`, `produce-message`, `consume-messages`, `list-consumer-groups`, `describe-consumer-group`, `get-consumer-group-lag` | Manage topics, produce/consume messages, inspect consumer groups |
-| **Schema Registry** | `list-schemas`, `delete-schema`                                                                                                                                     | List, inspect, and delete data schemas                           |
+| **Schema Registry** | `list-schemas`, `create-schema`, `delete-schema`                                                                                                                    | List, inspect, create, and delete data schemas                   |
 
 ## Using with Confluent Platform
 
@@ -128,7 +138,7 @@ CP clusters frequently sit behind an internal CA.
 If you see TLS handshake failures against the broker or Schema Registry, point Node at your CA bundle when starting the server:
 
 ```bash
-NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem npm run start -- --config path/to/config.yaml
+NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem pnpm run start -- --config path/to/config.yaml
 ```
 
 ### End-to-end smoke test
@@ -140,21 +150,30 @@ The matching integration tests are tagged `@cp` and live next to their handlers
 docker compose -f docker-compose.cp-test.yml up -d
 # Wait ~30s for Kafka + SR to become ready, then:
 CP_KAFKA_USERNAME=mcp CP_KAFKA_PASSWORD=mcp-secret \
-  npm run test:integration -- --tags-filter=@cp
+  pnpm run test:integration --tags-filter=@cp
 docker compose -f docker-compose.cp-test.yml down -v
 ```
 
-The tests skip cleanly when those env vars are unset, so `npm run test:unit` and a default `npm run test:integration` against your real Confluent Cloud account are unaffected if you don't have the docker stack running.
+The tests skip cleanly when those env vars are unset, so `pnpm run test:unit` and a default `pnpm run test:integration` against your real Confluent Cloud account are unaffected if you don't have the docker stack running.
 
 ## Getting Started
 
 ### Prerequisites
 
-- **Node.js 22 or later** -- we recommend using [NVM](https://github.com/nvm-sh/nvm) to manage versions:
+- **Node.js 22.19.0 or later** -- we recommend using [NVM](https://github.com/nvm-sh/nvm) to manage versions:
   ```bash
   nvm install 22
   nvm use 22
   ```
+- **[pnpm](https://pnpm.io/installation)** -- only needed to build from source (the `npx` quick start above does not require it).
+  On macOS the simplest install is Homebrew; `npm` works cross-platform:
+  ```bash
+  brew install pnpm        # macOS
+  # or, cross-platform:
+  npm install -g pnpm
+  ```
+  See pnpm's [installation guide](https://pnpm.io/installation) for other options.
+  The exact pnpm version is pinned in the `packageManager` field of `package.json`, and pnpm automatically runs that pinned version (via its built-in package-manager version management), so a recent pnpm install is all you need -- no separate Corepack setup required.
 - A local environment with Kafka or Schema Registry running, or a **Confluent Cloud** account with appropriate API keys or login credentials if [using OAuth to authenticate](#oauth-authentication-for-confluent-cloud).
 
 ### General Setup Steps
@@ -180,8 +199,8 @@ npx @confluentinc/mcp-confluent --init-config
 3. **Start the Server:** You can run the MCP server in one of two ways:
    - **From source:** Follow the instructions in the [Contributing Guide](CONTRIBUTING.md) to build and run the server from source.
      This typically involves:
-     - Installing dependencies (`npm install`)
-     - Building the project (`npm run build` or `npm run dev`)
+     - Installing dependencies (`pnpm install`)
+     - Building the project (`pnpm run build` or `pnpm run dev`)
    - **With npx:** You can start the server directly using npx, no build required:
 
      ```bash
@@ -204,8 +223,8 @@ The full configuration reference — YAML schema, every service block, env-var i
 
 > **Compatibility note.** This release ships full parity between YAML (`-c config.yaml`) and the legacy env-var path (`-e config.env`) for a single connection.
 > The env-var-only path will emit a startup warning in a near-future release and be removed a release or two later.
-> Multi-connection support (next release) will be YAML-only.
-> See [CONFIGURATION.md → Two paths, one configuration](CONFIGURATION.md#two-paths-one-configuration).
+> Defining multiple connections (or none) is YAML-only — the env-var path can express only a single connection.
+> See [CONFIGURATION.md → Two paths, one configuration](CONFIGURATION.md#two-paths-one-configuration) and [CONFIGURATION.md → Multiple connections (and zero connections)](CONFIGURATION.md#multiple-connections-and-zero-connections).
 
 ### Prerequisites & setup for Tableflow commands
 
@@ -383,17 +402,18 @@ flink:
   detect-flink-statement-issues: Detect issues for a Flink SQL statement by analyzing status, exceptions, and performance metrics. Identifies problems...
   get-flink-statement-exceptions: Retrieve the 10 most recent exceptions for a Flink SQL statement. Useful for diagnosing failed or failing statements.
   get-flink-statement-profile: Get Query Profiler data for a Flink SQL statement. Returns the task graph with human-readable task/operator names, pe...
+  get-flink-statement-results: Fetch the result rows produced by a Flink SQL statement.
   get-flink-table-info: Get table metadata via INFORMATION_SCHEMA.TABLES. Returns watermark configuration, distribution info, and table type.
+  list-compute-pools: Get the Flink compute pools in the Confluent Cloud environment. Paginated; if the response includes a nextPageToken, pas...
   list-flink-catalogs: List all catalogs available in the Flink environment via INFORMATION_SCHEMA.CATALOGS.
   list-flink-databases: List all databases (schemas) in a Flink catalog via INFORMATION_SCHEMA.SCHEMATA. Returns catalog and database names.
   list-flink-statements: Retrieve a sorted, filtered, paginated list of all statements.
   list-flink-tables: List all tables in a Flink database via INFORMATION_SCHEMA.TABLES. Returns table names and types.
-  read-flink-statement: Make a request to read a statement and its results
 
 kafka:
   alter-topic-config: Alter topic configuration in Confluent Cloud.
   consume-messages: Consume messages from Kafka topics. Optionally restrict to a partition, start from an offset, timestamp, earliest, la...
-  create-topics: Create one or more Kafka topics with an optional partition count.
+  create-topics: Create one or more Kafka topics with an optional partition count and replication factor.
   delete-topics: Delete the topic with the given names.
   describe-consumer-group: Describe a single consumer group on a Kafka cluster. Returns the group's state, type, protocol, partition assignor, c...
   get-consumer-group-lag: Compute live offset lag for a single Kafka consumer group. Returns per-(topic, partition) {committedOffset, highWater...
@@ -404,13 +424,16 @@ kafka:
   produce-message: Produce records to a Kafka topic. Supports Confluent Schema Registry serialization (AVRO, JSON, PROTOBUF) for both ke...
 
 mcp-server-diagnostics:
+  config-help: Call when the user wants to enable or unlock a specific tool (e.g. "how do I enable the tableflow tools?", "what config does cr...
   explain-disabled-tools: Call when the user asks why a tool is missing or unavailable (e.g., "why can't I list Kafka topics?", "where are the ...
+  list-configured-connections: List every configured connection and the connection-routable tools you can invoke against each. The connection id (th...
 
 metrics:
   list-available-metrics: List available Confluent Cloud metrics and their filter fields from the Telemetry API. Use this tool BEFORE query-met...
   query-metrics: Query Confluent Cloud metrics from the Telemetry API. IMPORTANT: Use the list-available-metrics tool first to discove...
 
 schema-registry:
+  create-schema: Register a new schema (or a new version of an existing schema) under a subject in the Schema Registry.
   delete-schema: Delete a schema subject or a specific version from the Schema Registry. If version is omitted, all versions of the su...
   list-schemas: List all schemas in the Schema Registry.
 
@@ -448,13 +471,13 @@ Please refer to the following guides for step-by-step instructions on setting up
 
 ## Telemetry
 
-This MCP server collects usage data to help make improvements.
-You can opt out by setting `DO_NOT_TRACK=true` in your environment.
-See [telemetry.md](telemetry.md) for full details on what is collected.
+This MCP server collects usage data and reports server-side runtime errors (via [Sentry](https://sentry.io)) to help make improvements.
+You can opt out of both by setting `DO_NOT_TRACK=true` in your environment (or `server.do_not_track: true` in YAML).
+See [telemetry.md](telemetry.md) for full details on what is collected and what is never sent.
 
 ## Troubleshooting
 
-**"Node.js version not supported"** -- This project requires Node.js 22 or later.
+**"Node.js version not supported"** -- This project requires Node.js 22.19.0 or later.
 Check your version with `node -v` and upgrade if needed.
 
 **Tools not appearing** -- Each tool requires specific service blocks in your `config.yaml`.

package/config.example.yaml

@@ -8,9 +8,11 @@
 # rather than the YAML itself. Plain literal values are also fine when you do
 # not need interpolation.
 #
-# Each sub-block under `connections.<name>` is independently optional; remove
-# the ones you do not need. At least one of `kafka`, `schema_registry`,
-# `confluent_cloud`, `flink`, `tableflow`, or `telemetry` must remain.
+# Each service block under a `direct` connection (`kafka`, `schema_registry`,
+# `confluent_cloud`, `flink`, `tableflow`, `telemetry`) is independently
+# optional; remove the ones you do not need, but at least one must remain. An
+# `oauth` connection carries no service blocks — see the commented-out example
+# at the end of this file.
 
 # --- Server ---
 # MCP server transport, authentication, and logging settings.
@@ -64,13 +66,26 @@ server:
     # disabled: true
 
 connections:
-  # Connection name is freeform. Today exactly one connection is read at
-  # runtime; multi-connection support is the focus of the next release, and
-  # this plural structure is here so that landing it does not require any
-  # schema changes on your side.
+  # Connection id is freeform. A config may define several connections
+  # and route each tool call to one by id — and may mix api-key (`direct`)
+  # connections with at most one browser-login (`oauth`) connection. See the
+  # commented-out OAuth connection at the end of this file.
   default:
     type: direct
 
+    # Optional human-readable label for this connection, echoed back by the
+    # `list-configured-connections` tool so an agent can tell your connections apart.
+    # A blank value is treated as no description.
+    description: "Primary Confluent Cloud connection"
+
+    # Read-only policy (default false). With `read_only: true`, every tool that
+    # mutates state is auto-disabled for this connection — only read-only tools
+    # stay enabled (a tool's posture comes from its `readOnlyHint` annotation).
+    # Use it to hand an agent a staging/prod connection while keeping full
+    # read/write on a dev one. Left at the default here so this connection
+    # stays read/write:
+    # read_only: true
+
     # --- Kafka ---
     # `bootstrap_servers` is required for any Kafka client (admin, producer,
     # consumer). `rest_endpoint` + `cluster_id` + `env_id` are required for
@@ -147,3 +162,17 @@ connections:
     #     type: api_key
     #     key: "${TELEMETRY_API_KEY}"
     #     secret: "${TELEMETRY_API_SECRET}"
+
+  # --- OAuth connection (browser login instead of API keys) ---
+  # A config may pair any number of `direct` connections like the one above with
+  # at most one `oauth` connection. Uncomment to add one: on the first tool call
+  # needing Confluent Cloud access, the server opens the CCloud sign-in page
+  # (PKCE) and reuses that session for the rest of the process — no API keys to
+  # provision. OAuth connections carry no service blocks; resource IDs
+  # (cluster_id, environment_id, ...) are passed as tool arguments at call time.
+  # Not every tool is OAuth-eligible yet (see CONFIGURATION.md → Authentication
+  # modes). For an OAuth-only starter, run `--init-oauth-config` instead.
+  # ccloud:
+  #   type: oauth
+  #   description: "Confluent Cloud (OAuth login)"
+  #   # read_only: true

package/config.oauth.example.yaml

@@ -32,11 +32,24 @@
 #     # disabled: true
 
 connections:
-  # Connection name is freeform. The `type: oauth` declaration is the only
+  # Connection id is freeform. The `type: oauth` declaration is the only
   # required field.
   ccloud-oauth:
     type: oauth
 
+    # Optional human-readable label for this connection, echoed back by the
+    # `list-configured-connections` tool so an agent can tell your connections apart.
+    # A blank value is treated as no description.
+    description: "Confluent Cloud (OAuth login)"
+
+    # Read-only policy (default false). With `read_only: true`, every tool that
+    # mutates state is auto-disabled for this connection — only read-only tools
+    # stay enabled (a tool's posture comes from its `readOnlyHint` annotation,
+    # so there is nothing to configure per-tool). This is the recommended
+    # posture for pointing an agent at a production Cloud login while keeping
+    # full read/write on a dev connection. Uncomment to lock this one down:
+    # read_only: true
+
     # librdkafka `debug` contexts to emit on stderr for this OAuth connection's
     # native Kafka client. Reach for it when an OAuth/OAUTHBEARER SASL handshake
     # misbehaves and you need to see which side broke — works the same in

package/dist/build-config.d.ts

@@ -1,2 +1,3 @@
 export declare const TELEMETRY_WRITE_KEY = "";
+export declare const SENTRY_DSN = "";
 //# sourceMappingURL=build-config.d.ts.map

package/dist/build-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-config.d.ts","sourceRoot":"","sources":["../src/build-config.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,mBAAmB,KAAK,CAAC"}
+{"version":3,"file":"build-config.d.ts","sourceRoot":"","sources":["../src/build-config.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,UAAU,KAAK,CAAC"}

package/dist/build-config.js

@@ -1,2 +1,3 @@
 // build-time values injected by scripts/inject-build-config.mjs during `npm pack`
 export const TELEMETRY_WRITE_KEY = "r8x6rkJhvAkwtFMklJ93VfURC2X5jqBb";
+export const SENTRY_DSN = "https://cf649c7d3782809b1b475085cb8b72d9@o114100.ingest.us.sentry.io/4511649921761280";

package/dist/build-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-config.js","sourceRoot":"","sources":["../src/build-config.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC"}
+{"version":3,"file":"build-config.js","sourceRoot":"","sources":["../src/build-config.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AACtC,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC"}

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 import { ToolName } from "./confluent/tools/tool-name.js";
 import { TransportType } from "./mcp/transports/types.js";
-import { KeyValuePairObject } from "properties-file";
+import type { KeyValuePairObject } from "properties-file";
 /**
  * Thrown when Commander has already printed help or version text and the process
  * should exit cleanly (code 0). Callers catch this to call process.exit(0)

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,OAAO,EAAiB,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGpE;;;;GAIG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;;CAKxD;AAGD,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAkGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAwJvD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,EAAE,MAAM,EAAE,GACnB,QAAQ,EAAE,CA4CZ;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAexE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAI1D;;;;GAIG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;;CAKxD;AAGD,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAiRD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAmBvD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,EAAE,MAAM,EAAE,GACnB,QAAQ,EAAE,CAmBZ;AA6CD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAexE"}

package/dist/cli.js

@@ -73,6 +73,47 @@ function readFileLines(filePath) {
         .filter((line) => line && !line.startsWith("#"));
     return lines;
 }
+/**
+ * Enforces the three post-parse mutual-exclusivity rules not already covered by
+ * `assertNoConfigConflicts` (which handles `--config`'s exclusivity with
+ * `--transport`, `--disable-auth`, `--allowed-hosts`, and `--kafka-config-file`).
+ */
+function assertNoMutuallyExclusiveOptions(opts) {
+    if (opts.ccloudEnv && !opts.oauth) {
+        throw new Error("--ccloud-env requires --oauth");
+    }
+    if (opts.oauth && opts.config) {
+        throw new Error("--oauth and --config cannot be combined: declare OAuth as a connection inside the YAML (type: oauth) instead of passing --oauth");
+    }
+    if (opts.initConfig && opts.initOauthConfig) {
+        throw new Error("--init-config and --init-oauth-config are mutually exclusive: pick one template to bootstrap.");
+    }
+}
+/**
+ * Resolves the shared allow/block-list precedence: an inline CLI value wins,
+ * otherwise fall back to reading the file, otherwise undefined.
+ */
+function resolveToolList(inlineValue, fileValue) {
+    if (inlineValue) {
+        return parseToolList(inlineValue);
+    }
+    if (fileValue) {
+        return readFileLines(fileValue);
+    }
+    return undefined;
+}
+/**
+ * Translates a Commander parse failure into `DisplayedCommandLineUsageError`
+ * when Commander already printed help/version text, otherwise rethrows as-is.
+ */
+function rethrowCommanderError(error) {
+    if (error instanceof CommanderError &&
+        (error.code === "commander.helpDisplayed" ||
+            error.code === "commander.version")) {
+        throw new DisplayedCommandLineUsageError();
+    }
+    throw error;
+}
 function assertNoConfigConflicts(config, kafkaConfigFile, disableAuth, allowedHosts, transportExplicitlySet) {
     if (!config)
         return;
@@ -94,21 +135,12 @@ function assertNoConfigConflicts(config, kafkaConfigFile, disableAuth, allowedHo
     }
 }
 /**
- * Parse command line arguments into a structured CLIOptions object.
- *
- * Only minimally interprets the raw CLI input in order to populate CLIOptions:
- *  1. Will dereference and parse named files for tool allow/block lists.
- *  2. Will parse the kafka config properties file into an object.
- *
- * Does NOT load environment variables from the env file, nor does it load or
- * validate the YAML configuration file.
- *
- * @param argv - Array of command line arguments (e.g., process.argv)
- * @returns Structured CLIOptions object with parsed and validated values.
- * @throws Error if CLI arguments are invalid, if specified files cannot be read, or if file contents are malformed.
+ * Builds the Commander program definition (name, description, all options).
+ * Split out from `parseCliArgs` purely so `ParsedCliOptions` below can be
+ * derived from its return type instead of hand-duplicated.
  */
-export function parseCliArgs(argv) {
-    const program = new Command()
+function buildProgram() {
+    return new Command()
         .name("mcp-confluent")
         .description("Confluent MCP Server - Model Context Protocol implementation for Confluent Cloud")
         .version(getPackageVersion())
@@ -133,67 +165,60 @@ export function parseCliArgs(argv) {
         .addOption(new Option("--ccloud-env <env>", "Override the Auth0 environment for --oauth (devel/stag/prod). Defaults to prod when omitted.").choices(["devel", "stag", "prod"]))
         .allowExcessArguments(false)
         .exitOverride();
+}
+/**
+ * Maps Commander's parsed options to the CLIOptions shape returned by
+ * `parseCliArgs`, applying the allow/block tool-list precedence and the
+ * optional-field coercions the CLI contract requires.
+ */
+function optsToCliOptions(opts) {
+    return {
+        envFile: opts.envFile,
+        config: opts.config,
+        transports: Array.isArray(opts.transport)
+            ? opts.transport
+            : [opts.transport],
+        allowTools: resolveToolList(opts.allowTools, opts.allowToolsFile),
+        blockTools: resolveToolList(opts.blockTools, opts.blockToolsFile),
+        listTools: !!opts.listTools,
+        kafkaConfig: opts.kafkaConfigFile
+            ? parsePropertiesFile(opts.kafkaConfigFile)
+            : undefined,
+        disableAuth: opts.disableAuth ? true : undefined,
+        allowedHosts: opts.allowedHosts
+            ? opts.allowedHosts.split(",").map((h) => h.trim().toLowerCase())
+            : undefined,
+        generateKey: !!opts.generateKey,
+        initConfig: !!opts.initConfig,
+        initOauthConfig: !!opts.initOauthConfig,
+        oauth: opts.oauth,
+        ccloudEnv: opts.ccloudEnv,
+    };
+}
+/**
+ * Parse command line arguments into a structured CLIOptions object.
+ *
+ * Only minimally interprets the raw CLI input in order to populate CLIOptions:
+ *  1. Will dereference and parse named files for tool allow/block lists.
+ *  2. Will parse the kafka config properties file into an object.
+ *
+ * Does NOT load environment variables from the env file, nor does it load or
+ * validate the YAML configuration file.
+ *
+ * @param argv - Array of command line arguments (e.g., process.argv)
+ * @returns Structured CLIOptions object with parsed and validated values.
+ * @throws Error if CLI arguments are invalid, if specified files cannot be read, or if file contents are malformed.
+ */
+export function parseCliArgs(argv) {
+    const program = buildProgram();
     try {
         const opts = program.parse(argv).opts();
         assertNoConfigConflicts(opts.config, opts.kafkaConfigFile, opts.disableAuth, opts.allowedHosts, program.getOptionValueSource("transport") === "cli");
-        if (opts.ccloudEnv && !opts.oauth) {
-            throw new Error("--ccloud-env requires --oauth");
-        }
-        if (opts.oauth && opts.config) {
-            throw new Error("--oauth and --config cannot be combined: declare OAuth as a connection inside the YAML (type: oauth) instead of passing --oauth");
-        }
-        if (opts.initConfig && opts.initOauthConfig) {
-            throw new Error("--init-config and --init-oauth-config are mutually exclusive: pick one template to bootstrap.");
-        }
-        // Precedence: CLI > file > undefined
-        let allowTools = undefined;
-        let blockTools = undefined;
-        if (opts.allowTools) {
-            allowTools = parseToolList(opts.allowTools);
-        }
-        else if (opts.allowToolsFile) {
-            allowTools = readFileLines(opts.allowToolsFile);
-        }
-        if (opts.blockTools) {
-            blockTools = parseToolList(opts.blockTools);
-        }
-        else if (opts.blockToolsFile) {
-            blockTools = readFileLines(opts.blockToolsFile);
-        }
-        return {
-            envFile: opts.envFile,
-            config: opts.config,
-            transports: Array.isArray(opts.transport)
-                ? opts.transport
-                : [opts.transport],
-            allowTools,
-            blockTools,
-            listTools: !!opts.listTools,
-            kafkaConfig: opts.kafkaConfigFile
-                ? parsePropertiesFile(opts.kafkaConfigFile)
-                : undefined,
-            disableAuth: opts.disableAuth ? true : undefined,
-            allowedHosts: opts.allowedHosts
-                ? opts.allowedHosts
-                    .split(",")
-                    .map((h) => h.trim().toLowerCase())
-                : undefined,
-            generateKey: !!opts.generateKey,
-            initConfig: !!opts.initConfig,
-            initOauthConfig: !!opts.initOauthConfig,
-            oauth: opts.oauth,
-            ccloudEnv: opts.ccloudEnv,
-        };
+        assertNoMutuallyExclusiveOptions(opts);
+        return optsToCliOptions(opts);
     }
     catch (error) {
-        if (error instanceof CommanderError &&
-            (error.code === "commander.helpDisplayed" ||
-                error.code === "commander.version")) {
-            // Help or version was displayed, signal to main() to exit(0).
-            throw new DisplayedCommandLineUsageError();
-        }
-        // throw anything else as back to main() unchanged.
-        throw error;
+        rethrowCommanderError(error);
     }
 }
 /**
@@ -256,34 +281,43 @@ export function loadDotEnvFile(envFile) {
  * @returns An alphabetically sorted array of enabled ToolNames.
  */
 export function getFilteredToolNames(allowTools, blockTools) {
-    let filteredToolNames = new Set(Object.values(ToolName));
     const validToolNames = new Set(Object.values(ToolName));
-    if ((!allowTools || allowTools.length === 0) &&
-        (!blockTools || blockTools.length === 0)) {
+    if (allowTools.length === 0 && blockTools.length === 0) {
         logger.info("No allow/block tool lists provided; all tools are enabled by default.");
     }
-    else {
-        if (allowTools.length > 0) {
-            const valid = allowTools.filter((t) => validToolNames.has(t));
-            const invalid = allowTools.filter((t) => !validToolNames.has(t));
-            if (invalid.length > 0) {
-                logger.warn(`Ignoring invalid tool names in allow list: ${invalid.join(", ")}`);
-            }
-            filteredToolNames = new Set(valid.map((t) => t));
-        }
-        if (blockTools.length > 0) {
-            const validBlock = new Set(blockTools.filter((t) => validToolNames.has(t)));
-            const invalidBlock = blockTools.filter((t) => !validToolNames.has(t));
-            if (invalidBlock.length > 0) {
-                logger.warn(`Ignoring invalid tool names in block list: ${invalidBlock.join(", ")}`);
-            }
-            for (const tool of validBlock) {
-                filteredToolNames.delete(tool);
-            }
-        }
+    const filteredToolNames = allowTools.length > 0
+        ? applyAllowList(allowTools, validToolNames)
+        : new Set(validToolNames);
+    if (blockTools.length > 0) {
+        applyBlockList(filteredToolNames, blockTools, validToolNames);
+    }
+    return Array.from(filteredToolNames).sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Narrows `allowTools` to the set of valid `ToolName`s, warning about any
+ * unrecognized names rather than rejecting the whole list.
+ */
+function applyAllowList(allowTools, validToolNames) {
+    const valid = allowTools.filter((t) => validToolNames.has(t));
+    const invalid = allowTools.filter((t) => !validToolNames.has(t));
+    if (invalid.length > 0) {
+        logger.warn(`Ignoring invalid tool names in allow list: ${invalid.join(", ")}`);
+    }
+    return new Set(valid.map((t) => t));
+}
+/**
+ * Removes `blockTools`' valid `ToolName`s from `current` in place, warning
+ * about any unrecognized names rather than rejecting the whole list.
+ */
+function applyBlockList(current, blockTools, validToolNames) {
+    const validBlock = new Set(blockTools.filter((t) => validToolNames.has(t)));
+    const invalidBlock = blockTools.filter((t) => !validToolNames.has(t));
+    if (invalidBlock.length > 0) {
+        logger.warn(`Ignoring invalid tool names in block list: ${invalidBlock.join(", ")}`);
+    }
+    for (const tool of validBlock) {
+        current.delete(tool);
     }
-    // Convert to array, sort, return.
-    return Array.from(filteredToolNames).sort();
 }
 /**
  * Loads configuration from a properties file