@confluentinc/mcp-confluent 1.2.1 → 1.3.0

package/dist/confluent/oauth/token-lifetimes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-lifetimes.js","sourceRoot":"","sources":["../../../src/confluent/oauth/token-lifetimes.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE7D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE3D,oFAAoF;AACpF,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAErE,oFAAoF;AACpF,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjE,uFAAuF;AACvF,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,GAAG,IAAI,CAAC;AAEzD,gFAAgF;AAChF,MAAM,CAAC,MAAM,kCAAkC,GAAG,EAAE,CAAC"}

package/dist/confluent/oauth/types.d.ts

@@ -0,0 +1,68 @@
+export type Auth0Environment = "devel" | "stag" | "prod";
+export interface Auth0Config {
+    clientId: string;
+    domain: string;
+    apiUrl: string;
+    /** Confluent Cloud REST API base URL for this environment (e.g. https://api.confluent.cloud for prod). */
+    cloudRestUrl: string;
+    callbackUrl: string;
+    scopes: string;
+}
+export interface ConfluentTokenSet {
+    /** Auth0 refresh token — single-use, rotated each refresh cycle */
+    refreshToken: string;
+    /** Absolute expiration of the refresh token family (epoch ms). 8hr from original login. */
+    refreshTokenAbsoluteExpiresAt: number;
+    /** Idle expiration of the current refresh token (epoch ms). 4hr from last rotation. */
+    refreshTokenIdleExpiresAt: number;
+    /** Confluent Cloud control plane token (Bearer token for api.confluent.cloud) */
+    controlPlaneToken: string;
+    /** Control plane token expiration (epoch ms). ~5 min TTL. */
+    controlPlaneExpiresAt: number;
+    /** Confluent Cloud data plane token (Bearer token for cluster-specific endpoints) */
+    dataPlaneToken: string;
+    /** Data plane token expiration (epoch ms). ~10 min TTL. */
+    dataPlaneExpiresAt: number;
+    /** Opaque access token returned to MCP clients. Stable across refreshes. */
+    accessToken: string;
+}
+export interface OAuthConfig {
+    auth: "oauth";
+    environment: Auth0Environment;
+}
+/**
+ * Response from POST login.confluent.io/oauth/token
+ */
+export interface Auth0TokenResponse {
+    id_token: string;
+    refresh_token: string;
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+}
+/**
+ * User identity returned in the body of POST confluent.cloud/api/sessions.
+ * Sourced from the JSON response, not from any JWT claim. Fields beyond what
+ * we consume are intentionally omitted.
+ */
+export interface UserDetails {
+    id?: string;
+    email?: string;
+    resource_id?: string;
+}
+/**
+ * Response from POST confluent.cloud/api/sessions
+ */
+export interface ControlPlaneTokenResponse {
+    token: string;
+    expires_at: string;
+    user?: UserDetails;
+}
+/**
+ * Response from POST confluent.cloud/api/access_tokens
+ */
+export interface DataPlaneTokenResponse {
+    token: string;
+    expires_at: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/confluent/oauth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/confluent/oauth/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,6BAA6B,EAAE,MAAM,CAAC;IACtC,uFAAuF;IACvF,yBAAyB,EAAE,MAAM,CAAC;IAElC,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;IAE9B,qFAAqF;IACrF,cAAc,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,kBAAkB,EAAE,MAAM,CAAC;IAE3B,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,gBAAgB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/confluent/oauth/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/confluent/oauth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/confluent/oauth/types.ts"],"names":[],"mappings":""}

package/dist/confluent/oauth-client-manager.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview OAuth (bearer-auth) client manager. Wires Confluent Cloud
+ * REST surfaces, native Kafka admin/producer/consumer (via `@confluentinc/kafka-javascript` +
+ * SASL/OAUTHBEARER), and the Schema Registry SDK to bearer tokens supplied
+ * by an {@link OAuthHolder}. REST endpoint URLs and Kafka bootstrap servers
+ * are resolved at call time from the CCloud environment + cluster IDs the
+ * agent supplies as tool args.
+ *
+ * Native Kafka clients are built fresh per call; handlers wrap usage in
+ * `try { ... } finally { await disposeIfOAuth(...) }` for caller-owned
+ * disposal. SASL/OAUTHBEARER is configured via librdkafka's synchronous
+ * token-refresh callback (no kafkaJS-compat async-provider race), so no
+ * warmup workaround is needed.
+ *
+ * Schema Registry serialization is supported through `produce-message` and
+ * `consume-messages`: the manager's `getSchemaRegistrySdkClient` auto-resolves
+ * the SR cluster id from the environment id supplied by the agent (single SR
+ * per environment is the CCloud invariant) and builds a bearer-authenticated
+ * SDK client per call.
+ */
+import type { KafkaJS } from "@confluentinc/kafka-javascript";
+import { SchemaRegistryClient } from "@confluentinc/schemaregistry";
+import { BaseClientManager } from "../confluent/base-client-manager.js";
+import type { ConfluentRestClient } from "../confluent/client-manager.js";
+import { OAuthHolder } from "../confluent/oauth/oauth-holder.js";
+import type { Auth0Environment } from "../confluent/oauth/types.js";
+/**
+ * Bearer-auth client manager. Wires every REST surface to the OAuth holder's
+ * tokens — control plane (cloud / tableflow / telemetry) reads
+ * {@link OAuthHolder.getControlPlaneToken}; data plane (flink / schema-registry
+ * REST / kafka REST) reads {@link OAuthHolder.getDataPlaneToken}. Cloud REST URL
+ * is auto-derived from the CCloud env. Native Kafka clients (admin, producer,
+ * consumer) are built fresh per call against bootstrap endpoints resolved
+ * via the cmk REST API; SASL/OAUTHBEARER is configured via librdkafka's
+ * synchronous token-refresh callback to avoid the kafkaJS-compat
+ * async-provider race that previously required a warmup workaround.
+ */
+export declare class OAuthClientManager extends BaseClientManager {
+    private readonly holder;
+    private readonly kafkaDebug;
+    /**
+     * @param kafkaDebug Optional librdkafka `debug` contexts string, threaded
+     *   through to every native Kafka client built by this manager. Sourced
+     *   from `connections.<name>.kafka_debug` on the OAuth YAML arm; used as a
+     *   diagnostic knob when a SASL/OAUTHBEARER handshake misbehaves.
+     */
+    constructor(holder: OAuthHolder, env: Auth0Environment, kafkaDebug?: string);
+    /** @inheritdoc */
+    getSchemaRegistrySdkClient(envId?: string): Promise<SchemaRegistryClient>;
+    /** @inheritdoc */
+    getConfluentCloudKafkaRestClient(clusterId?: string, envId?: string): Promise<ConfluentRestClient>;
+    /** @inheritdoc */
+    getSchemaRegistryRestClient(envId?: string): Promise<ConfluentRestClient>;
+    /** @inheritdoc */
+    getKafkaAdminClient(clusterId?: string, envId?: string): Promise<KafkaJS.Admin>;
+    /** @inheritdoc */
+    getKafkaProducer(clusterId?: string, envId?: string): Promise<KafkaJS.Producer>;
+    /** @inheritdoc */
+    buildKafkaConsumer(clusterId?: string, envId?: string, groupId?: string): Promise<KafkaJS.Consumer>;
+    /** @inheritdoc */
+    disconnect(): Promise<void>;
+    /**
+     * Returns the current data-plane token, throwing when none is available.
+     * Used by every OAuth-side client accessor to fail fast before
+     * constructing a client with an empty bearer.
+     *
+     * The MCP tool-call gate calls `holder.ensureLoggedIn()` before any
+     * handler that needs Confluent access, so by the time this method runs
+     * login has already completed. A missing DPAT here means the holder was
+     * cleared mid-call (shutdown raced with a tool call) or a non-transient
+     * refresh error has invalidated the token between the gate check and
+     * the client construction — both rare and surface a clear message.
+     */
+    private requireDataPlaneToken;
+    private requireClusterArgs;
+    private buildOAuthKafkaClient;
+}
+//# sourceMappingURL=oauth-client-manager.d.ts.map

package/dist/confluent/oauth-client-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-client-manager.d.ts","sourceRoot":"","sources":["../../src/confluent/oauth-client-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAgB,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAa5E,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAqBtE;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,SAAQ,iBAAiB;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAEhD;;;;;OAKG;gBACS,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,gBAAgB,EAAE,UAAU,CAAC,EAAE,MAAM;IA8B3E,kBAAkB;IACZ,0BAA0B,CAC9B,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,oBAAoB,CAAC;IA0BhC,kBAAkB;IACZ,gCAAgC,CACpC,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC;IAoB/B,kBAAkB;IACZ,2BAA2B,CAC/B,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC;IA0B/B,kBAAkB;IACZ,mBAAmB,CACvB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;IAuBzB,kBAAkB;IACZ,gBAAgB,CACpB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAQ5B,kBAAkB;IACZ,kBAAkB,CACtB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAY5B,kBAAkB;IACZ,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,kBAAkB;YAiBZ,qBAAqB;CAuDpC"}

package/dist/confluent/oauth-client-manager.js

@@ -0,0 +1,265 @@
+/**
+ * @fileoverview OAuth (bearer-auth) client manager. Wires Confluent Cloud
+ * REST surfaces, native Kafka admin/producer/consumer (via `@confluentinc/kafka-javascript` +
+ * SASL/OAUTHBEARER), and the Schema Registry SDK to bearer tokens supplied
+ * by an {@link OAuthHolder}. REST endpoint URLs and Kafka bootstrap servers
+ * are resolved at call time from the CCloud environment + cluster IDs the
+ * agent supplies as tool args.
+ *
+ * Native Kafka clients are built fresh per call; handlers wrap usage in
+ * `try { ... } finally { await disposeIfOAuth(...) }` for caller-owned
+ * disposal. SASL/OAUTHBEARER is configured via librdkafka's synchronous
+ * token-refresh callback (no kafkaJS-compat async-provider race), so no
+ * warmup workaround is needed.
+ *
+ * Schema Registry serialization is supported through `produce-message` and
+ * `consume-messages`: the manager's `getSchemaRegistrySdkClient` auto-resolves
+ * the SR cluster id from the environment id supplied by the agent (single SR
+ * per environment is the CCloud invariant) and builds a bearer-authenticated
+ * SDK client per call.
+ */
+import { SchemaRegistryClient } from "@confluentinc/schemaregistry";
+import { BaseClientManager } from "../confluent/base-client-manager.js";
+import { createAuthMiddleware, } from "../confluent/middleware.js";
+import { kafkaDeps } from "../confluent/node-deps.js";
+import { resolveKafkaBootstrap, resolveKafkaRestEndpoint, resolveSchemaRegistryClusterId, resolveSchemaRegistryEndpoint, } from "../confluent/oauth-resource-resolvers.js";
+import { getCloudRestUrlForEnv } from "../confluent/oauth/auth0-config.js";
+import { kafkaLogger } from "../logger.js";
+import createClient from "openapi-fetch";
+import { DATA_PLANE_TOKEN_LIFETIME_MS } from "./oauth/token-lifetimes.js";
+/**
+ * Bearer-auth client manager. Wires every REST surface to the OAuth holder's
+ * tokens — control plane (cloud / tableflow / telemetry) reads
+ * {@link OAuthHolder.getControlPlaneToken}; data plane (flink / schema-registry
+ * REST / kafka REST) reads {@link OAuthHolder.getDataPlaneToken}. Cloud REST URL
+ * is auto-derived from the CCloud env. Native Kafka clients (admin, producer,
+ * consumer) are built fresh per call against bootstrap endpoints resolved
+ * via the cmk REST API; SASL/OAUTHBEARER is configured via librdkafka's
+ * synchronous token-refresh callback to avoid the kafkaJS-compat
+ * async-provider race that previously required a warmup workaround.
+ */
+export class OAuthClientManager extends BaseClientManager {
+    holder;
+    kafkaDebug;
+    /**
+     * @param kafkaDebug Optional librdkafka `debug` contexts string, threaded
+     *   through to every native Kafka client built by this manager. Sourced
+     *   from `connections.<name>.kafka_debug` on the OAuth YAML arm; used as a
+     *   diagnostic knob when a SASL/OAUTHBEARER handshake misbehaves.
+     */
+    constructor(holder, env, kafkaDebug) {
+        const cpToken = () => holder.getControlPlaneToken();
+        const dpToken = () => holder.getDataPlaneToken();
+        super({
+            endpoints: {
+                // BaseClientManager re-uses `cloud` for the Tableflow base URL too.
+                cloud: getCloudRestUrlForEnv(env),
+                flink: undefined,
+                schemaRegistry: undefined,
+                kafka: undefined,
+                telemetry: undefined,
+            },
+            auth: {
+                cloud: { type: "oauth", getToken: cpToken },
+                tableflow: { type: "oauth", getToken: cpToken },
+                telemetry: { type: "oauth", getToken: cpToken },
+                flink: { type: "oauth", getToken: dpToken },
+                schemaRegistry: { type: "oauth", getToken: dpToken },
+                kafka: { type: "oauth", getToken: dpToken },
+            },
+        });
+        this.holder = holder;
+        this.kafkaDebug = kafkaDebug;
+        // Eager construction: surface the cloud REST client at startup so a bad
+        // endpoint or middleware wiring fails fast rather than at first tool call.
+        this.getConfluentCloudRestClient();
+    }
+    /** @inheritdoc */
+    async getSchemaRegistrySdkClient(envId) {
+        // The SR SDK captures `Authorization: Bearer <token>` in its axios
+        // `createAxiosDefaults` at construction time, so a build during initial
+        // login or a broken refresh would freeze an empty bearer into every
+        // subsequent request — fail fast here before that can happen.
+        const dpat = this.requireDataPlaneToken();
+        if (!envId) {
+            throw new Error("environment_id is required under OAuth for Schema Registry access. " +
+                "Call list-environments to discover available environments.");
+        }
+        const cloud = this.getConfluentCloudRestClient();
+        const lsrc = await resolveSchemaRegistryClusterId(cloud, envId);
+        const endpoint = await resolveSchemaRegistryEndpoint(cloud, lsrc, envId);
+        return new SchemaRegistryClient({
+            baseURLs: [endpoint],
+            createAxiosDefaults: {
+                headers: {
+                    Authorization: `Bearer ${dpat}`,
+                    "target-sr-cluster": lsrc,
+                },
+            },
+        });
+    }
+    /** @inheritdoc */
+    async getConfluentCloudKafkaRestClient(clusterId, envId) {
+        this.requireClusterArgs(clusterId, envId);
+        // The bearer middleware reads `auth.getToken()` per-request, but failing
+        // fast here gives the agent a clear error rather than letting an empty
+        // bearer go out on the wire.
+        this.requireDataPlaneToken();
+        const baseUrl = await resolveKafkaRestEndpoint(this.getConfluentCloudRestClient(), clusterId, envId);
+        const auth = {
+            type: "oauth",
+            getToken: () => this.holder.getDataPlaneToken(),
+        };
+        const client = createClient({ baseUrl });
+        client.use(createAuthMiddleware(auth));
+        return client;
+    }
+    /** @inheritdoc */
+    async getSchemaRegistryRestClient(envId) {
+        this.requireDataPlaneToken();
+        if (!envId) {
+            throw new Error("environment_id is required under OAuth for Schema Registry REST access. " +
+                "Call list-environments to discover available environments.");
+        }
+        const cloud = this.getConfluentCloudRestClient();
+        const lsrc = await resolveSchemaRegistryClusterId(cloud, envId);
+        const baseUrl = await resolveSchemaRegistryEndpoint(cloud, lsrc, envId);
+        const auth = {
+            type: "oauth",
+            getToken: () => this.holder.getDataPlaneToken(),
+        };
+        const client = createClient({
+            baseUrl,
+            // The `target-sr-cluster` header pins all requests on this client to
+            // the right logical SR cluster — mirrors the SR SDK construction in
+            // `getSchemaRegistrySdkClient`.
+            headers: { "target-sr-cluster": lsrc },
+        });
+        client.use(createAuthMiddleware(auth));
+        return client;
+    }
+    /** @inheritdoc */
+    async getKafkaAdminClient(clusterId, envId) {
+        this.requireClusterArgs(clusterId, envId);
+        const kafka = await this.buildOAuthKafkaClient(clusterId, envId);
+        const admin = kafka.admin();
+        try {
+            await admin.connect();
+            // Metadata warmup: `admin.connect()` returns before librdkafka has
+            // discovered the controller broker. The first non-list operation
+            // (createTopics, deleteTopics) needs the controller and times out
+            // locally if metadata isn't yet cached. listTopics is a cheap
+            // metadata-only roundtrip that primes the broker map; subsequent
+            // ops on this admin instance reuse it. Costs ~50-200ms per OAuth
+            // admin call; acceptable given clients are per-call by design.
+            await admin.listTopics();
+            return admin;
+        }
+        catch (err) {
+            // Disconnect the half-built admin so we don't leak the broker
+            // connection on a failed warmup.
+            await admin.disconnect().catch(() => undefined);
+            throw err;
+        }
+    }
+    /** @inheritdoc */
+    async getKafkaProducer(clusterId, envId) {
+        this.requireClusterArgs(clusterId, envId);
+        const kafka = await this.buildOAuthKafkaClient(clusterId, envId);
+        const producer = kafka.producer();
+        await producer.connect();
+        return producer;
+    }
+    /** @inheritdoc */
+    async buildKafkaConsumer(clusterId, envId, groupId) {
+        this.requireClusterArgs(clusterId, envId);
+        const kafka = await this.buildOAuthKafkaClient(clusterId, envId);
+        return kafka.consumer({
+            kafkaJS: {
+                groupId: groupId ?? "mcp-confluent",
+                autoCommit: false,
+                fromBeginning: true,
+            },
+        });
+    }
+    /** @inheritdoc */
+    async disconnect() {
+        // No state to drain — every Kafka client is caller-owned and disposed
+        // by the handler's `finally` block via `disposeIfOAuth`.
+    }
+    /**
+     * Returns the current data-plane token, throwing when none is available.
+     * Used by every OAuth-side client accessor to fail fast before
+     * constructing a client with an empty bearer.
+     *
+     * The MCP tool-call gate calls `holder.ensureLoggedIn()` before any
+     * handler that needs Confluent access, so by the time this method runs
+     * login has already completed. A missing DPAT here means the holder was
+     * cleared mid-call (shutdown raced with a tool call) or a non-transient
+     * refresh error has invalidated the token between the gate check and
+     * the client construction — both rare and surface a clear message.
+     */
+    requireDataPlaneToken() {
+        const dpat = this.holder.getDataPlaneToken();
+        if (!dpat) {
+            throw new Error("No data-plane token available. The OAuth holder may have been " +
+                "shut down or an authentication error has invalidated the token.");
+        }
+        return dpat;
+    }
+    requireClusterArgs(clusterId, envId) {
+        if (clusterId === undefined || envId === undefined) {
+            // Defensive check — handlers should validate arg-name shape and throw
+            // their own user-facing error via resolveKafkaClusterArgs (native, snake_case)
+            // or resolveKafkaRestArgs (REST, camelCase) before reaching the manager.
+            // This message fires only when a caller bypasses those resolvers, so
+            // it's worded generically rather than tied to either arg-name convention.
+            throw new Error("OAuth client construction requires a cluster id and environment id. " +
+                "Discover via list-environments and list-clusters; pass the cluster's `id` and `spec.environment.id`.");
+        }
+    }
+    async buildOAuthKafkaClient(clusterId, envId) {
+        // Ensure the DPAT is populated before librdkafka starts the SASL
+        // handshake — the synchronous `oauthbearer_token_refresh_cb` (configured
+        // below) reads it on demand, so an empty token here would surface as a
+        // broker-side auth failure with no useful diagnostic.
+        this.requireDataPlaneToken();
+        // librdkafka debug logs — gated by `kafka_debug` on the OAuth YAML arm so
+        // they don't pollute normal server stderr. Set
+        // `connections.<name>.kafka_debug: "security,broker,protocol"` (or "all")
+        // to see the full SASL/OAUTHBEARER handshake and broker traffic.
+        const debug = this.kafkaDebug;
+        const bootstrap = await resolveKafkaBootstrap(this.getConfluentCloudRestClient(), clusterId, envId);
+        const config = {
+            "bootstrap.servers": bootstrap,
+            "security.protocol": "sasl_ssl",
+            "sasl.mechanisms": "OAUTHBEARER",
+            // Synchronous librdkafka-native refresh callback. Reads the holder's
+            // current DPAT and pushes it into librdkafka via postProcessTokenRefresh
+            // inline — no async, no microtask race with the SASL state machine.
+            oauthbearer_token_refresh_cb: (_oauthbearerConfig, postProcessTokenRefresh) => {
+                const dpat = this.holder.getDataPlaneToken();
+                if (!dpat) {
+                    postProcessTokenRefresh(new Error("Data-plane token unavailable for SASL refresh"));
+                    return;
+                }
+                postProcessTokenRefresh(null, {
+                    tokenValue: dpat,
+                    lifetime: Date.now() + DATA_PLANE_TOKEN_LIFETIME_MS,
+                    principal: clusterId,
+                    extensions: { logicalCluster: clusterId },
+                });
+            },
+            ...(debug ? { debug } : {}),
+        };
+        // Critical for stdio MCP: route KafkaJS / librdkafka logs through pino
+        // (which writes to stderr). Without this, the default logger prints to
+        // stdout in pretty format, corrupting the stdio JSON-RPC stream.
+        return new kafkaDeps.Kafka({
+            ...config,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            kafkaJS: { logger: kafkaLogger },
+        });
+    }
+}
+//# sourceMappingURL=oauth-client-manager.js.map

package/dist/confluent/oauth-client-manager.js.map

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

package/dist/confluent/oauth-resource-resolvers.d.ts

@@ -0,0 +1,6 @@
+import type { ConfluentRestClient } from "../confluent/client-manager.js";
+export declare function resolveKafkaBootstrap(cloudClient: ConfluentRestClient, clusterId: string, envId: string): Promise<string>;
+export declare function resolveKafkaRestEndpoint(cloudClient: ConfluentRestClient, clusterId: string, envId: string): Promise<string>;
+export declare function resolveSchemaRegistryEndpoint(cloudClient: ConfluentRestClient, clusterId: string, envId: string): Promise<string>;
+export declare function resolveSchemaRegistryClusterId(cloudClient: ConfluentRestClient, envId: string): Promise<string>;
+//# sourceMappingURL=oauth-resource-resolvers.d.ts.map

package/dist/confluent/oauth-resource-resolvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-resource-resolvers.d.ts","sourceRoot":"","sources":["../../src/confluent/oauth-resource-resolvers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,mBAAmB,EAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,mBAAmB,EAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,wBAAsB,6BAA6B,CACjD,WAAW,EAAE,mBAAmB,EAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,wBAAsB,8BAA8B,CAClD,WAAW,EAAE,mBAAmB,EAChC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAgCjB"}

package/dist/confluent/oauth-resource-resolvers.js

@@ -0,0 +1,65 @@
+export async function resolveKafkaBootstrap(cloudClient, clusterId, envId) {
+    const { data, error } = await cloudClient.GET("/cmk/v2/clusters/{id}", {
+        params: { path: { id: clusterId }, query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to read Kafka cluster ${clusterId} in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const bootstrap = data?.spec?.kafka_bootstrap_endpoint;
+    if (typeof bootstrap !== "string" || bootstrap.length === 0) {
+        throw new Error(`Cluster ${clusterId} in environment ${envId} has no kafka_bootstrap_endpoint`);
+    }
+    return bootstrap;
+}
+export async function resolveKafkaRestEndpoint(cloudClient, clusterId, envId) {
+    const { data, error } = await cloudClient.GET("/cmk/v2/clusters/{id}", {
+        params: { path: { id: clusterId }, query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to read Kafka cluster ${clusterId} in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const httpEndpoint = data?.spec?.http_endpoint;
+    if (typeof httpEndpoint !== "string" || httpEndpoint.length === 0) {
+        throw new Error(`Cluster ${clusterId} in environment ${envId} has no http_endpoint`);
+    }
+    return httpEndpoint;
+}
+export async function resolveSchemaRegistryEndpoint(cloudClient, clusterId, envId) {
+    const { data, error } = await cloudClient.GET("/srcm/v3/clusters/{id}", {
+        params: { path: { id: clusterId }, query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to read Schema Registry cluster ${clusterId} in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const httpEndpoint = data?.spec?.http_endpoint;
+    if (typeof httpEndpoint !== "string" || httpEndpoint.length === 0) {
+        throw new Error(`Schema Registry cluster ${clusterId} in environment ${envId} has no http_endpoint`);
+    }
+    return httpEndpoint;
+}
+export async function resolveSchemaRegistryClusterId(cloudClient, envId) {
+    const { data, error } = await cloudClient.GET("/srcm/v3/clusters", {
+        params: { query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to list Schema Registry clusters in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const clusters = data?.data ?? [];
+    if (clusters.length === 0) {
+        throw new Error(`No Schema Registry cluster found in environment ${envId}. ` +
+            `Schema Registry must be enabled on the environment in Confluent Cloud.`);
+    }
+    if (clusters.length > 1) {
+        // Defensive: CCloud's documented invariant is one SR per environment.
+        // If that ever changes, callers will need to pick a specific cluster
+        // rather than have us silently take the first.
+        throw new Error(`Multiple Schema Registry clusters found in environment ${envId} (count: ${clusters.length}). ` +
+            `Single SR per environment is assumed; multi-SR is not supported.`);
+    }
+    const id = clusters[0]?.id;
+    if (typeof id !== "string" || id.length === 0) {
+        throw new Error(`Schema Registry cluster in environment ${envId} has no id`);
+    }
+    return id;
+}
+//# sourceMappingURL=oauth-resource-resolvers.js.map

package/dist/confluent/oauth-resource-resolvers.js.map

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

package/dist/confluent/telemetry.d.ts

@@ -1,5 +1,28 @@
 export declare enum TelemetryEvent {
-    TOOL_CALL = "Tool Call"
+    /**
+     * Emitted once after successful startup so we can count boots independently
+     * of tool calls.
+     */
+    SERVER_START = "Server Start",
+    /**
+     * Emitted once for every tool call for telemetry on tool usage.
+     */
+    TOOL_CALL = "Tool Call",
+    /**
+     * Emitted once per terminal OAuth PKCE login attempt (success or failure).
+     * Refresh-token rotations are not tracked here.
+     */
+    CCLOUD_AUTHENTICATION = "CCloud Authentication"
+}
+/**
+ * Inputs to {@link TelemetryService.initialize}. `writeKey` is whatever the
+ * caller resolved (YAML override, build-config injected value, or undefined);
+ * the service treats `undefined`/`""` as "telemetry off" and otherwise hands
+ * the value to the Segment Analytics constructor.
+ */
+export interface TelemetryInitOptions {
+    readonly doNotTrack: boolean;
+    readonly writeKey: string | undefined;
 }
 export declare const FALLBACK_MACHINE_ID = "00000000-0000-0000-0000-000000000000";
 export declare class TelemetryService {
@@ -9,6 +32,14 @@ export declare class TelemetryService {
     private serverSessionId;
     private commonProperties;
     private constructor();
+    /**
+     * Bootstrap-time entry point. The caller (main()) is responsible for
+     * resolving `writeKey` from its sources — typically
+     * `mcpConfig.server.analytics?.write_key ?? buildConfig.TELEMETRY_WRITE_KEY`
+     * — before invoking this. A falsy `writeKey` (`undefined` or `""`) keeps
+     * analytics disabled even when `doNotTrack` is false.
+     */
+    static initialize(opts: TelemetryInitOptions): void;
     static getInstance(): TelemetryService;
     setCommonProperties(properties: Record<string, unknown>): void;
     track(event: TelemetryEvent, properties: Record<string, unknown>): void;

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

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/confluent/telemetry.ts"],"names":[],"mappings":"AAWA,oBAAY,cAAc;IACxB,SAAS,cAAc;CACxB;AAED,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAsC1E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA+B;IACtD,OAAO,CAAC,SAAS,CAAuD;IACxE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAA0B;IAElD,OAAO;IAwBP,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAOtC,mBAAmB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI9D,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IASvE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKzD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/confluent/telemetry.ts"],"names":[],"mappings":"AAIA,oBAAY,cAAc;IACxB;;;OAGG;IACH,YAAY,iBAAiB;IAC7B;;OAEG;IACH,SAAS,cAAc;IACvB;;;OAGG;IACH,qBAAqB,0BAA0B;CAChD;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAsC1E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA+B;IACtD,OAAO,CAAC,SAAS,CAAuD;IACxE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAA0B;IAElD,OAAO;IAoBP;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IASnD,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAStC,mBAAmB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI9D,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IASvE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKzD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}