@confluentinc/mcp-confluent 1.2.2 → 1.4.0

package/dist/confluent/tools/handlers/kafka/get-partition-offsets-handler.d.ts

@@ -0,0 +1,43 @@
+import { CallToolResult } from "../../../../confluent/schema.js";
+import { BaseToolHandler, ToolCategory, ToolConfig } from "../../../../confluent/tools/base-tools.js";
+import { ServerRuntime } from "../../../../server-runtime.js";
+import { z } from "zod";
+export declare const getPartitionOffsetsArgs: z.ZodObject<{
+    topicName: z.ZodString;
+    partition: z.ZodOptional<z.ZodNumber>;
+    cluster_id: z.ZodOptional<z.ZodString>;
+    environment_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * One partition's offset metadata as the tool returns it. `lowWatermark` and
+ * `highWatermark` are strings to preserve int64 precision past JS's 2^53
+ * safe-integer boundary; `messageCount` is a `Number` because the BigInt
+ * subtraction is done server-side and asking an LLM caller to subtract two
+ * int64-typed strings is the wrong ergonomic trade.
+ */
+export type PartitionOffsetInfo = {
+    partition: number;
+    lowWatermark: string;
+    highWatermark: string;
+    messageCount: number;
+};
+/** Structured response payload mirrored into `result.structuredContent`. */
+export type GetPartitionOffsetsResponse = {
+    topicName: string;
+    partitions: PartitionOffsetInfo[];
+};
+/**
+ * Read-only tool that returns per-partition low/high watermarks (and the
+ * derived message count) for a single Kafka topic. Thin wrapper over the
+ * broker's `Admin.fetchTopicOffsets` admin call — the metadata primitive
+ * that `consume-messages` already relies on internally for `start:
+ * "earliest" / "latest" / {timestamp} / {tail}` resolution but doesn't
+ * surface in its response.
+ */
+export declare class GetPartitionOffsetsHandler extends BaseToolHandler {
+    handle(runtime: ServerRuntime, toolArguments: Record<string, unknown>): Promise<CallToolResult>;
+    getToolConfig(): ToolConfig;
+    readonly category = ToolCategory.Kafka;
+    readonly predicate: import("../../../../confluent/tools/connection-predicates.js").ConnectionPredicate;
+}
+//# sourceMappingURL=get-partition-offsets-handler.d.ts.map

package/dist/confluent/tools/handlers/kafka/get-partition-offsets-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-partition-offsets-handler.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/get-partition-offsets-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,eAAe,EAEf,YAAY,EACZ,UAAU,EACX,MAAM,oCAAoC,CAAC;AAc5C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,uBAAuB;;;;;iBA0BlC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,2BAA2B,GAAG;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC,CAAC;AAsBF;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,eAAe;IACvD,MAAM,CACV,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC;IAkF1B,aAAa,IAAI,UAAU;IAY3B,QAAQ,CAAC,QAAQ,sBAAsB;IACvC,QAAQ,CAAC,SAAS,8EAAyB;CAC5C"}

package/dist/confluent/tools/handlers/kafka/get-partition-offsets-handler.js

@@ -0,0 +1,123 @@
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+import { BaseToolHandler, READ_ONLY, ToolCategory, } from "../../../../confluent/tools/base-tools.js";
+import { disposeIfOAuth, formatKafkaError, resolveKafkaClusterArgs, } from "../../../../confluent/tools/cluster-arg-resolvers.js";
+import { kafkaBootstrapOrOAuth } from "../../../../confluent/tools/connection-predicates.js";
+import { fetchPartitionWatermarks, narrowMessageCount, } from "../../../../confluent/tools/handlers/kafka/partition-watermarks.js";
+import { ToolName } from "../../../../confluent/tools/tool-name.js";
+import { logger } from "../../../../logger.js";
+import { z } from "zod";
+export const getPartitionOffsetsArgs = z.object({
+    topicName: z
+        .string()
+        .nonempty()
+        .describe("Name of the Kafka topic to fetch partition offsets for."),
+    partition: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Optional. Restrict the response to this partition (0-indexed). " +
+        "Omit to return every partition of the topic."),
+    cluster_id: z
+        .string()
+        .optional()
+        .describe("Confluent Cloud logical Kafka cluster ID (lkc-...). Discover via list-clusters."),
+    environment_id: z
+        .string()
+        .optional()
+        .describe("Confluent Cloud environment ID (env-...) that owns the cluster. Discover via list-environments."),
+});
+function mapToPartitionOffsetInfo(topicName, watermark) {
+    const low = BigInt(watermark.low);
+    const high = BigInt(watermark.high);
+    const diff = high - low;
+    return {
+        partition: watermark.partition,
+        lowWatermark: watermark.low,
+        highWatermark: watermark.high,
+        messageCount: narrowMessageCount(diff, {
+            topicName,
+            partition: watermark.partition,
+            low: watermark.low,
+            high: watermark.high,
+        }),
+    };
+}
+/**
+ * Read-only tool that returns per-partition low/high watermarks (and the
+ * derived message count) for a single Kafka topic. Thin wrapper over the
+ * broker's `Admin.fetchTopicOffsets` admin call — the metadata primitive
+ * that `consume-messages` already relies on internally for `start:
+ * "earliest" / "latest" / {timestamp} / {tail}` resolution but doesn't
+ * surface in its response.
+ */
+export class GetPartitionOffsetsHandler extends BaseToolHandler {
+    async handle(runtime, toolArguments) {
+        const parsed = getPartitionOffsetsArgs.parse(toolArguments);
+        const { connId, clientManager } = this.resolveSoleConnection(runtime);
+        const resolved = resolveKafkaClusterArgs(parsed, runtime, connId);
+        const admin = await clientManager.getKafkaAdminClient(resolved.clusterId, resolved.envId);
+        try {
+            let watermarks;
+            try {
+                watermarks = await fetchPartitionWatermarks(admin, parsed.topicName);
+            }
+            catch (err) {
+                // Two distinct librdkafka codes report the same conceptual failure:
+                //   - ERR_UNKNOWN_TOPIC_OR_PART (broker-issued, single underscore)
+                //   - ERR__UNKNOWN_TOPIC (local-side, double underscore — fires when
+                //     the client's own metadata cache rejects the topic before
+                //     reaching the broker)
+                // Only those two get the friendly "topic not found" message;
+                // everything else (auth denials, TLS failures, broker timeouts,
+                // unknown shapes) flows through formatKafkaError so callers see
+                // actionable signal instead of a misleading not-found label.
+                const isUnknownTopic = err instanceof KafkaJS.KafkaJSError &&
+                    (err.code === KafkaJS.ErrorCodes.ERR_UNKNOWN_TOPIC_OR_PART ||
+                        err.code === KafkaJS.ErrorCodes.ERR__UNKNOWN_TOPIC);
+                if (isUnknownTopic) {
+                    logger.warn({ error: err, topicName: parsed.topicName }, `fetchTopicOffsets rejected for "${parsed.topicName}" — surfacing as topic-not-found`);
+                    return this.createResponse(`Topic "${parsed.topicName}" not found on this cluster.`, true);
+                }
+                return this.createResponse(`Failed to fetch partition offsets for "${parsed.topicName}": ${formatKafkaError(err)}`, true);
+            }
+            if (watermarks.length === 0) {
+                return this.createResponse(`Topic "${parsed.topicName}" not found on this cluster.`, true);
+            }
+            if (parsed.partition !== undefined) {
+                const numPartitions = watermarks.length;
+                const requested = parsed.partition;
+                const match = watermarks.find((w) => w.partition === requested);
+                if (!match) {
+                    return this.createResponse(`Topic "${parsed.topicName}" has ${numPartitions} partition(s) ` +
+                        `(0..${numPartitions - 1}); requested partition ${requested} is out of range.`, true);
+                }
+                watermarks = [match];
+            }
+            const payload = {
+                topicName: parsed.topicName,
+                partitions: watermarks.map((w) => mapToPartitionOffsetInfo(parsed.topicName, w)),
+            };
+            const summary = `Partition offsets for "${parsed.topicName}" ` +
+                `(${payload.partitions.length} partition(s)):\n` +
+                JSON.stringify(payload, null, 2);
+            return this.createStructuredResponse(summary, payload);
+        }
+        finally {
+            await disposeIfOAuth(runtime, connId, admin);
+        }
+    }
+    getToolConfig() {
+        return {
+            name: ToolName.GET_PARTITION_OFFSETS,
+            description: "Return per-partition low/high watermarks and message counts for a Kafka topic. " +
+                "Use this to size a backfill, measure lag relative to a known offset, or check whether a topic is still receiving writes — without consuming. " +
+                "Pass `partition` to restrict the response to a single partition.",
+            inputSchema: getPartitionOffsetsArgs.shape,
+            annotations: READ_ONLY,
+        };
+    }
+    category = ToolCategory.Kafka;
+    predicate = kafkaBootstrapOrOAuth;
+}
+//# sourceMappingURL=get-partition-offsets-handler.js.map

