@confluentinc/mcp-confluent 1.4.0 → 1.6.0

package/dist/confluent/sentry.js

@@ -0,0 +1,68 @@
+import { buildConfig, sentry } from "../confluent/node-deps.js";
+import { redactEvent } from "../confluent/sentry-redact.js";
+import { logger } from "../logger.js";
+let initialized = false;
+/** DSN baked at pack time; empty (-> disabled) on dev/unpacked builds. */
+export function resolveSentryDsn() {
+    return buildConfig.SENTRY_DSN || undefined;
+}
+function joinSorted(values) {
+    return values.length
+        ? [...values].sort((a, b) => a.localeCompare(b)).join(",")
+        : "none";
+}
+/**
+ * Initialize crash reporting. Short-circuits — no DSN registered, no transport,
+ * no global handlers — when the user has opted out or no DSN was baked in. Uses
+ * the same resolved `doNotTrack` value as usage analytics, so one switch
+ * disables both.
+ */
+export function initSentry(opts) {
+    if (initialized)
+        return; // idempotent: never register the client twice
+    if (opts.doNotTrack || !opts.dsn) {
+        logger.info("Error reporting disabled");
+        return;
+    }
+    sentry.init({
+        dsn: opts.dsn,
+        release: opts.release,
+        debug: false,
+        attachStacktrace: true,
+        includeLocalVariables: false,
+        tracesSampleRate: 0,
+        profilesSampleRate: 0,
+        // Defense in depth on top of `beforeSend`: this server handles credentials,
+        // so never attach HTTP bodies (may carry secrets) and don't set user.* fields.
+        dataCollection: {
+            userInfo: false,
+            httpBodies: [],
+        },
+        initialScope: {
+            tags: {
+                transport: joinSorted(opts.transports),
+                connections: joinSorted(opts.connectionTypes),
+            },
+        },
+        integrations: (defaults) => [
+            ...defaults,
+            sentry.rewriteFramesIntegration(),
+        ],
+        beforeSend: (event) => redactEvent(event),
+    });
+    initialized = true;
+    logger.info("Error reporting enabled");
+}
+/** Report an error. No-op until {@link initSentry} has registered a client. */
+export function captureException(error, context) {
+    if (!initialized)
+        return;
+    sentry.captureException(error, context);
+}
+export async function closeSentry(timeoutMs = 2000) {
+    if (!initialized)
+        return true;
+    initialized = false;
+    return sentry.close(timeoutMs);
+}
+//# sourceMappingURL=sentry.js.map

package/dist/confluent/sentry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentry.js","sourceRoot":"","sources":["../../src/confluent/sentry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,CAAC,UAAU,IAAI,SAAS,CAAC;AAC7C,CAAC;AAWD,SAAS,UAAU,CAAC,MAAyB;IAC3C,OAAO,MAAM,CAAC,MAAM;QAClB,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAC1D,CAAC,CAAC,MAAM,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,IAAI,WAAW;QAAE,OAAO,CAAC,8CAA8C;IACvE,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACxC,OAAO;IACT,CAAC;IACD,MAAM,CAAC,IAAI,CAAC;QACV,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,KAAK;QACZ,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,KAAK;QAC5B,gBAAgB,EAAE,CAAC;QACnB,kBAAkB,EAAE,CAAC;QACrB,4EAA4E;QAC5E,+EAA+E;QAC/E,cAAc,EAAE;YACd,QAAQ,EAAE,KAAK;YACf,UAAU,EAAE,EAAE;SACf;QACD,YAAY,EAAE;YACZ,IAAI,EAAE;gBACJ,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC;gBACtC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC;aAC9C;SACF;QACD,YAAY,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC1B,GAAG,QAAQ;YACX,MAAM,CAAC,wBAAwB,EAAE;SAClC;QACD,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC;KAC1C,CAAC,CAAC;IACH,WAAW,GAAG,IAAI,CAAC;IACnB,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;AACzC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAC9B,KAAc,EACd,OAA2C;IAE3C,IAAI,CAAC,WAAW;QAAE,OAAO;IACzB,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,SAAS,GAAG,IAAI;IAChD,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,WAAW,GAAG,KAAK,CAAC;IACpB,OAAO,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AACjC,CAAC"}

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

@@ -1,11 +1,12 @@
 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 type { CallToolResult } from "../../confluent/schema.js";
+import type { 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 type { ServerRuntime } from "../../server-runtime.js";
+import type { ZodRawShape } from "zod";
+import { z } from "zod";
 /**
  * Standard MCP tool annotations.
  * Tools should reference these constants rather than creating ad-hoc instances.
@@ -13,6 +14,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 +47,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 +91,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 +108,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 +206,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 +218,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 +260,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,8 @@
+import { alwaysEnabled, ENABLED, ToolDisabledReason, } from "../../confluent/tools/connection-predicates.js";
+import { ToolInputError } from "../../confluent/tools/tool-input-error.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 +18,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 +53,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 +131,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 +185,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.
@@ -93,7 +297,7 @@ export class BaseToolHandler {
     resolveParam(argValue, configValue, label) {
         const resolved = argValue?.trim() || configValue?.trim();
         if (!resolved)
-            throw new Error(`${label} is required`);
+            throw new ToolInputError(`${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. */