@confluentinc/mcp-confluent 1.3.0 → 1.4.0

package/dist/confluent/tools/handlers/kafka/describe-consumer-group-handler.js

@@ -0,0 +1,140 @@
+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 { stateName, typeName, } from "../../../../confluent/tools/handlers/kafka/consumer-group-enums.js";
+import { describeGroupOutcome, notFoundGroupMessage, } from "../../../../confluent/tools/handlers/kafka/consumer-group-helpers.js";
+import { ToolName } from "../../../../confluent/tools/tool-name.js";
+import { logger } from "../../../../logger.js";
+import { z } from "zod";
+export const describeConsumerGroupArgs = z.object({
+    groupId: z
+        .string()
+        .min(1)
+        .describe("Consumer group ID to describe. Discover existing group IDs via list-consumer-groups."),
+    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 DescribeConsumerGroupHandler extends BaseToolHandler {
+    category = ToolCategory.Kafka;
+    predicate = kafkaBootstrapOrOAuth;
+    getToolConfig() {
+        return {
+            name: ToolName.DESCRIBE_CONSUMER_GROUP,
+            description: "Describe a single consumer group on a Kafka cluster. " +
+                "Returns the group's state, type, protocol, partition assignor, " +
+                "coordinator, and per-member assignment as a flat array " +
+                "of {topic, partition} pairs.",
+            inputSchema: describeConsumerGroupArgs.shape,
+            annotations: READ_ONLY,
+        };
+    }
+    async handle(runtime, toolArguments) {
+        const parsed = describeConsumerGroupArgs.parse(toolArguments);
+        const { connId, clientManager } = this.resolveSoleConnection(runtime);
+        const { clusterId, envId } = resolveKafkaClusterArgs(parsed, runtime, connId);
+        const admin = await clientManager.getKafkaAdminClient(clusterId, envId);
+        try {
+            const outcome = await describeGroupOutcome(admin, parsed.groupId);
+            if (outcome.kind === "notFound") {
+                return this.createResponse(notFoundGroupMessage(parsed.groupId), true);
+            }
+            if (outcome.kind === "error") {
+                return this.createResponse(outcome.error.message, true);
+            }
+            const groupDesc = outcome.group;
+            const payload = {
+                groupId: groupDesc.groupId,
+                state: stateName(groupDesc.state),
+                type: typeName(groupDesc.type),
+                protocol: groupDesc.protocol,
+                partitionAssignor: groupDesc.partitionAssignor,
+                isSimpleConsumerGroup: groupDesc.isSimpleConsumerGroup,
+                coordinator: buildCoordinator(groupDesc.coordinator),
+                members: groupDesc.members.map(buildMember),
+            };
+            const summary = `Consumer group "${payload.groupId}" is ${payload.state} ` +
+                `with ${payload.members.length} member(s); ` +
+                `coordinator ${payload.coordinator.host}:${payload.coordinator.port}.`;
+            return this.createStructuredResponse(summary, payload);
+        }
+        finally {
+            await disposeIfOAuth(runtime, connId, admin);
+        }
+    }
+}
+function buildCoordinator(node) {
+    const out = {
+        id: node.id,
+        host: node.host,
+        port: node.port,
+    };
+    if (node.rack !== undefined)
+        out.rack = node.rack;
+    return out;
+}
+function buildMember(member) {
+    const out = {
+        memberId: member.memberId,
+        clientId: member.clientId,
+        clientHost: member.clientHost,
+        assignment: buildAssignment(member),
+    };
+    if (member.groupInstanceId !== undefined) {
+        out.groupInstanceId = member.groupInstanceId;
+    }
+    return out;
+}
+/**
+ * Cooked partition-list extraction from a {@link MemberDescription}'s
+ * `assignment` field, working around an upstream type/runtime mismatch.
+ *
+ * The kafkajs `.d.ts` declares `assignment: TopicPartition[]` (flat array),
+ * but the native C++ binding actually returns `assignment: { topicPartitions:
+ * TopicPartition[] }` (wrapped object) — verified in
+ * `node_modules/@confluentinc/kafka-javascript/src/common.cc` →
+ * `FromMemberDescription`. The wrapped shape is also where the binding
+ * exposes an optional `targetAssignment: { topicPartitions: ... }` field
+ * the `.d.ts` doesn't acknowledge at all.
+ *
+ * Handle both shapes defensively: if the binding ever reconciles the
+ * mismatch in either direction, the handler keeps working. Anything else
+ * gets a "Wacky --" log and falls through to an empty array so a future
+ * binding surprise doesn't crash the tool.
+ *
+ * Map field-by-field rather than passing the upstream array verbatim —
+ * the upstream `TopicPartition` carries optional `error` / `leaderEpoch`
+ * fields we don't want leaking into the response.
+ */
+function buildAssignment(member) {
+    const raw = member.assignment;
+    if (Array.isArray(raw)) {
+        return raw.map(toAssignedPartition);
+    }
+    if (raw !== null &&
+        typeof raw === "object" &&
+        "topicPartitions" in raw &&
+        Array.isArray(raw.topicPartitions)) {
+        return raw.topicPartitions.map(toAssignedPartition);
+    }
+    logger.warn({
+        memberId: member.memberId,
+        clientId: member.clientId,
+        assignmentType: typeof raw,
+        isBuffer: Buffer.isBuffer(raw),
+        sampleKeys: raw !== null && typeof raw === "object" && !Buffer.isBuffer(raw)
+            ? Object.keys(raw).slice(0, 10)
+            : undefined,
+    }, "Wacky -- MemberDescription.assignment is neither a TopicPartition[] " +
+        "nor a {topicPartitions: TopicPartition[]} wrapper; surfacing as empty array.");
+    return [];
+}
+function toAssignedPartition(tp) {
+    return { topic: tp.topic, partition: tp.partition };
+}
+//# sourceMappingURL=describe-consumer-group-handler.js.map

package/dist/confluent/tools/handlers/kafka/describe-consumer-group-handler.js.map

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

package/dist/confluent/tools/handlers/kafka/get-consumer-group-lag-handler.d.ts

@@ -0,0 +1,73 @@
+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 getConsumerGroupLagArgs: z.ZodObject<{
+    groupId: z.ZodString;
+    topics: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cluster_id: z.ZodOptional<z.ZodString>;
+    environment_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Per-partition lag row as the tool returns it. `committedOffset` /
+ * `highWatermark` are strings to preserve int64 precision past JS's 2^53
+ * safe-integer boundary; `lag` 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. `null` for both `committedOffset`
+ * and `lag` marks a partition where the lag is unknown — either the group
+ * has never committed (distinct from a zero-lag partition the group is
+ * caught up on) or the broker reported a per-partition error on the
+ * OffsetFetch response (see {@link error}).
+ */
+export type ConsumerGroupLagPartition = {
+    partition: number;
+    committedOffset: string | null;
+    highWatermark: string;
+    lag: number | null;
+    metadata: string | null;
+    leaderEpoch: number | null;
+    /**
+     * Set when the broker reported a per-partition error on the
+     * OffsetFetch response (e.g., leader unavailable, partition-level
+     * authorization failure). `committedOffset` and `lag` are `null` in
+     * this case — the broker's `offset` value is not meaningful when an
+     * error is attached — and the partition is excluded from `totalLag`.
+     * Surfacing the `code` and `message` lets the caller act on the
+     * specific failure rather than guessing why the lag is unknown.
+     */
+    error?: {
+        code: number;
+        message: string;
+    };
+};
+/** Per-topic group of {@link ConsumerGroupLagPartition} rows. */
+export type ConsumerGroupLagTopic = {
+    topic: string;
+    partitions: ConsumerGroupLagPartition[];
+};
+/** Structured response payload mirrored into `result.structuredContent`. */
+export type GetConsumerGroupLagResponse = {
+    groupId: string;
+    topics: ConsumerGroupLagTopic[];
+    totalLag: number;
+};
+/**
+ * Read-only tool that computes live offset lag for a single Kafka
+ * consumer group, returning per-(topic, partition) {committed, high, lag}
+ * rows and a total lag count. Combines `admin.fetchOffsets({groupId})`
+ * (committed offsets) with the shared `fetchPartitionWatermarks` helper
+ * (high watermarks), then BigInt-subtracts per partition. A partition the
+ * group has never committed to surfaces as {committedOffset: null,
+ * lag: null} and is excluded from the `totalLag` sum. Lag may briefly go
+ * negative during a consumer-group rebalance (committed offset captured
+ * at a different isolation level than the watermark snapshot); the value
+ * is surfaced as-is rather than clamped, since clamping would hide a real
+ * if rare state.
+ */
+export declare class GetConsumerGroupLagHandler 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=get-consumer-group-lag-handler.d.ts.map

package/dist/confluent/tools/handlers/kafka/get-consumer-group-lag-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-consumer-group-lag-handler.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/kafka/get-consumer-group-lag-handler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,eAAe,EAEf,YAAY,EACZ,UAAU,EACX,MAAM,oCAAoC,CAAC;AAoB5C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,uBAAuB;;;;;iBA2BlC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,yBAAyB,EAAE,CAAC;CACzC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,qBAAa,0BAA2B,SAAQ,eAAe;IAC7D,QAAQ,CAAC,QAAQ,sBAAsB;IACvC,QAAQ,CAAC,SAAS,8EAAyB;IAE3C,aAAa,IAAI,UAAU;IAgBrB,MAAM,CACV,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC;CAoH3B"}

package/dist/confluent/tools/handlers/kafka/get-consumer-group-lag-handler.js

@@ -0,0 +1,337 @@
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+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 { describeGroupOutcome, isGroupIdNotFoundError, notFoundGroupMessage, } from "../../../../confluent/tools/handlers/kafka/consumer-group-helpers.js";
+import { createWatermarkCache, narrowMessageCount, } from "../../../../confluent/tools/handlers/kafka/partition-watermarks.js";
+import { normalizeFetchTopicMetadataResponse } from "../../../../confluent/tools/handlers/kafka/topic-metadata.js";
+import { ToolName } from "../../../../confluent/tools/tool-name.js";
+import { logger } from "../../../../logger.js";
+import { z } from "zod";
+export const getConsumerGroupLagArgs = z.object({
+    groupId: z
+        .string()
+        .min(1)
+        .describe("Consumer group ID to compute lag for. Discover groups via list-consumer-groups."),
+    topics: z
+        .array(z.string().min(1))
+        .nonempty()
+        .optional()
+        .describe("Restrict lag computation to these topics. " +
+        "Omit to compute lag for every topic the group has committed offsets on."),
+    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."),
+});
+/**
+ * Read-only tool that computes live offset lag for a single Kafka
+ * consumer group, returning per-(topic, partition) {committed, high, lag}
+ * rows and a total lag count. Combines `admin.fetchOffsets({groupId})`
+ * (committed offsets) with the shared `fetchPartitionWatermarks` helper
+ * (high watermarks), then BigInt-subtracts per partition. A partition the
+ * group has never committed to surfaces as {committedOffset: null,
+ * lag: null} and is excluded from the `totalLag` sum. Lag may briefly go
+ * negative during a consumer-group rebalance (committed offset captured
+ * at a different isolation level than the watermark snapshot); the value
+ * is surfaced as-is rather than clamped, since clamping would hide a real
+ * if rare state.
+ */
+export class GetConsumerGroupLagHandler extends BaseToolHandler {
+    category = ToolCategory.Kafka;
+    predicate = kafkaBootstrapOrOAuth;
+    getToolConfig() {
+        return {
+            name: ToolName.GET_CONSUMER_GROUP_LAG,
+            description: "Compute live offset lag for a single Kafka consumer group. " +
+                "Returns per-(topic, partition) {committedOffset, highWatermark, lag} rows " +
+                "and a total lag count across the group. " +
+                "Pass `topics` to restrict the response to specific topics; " +
+                "omit to compute lag for every topic the group has touched. " +
+                "Partitions the group has never committed to surface with " +
+                "`committedOffset: null` and `lag: null` and are excluded from `totalLag`.",
+            inputSchema: getConsumerGroupLagArgs.shape,
+            annotations: READ_ONLY,
+        };
+    }
+    async handle(runtime, toolArguments) {
+        const parsed = getConsumerGroupLagArgs.parse(toolArguments);
+        const { connId, clientManager } = this.resolveSoleConnection(runtime);
+        const { clusterId, envId } = resolveKafkaClusterArgs(parsed, runtime, connId);
+        const admin = await clientManager.getKafkaAdminClient(clusterId, envId);
+        try {
+            // 1. Fetch the group's committed offsets.
+            let committedByTopic;
+            try {
+                committedByTopic = await admin.fetchOffsets(parsed.topics
+                    ? { groupId: parsed.groupId, topics: parsed.topics }
+                    : { groupId: parsed.groupId });
+            }
+            catch (err) {
+                if (isGroupIdNotFoundError(err)) {
+                    return this.createResponse(notFoundGroupMessage(parsed.groupId), true);
+                }
+                throw err;
+            }
+            // Disambiguate "unknown group" from "real group, no commits". CCloud's
+            // fetchOffsets resolves with `[]` for an unknown group ID rather than
+            // rejecting with ERR_GROUP_ID_NOT_FOUND (the documented path the catch
+            // above handles), which means an empty result by itself can't tell the
+            // caller whether the group exists or not. Probe via describeGroups
+            // before continuing — only on the empty path, so happy-path calls pay
+            // nothing.
+            if (committedByTopic.length === 0) {
+                const outcome = await describeGroupOutcome(admin, parsed.groupId);
+                if (outcome.kind === "notFound") {
+                    return this.createResponse(notFoundGroupMessage(parsed.groupId), true);
+                }
+                if (outcome.kind === "error") {
+                    // Propagate the raw librdkafka error so downstream handlers
+                    // and logs can inspect `code` / `errno` / `origin` rather
+                    // than just a message string.
+                    throw outcome.error;
+                }
+            }
+            // 2. For each topic+partition the group has committed to, fetch the
+            // partition's high watermark and compute lag = high - committed. A
+            // topic the group has committed offsets for but that's since been
+            // deleted from the cluster short-circuits with the same friendly
+            // "Topic not found" error the filter-topics path uses below.
+            const watermarkCache = createWatermarkCache(admin);
+            const lagResult = await buildLagFromCommittedOffsets(parsed.groupId, committedByTopic, watermarkCache);
+            if (lagResult.kind === "topicNotFound") {
+                return this.createResponse(lagResult.message, true);
+            }
+            const { topics: responseTopics, totalLagBigInt } = lagResult;
+            // 3. If the caller passed `topics`, verify that any never-committed
+            // filter topics exist on the cluster (so we can return
+            // `{topic, partitions: []}` for each) and surface a friendly
+            // "Topic not found" error for any that don't.
+            if (parsed.topics) {
+                const seenTopics = new Set(committedByTopic.map(({ topic }) => topic));
+                const filterResult = await resolveNeverCommittedFilterTopics(parsed.topics, seenTopics, admin);
+                if (filterResult.kind === "topicNotFound") {
+                    return this.createResponse(filterResult.message, true);
+                }
+                responseTopics.push(...filterResult.topics);
+            }
+            // 4. Narrow the BigInt accumulator to a JS Number for the wire
+            // payload, saturating at Number.MAX_SAFE_INTEGER (and emitting a
+            // Wacky log) if the cross-partition sum exceeds the safe-integer
+            // boundary even though each individual partition fit.
+            const totalLag = narrowMessageCount(totalLagBigInt, {
+                groupId: parsed.groupId,
+                scope: "totalLag",
+                topicCount: responseTopics.length,
+            });
+            const payload = {
+                groupId: parsed.groupId,
+                topics: responseTopics,
+                totalLag,
+            };
+            const summary = `Consumer group "${parsed.groupId}" has ${totalLag} message(s) of lag ` +
+                `across ${responseTopics.length} topic(s).`;
+            return this.createStructuredResponse(summary, payload);
+        }
+        finally {
+            await disposeIfOAuth(runtime, connId, admin);
+        }
+    }
+}
+/**
+ * Build one {@link ConsumerGroupLagPartition} row from a committed offset
+ * and a paired watermark. Splits the never-committed sentinel
+ * (`offset === "-1"`) from the real arithmetic path so the latter remains
+ * a clean BigInt subtraction. Returns the raw BigInt diff (or `null` for
+ * the never-committed case) alongside the row so the caller can
+ * accumulate `totalLag` in BigInt across partitions and narrow once at
+ * the end via {@link narrowMessageCount} — individual per-partition lags
+ * each fit in `Number`, but their sum can still overflow the
+ * safe-integer boundary.
+ */
+function buildLagRow(groupId, topic, committed, watermark) {
+    // Broker-reported per-partition error: the offset value isn't
+    // meaningful (could be a sentinel, stale, or garbage), so surface the
+    // error code and message verbatim and treat the lag as unknown.
+    // Excluded from the cross-partition `totalLag` sum. `!= null` (loose
+    // equality) catches both `undefined` (the TypeScript-declared shape)
+    // and `null` (what kafkajs-compat actually populates for successful
+    // partitions — the upstream type lies about the runtime).
+    if (committed.error != null) {
+        return {
+            row: {
+                partition: committed.partition,
+                committedOffset: null,
+                highWatermark: watermark.high,
+                lag: null,
+                metadata: committed.metadata,
+                leaderEpoch: committed.leaderEpoch,
+                error: {
+                    code: committed.error.code,
+                    message: committed.error.message,
+                },
+            },
+            lagBigInt: null,
+        };
+    }
+    if (committed.offset === "-1") {
+        return {
+            row: {
+                partition: committed.partition,
+                committedOffset: null,
+                highWatermark: watermark.high,
+                lag: null,
+                metadata: committed.metadata,
+                leaderEpoch: committed.leaderEpoch,
+            },
+            lagBigInt: null,
+        };
+    }
+    const diff = BigInt(watermark.high) - BigInt(committed.offset);
+    const lag = narrowMessageCount(diff, {
+        groupId,
+        topic,
+        partition: committed.partition,
+        committed: committed.offset,
+        high: watermark.high,
+    });
+    return {
+        row: {
+            partition: committed.partition,
+            committedOffset: committed.offset,
+            highWatermark: watermark.high,
+            lag,
+            metadata: committed.metadata,
+            leaderEpoch: committed.leaderEpoch,
+        },
+        lagBigInt: diff,
+    };
+}
+/**
+ * Two distinct librdkafka codes report the same conceptual failure:
+ * `ERR_UNKNOWN_TOPIC_OR_PART` (broker-issued, single underscore) and
+ * `ERR__UNKNOWN_TOPIC` (local-side, double underscore — fires when the
+ * client's own metadata cache rejects the topic before the broker is
+ * consulted). Both funnel into the same friendly "topic not found"
+ * message; same posture get-partition-offsets takes.
+ */
+function isUnknownTopicError(err) {
+    if (typeof err !== "object" || err === null || !("code" in err)) {
+        return false;
+    }
+    const code = err.code;
+    return (code === KafkaJS.ErrorCodes.ERR_UNKNOWN_TOPIC_OR_PART ||
+        code === KafkaJS.ErrorCodes.ERR__UNKNOWN_TOPIC);
+}
+/**
+ * Iterate the group's committed offsets and produce per-(topic, partition)
+ * lag rows paired with a BigInt running total. The accumulator stays in
+ * BigInt so a sum that exceeds the safe-integer boundary stays precise;
+ * narrow once at the end via {@link narrowMessageCount}. A
+ * deleted-but-still-committed-to topic short-circuits with its name in
+ * the `topicNotFound` arm — see {@link BuildLagResult}.
+ */
+async function buildLagFromCommittedOffsets(groupId, committedByTopic, watermarkCache) {
+    const topics = [];
+    let totalLagBigInt = 0n;
+    for (const { topic, partitions: committedPartitions } of committedByTopic) {
+        let watermarks;
+        try {
+            watermarks = await watermarkCache(topic);
+        }
+        catch (err) {
+            if (isUnknownTopicError(err)) {
+                return {
+                    kind: "topicNotFound",
+                    message: notFoundTopicMessage(topic),
+                };
+            }
+            throw err;
+        }
+        const watermarkByPartition = new Map(watermarks.map((w) => [w.partition, w]));
+        const rows = [];
+        for (const committed of committedPartitions) {
+            const watermark = watermarkByPartition.get(committed.partition);
+            if (watermark === undefined) {
+                logger.warn({ groupId, topic, partition: committed.partition }, "Wacky -- committed offset reported for a partition with no matching watermark; skipping");
+                continue;
+            }
+            const { row, lagBigInt } = buildLagRow(groupId, topic, committed, watermark);
+            rows.push(row);
+            if (lagBigInt !== null) {
+                totalLagBigInt += lagBigInt;
+            }
+        }
+        topics.push({ topic, partitions: rows });
+    }
+    return { kind: "resolved", topics, totalLagBigInt };
+}
+/**
+ * Verify each filter topic that didn't appear in the `fetchOffsets`
+ * response (group never committed to them) exists on the cluster, via
+ * `admin.fetchTopicMetadata` — the right primitive for a yes/no
+ * existence question, where `fetchTopicOffsets` would fan out per
+ * partition and discard the watermark data we don't need on this path.
+ * Topics that exist but the group hasn't committed to surface as
+ * `{topic, partitions: []}` in the `resolved` arm; topics that don't
+ * exist short-circuit with a pre-formatted user-facing message in the
+ * `topicNotFound` arm. Non-unknown-topic errors propagate via throw.
+ *
+ * Defensive against both unknown-topic surface shapes: librdkafka may
+ * reject the batched call with `ERR_UNKNOWN_TOPIC_OR_PART` /
+ * `ERR__UNKNOWN_TOPIC` (which doesn't identify which candidate
+ * triggered it — we surface the full list in the message) or resolve
+ * cleanly with the unknown topic absent from the returned `topics`
+ * array (which does give us specificity).
+ */
+async function resolveNeverCommittedFilterTopics(filterTopics, seenTopics, admin) {
+    const missing = filterTopics.filter((t) => !seenTopics.has(t));
+    if (missing.length === 0) {
+        return { kind: "resolved", topics: [] };
+    }
+    let rawMetadata;
+    try {
+        rawMetadata = await admin.fetchTopicMetadata({ topics: [...missing] });
+    }
+    catch (err) {
+        if (!isUnknownTopicError(err))
+            throw err;
+        // The batched call rejected with an unknown-topic code but doesn't
+        // tell us which candidate triggered the failure. With K=1 there's
+        // only one possibility so we can still name it; with K>1 surface
+        // the full list so the caller can spot the typo without us paying
+        // K extra round-trips to identify the specific one.
+        const message = missing.length === 1
+            ? notFoundTopicMessage(missing[0])
+            : `Topic not found in [${missing.join(", ")}] on this cluster.`;
+        return { kind: "topicNotFound", message };
+    }
+    // Defensive against the silently-omits-missing-topic surface shape:
+    // locate the first requested topic that didn't come back, in
+    // user-supplied order.
+    const returnedNames = new Set(normalizeFetchTopicMetadataResponse(rawMetadata).map((t) => t.name));
+    const firstMissing = missing.find((t) => !returnedNames.has(t));
+    if (firstMissing !== undefined) {
+        return {
+            kind: "topicNotFound",
+            message: notFoundTopicMessage(firstMissing),
+        };
+    }
+    return {
+        kind: "resolved",
+        topics: missing.map((topic) => ({ topic, partitions: [] })),
+    };
+}
+/**
+ * Canonical user-facing "topic not found" message format. Centralizes
+ * the phrasing so the step-2 (deleted-since-commit topic) and step-3
+ * (filter topic missing from metadata) paths can't drift apart.
+ */
+function notFoundTopicMessage(topic) {
+    return `Topic "${topic}" not found on this cluster.`;
+}
+//# sourceMappingURL=get-consumer-group-lag-handler.js.map

package/dist/confluent/tools/handlers/kafka/get-consumer-group-lag-handler.js.map

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

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"}