package/dist/confluent/tools/handlers/kafka/get-partition-offsets-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-partition-offsets-handler.js","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/get-partition-offsets-handler.ts"],"names":[],"mappings":"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"}

package/dist/confluent/tools/handlers/kafka/get-topic-config.d.ts

@@ -1,16 +1,15 @@
-import { ClientManager } from "../../../../confluent/client-manager.js";
 import { CallToolResult } from "../../../../confluent/schema.js";
-import { BaseToolHandler, ToolConfig } from "../../../../confluent/tools/base-tools.js";
-import { EnvVar } from "../../../../env-schema.js";
+import { BaseToolHandler, ToolCategory, ToolConfig } from "../../../../confluent/tools/base-tools.js";
+import { ServerRuntime } from "../../../../server-runtime.js";
 /**
  * Handler for retrieving Kafka topic configurations through Confluent Cloud REST API.
  * This implementation uses Confluent's REST API endpoints to fetch topic configuration
  * details that aren't directly accessible through the native Kafka admin client API.
  */
 export declare class GetTopicConfigHandler extends BaseToolHandler {
-    handle(clientManager: ClientManager, toolArguments: Record<string, unknown>): Promise<CallToolResult>;
+    handle(runtime: ServerRuntime, toolArguments: Record<string, unknown>): Promise<CallToolResult>;
     getToolConfig(): ToolConfig;
-    getRequiredEnvVars(): readonly EnvVar[];
-    isConfluentCloudOnly(): boolean;
+    readonly category = ToolCategory.Kafka;
+    readonly predicate: import("../../../../confluent/tools/connection-predicates.js").ConnectionPredicate;
 }
 //# sourceMappingURL=get-topic-config.d.ts.map

