@confluentinc/mcp-confluent 1.2.1 → 1.3.0

package/dist/confluent/telemetry.js

@@ -1,9 +1,22 @@
-import { buildConfig, config, fs, os, path, segment, } from "../confluent/node-deps.js";
+import { fs, os, path, segment } from "../confluent/node-deps.js";
 import { logger } from "../logger.js";
 import { randomUUID } from "node:crypto";
 export var TelemetryEvent;
 (function (TelemetryEvent) {
+    /**
+     * Emitted once after successful startup so we can count boots independently
+     * of tool calls.
+     */
+    TelemetryEvent["SERVER_START"] = "Server Start";
+    /**
+     * Emitted once for every tool call for telemetry on tool usage.
+     */
     TelemetryEvent["TOOL_CALL"] = "Tool Call";
+    /**
+     * Emitted once per terminal OAuth PKCE login attempt (success or failure).
+     * Refresh-token rotations are not tracked here.
+     */
+    TelemetryEvent["CCLOUD_AUTHENTICATION"] = "CCloud Authentication";
 })(TelemetryEvent || (TelemetryEvent = {}));
 export const FALLBACK_MACHINE_ID = "00000000-0000-0000-0000-000000000000";
 const CONFIG_DIR = ".mcp-confluent";
@@ -47,11 +60,8 @@ export class TelemetryService {
     machineId;
     serverSessionId;
     commonProperties;
-    constructor() {
-        // runtime env var can override the build-time value for local dev/testing
-        const writeKey = process.env.TELEMETRY_WRITE_KEY || buildConfig.TELEMETRY_WRITE_KEY;
-        const disabled = config.env.DO_NOT_TRACK;
-        const enabled = !disabled && !!writeKey;
+    constructor(opts) {
+        const enabled = !opts.doNotTrack && !!opts.writeKey;
         this.machineId = getOrCreateMachineId();
         this.serverSessionId = randomUUID();
         this.commonProperties = {
@@ -61,16 +71,29 @@ export class TelemetryService {
             osArch: os.arch(),
         };
         if (enabled) {
-            this.analytics = new segment.Analytics({ writeKey });
+            this.analytics = new segment.Analytics({ writeKey: opts.writeKey });
             logger.info("Telemetry enabled");
         }
         else {
             logger.info("Telemetry disabled");
         }
     }
+    /**
+     * 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) {
+        if (TelemetryService.instance) {
+            throw new Error("TelemetryService has already been initialized — initialize() must be called exactly once before getInstance()");
+        }
+        TelemetryService.instance = new TelemetryService(opts);
+    }
     static getInstance() {
         if (!TelemetryService.instance) {
-            TelemetryService.instance = new TelemetryService();
+            throw new Error("TelemetryService.initialize() must be called before getInstance()");
         }
         return TelemetryService.instance;
     }

package/dist/confluent/telemetry.js.map

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

package/dist/confluent/tools/base-tools.d.ts

@@ -1,60 +1,134 @@
-import { ClientManager } from "../../confluent/client-manager.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { ConnectionConfig } from "../../config/models.js";
+import type { BaseClientManager } from "../../confluent/base-client-manager.js";
 import { CallToolResult } from "../../confluent/schema.js";
+import { ConnectionPredicate, PredicateResult } from "../../confluent/tools/connection-predicates.js";
 import { ToolName } from "../../confluent/tools/tool-name.js";
-import { EnvVar } from "../../env-schema.js";
+import { ServerRuntime } from "../../server-runtime.js";
 import { ZodRawShape } from "zod";
+/**
+ * Standard MCP tool annotations.
+ * Tools should reference these constants rather than creating ad-hoc instances.
+ */
+export declare const READ_ONLY: ToolAnnotations;
+export declare const CREATE_UPDATE: ToolAnnotations;
+export declare const DESTRUCTIVE: ToolAnnotations;
 export interface ToolHandler {
-    handle(clientManager: ClientManager, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
+    handle(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
     getToolConfig(): ToolConfig;
     /**
-     * Returns an array of environment variables required for this tool to function.
-     *
-     * This method is used to conditionally enable/disable tools based on the availability
-     * of required environment variables. Tools will be disabled if any of their required
-     * environment variables are not set.
-     *
-     *
-     * Example:
-     * ```typescript
-     * getRequiredEnvVars(): EnvVar[] {
-     *   return [
-     *     "KAFKA_API_KEY",
-     *     "KAFKA_API_SECRET",
-     *     "BOOTSTRAP_SERVERS"
-     *   ];
-     * }
-     * ```
+     * The connection predicate that gates this tool's enablement. Lifted onto
+     * the interface so the MCP tool-call wrapper can compare it against
+     * `alwaysEnabled` to skip the OAuth login gate for tools that don't touch
+     * the client manager (currently the doc-lookup tools). See
+     * {@linkcode BaseToolHandler.predicate} for the rules around setting it.
+     */
+    readonly predicate: ConnectionPredicate;
+    /**
+     * IDs of connections that satisfy this tool's service requirements. A
+     * non-empty result enables the tool; an empty result disables it. Always a
+     * subset of `runtime.config.connections` keys.
      *
-     * @returns Array of environment variable names required by this tool
+     * Implementations that extend {@linkcode BaseToolHandler} (the standard
+     * path for every tool in this codebase) must not override this — declare
+     * a {@linkcode BaseToolHandler.predicate} property and let the base class
+     * derive the result.
      */
-    getRequiredEnvVars(): EnvVar[];
+    enabledConnectionIds(runtime: ServerRuntime): string[];
     /**
-     * Returns true if this tool can only be used with Confluent Cloud REST APIs.
-     * Override in subclasses for cloud-only tools.
+     * Per-connection verdict map for this tool: `{ enabled: true }` for
+     * connections that satisfy its requirements, `{ enabled: false; reason }`
+     * for those that don't. Powers startup-log grouping and the
+     * `describe-tool-availability` diagnostic tool.
      */
-    isConfluentCloudOnly(): boolean;
+    connectionVerdicts(runtime: ServerRuntime): Map<string, PredicateResult>;
 }
 export interface ToolConfig {
     name: ToolName;
     description: string;
     inputSchema: ZodRawShape;
+    annotations: ToolAnnotations;
 }
 export declare abstract class BaseToolHandler implements ToolHandler {
-    abstract handle(clientManager: ClientManager, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
+    abstract handle(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
     abstract getToolConfig(): ToolConfig;
     /**
-     * Default implementation that returns an empty array, indicating no environment
-     * variables are required. Override this method in your tool handler if the tool
-     * requires specific environment variables to function.
+     * The connection predicate that gates this tool. The single customization
+     * seam for tool enablement — declared as a one-line readonly property:
+     *
+     *     readonly predicate = hasKafka;                  // base predicate
+     *     readonly predicate = kafkaBootstrapOrOAuth;     // named composite
+     *     readonly predicate = alwaysEnabled;             // no requirement
+     *
+     * **Must reference a named export from `connection-predicates.ts`.** Do
+     * not compose with `allOf(...)` or `widenForOAuth(...)` at the use site.
+     * If no existing named export expresses the gate you need, add one —
+     * with a per-predicate test in `connection-predicates.test.ts` matching
+     * the depth of the existing `hasKafka` / `flinkWithTelemetry` blocks —
+     * and reference that. Enforced mechanically: the `predicate property`
+     * block in `tool-registry.test.ts` maintains an explicit
+     * `Readonly<Record<ToolName, ConnectionPredicate>>` (`EXPECTED_PREDICATES`)
+     * pinning every tool to its expected predicate. The `Record` over
+     * `ToolName` makes exhaustiveness a compile-time check (a missing tool
+     * is a `tsc` error, not a runtime one), and the value type rejects
+     * combinators at compile time. The `it.each` over the record fails with
+     * the offending tool name in the row label whenever a handler's
+     * `predicate` drifts from the table. New tools or rewires are a one-line
+     * table edit.
+     *
+     * Both {@linkcode enabledConnectionIds} and {@linkcode connectionVerdicts}
+     * are derived from this property and are marked `@final`; never override
+     * either method. The retired iteration helpers `connectionIdsWhere` and
+     * `connectionReasonsWhere` are no longer exported — the base class walks
+     * `runtime.config.connections` for you.
+     */
+    abstract readonly predicate: ConnectionPredicate;
+    /**
+     * IDs of connections that satisfy this tool's {@linkcode predicate}. A
+     * non-empty result enables the tool; an empty result disables it.
+     *
+     * Customize tool gating by declaring {@linkcode predicate}, never by
+     * replacing this derivation.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    enabledConnectionIds(runtime: ServerRuntime): string[];
+    /**
+     * Per-connection verdict map for this tool, derived from
+     * {@linkcode predicate}. Powers grouped startup logging and
+     * the diagnostic-tool surface.
+     *
+     * Customize tool gating by declaring {@linkcode predicate}, never by
+     * replacing this derivation.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    connectionVerdicts(runtime: ServerRuntime): Map<string, PredicateResult>;
+    /**
+     * Resolves the single connection enabled for this tool, returning the
+     * connection id, its config, and the matching client manager. Designed
+     * for handlers that look up `runtime.clientManagers[connId]` (multi-
+     * connection-ready shape).
      *
-     * @returns Empty array by default
+     * Selects `enabledConnectionIds(runtime)[0]` — current runtime is single-
+     * connection, so this is unambiguous; if multi-connection support lands
+     * later, handlers can switch to iterating ids.
      */
-    getRequiredEnvVars(): EnvVar[];
+    protected resolveSoleConnection(runtime: ServerRuntime): {
+        connId: string;
+        conn: ConnectionConfig;
+        clientManager: BaseClientManager;
+    };
     /**
-     * Default implementation returns false, indicating the tool is not Confluent Cloud only.
-     * Override in subclasses for cloud-only tools.
+     * Resolves a required string from an explicit tool argument, falling back to
+     * a connection-config value. Throws if neither is present.
+     * `label` is the human-readable field name (e.g. `"Organization ID"`);
+     * the thrown message is `"${label} is required"`.
+     * The returned value is always trimmed.
      */
-    isConfluentCloudOnly(): boolean;
+    protected resolveParam(argValue: string | undefined, configValue: string | undefined, label: string): string;
+    /** Like resolveParam but returns undefined instead of throwing when both are absent or blank. The returned value is always trimmed. */
+    protected resolveOptionalParam(argValue: string | undefined, configValue: string | undefined): string | undefined;
     createResponse(message: string, isError?: boolean, _meta?: Record<string, unknown>): CallToolResult;
 }
 //# sourceMappingURL=base-tools.d.ts.map

package/dist/confluent/tools/base-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-tools.d.ts","sourceRoot":"","sources":["../../../src/confluent/tools/base-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAElC,MAAM,WAAW,WAAW;IAC1B,MAAM,CACJ,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAClD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;IAE5C,aAAa,IAAI,UAAU,CAAC;IAE5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAAkB,IAAI,MAAM,EAAE,CAAC;IAE/B;;;OAGG;IACH,oBAAoB,IAAI,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,8BAAsB,eAAgB,YAAW,WAAW;IAC1D,QAAQ,CAAC,MAAM,CACb,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAClD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc;IAE3C,QAAQ,CAAC,aAAa,IAAI,UAAU;IAEpC;;;;;;OAMG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;;OAGG;IACH,oBAAoB,IAAI,OAAO;IAI/B,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,OAAe,EACxB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,cAAc;CAalB"}
+{"version":3,"file":"base-tools.d.ts","sourceRoot":"","sources":["../../../src/confluent/tools/base-tools.ts"],"names":[],"mappings":"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"}

package/dist/confluent/tools/base-tools.js

@@ -1,20 +1,83 @@
+/**
+ * Standard MCP tool annotations.
+ * Tools should reference these constants rather than creating ad-hoc instances.
+ */
+export const READ_ONLY = {
+    readOnlyHint: true,
+};
+export const CREATE_UPDATE = {
+    destructiveHint: false,
+    readOnlyHint: false,
+};
+export const DESTRUCTIVE = {
+    destructiveHint: true,
+    readOnlyHint: false,
+};
 export class BaseToolHandler {
     /**
-     * Default implementation that returns an empty array, indicating no environment
-     * variables are required. Override this method in your tool handler if the tool
-     * requires specific environment variables to function.
+     * IDs of connections that satisfy this tool's {@linkcode predicate}. A
+     * non-empty result enables the tool; an empty result disables it.
      *
-     * @returns Empty array by default
+     * Customize tool gating by declaring {@linkcode predicate}, never by
+     * replacing this derivation.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    enabledConnectionIds(runtime) {
+        return Object.entries(runtime.config.connections)
+            .filter(([, conn]) => this.predicate(conn).enabled)
+            .map(([id]) => id);
+    }
+    /**
+     * Per-connection verdict map for this tool, derived from
+     * {@linkcode predicate}. Powers grouped startup logging and
+     * the diagnostic-tool surface.
+     *
+     * Customize tool gating by declaring {@linkcode predicate}, never by
+     * replacing this derivation.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
      */
-    getRequiredEnvVars() {
-        return [];
+    connectionVerdicts(runtime) {
+        return new Map(Object.entries(runtime.config.connections).map(([id, conn]) => [
+            id,
+            this.predicate(conn),
+        ]));
     }
     /**
-     * Default implementation returns false, indicating the tool is not Confluent Cloud only.
-     * Override in subclasses for cloud-only tools.
+     * Resolves the single connection enabled for this tool, returning the
+     * connection id, its config, and the matching client manager. Designed
+     * for handlers that look up `runtime.clientManagers[connId]` (multi-
+     * connection-ready shape).
+     *
+     * Selects `enabledConnectionIds(runtime)[0]` — current runtime is single-
+     * connection, so this is unambiguous; if multi-connection support lands
+     * later, handlers can switch to iterating ids.
+     */
+    resolveSoleConnection(runtime) {
+        const connId = this.enabledConnectionIds(runtime)[0];
+        return {
+            connId,
+            conn: runtime.config.connections[connId],
+            clientManager: runtime.clientManagers[connId],
+        };
+    }
+    /**
+     * Resolves a required string from an explicit tool argument, falling back to
+     * a connection-config value. Throws if neither is present.
+     * `label` is the human-readable field name (e.g. `"Organization ID"`);
+     * the thrown message is `"${label} is required"`.
+     * The returned value is always trimmed.
      */
-    isConfluentCloudOnly() {
-        return false;
+    resolveParam(argValue, configValue, label) {
+        const resolved = argValue?.trim() || configValue?.trim();
+        if (!resolved)
+            throw new Error(`${label} is required`);
+        return resolved;
+    }
+    /** Like resolveParam but returns undefined instead of throwing when both are absent or blank. The returned value is always trimmed. */
+    resolveOptionalParam(argValue, configValue) {
+        return argValue?.trim() || configValue?.trim() || undefined;
     }
     createResponse(message, isError = false, _meta) {
         const response = {

package/dist/confluent/tools/base-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-tools.js","sourceRoot":"","sources":["../../../src/confluent/tools/base-tools.ts"],"names":[],"mappings":"AAmDA,MAAM,OAAgB,eAAe;IASnC;;;;;;OAMG;IACH,kBAAkB;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;OAGG;IACH,oBAAoB;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,cAAc,CACZ,OAAe,EACf,UAAmB,KAAK,EACxB,KAA+B;QAE/B,MAAM,QAAQ,GAAmB;YAC/B,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,OAAO;iBACd;aACF;YACD,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,KAAK;SACb,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}
+{"version":3,"file":"base-tools.js","sourceRoot":"","sources":["../../../src/confluent/tools/base-tools.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAoB;IACxC,YAAY,EAAE,IAAI;CACV,CAAC;AAEX,MAAM,CAAC,MAAM,aAAa,GAAoB;IAC5C,eAAe,EAAE,KAAK;IACtB,YAAY,EAAE,KAAK;CACX,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAoB;IAC1C,eAAe,EAAE,IAAI;IACrB,YAAY,EAAE,KAAK;CACX,CAAC;AAgDX,MAAM,OAAgB,eAAe;IAyCnC;;;;;;;;OAQG;IACH,oBAAoB,CAAC,OAAsB;QACzC,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC;aAC9C,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;aAClD,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;IAED;;;;;;;;;OASG;IACH,kBAAkB,CAAC,OAAsB;QACvC,OAAO,IAAI,GAAG,CACZ,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;YAC7D,EAAE;YACF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SACrB,CAAC,CACH,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACO,qBAAqB,CAAC,OAAsB;QAKpD,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,CAAC;QACtD,OAAO;YACL,MAAM;YACN,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAE;YACzC,aAAa,EAAE,OAAO,CAAC,cAAc,CAAC,MAAM,CAAE;SAC/C,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACO,YAAY,CACpB,QAA4B,EAC5B,WAA+B,EAC/B,KAAa;QAEb,MAAM,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,IAAI,EAAE,CAAC;QACzD,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,cAAc,CAAC,CAAC;QACvD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,uIAAuI;IAC7H,oBAAoB,CAC5B,QAA4B,EAC5B,WAA+B;QAE/B,OAAO,QAAQ,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAC9D,CAAC;IAED,cAAc,CACZ,OAAe,EACf,UAAmB,KAAK,EACxB,KAA+B;QAE/B,MAAM,QAAQ,GAAmB;YAC/B,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,OAAO;iBACd;aACF;YACD,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,KAAK;SACb,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/confluent/tools/cluster-arg-resolvers.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Cluster-arg resolver for native Kafka handlers. Asymmetric by connection
+ * type:
+ *
+ * - Direct: returns `{ clusterId: undefined, envId: undefined }`. The
+ *   `DirectClientManager` ignores cluster args and uses its eagerly-built
+ *   single-instance client(s); the handler passes the undefineds through.
+ * - OAuth: requires the args; throws with a discovery hint if missing.
+ *   Handlers catch the throw at entry and convert to a `CallToolResult`
+ *   with `isError: true` so the agent receives a normal tool-call error
+ *   rather than an RPC failure.
+ */
+import { ServerRuntime } from "../../server-runtime.js";
+export declare function resolveKafkaClusterArgs(args: {
+    cluster_id?: string;
+    environment_id?: string;
+}, runtime: ServerRuntime, connId: string): {
+    clusterId: string | undefined;
+    envId: string | undefined;
+};
+/**
+ * REST-tool variant of {@link resolveKafkaClusterArgs}. The Kafka REST API
+ * places `cluster_id` directly in the URL path
+ * (e.g. `/kafka/v3/clusters/{id}/topics`), so the handler always needs a
+ * concrete cluster id — even on direct connections that omit the arg and
+ * rely on the configured fallback.
+ *
+ * Direct: `args.clusterId ?? conn.kafka?.cluster_id`; throws if neither.
+ *   `envId` is unused (direct's `kafka.rest_endpoint` already targets the
+ *   per-cluster hostname).
+ * OAuth: both `clusterId` and `environmentId` required. Argument names are
+ *   camelCase to match the existing input-schema convention of these tools
+ *   and `list-clusters`; the native-Kafka tools' snake_case `cluster_id` is
+ *   a separate convention.
+ */
+export declare function resolveKafkaRestArgs(args: {
+    clusterId?: string;
+    environmentId?: string;
+}, runtime: ServerRuntime, connId: string): {
+    clusterId: string;
+    envId: string | undefined;
+};
+/**
+ * Env-only resolver for tools that scope a request to a single CCloud
+ * environment without a cluster identifier (e.g., `list-clusters`).
+ *
+ * Direct: arg wins; falls back to `conn.kafka?.env_id`; throws if neither
+ *   source supplies a value.
+ * OAuth: arg required (no service block to fall back to); throws with a
+ *   discovery hint pointing at `list-environments`.
+ *
+ * Argument name is camelCase (`environmentId`) to match the existing
+ * input-schema convention of cluster-management tools.
+ */
+export declare function resolveEnvArg(args: {
+    environmentId?: string;
+}, runtime: ServerRuntime, connId: string): string;
+/**
+ * Disposes a Kafka client (admin or producer) iff the connection is OAuth-typed.
+ * On direct connections this is a no-op — direct's `AsyncLazy` admin/producer
+ * are manager-owned singletons and must not be disconnected by handlers. On
+ * OAuth, calls `client.disconnect()` and swallows + logs any error so disposal
+ * failure never masks the handler's own error.
+ */
+export declare function disposeIfOAuth(runtime: ServerRuntime, connId: string, client: {
+    disconnect: () => Promise<void>;
+}): Promise<void>;
+/**
+ * Renders any error thrown from a Kafka admin/producer/consumer call into a
+ * single agent-readable string. Preserves per-topic-cause unwrapping for
+ * `KafkaJSAggregateError`, surfaces `KafkaJSError.code` when present, and
+ * falls back gracefully for unknown shapes.
+ */
+export declare function formatKafkaError(err: unknown): string;
+//# sourceMappingURL=cluster-arg-resolvers.d.ts.map

package/dist/confluent/tools/cluster-arg-resolvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-arg-resolvers.d.ts","sourceRoot":"","sources":["../../../src/confluent/tools/cluster-arg-resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb;IAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAe9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EACpD,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAqBlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EAChC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb,MAAM,CAaR;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAoBrD"}

package/dist/confluent/tools/cluster-arg-resolvers.js

@@ -0,0 +1,127 @@
+/**
+ * Cluster-arg resolver for native Kafka handlers. Asymmetric by connection
+ * type:
+ *
+ * - Direct: returns `{ clusterId: undefined, envId: undefined }`. The
+ *   `DirectClientManager` ignores cluster args and uses its eagerly-built
+ *   single-instance client(s); the handler passes the undefineds through.
+ * - OAuth: requires the args; throws with a discovery hint if missing.
+ *   Handlers catch the throw at entry and convert to a `CallToolResult`
+ *   with `isError: true` so the agent receives a normal tool-call error
+ *   rather than an RPC failure.
+ */
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+import { logger } from "../../logger.js";
+export function resolveKafkaClusterArgs(args, runtime, connId) {
+    const conn = runtime.config.connections[connId];
+    if (conn.type === "direct") {
+        return { clusterId: undefined, envId: undefined };
+    }
+    if (args.cluster_id === undefined || args.environment_id === undefined) {
+        throw new Error("cluster_id and environment_id are required under OAuth connection type. " +
+            "Discover the environment via list-environments, then call list-clusters " +
+            "with environment_id and pass the cluster's `id` and `spec.environment.id`.");
+    }
+    return { clusterId: args.cluster_id, envId: args.environment_id };
+}
+/**
+ * REST-tool variant of {@link resolveKafkaClusterArgs}. The Kafka REST API
+ * places `cluster_id` directly in the URL path
+ * (e.g. `/kafka/v3/clusters/{id}/topics`), so the handler always needs a
+ * concrete cluster id — even on direct connections that omit the arg and
+ * rely on the configured fallback.
+ *
+ * Direct: `args.clusterId ?? conn.kafka?.cluster_id`; throws if neither.
+ *   `envId` is unused (direct's `kafka.rest_endpoint` already targets the
+ *   per-cluster hostname).
+ * OAuth: both `clusterId` and `environmentId` required. Argument names are
+ *   camelCase to match the existing input-schema convention of these tools
+ *   and `list-clusters`; the native-Kafka tools' snake_case `cluster_id` is
+ *   a separate convention.
+ */
+export function resolveKafkaRestArgs(args, runtime, connId) {
+    const conn = runtime.config.connections[connId];
+    if (conn.type === "direct") {
+        const clusterId = args.clusterId ?? conn.kafka?.cluster_id;
+        if (!clusterId) {
+            throw new Error("clusterId is required: pass it as a tool argument or set kafka.cluster_id in the connection config.");
+        }
+        return { clusterId, envId: undefined };
+    }
+    if (!args.clusterId || !args.environmentId) {
+        throw new Error("clusterId and environmentId are required under OAuth connection type. " +
+            "Discover the environment via list-environments, then call list-clusters " +
+            "with environmentId and pass the cluster's `id` and `spec.environment.id`.");
+    }
+    return { clusterId: args.clusterId, envId: args.environmentId };
+}
+/**
+ * Env-only resolver for tools that scope a request to a single CCloud
+ * environment without a cluster identifier (e.g., `list-clusters`).
+ *
+ * Direct: arg wins; falls back to `conn.kafka?.env_id`; throws if neither
+ *   source supplies a value.
+ * OAuth: arg required (no service block to fall back to); throws with a
+ *   discovery hint pointing at `list-environments`.
+ *
+ * Argument name is camelCase (`environmentId`) to match the existing
+ * input-schema convention of cluster-management tools.
+ */
+export function resolveEnvArg(args, runtime, connId) {
+    const conn = runtime.config.connections[connId];
+    const fallback = conn.type === "direct" ? conn.kafka?.env_id : undefined;
+    const resolved = args.environmentId ?? fallback;
+    if (!resolved) {
+        throw new Error("environmentId is required: pass it as a tool argument or " +
+            (conn.type === "direct"
+                ? "set kafka.env_id in the connection config."
+                : "call list-environments to discover available environments."));
+    }
+    return resolved;
+}
+/**
+ * Disposes a Kafka client (admin or producer) iff the connection is OAuth-typed.
+ * On direct connections this is a no-op — direct's `AsyncLazy` admin/producer
+ * are manager-owned singletons and must not be disconnected by handlers. On
+ * OAuth, calls `client.disconnect()` and swallows + logs any error so disposal
+ * failure never masks the handler's own error.
+ */
+export async function disposeIfOAuth(runtime, connId, client) {
+    if (runtime.config.connections[connId].type !== "oauth")
+        return;
+    try {
+        await client.disconnect();
+    }
+    catch (err) {
+        logger.warn({ err, connId }, "OAuth Kafka client disconnect failed");
+    }
+}
+/**
+ * Renders any error thrown from a Kafka admin/producer/consumer call into a
+ * single agent-readable string. Preserves per-topic-cause unwrapping for
+ * `KafkaJSAggregateError`, surfaces `KafkaJSError.code` when present, and
+ * falls back gracefully for unknown shapes.
+ */
+export function formatKafkaError(err) {
+    if (err instanceof KafkaJS.KafkaJSAggregateError) {
+        const details = err.errors
+            .map((inner) => {
+            if (inner instanceof KafkaJS.KafkaJSCreateTopicError) {
+                return `- ${inner.topic}: ${inner.message}`;
+            }
+            if (inner instanceof KafkaJS.KafkaJSError) {
+                return `- ${inner.code ?? "unknown"}: ${inner.message}`;
+            }
+            return `- ${typeof inner === "string" ? inner : String(inner)}`;
+        })
+            .join("\n");
+        return `${err.message}\n${details}`;
+    }
+    if (err instanceof KafkaJS.KafkaJSError) {
+        return `Kafka error (${err.code ?? "unknown"}): ${err.message}`;
+    }
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+//# sourceMappingURL=cluster-arg-resolvers.js.map

package/dist/confluent/tools/cluster-arg-resolvers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-arg-resolvers.js","sourceRoot":"","sources":["../../../src/confluent/tools/cluster-arg-resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,MAAM,UAAU,uBAAuB,CACrC,IAAsD,EACtD,OAAsB,EACtB,MAAc;IAEd,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAE,CAAC;IAEjD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACpD,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CACb,0EAA0E;YACxE,0EAA0E;YAC1E,4EAA4E,CAC/E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAoD,EACpD,OAAsB,EACtB,MAAc;IAEd,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAE,CAAC;IAEjD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC;QAC3D,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,qGAAqG,CACtG,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,wEAAwE;YACtE,0EAA0E;YAC1E,2EAA2E,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAgC,EAChC,OAAsB,EACtB,MAAc;IAEd,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAE,CAAC;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,IAAI,QAAQ,CAAC;IAChD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,2DAA2D;YACzD,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ;gBACrB,CAAC,CAAC,4CAA4C;gBAC9C,CAAC,CAAC,4DAA4D,CAAC,CACpE,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAsB,EACtB,MAAc,EACd,MAA2C;IAE3C,IAAI,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAE,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO;IACjE,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,sCAAsC,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,IAAI,GAAG,YAAY,OAAO,CAAC,qBAAqB,EAAE,CAAC;QACjD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM;aACvB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACb,IAAI,KAAK,YAAY,OAAO,CAAC,uBAAuB,EAAE,CAAC;gBACrD,OAAO,KAAK,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;YAC9C,CAAC;YACD,IAAI,KAAK,YAAY,OAAO,CAAC,YAAY,EAAE,CAAC;gBAC1C,OAAO,KAAK,KAAK,CAAC,IAAI,IAAI,SAAS,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;YAC1D,CAAC;YACD,OAAO,KAAK,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAClE,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO,GAAG,GAAG,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;IACtC,CAAC;IACD,IAAI,GAAG,YAAY,OAAO,CAAC,YAAY,EAAE,CAAC;QACxC,OAAO,gBAAgB,GAAG,CAAC,IAAI,IAAI,SAAS,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;IAClE,CAAC;IACD,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IAC7C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC"}