@confluentinc/mcp-confluent 1.4.0 → 1.5.0

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

@@ -1,11 +1,11 @@
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import type { ConnectionConfig } from "../../config/models.js";
+import type { ConnectionConfig, DirectConnectionConfig } 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 { ServerRuntime } from "../../server-runtime.js";
-import { ZodRawShape } from "zod";
+import { z, ZodRawShape } from "zod";
 /**
  * Standard MCP tool annotations.
  * Tools should reference these constants rather than creating ad-hoc instances.
@@ -13,6 +13,18 @@ import { ZodRawShape } from "zod";
 export declare const READ_ONLY: ToolAnnotations;
 export declare const CREATE_UPDATE: ToolAnnotations;
 export declare const DESTRUCTIVE: ToolAnnotations;
+/**
+ * Opening clause of the injected `connectionId` parameter description, before the
+ * quoted, comma-separated list of viable connection ids (see
+ * {@linkcode quoteJoinIds}) is appended.
+ */
+export declare const CONNECTION_ID_DESCRIPTION_PREFIX = "Which configured connection to target. One of: ";
+/**
+ * Sentence appended to the `connectionId` description that steers the agent at the
+ * discovery tool. Emitted only when that tool is itself reachable; the joining space
+ * is added at the call site so a blocked tool leaves no dangling trailing space.
+ */
+export declare const LIST_CONFIGURED_CONNECTIONS_POINTER = "Discover connections and learn what tools are supported by each connection by invoking 'list-configured-connections'.";
 /**
  * Operator-facing taxonomy of tool kinds.
  *
@@ -34,8 +46,18 @@ export declare enum ToolCategory {
     Tableflow = "tableflow"
 }
 export interface ToolHandler {
+    /** Handle a tool invocation. */
     handle(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
-    getToolConfig(): ToolConfig;
+    /**
+     * Produce the actual config registered with MCP for this tool, injecting a
+     * required `connectionId` parameter when the server holds more than one
+     * connection. See {@linkcode BaseToolHandler.getRegisteredToolConfig} for the
+     * rules.
+     *
+     * This method is called when setting up the MCP server, and we ourselves make
+     * the downcall to the handler-authored `getToolConfig()`.
+     */
+    getRegisteredToolConfig(runtime: ServerRuntime): RegisteredToolConfig;
     /**
      * The connection predicate that gates this tool's enablement. Lifted onto
      * the interface so the MCP tool-call wrapper can compare it against
@@ -68,6 +90,16 @@ export interface ToolHandler {
      * `describe-tool-availability` diagnostic tool.
      */
     connectionVerdicts(runtime: ServerRuntime): Map<string, PredicateResult>;
+    /**
+     * Whether this tool is enabled irrespective of the configured connections.
+     * See {@linkcode BaseToolHandler.isConnectionIndependent}.
+     */
+    readonly isConnectionIndependent: boolean;
+    /**
+     * The connection id this invocation routes to, or `undefined` when it routes
+     * to none. See {@linkcode BaseToolHandler.resolvedTargetConnectionId}.
+     */
+    resolvedTargetConnectionId(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined): string | undefined;
 }
 export interface ToolConfig {
     name: ToolName;
@@ -75,9 +107,65 @@ export interface ToolConfig {
     inputSchema: ZodRawShape;
     annotations: ToolAnnotations;
 }
+/**
+ * The config actually registered with MCP, produced by
+ * {@linkcode BaseToolHandler.getRegisteredToolConfig}. Differs from the
+ * handler-authored {@linkcode ToolConfig} in that `inputSchema` is a resolved,
+ * strict Zod object rather than a bare shape: strict so unknown parameters are
+ * rejected (not silently stripped) before `handle()` runs, and resolved because
+ * a multi-connection server injects the required `connectionId` enum into it.
+ */
+export interface RegisteredToolConfig extends Omit<ToolConfig, "inputSchema"> {
+    inputSchema: z.ZodObject;
+}
+/**
+ * What the connection-resolution helpers hand back: the chosen connection id,
+ * its resolved config, and the client manager bound to it.
+ *
+ * Generic over the connection arm so the type-neutral resolvers
+ * ({@linkcode BaseToolHandler.resolveConnection}) and the direct-narrowing one
+ * ({@linkcode BaseToolHandler.resolveDirectConnection}) share a single name —
+ * the latter instantiates it via the {@link ResolvedDirectConnection} alias.
+ */
+export interface ResolvedConnection<C extends ConnectionConfig = ConnectionConfig> {
+    connId: string;
+    conn: C;
+    clientManager: BaseClientManager;
+}
+/**
+ * A {@link ResolvedConnection} pre-narrowed to the direct arm — the return type
+ * of {@linkcode BaseToolHandler.resolveDirectConnection}.
+ */
+export type ResolvedDirectConnection = ResolvedConnection<DirectConnectionConfig>;
 export declare abstract class BaseToolHandler implements ToolHandler {
     abstract handle(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
-    abstract getToolConfig(): ToolConfig;
+    protected abstract getToolConfig(): ToolConfig;
+    /**
+     * Produce the actual config registered with MCP for this tool.
+     *
+     *   * If the tool is connection-oriented and the server is configured
+     *    with multiple connections, injects a required `connectionId` parameter
+     *    indicating which connection the tool call should route to.
+     *    See {@linkcode registeredInputShape} for more details.
+     *
+     *   * Wrap the input schema in `z.object(...).strict()` to uniformly reject
+     *     unknown parameters before `handle()` runs.
+     *
+     * This method is called for each active tool when setting up the MCP server.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    getRegisteredToolConfig(runtime: ServerRuntime): RegisteredToolConfig;
+    /**
+     * The input shape to register, before strict-wrapping: the authored shape,
+     * plus a required `connectionId` enum when the server holds more than one
+     * connection AND this tool is connection-oriented. A single-element enum (when
+     * only one connection is viable) is still injected on a multi-connection server,
+     * so that an explicit request for a non-viable connection (e.g. to a disabled
+     * tool because it is read_only) is rejected by the enum rather than silently
+     * auto-routed.
+     */
+    private registeredInputShape;
     /**
      * The connection predicate that gates this tool. The single customization
      * seam for tool enablement — declared as a one-line readonly property:
@@ -117,8 +205,10 @@ export declare abstract class BaseToolHandler implements ToolHandler {
      */
     abstract readonly category: ToolCategory;
     /**
-     * IDs of connections that satisfy this tool's {@linkcode predicate}. A
-     * non-empty result enables the tool; an empty result disables it.
+     * IDs of connections that satisfy this tool's {@linkcode predicate} and are
+     * not blocked by the read-only overlay. A non-empty result enables the tool;
+     * an empty result disables it. Derived from {@linkcode connectionVerdicts} so
+     * the two stay in lockstep.
      *
      * Customize tool gating by declaring {@linkcode predicate}, never by
      * replacing this derivation.
@@ -127,9 +217,40 @@ export declare abstract class BaseToolHandler implements ToolHandler {
      */
     enabledConnectionIds(runtime: ServerRuntime): string[];
     /**
-     * Per-connection verdict map for this tool, derived from
-     * {@linkcode predicate}. Powers grouped startup logging and
-     * the diagnostic-tool surface.
+     * Whether this tool is enabled regardless of the configured connections —
+     * true exactly when its {@linkcode predicate} is `alwaysEnabled`, the only
+     * predicate that returns enabled without inspecting a connection. Such tools
+     * (docs lookup, server diagnostics) never route to a connection, so they
+     * register even on a zero-connection config, where the per-connection verdict
+     * map driving {@linkcode enabledConnectionIds} is empty.
+     */
+    get isConnectionIndependent(): boolean;
+    /**
+     * The connection id this invocation routes to — the OAuth-login gate uses it
+     * to launch the browser flow only when a call actually targets the OAuth
+     * connection, not merely because one exists somewhere in the config.
+     *
+     * Returns `undefined` for a connection-independent tool — it routes to no
+     * connection, so there is nothing to pre-launch a login for.
+     *
+     * Otherwise delegates to {@linkcode resolveConnection} so routing is decided
+     * in one place rather than duplicated in the gate, and propagates its throw.
+     * Every throw path there is a `"Wacky --"` invariant violation: the injected
+     * schema (see {@linkcode getRegisteredToolConfig}) makes `connectionId`
+     * required for multi-connection tools and strips it for single-connection
+     * ones, so a call that can't resolve means that contract broke. Surfacing the
+     * error rather than swallowing it to `undefined` lets the broken invariant
+     * reach the caller instead of being silently re-discovered inside `handle()`.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    resolvedTargetConnectionId(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined): string | undefined;
+    /**
+     * Per-connection verdict map for this tool — the single source of truth for
+     * enablement. Each verdict composes the {@linkcode predicate} with the
+     * read-only overlay (see {@linkcode connectionVerdict}). Powers grouped
+     * startup logging, the diagnostic-tool surface, and
+     * {@linkcode enabledConnectionIds}.
      *
      * Customize tool gating by declaring {@linkcode predicate}, never by
      * replacing this derivation.
@@ -138,20 +259,43 @@ export declare abstract class BaseToolHandler implements ToolHandler {
      */
     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).
+     * Single-connection verdict composing the two gating layers: the
+     * {@linkcode predicate} (service reachability) and the read-only overlay.
+     *
+     * A connection the predicate already disables keeps that verdict unchanged —
+     * service reachability is the more fundamental reason and wins, so a
+     * connection missing the service block is never reported as "read-only
+     * blocked". Otherwise, a `read_only` connection disables any tool that
+     * mutates state (`annotations.readOnlyHint !== true`).
+     */
+    private connectionVerdict;
+    /**
+     * Resolves which connection a tool call targets: the explicit `connectionId`
+     * argument when present, else the sole connection enabled for this tool.
+     * Throws a listing error when the id is unknown/not-enabled, when it is
+     * present but not a string, or when omitted while two or more connections are
+     * candidates (the augmented schema makes all three unreachable in normal MCP
+     * flow — these are defensive backstops against internal call sites).
+     *
+     * Reads `connectionId` off the **raw** `toolArguments` rather than off the
+     * handler's locally-parsed object: the framework already validated it against
+     * the registered schema (see {@linkcode getRegisteredToolConfig}), and a
+     * handler's own `z.object` re-`parse()` would strip the key it never declared.
      *
-     * 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.
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    protected resolveConnection(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined): ResolvedConnection;
+    /**
+     * Like {@linkcode resolveConnection}, but narrows the resolved connection to
+     * a {@link DirectConnectionConfig} — throwing if the addressed connection is
+     * OAuth-typed. The throw is a defensive backstop: a tool's `connectionId`
+     * enum only offers connections its predicate enables, and the direct-block
+     * predicates exclude OAuth, so an OAuth connection is unreachable here via
+     * normal MCP flow.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
      */
-    protected resolveSoleConnection(runtime: ServerRuntime): {
-        connId: string;
-        conn: ConnectionConfig;
-        clientManager: BaseClientManager;
-    };
+    protected resolveDirectConnection(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined): ResolvedDirectConnection;
     /**
      * Resolves a required string from an explicit tool argument, falling back to
      * a connection-config value. Throws if neither is present.

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":"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"}
+{"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,3 +1,7 @@
+import { alwaysEnabled, ENABLED, ToolDisabledReason, } from "../../confluent/tools/connection-predicates.js";
+import { ToolName } from "../../confluent/tools/tool-name.js";
+import { quoteJoinIds } from "../../utils/quote-join-ids.js";
+import { z } from "zod";
 /**
  * Standard MCP tool annotations.
  * Tools should reference these constants rather than creating ad-hoc instances.
@@ -13,6 +17,18 @@ export const DESTRUCTIVE = {
     destructiveHint: true,
     readOnlyHint: false,
 };
+/**
+ * Opening clause of the injected `connectionId` parameter description, before the
+ * quoted, comma-separated list of viable connection ids (see
+ * {@linkcode quoteJoinIds}) is appended.
+ */
+export const CONNECTION_ID_DESCRIPTION_PREFIX = "Which configured connection to target. One of: ";
+/**
+ * Sentence appended to the `connectionId` description that steers the agent at the
+ * discovery tool. Emitted only when that tool is itself reachable; the joining space
+ * is added at the call site so a blocked tool leaves no dangling trailing space.
+ */
+export const LIST_CONFIGURED_CONNECTIONS_POINTER = `Discover connections and learn what tools are supported by each connection by invoking '${ToolName.LIST_CONFIGURED_CONNECTIONS}'.`;
 /**
  * Operator-facing taxonomy of tool kinds.
  *
@@ -36,8 +52,77 @@ export var ToolCategory;
 })(ToolCategory || (ToolCategory = {}));
 export class BaseToolHandler {
     /**
-     * IDs of connections that satisfy this tool's {@linkcode predicate}. A
-     * non-empty result enables the tool; an empty result disables it.
+     * Produce the actual config registered with MCP for this tool.
+     *
+     *   * If the tool is connection-oriented and the server is configured
+     *    with multiple connections, injects a required `connectionId` parameter
+     *    indicating which connection the tool call should route to.
+     *    See {@linkcode registeredInputShape} for more details.
+     *
+     *   * Wrap the input schema in `z.object(...).strict()` to uniformly reject
+     *     unknown parameters before `handle()` runs.
+     *
+     * This method is called for each active tool when setting up the MCP server.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    getRegisteredToolConfig(runtime) {
+        const config = this.getToolConfig();
+        return {
+            ...config,
+            inputSchema: z
+                .object(this.registeredInputShape(config, runtime))
+                .strict(),
+        };
+    }
+    /**
+     * The input shape to register, before strict-wrapping: the authored shape,
+     * plus a required `connectionId` enum when the server holds more than one
+     * connection AND this tool is connection-oriented. A single-element enum (when
+     * only one connection is viable) is still injected on a multi-connection server,
+     * so that an explicit request for a non-viable connection (e.g. to a disabled
+     * tool because it is read_only) is rejected by the enum rather than silently
+     * auto-routed.
+     */
+    registeredInputShape(config, runtime) {
+        // Connection-independent tools (docs, diagnostics) never route to a
+        // connection and so never need a connectionId parameter.
+        if (this.isConnectionIndependent)
+            return config.inputSchema;
+        // A single-connection (or zero-connection) server has no ambiguity as to
+        // which connection a call routes to, so the call auto-routes with no extra
+        // argument. The zero-connection case also covers the `--list-tools` runtime,
+        // which wants the unaugmented view.
+        if (runtime.config.getConnectionIds().length <= 1)
+            return config.inputSchema;
+        const ids = this.enabledConnectionIds(runtime);
+        // A tool viable on no connection is never registered (the enablement filter
+        // in index.ts drops it), so this method is never called for one. Reaching
+        // here means the wiring is broken; bail loudly rather than build an illegal
+        // `z.enum([])`.
+        if (ids.length === 0) {
+            throw new Error(`Wacky -- tool ${config.name} resolved to zero enabled connections on a multi-connection server; it should never have been registered`);
+        }
+        // Point the agent at list-configured-connections so it can learn which
+        // tools each connection supports — but only when that tool is itself
+        // reachable; naming a tool the operator blocked would send the agent
+        // chasing a ghost. The leading space rides with the pointer (not the
+        // template) so the blocked, empty-pointer case ends cleanly at the period.
+        const listConfiguredConnectionsPointer = runtime.isToolAllowed(ToolName.LIST_CONFIGURED_CONNECTIONS)
+            ? ` ${LIST_CONFIGURED_CONNECTIONS_POINTER}`
+            : "";
+        return {
+            ...config.inputSchema,
+            connectionId: z
+                .enum(ids)
+                .describe(`${CONNECTION_ID_DESCRIPTION_PREFIX}${quoteJoinIds(ids)}.${listConfiguredConnectionsPointer}`),
+        };
+    }
+    /**
+     * IDs of connections that satisfy this tool's {@linkcode predicate} and are
+     * not blocked by the read-only overlay. A non-empty result enables the tool;
+     * an empty result disables it. Derived from {@linkcode connectionVerdicts} so
+     * the two stay in lockstep.
      *
      * Customize tool gating by declaring {@linkcode predicate}, never by
      * replacing this derivation.
@@ -45,14 +130,51 @@ export class BaseToolHandler {
      * @final — concrete on `BaseToolHandler`; subclasses must not override.
      */
     enabledConnectionIds(runtime) {
-        return Object.entries(runtime.config.connections)
-            .filter(([, conn]) => this.predicate(conn).enabled)
+        return [...this.connectionVerdicts(runtime)]
+            .filter(([, verdict]) => verdict.enabled)
             .map(([id]) => id);
     }
     /**
-     * Per-connection verdict map for this tool, derived from
-     * {@linkcode predicate}. Powers grouped startup logging and
-     * the diagnostic-tool surface.
+     * Whether this tool is enabled regardless of the configured connections —
+     * true exactly when its {@linkcode predicate} is `alwaysEnabled`, the only
+     * predicate that returns enabled without inspecting a connection. Such tools
+     * (docs lookup, server diagnostics) never route to a connection, so they
+     * register even on a zero-connection config, where the per-connection verdict
+     * map driving {@linkcode enabledConnectionIds} is empty.
+     */
+    get isConnectionIndependent() {
+        return this.predicate === alwaysEnabled;
+    }
+    /**
+     * The connection id this invocation routes to — the OAuth-login gate uses it
+     * to launch the browser flow only when a call actually targets the OAuth
+     * connection, not merely because one exists somewhere in the config.
+     *
+     * Returns `undefined` for a connection-independent tool — it routes to no
+     * connection, so there is nothing to pre-launch a login for.
+     *
+     * Otherwise delegates to {@linkcode resolveConnection} so routing is decided
+     * in one place rather than duplicated in the gate, and propagates its throw.
+     * Every throw path there is a `"Wacky --"` invariant violation: the injected
+     * schema (see {@linkcode getRegisteredToolConfig}) makes `connectionId`
+     * required for multi-connection tools and strips it for single-connection
+     * ones, so a call that can't resolve means that contract broke. Surfacing the
+     * error rather than swallowing it to `undefined` lets the broken invariant
+     * reach the caller instead of being silently re-discovered inside `handle()`.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    resolvedTargetConnectionId(runtime, toolArguments) {
+        if (this.isConnectionIndependent)
+            return undefined;
+        return this.resolveConnection(runtime, toolArguments).connId;
+    }
+    /**
+     * Per-connection verdict map for this tool — the single source of truth for
+     * enablement. Each verdict composes the {@linkcode predicate} with the
+     * read-only overlay (see {@linkcode connectionVerdict}). Powers grouped
+     * startup logging, the diagnostic-tool surface, and
+     * {@linkcode enabledConnectionIds}.
      *
      * Customize tool gating by declaring {@linkcode predicate}, never by
      * replacing this derivation.
@@ -62,27 +184,108 @@ export class BaseToolHandler {
     connectionVerdicts(runtime) {
         return new Map(Object.entries(runtime.config.connections).map(([id, conn]) => [
             id,
-            this.predicate(conn),
+            this.connectionVerdict(conn),
         ]));
     }
     /**
-     * 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).
+     * Single-connection verdict composing the two gating layers: the
+     * {@linkcode predicate} (service reachability) and the read-only overlay.
+     *
+     * A connection the predicate already disables keeps that verdict unchanged —
+     * service reachability is the more fundamental reason and wins, so a
+     * connection missing the service block is never reported as "read-only
+     * blocked". Otherwise, a `read_only` connection disables any tool that
+     * mutates state (`annotations.readOnlyHint !== true`).
+     */
+    connectionVerdict(conn) {
+        const verdict = this.predicate(conn);
+        if (!verdict.enabled)
+            return verdict;
+        if (conn.read_only === true &&
+            this.getToolConfig().annotations.readOnlyHint !== true) {
+            return { enabled: false, reason: ToolDisabledReason.ReadOnlyConnection };
+        }
+        return ENABLED;
+    }
+    /**
+     * Resolves which connection a tool call targets: the explicit `connectionId`
+     * argument when present, else the sole connection enabled for this tool.
+     * Throws a listing error when the id is unknown/not-enabled, when it is
+     * present but not a string, or when omitted while two or more connections are
+     * candidates (the augmented schema makes all three unreachable in normal MCP
+     * flow — these are defensive backstops against internal call sites).
      *
-     * 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.
+     * Reads `connectionId` off the **raw** `toolArguments` rather than off the
+     * handler's locally-parsed object: the framework already validated it against
+     * the registered schema (see {@linkcode getRegisteredToolConfig}), and a
+     * handler's own `z.object` re-`parse()` would strip the key it never declared.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
      */
-    resolveSoleConnection(runtime) {
-        const connId = this.enabledConnectionIds(runtime)[0];
+    resolveConnection(runtime, toolArguments) {
+        // The connection this tool call should route to.
+        let determinedId;
+        // What connection ids this tool possibly supports.
+        const enabledIds = this.enabledConnectionIds(runtime);
+        // The requested connection id, if the caller provided one. Per the Zod schema injected by
+        // `getRegisteredToolConfig()` it should be a string that is one of the enabled ids; both
+        // expectations are enforced below rather than assumed.
+        const requestedId = toolArguments?.connectionId;
+        if (typeof requestedId === "string") {
+            if (!enabledIds.includes(requestedId)) {
+                throw new Error(`Wacky -- connection "${requestedId}" is not an enabled connection for this tool; enabled: ${enabledIds.join(", ")}`);
+            }
+            // Explicit requested ID must be valid based on the injected schema enum already having validated it, so can
+            // at this point trust fully.
+            determinedId = requestedId;
+        }
+        else if (requestedId !== undefined) {
+            // Unreachable in normal operation: Zod has already validated `args`
+            // against the registered schema before `handle()` runs, and that schema
+            // either declares `connectionId` as a string enum (multi-connection
+            // servers — a non-string fails parsing) or omits it entirely (single-
+            // connection servers — the strict schema rejects the unknown key). Either
+            // way a non-string can't survive to reach this branch. It exists purely as a symmetric
+            // peer to the two backstops below, so a malformed value can never quietly
+            // masquerade as an omission and auto-route.
+            throw new Error(`Wacky -- connectionId present but not a string (got ${typeof requestedId}); the injected schema should have rejected this`);
+        }
+        else if (enabledIds.length === 1) {
+            // No requested ID, but only one enabled connection — unambiguous, so route there.
+            determinedId = enabledIds[0];
+        }
+        else {
+            // Not a string and not a sole enabled connection. Should have been blocked by the injected schema.
+            throw new Error(`Wacky -- connectionId omitted but this tool is enabled for ${enabledIds.length} connections (${enabledIds.join(", ") || "none"}); cannot auto-route`);
+        }
         return {
-            connId,
-            conn: runtime.config.connections[connId],
-            clientManager: runtime.clientManagers[connId],
+            connId: determinedId,
+            conn: runtime.config.connections[determinedId],
+            clientManager: runtime.clientManagers[determinedId],
         };
     }
+    /**
+     * Like {@linkcode resolveConnection}, but narrows the resolved connection to
+     * a {@link DirectConnectionConfig} — throwing if the addressed connection is
+     * OAuth-typed. The throw is a defensive backstop: a tool's `connectionId`
+     * enum only offers connections its predicate enables, and the direct-block
+     * predicates exclude OAuth, so an OAuth connection is unreachable here via
+     * normal MCP flow.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    resolveDirectConnection(runtime, toolArguments) {
+        // Reuse resolveConnection for id selection + validation; this method only
+        // adds the direct-vs-oauth narrowing on top of its type-neutral result.
+        const { connId, conn, clientManager } = this.resolveConnection(runtime, toolArguments);
+        // A resolved OAuth connection means the wiring is broken (a non-oauth tool
+        // somehow offered an oauth id), not that a caller legitimately asked for one.
+        if (conn.type !== "direct") {
+            throw new Error(`Wacky -- connection "${connId}" is ${conn.type}-typed; this tool requires a direct connection`);
+        }
+        // conn is narrowed to DirectConnectionConfig by the guard above.
+        return { connId, conn, clientManager };
+    }
     /**
      * Resolves a required string from an explicit tool argument, falling back to
      * a connection-config value. Throws if neither is present.

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

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

@@ -10,7 +10,28 @@
  *   with `isError: true` so the agent receives a normal tool-call error
  *   rather than an RPC failure.
  */
+import { ConnectionConfig } from "../../config/models.js";
 import { ServerRuntime } from "../../server-runtime.js";
+/**
+ * Shared env + Kafka-cluster resolver for Confluent Cloud REST handlers that
+ * address a resource by environment + cluster and carry those ids in the
+ * request URL/body (Connect, Tableflow). Distinct from the native-Kafka
+ * {@link resolveKafkaClusterArgs}, which returns `undefined` on direct because
+ * the `DirectClientManager` ignores cluster args — here the handler genuinely
+ * needs the concrete ids.
+ *
+ * - Direct: explicit tool args win, falling back to the connection's
+ *   `kafka.env_id` / `kafka.cluster_id`. Throws `"Environment ID is required"` /
+ *   `"Kafka Cluster ID is required"` if either value is absent from both
+ *   sources.
+ * - OAuth: both args are required (an OAuth connection carries no `kafka` block
+ *   to fall back to). Throws a discovery hint pointing at `list-environments` /
+ *   `list-clusters` when either is missing.
+ */
+export declare function resolveEnvAndClusterArgs(conn: ConnectionConfig, envIdArg: string | undefined, clusterIdArg: string | undefined): {
+    environment_id: string;
+    kafka_cluster_id: string;
+};
 export declare function resolveKafkaClusterArgs(args: {
     cluster_id?: string;
     environment_id?: string;

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

@@ -1 +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"}
+{"version":3,"file":"cluster-arg-resolvers.d.ts","sourceRoot":"","sources":["../../../src/confluent/tools/cluster-arg-resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAmBvD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAyBtD;AAED,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"}