package/dist/confluent/tools/handlers/kafka/get-topic-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-topic-config.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/get-topic-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,eAAe,EAEf,UAAU,EACX,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAgC,MAAM,oBAAoB,CAAC;AAe1E;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,eAAe;IAClD,MAAM,CACV,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC;IAkD1B,aAAa,IAAI,UAAU;IAS3B,kBAAkB,IAAI,SAAS,MAAM,EAAE;IAIvC,oBAAoB,IAAI,OAAO;CAGhC"}
+{"version":3,"file":"get-topic-config.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/get-topic-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,eAAe,EAEf,YAAY,EACZ,UAAU,EACX,MAAM,oCAAoC,CAAC;AAI5C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAuBvD;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,eAAe;IAClD,MAAM,CACV,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC;IAgD1B,aAAa,IAAI,UAAU;IAQ3B,QAAQ,CAAC,QAAQ,sBAAsB;IACvC,QAAQ,CAAC,SAAS,8EAA4B;CAC/C"}

package/dist/confluent/tools/handlers/kafka/get-topic-config.js

@@ -1,18 +1,22 @@
-import { getEnsuredParam } from "../../../../confluent/helpers.js";
-import { BaseToolHandler, READ_ONLY, } from "../../../../confluent/tools/base-tools.js";
+import { BaseToolHandler, READ_ONLY, ToolCategory, } from "../../../../confluent/tools/base-tools.js";
+import { resolveKafkaRestArgs } from "../../../../confluent/tools/cluster-arg-resolvers.js";
+import { kafkaRestWithAuthOrOAuth } from "../../../../confluent/tools/connection-predicates.js";
 import { ToolName } from "../../../../confluent/tools/tool-name.js";
