@confluentinc/mcp-confluent 1.3.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,9 +13,51 @@ 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.
+ *
+ * Answers "what kind of tool is this?" — orthogonal to the
+ * {@linkcode ConnectionPredicate}-based "is this tool enabled?" question that
+ * lives next door. Predicates gate advertisement; categories classify intent.
+ */
+export declare enum ToolCategory {
+    Billing = "billing",
+    Catalog = "catalog",
+    ConfluentCloud = "confluent-cloud",
+    Connect = "connect",
+    Docs = "docs",
+    Flink = "flink",
+    Kafka = "kafka",
+    McpServerDiagnostics = "mcp-server-diagnostics",
+    Metrics = "metrics",
+    SchemaRegistry = "schema-registry",
+    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
@@ -24,6 +66,12 @@ export interface ToolHandler {
      * {@linkcode BaseToolHandler.predicate} for the rules around setting it.
      */
     readonly predicate: ConnectionPredicate;
+    /**
+     * The {@linkcode ToolCategory} this tool belongs to — operator-facing
+     * taxonomy, orthogonal to {@linkcode predicate}. See
+     * {@linkcode BaseToolHandler.category} for the rules around setting it.
+     */
+    readonly category: ToolCategory;
     /**
      * IDs of connections that satisfy this tool's service requirements. A
      * non-empty result enables the tool; an empty result disables it. Always a
@@ -42,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;
@@ -49,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:
@@ -84,8 +198,17 @@ export declare abstract class BaseToolHandler implements ToolHandler {
      */
     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.
+     * The {@linkcode ToolCategory} this tool belongs to — operator-facing
+     * taxonomy answering "what kind of tool is this?" Orthogonal to
+     * {@linkcode predicate} (which gates advertisement); category classifies
+     * intent for grouping in diagnostic surfaces and AI-client UX.
+     */
+    abstract readonly category: ToolCategory;
+    /**
+     * 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.
@@ -94,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.
@@ -105,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.
      *
-     * 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.
+     * 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.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
      */
-    protected resolveSoleConnection(runtime: ServerRuntime): {
-        connId: string;
-        conn: ConnectionConfig;
-        clientManager: BaseClientManager;
-    };
+    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 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.
@@ -130,5 +307,14 @@ export declare abstract class BaseToolHandler implements ToolHandler {
     /** 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;
+    /**
+     * Variant of {@link createResponse} that surfaces the response's
+     * machine-readable payload via MCP's `structuredContent` channel (per the
+     * [2025-11-25 spec](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)).
+     * The `message` carries the human-readable summary on `content`; the
+     * `structuredContent` field carries the typed JSON payload callers (or
+     * `outputSchema` validators) can consume directly.
+     */
+    createStructuredResponse(message: string, structuredContent: 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":"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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,10 +17,112 @@ 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.
+ *
+ * Answers "what kind of tool is this?" — orthogonal to the
+ * {@linkcode ConnectionPredicate}-based "is this tool enabled?" question that
+ * lives next door. Predicates gate advertisement; categories classify intent.
+ */
+export var ToolCategory;
+(function (ToolCategory) {
+    ToolCategory["Billing"] = "billing";
+    ToolCategory["Catalog"] = "catalog";
+    ToolCategory["ConfluentCloud"] = "confluent-cloud";
+    ToolCategory["Connect"] = "connect";
+    ToolCategory["Docs"] = "docs";
+    ToolCategory["Flink"] = "flink";
+    ToolCategory["Kafka"] = "kafka";
+    ToolCategory["McpServerDiagnostics"] = "mcp-server-diagnostics";
+    ToolCategory["Metrics"] = "metrics";
+    ToolCategory["SchemaRegistry"] = "schema-registry";
+    ToolCategory["Tableflow"] = "tableflow";
+})(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.
@@ -24,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.
@@ -41,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.
      *
-     * 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.
+     * 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`).
      */
-    resolveSoleConnection(runtime) {
-        const connId = this.enabledConnectionIds(runtime)[0];
+    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).
+     *
+     * 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.
+     */
+    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.
@@ -92,5 +316,20 @@ export class BaseToolHandler {
         };
         return response;
     }
+    /**
+     * Variant of {@link createResponse} that surfaces the response's
+     * machine-readable payload via MCP's `structuredContent` channel (per the
+     * [2025-11-25 spec](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)).
+     * The `message` carries the human-readable summary on `content`; the
+     * `structuredContent` field carries the typed JSON payload callers (or
+     * `outputSchema` validators) can consume directly.
+     */
+    createStructuredResponse(message, structuredContent) {
+        return {
+            content: [{ type: "text", text: message }],
+            structuredContent,
+            isError: false,
+        };
+    }
 }
 //# sourceMappingURL=base-tools.js.map