-import { KAFKA_REST_REQUIRED_ENV_VARS } from "../../../../env-schema.js";
 import { wrapAsPathBasedClient } from "openapi-fetch";
 import { z } from "zod";
 const getTopicConfigArguments = z.object({
-    clusterId: z
-        .string()
-        .optional()
-        .describe("The unique identifier for the Kafka cluster."),
     topicName: z
         .string()
         .describe("Name of the topic to get configuration for")
         .nonempty(),
+    clusterId: z
+        .string()
+        .optional()
+        .describe("Confluent Cloud logical Kafka cluster ID (lkc-...). Discover via list-clusters."),
+    environmentId: z
+        .string()
+        .optional()
+        .describe("Confluent Cloud environment ID (env-...) that owns the cluster. Discover via list-environments."),
 });
 /**
  * Handler for retrieving Kafka topic configurations through Confluent Cloud REST API.
@@ -20,17 +24,19 @@ const getTopicConfigArguments = z.object({
  * details that aren't directly accessible through the native Kafka admin client API.
  */
 export class GetTopicConfigHandler extends BaseToolHandler {
-    async handle(clientManager, toolArguments) {
-        const { clusterId, topicName } = getTopicConfigArguments.parse(toolArguments);
-        const kafka_cluster_id = getEnsuredParam("KAFKA_CLUSTER_ID", "Kafka Cluster ID is required", clusterId);
-        const pathBasedClient = wrapAsPathBasedClient(clientManager.getConfluentCloudKafkaRestClient());
+    async handle(runtime, toolArguments) {
+        const parsed = getTopicConfigArguments.parse(toolArguments);
+        const { connId, clientManager } = this.resolveSoleConnection(runtime);
+        const { clusterId, envId } = resolveKafkaRestArgs(parsed, runtime, connId);
+        const restClient = await clientManager.getConfluentCloudKafkaRestClient(clusterId, envId);
+        const pathBasedClient = wrapAsPathBasedClient(restClient);
         // First, get topic details
-        const { data: topicData, error: topicError } = await pathBasedClient[`/kafka/v3/clusters/${kafka_cluster_id}/topics/${topicName}`].GET();
+        const { data: topicData, error: topicError } = await pathBasedClient[`/kafka/v3/clusters/${clusterId}/topics/${parsed.topicName}`].GET();
         if (topicError) {
             return this.createResponse(`Failed to retrieve topic details: ${JSON.stringify(topicError)}`, true);
         }
         // Then, get topic configurations
-        const { data: configData, error: configError } = await pathBasedClient[`/kafka/v3/clusters/${kafka_cluster_id}/topics/${topicName}/configs`].GET();
+        const { data: configData, error: configError } = await pathBasedClient[`/kafka/v3/clusters/${clusterId}/topics/${parsed.topicName}/configs`].GET();
         if (configError) {
             return this.createResponse(`Failed to retrieve topic configuration: ${JSON.stringify(configError)}`, true);
         }
@@ -39,7 +45,7 @@ export class GetTopicConfigHandler extends BaseToolHandler {
             topicDetails: topicData,
             topicConfig: configData,
         };
-        return this.createResponse(`Topic configuration for '${topicName}':\n${JSON.stringify(response, null, 2)}`);
+        return this.createResponse(`Topic configuration for '${parsed.topicName}':\n${JSON.stringify(response, null, 2)}`);
     }
     getToolConfig() {
         return {
@@ -49,11 +55,7 @@ export class GetTopicConfigHandler extends BaseToolHandler {
             annotations: READ_ONLY,
         };
     }
-    getRequiredEnvVars() {
-        return KAFKA_REST_REQUIRED_ENV_VARS;
-    }
-    isConfluentCloudOnly() {
-        return true;
-    }
+    category = ToolCategory.Kafka;
+    predicate = kafkaRestWithAuthOrOAuth;
 }
 //# sourceMappingURL=get-topic-config.js.map

package/dist/confluent/tools/handlers/kafka/get-topic-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-topic-config.js","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/get-topic-config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EACL,eAAe,EACf,SAAS,GAEV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAU,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,8CAA8C,CAAC;IAC3D,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,CAAC,4CAA4C,CAAC;SACtD,QAAQ,EAAE;CACd,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACxD,KAAK,CAAC,MAAM,CACV,aAA4B,EAC5B,aAAsC;QAEtC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAC5B,uBAAuB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC/C,MAAM,gBAAgB,GAAG,eAAe,CACtC,kBAAkB,EAClB,8BAA8B,EAC9B,SAAS,CACV,CAAC;QAEF,MAAM,eAAe,GAAG,qBAAqB,CAC3C,aAAa,CAAC,gCAAgC,EAAE,CACjD,CAAC;QAEF,2BAA2B;QAC3B,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,GAC1C,MAAM,eAAe,CACnB,sBAAsB,gBAAgB,WAAW,SAAS,EAAE,CAC7D,CAAC,GAAG,EAAE,CAAC;QAEV,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,IAAI,CAAC,cAAc,CACxB,qCAAqC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,EACjE,IAAI,CACL,CAAC;QACJ,CAAC;QAED,iCAAiC;QACjC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,GAC5C,MAAM,eAAe,CACnB,sBAAsB,gBAAgB,WAAW,SAAS,UAAU,CACrE,CAAC,GAAG,EAAE,CAAC;QAEV,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,cAAc,CACxB,2CAA2C,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,EACxE,IAAI,CACL,CAAC;QACJ,CAAC;QAED,iEAAiE;QACjE,MAAM,QAAQ,GAAG;YACf,YAAY,EAAE,SAAS;YACvB,WAAW,EAAE,UAAU;SACxB,CAAC;QAEF,OAAO,IAAI,CAAC,cAAc,CACxB,4BAA4B,SAAS,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAChF,CAAC;IACJ,CAAC;IAED,aAAa;QACX,OAAO;YACL,IAAI,EAAE,QAAQ,CAAC,gBAAgB;YAC/B,WAAW,EAAE,4DAA4D;YACzE,WAAW,EAAE,uBAAuB,CAAC,KAAK;YAC1C,WAAW,EAAE,SAAS;SACvB,CAAC;IACJ,CAAC;IAED,kBAAkB;QAChB,OAAO,4BAA4B,CAAC;IACtC,CAAC;IAED,oBAAoB;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"get-topic-config.js","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/get-topic-config.ts"],"names":[],"mappings":"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"}

package/dist/confluent/tools/handlers/kafka/list-consumer-groups-handler.d.ts

@@ -0,0 +1,45 @@
+import { CallToolResult } from "../../../../confluent/schema.js";
+import { BaseToolHandler, ToolCategory, ToolConfig } from "../../../../confluent/tools/base-tools.js";
+import { ServerRuntime } from "../../../../server-runtime.js";
+import { z } from "zod";
+export declare const listConsumerGroupsArgs: z.ZodObject<{
+    matchStates: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        Unknown: "Unknown";
+        PreparingRebalance: "PreparingRebalance";
+        CompletingRebalance: "CompletingRebalance";
+        Stable: "Stable";
+        Dead: "Dead";
+        Empty: "Empty";
+    }>>>;
+    matchType: z.ZodOptional<z.ZodEnum<{
+        Classic: "Classic";
+        Consumer: "Consumer";
+    }>>;
+    cluster_id: z.ZodOptional<z.ZodString>;
+    environment_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Wire-format response payload. `Record<string, unknown>` compatibility lets it
+ * thread cleanly through MCP's `structuredContent` channel without a boundary
+ * cast at the call site.
+ */
+export type ListConsumerGroupsResponse = {
+    groups: Array<{
+        groupId: string;
+        state: string;
+        type: string;
+        protocolType: string;
+        isSimpleConsumerGroup: boolean;
+    }>;
+    errors: Array<{
+        message: string;
+        code?: number;
+    }>;
+} & Record<string, unknown>;
+export declare class ListConsumerGroupsHandler extends BaseToolHandler {
+    readonly category = ToolCategory.Kafka;
+    readonly predicate: import("../../../../confluent/tools/connection-predicates.js").ConnectionPredicate;
+    getToolConfig(): ToolConfig;
+    handle(runtime: ServerRuntime, toolArguments: Record<string, unknown>): Promise<CallToolResult>;
+}
+//# sourceMappingURL=list-consumer-groups-handler.d.ts.map

package/dist/confluent/tools/handlers/kafka/list-consumer-groups-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-consumer-groups-handler.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/list-consumer-groups-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,eAAe,EAEf,YAAY,EACZ,UAAU,EACX,MAAM,oCAAoC,CAAC;AAe5C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;iBA6BjC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,KAAK,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,qBAAqB,EAAE,OAAO,CAAC;KAChC,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,qBAAa,yBAA0B,SAAQ,eAAe;IAC5D,QAAQ,CAAC,QAAQ,sBAAsB;IACvC,QAAQ,CAAC,SAAS,8EAAyB;IAE3C,aAAa,IAAI,UAAU;IAcrB,MAAM,CACV,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC;CA2D3B"}

package/dist/confluent/tools/handlers/kafka/list-consumer-groups-handler.js

@@ -0,0 +1,86 @@
+import { BaseToolHandler, READ_ONLY, ToolCategory, } from "../../../../confluent/tools/base-tools.js";
+import { disposeIfOAuth, resolveKafkaClusterArgs, } from "../../../../confluent/tools/cluster-arg-resolvers.js";
+import { kafkaBootstrapOrOAuth } from "../../../../confluent/tools/connection-predicates.js";
+import { STATE_NAME_TO_ENUM, STATE_NAMES, stateName, TYPE_NAME_TO_ENUM, TYPE_NAMES, typeName, } from "../../../../confluent/tools/handlers/kafka/consumer-group-enums.js";
+import { ToolName } from "../../../../confluent/tools/tool-name.js";
+import { z } from "zod";
+export const listConsumerGroupsArgs = z.object({
+    matchStates: z
+        .array(z.enum(STATE_NAMES))
+        .nonempty()
+        .optional()
+        .describe("Filter to groups in any of these states. Omit to return all. " +
+        'Options: "Stable" (live), "Empty" (orphaned), "Dead", ' +
+        '"PreparingRebalance", "CompletingRebalance", "Unknown".'),
+    matchType: z
+        .enum(TYPE_NAMES)
+        .optional()
+        .describe("Filter to groups of this protocol type. Omit to return both. " +
+        'Options: "Consumer" (new, KIP-848), "Classic" (legacy generation-based).'),
+    cluster_id: z
+        .string()
+        .optional()
+        .describe("Confluent Cloud logical Kafka cluster ID (lkc-...). Discover via list-clusters."),
+    environment_id: z
+        .string()
+        .optional()
+        .describe("Confluent Cloud environment ID (env-...) that owns the cluster. Discover via list-environments."),
+});
+export class ListConsumerGroupsHandler extends BaseToolHandler {
+    category = ToolCategory.Kafka;
+    predicate = kafkaBootstrapOrOAuth;
+    getToolConfig() {
+        return {
+            name: ToolName.LIST_CONSUMER_GROUPS,
+            description: "List consumer groups on a Kafka cluster — wraps the broker's " +
+                "listGroups admin call. Optional filters narrow the result " +
+                "server-side. Response carries one entry per group with groupId, " +
+                "state, type, protocolType, and isSimpleConsumerGroup, plus an " +
+                "errors array of any per-broker partial failures.",
+            inputSchema: listConsumerGroupsArgs.shape,
+            annotations: READ_ONLY,
+        };
+    }
+    async handle(runtime, toolArguments) {
+        const parsed = listConsumerGroupsArgs.parse(toolArguments);
+        const { connId, clientManager } = this.resolveSoleConnection(runtime);
+        const { clusterId, envId } = resolveKafkaClusterArgs(parsed, runtime, connId);
+        const admin = await clientManager.getKafkaAdminClient(clusterId, envId);
+        try {
+            const options = {};
+            if (parsed.matchStates !== undefined) {
+                options.matchConsumerGroupStates = parsed.matchStates.map((name) => STATE_NAME_TO_ENUM[name]);
+            }
+            if (parsed.matchType !== undefined) {
+                options.matchConsumerGroupTypes = [TYPE_NAME_TO_ENUM[parsed.matchType]];
+            }
+            const { groups: rawGroups, errors: rawErrors } = await admin.listGroups(options);
+            const filtered = parsed.matchStates !== undefined || parsed.matchType !== undefined;
+            if (rawGroups.length === 0 && rawErrors.length > 0) {
+                return this.createResponse(rawErrors[0].message, true);
+            }
+            const payload = {
+                groups: rawGroups.map((g) => ({
+                    groupId: g.groupId,
+                    state: stateName(g.state),
+                    type: typeName(g.type),
+                    protocolType: g.protocolType,
+                    isSimpleConsumerGroup: g.isSimpleConsumerGroup,
+                })),
+                errors: rawErrors.map((e) => ({ message: e.message, code: e.code })),
+            };
+            const count = payload.groups.length;
+            const noun = count === 1 ? "group" : "groups";
+            const suffix = filtered ? " (filtered)" : "";
+            const summary = count === 0
+                ? `Found 0 consumer ${noun}${suffix}.`
+                : `Found ${count} consumer ${noun}${suffix}:\n` +
+                    JSON.stringify(payload, null, 2);
+            return this.createStructuredResponse(summary, payload);
+        }
+        finally {
+            await disposeIfOAuth(runtime, connId, admin);
+        }
+    }
+}
+//# sourceMappingURL=list-consumer-groups-handler.js.map

package/dist/confluent/tools/handlers/kafka/list-consumer-groups-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-consumer-groups-handler.js","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/list-consumer-groups-handler.ts"],"names":[],"mappings":"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"}

package/dist/confluent/tools/handlers/kafka/list-topics-handler.d.ts

@@ -1,10 +1,10 @@
-import { ClientManager } from "../../../../confluent/client-manager.js";
 import { CallToolResult } from "../../../../confluent/schema.js";
-import { BaseToolHandler, ToolConfig } from "../../../../confluent/tools/base-tools.js";
-import { EnvVar } from "../../../../env-schema.js";
+import { BaseToolHandler, ToolCategory, ToolConfig } from "../../../../confluent/tools/base-tools.js";
+import { ServerRuntime } from "../../../../server-runtime.js";
 export declare class ListTopicsHandler extends BaseToolHandler {
-    handle(clientManager: ClientManager, toolArguments: Record<string, unknown>): Promise<CallToolResult>;
+    handle(runtime: ServerRuntime, toolArguments: Record<string, unknown>): Promise<CallToolResult>;
     getToolConfig(): ToolConfig;
-    getRequiredEnvVars(): EnvVar[];
+    readonly category = ToolCategory.Kafka;
+    readonly predicate: import("../../../../confluent/tools/connection-predicates.js").ConnectionPredicate;
 }
 //# sourceMappingURL=list-topics-handler.d.ts.map

package/dist/confluent/tools/handlers/kafka/list-topics-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-topics-handler.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/list-topics-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,eAAe,EAEf,UAAU,EACX,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAO5C,qBAAa,iBAAkB,SAAQ,eAAe;IAC9C,MAAM,CACV,aAAa,EAAE,aAAa,EAE5B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC;IAK1B,aAAa,IAAI,UAAU;IAS3B,kBAAkB,IAAI,MAAM,EAAE;CAG/B"}
+{"version":3,"file":"list-topics-handler.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/list-topics-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,eAAe,EAEf,YAAY,EACZ,UAAU,EACX,MAAM,oCAAoC,CAAC;AAO5C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAkBvD,qBAAa,iBAAkB,SAAQ,eAAe;IAC9C,MAAM,CACV,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC;IAgB1B,aAAa,IAAI,UAAU;IAS3B,QAAQ,CAAC,QAAQ,sBAAsB;IACvC,QAAQ,CAAC,SAAS,8EAAyB;CAC5C"}

package/dist/confluent/tools/handlers/kafka/list-topics-handler.js

@@ -1,15 +1,31 @@
-import { BaseToolHandler, READ_ONLY, } from "../../../../confluent/tools/base-tools.js";
+import { BaseToolHandler, READ_ONLY, ToolCategory, } from "../../../../confluent/tools/base-tools.js";
+import { disposeIfOAuth, resolveKafkaClusterArgs, } from "../../../../confluent/tools/cluster-arg-resolvers.js";
+import { kafkaBootstrapOrOAuth } from "../../../../confluent/tools/connection-predicates.js";
 import { ToolName } from "../../../../confluent/tools/tool-name.js";
 import { z } from "zod";
 const listTopicArgs = z.object({
-// No arguments
+    cluster_id: z
+        .string()
+        .optional()
+        .describe("Confluent Cloud logical Kafka cluster ID (lkc-...). Discover via list-clusters."),
+    environment_id: z
+        .string()
+        .optional()
+        .describe("Confluent Cloud environment ID (env-...) that owns the cluster. Discover via list-environments."),
 });
 export class ListTopicsHandler extends BaseToolHandler {
-    async handle(clientManager, 
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    toolArguments) {
-        const topics = await (await clientManager.getAdminClient()).listTopics();
-        return this.createResponse(`Kafka topics: ${topics.join(",")}`);
+    async handle(runtime, toolArguments) {
+        const parsed = listTopicArgs.parse(toolArguments);
+        const { connId, clientManager } = this.resolveSoleConnection(runtime);
+        const resolved = resolveKafkaClusterArgs(parsed, runtime, connId);
+        const admin = await clientManager.getKafkaAdminClient(resolved.clusterId, resolved.envId);
+        try {
+            const topics = await admin.listTopics();
+            return this.createResponse(`Kafka topics: ${topics.join(",")}`);
+        }
+        finally {
+            await disposeIfOAuth(runtime, connId, admin);
+        }
     }
     getToolConfig() {
         return {
@@ -19,8 +35,7 @@ export class ListTopicsHandler extends BaseToolHandler {
             annotations: READ_ONLY,
         };
     }
-    getRequiredEnvVars() {
-        return ["BOOTSTRAP_SERVERS"];
-    }
+    category = ToolCategory.Kafka;
+    predicate = kafkaBootstrapOrOAuth;
 }
 //# sourceMappingURL=list-topics-handler.js.map

package/dist/confluent/tools/handlers/kafka/list-topics-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-topics-handler.js","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/list-topics-handler.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EACf,SAAS,GAEV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAE7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;AAC7B,eAAe;CAChB,CAAC,CAAC;AAEH,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,KAAK,CAAC,MAAM,CACV,aAA4B;IAC5B,6DAA6D;IAC7D,aAAsC;QAEtC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,aAAa,CAAC,cAAc,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC;QACzE,OAAO,IAAI,CAAC,cAAc,CAAC,iBAAiB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,aAAa;QACX,OAAO;YACL,IAAI,EAAE,QAAQ,CAAC,WAAW;YAC1B,WAAW,EAAE,uCAAuC;YACpD,WAAW,EAAE,aAAa,CAAC,KAAK;YAChC,WAAW,EAAE,SAAS;SACvB,CAAC;IACJ,CAAC;IAED,kBAAkB;QAChB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC/B,CAAC;CACF"}
+{"version":3,"file":"list-topics-handler.js","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/list-topics-handler.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,SAAS,EACT,YAAY,GAEb,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,uBAAuB,GACxB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+CAA+C,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAE7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,iFAAiF,CAClF;IACH,cAAc,EAAE,CAAC;SACd,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,iGAAiG,CAClG;CACJ,CAAC,CAAC;AAEH,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IACpD,KAAK,CAAC,MAAM,CACV,OAAsB,EACtB,aAAsC;QAEtC,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAClD,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;QACtE,MAAM,QAAQ,GAAG,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAClE,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,mBAAmB,CACnD,QAAQ,CAAC,SAAS,EAClB,QAAQ,CAAC,KAAK,CACf,CAAC;QACF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,cAAc,CAAC,iBAAiB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClE,CAAC;gBAAS,CAAC;YACT,MAAM,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,aAAa;QACX,OAAO;YACL,IAAI,EAAE,QAAQ,CAAC,WAAW;YAC1B,WAAW,EAAE,uCAAuC;YACpD,WAAW,EAAE,aAAa,CAAC,KAAK;YAChC,WAAW,EAAE,SAAS;SACvB,CAAC;IACJ,CAAC;IAEQ,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC;IAC9B,SAAS,GAAG,qBAAqB,CAAC;CAC5C"}

package/dist/confluent/tools/handlers/kafka/partition-watermarks.d.ts

@@ -0,0 +1,54 @@
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+/**
+ * Per-partition low/high watermark pair, normalized to the fields the
+ * consume handler and the standalone `get-partition-offsets` tool both
+ * read. The upstream `admin.fetchTopicOffsets` response also carries a
+ * committed `offset` field (the next-to-be-committed group offset, not
+ * the partition end-of-log), which neither caller uses; this type drops
+ * it so a shared response shape governs both surfaces.
+ */
+export interface PartitionWatermark {
+    partition: number;
+    low: string;
+    high: string;
+}
+/**
+ * Narrow a {@link BigInt} difference to a JS `Number`, saturating at
+ * {@link Number.MAX_SAFE_INTEGER} or {@link Number.MIN_SAFE_INTEGER}
+ * when the result would lose precision. The narrow path is the only one
+ * expected to fire in practice (even a million-msg/sec partition with
+ * infinite retention takes ~285 years to exceed 2^53 - 1); the
+ * saturation arms are defensive sentinels — hence the `Wacky --` log
+ * signaling "this branch firing means something genuinely surprising
+ * happened". Symmetric guards on both ends of the safe range so a `diff`
+ * produced by an unexpected caller pattern (e.g. a far-ahead committed
+ * offset, or a cross-partition sum of many negative lags) can't silently
+ * lose precision.
+ *
+ * `context` is forwarded verbatim into the log payload so each caller
+ * can name the dimensions it knows about (`{topicName, partition}` for
+ * the standalone watermark tool, `{groupId, topic, partition}` for the
+ * consumer-group lag tool) without this helper hard-coding either.
+ */
+export declare function narrowMessageCount(diff: bigint, context: Record<string, unknown>): number;
+/**
+ * Thin wrapper around `admin.fetchTopicOffsets(topic)` that normalizes
+ * the response to {@link PartitionWatermark}. Shared seam between the
+ * consume handler's per-call watermark cache (see
+ * {@link createWatermarkCache}) and standalone
+ * `get-partition-offsets` tool — single source of truth for the
+ * response shape both surfaces see.
+ */
+export declare function fetchPartitionWatermarks(admin: KafkaJS.Admin, topic: string): Promise<PartitionWatermark[]>;
+/**
+ * Lazy per-topic memoized watermark fetcher. The consume handler hits
+ * `admin.fetchTopicOffsets` from four independent resolution paths
+ * within a single tool call (explicit-offset bounds check, timestamp's
+ * silent-substitution cross-check, earliest-minority low-watermark
+ * seek, and tail-mode seek resolution); the cache keeps the admin
+ * round-trip count linear in the number of distinct topics rather than
+ * the number of resolution sites.
+ */
+export type WatermarkCache = (topic: string) => Promise<PartitionWatermark[]>;
+export declare function createWatermarkCache(admin: KafkaJS.Admin): WatermarkCache;
+//# sourceMappingURL=partition-watermarks.d.ts.map

package/dist/confluent/tools/handlers/kafka/partition-watermarks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partition-watermarks.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/partition-watermarks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAGzD;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAkBR;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,OAAO,CAAC,KAAK,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAG/B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;AAE9E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,GAAG,cAAc,CAUzE"}