@confluentinc/mcp-confluent 1.4.0 → 1.5.0

package/dist/confluent/tools/handlers/diagnostics/describe-configured-connection-handler.d.ts

@@ -0,0 +1,31 @@
+import { CallToolResult } from "../../../../confluent/schema.js";
+import { ToolCategory, ToolConfig } from "../../../../confluent/tools/base-tools.js";
+import { ToolMetadataHandler } from "../../../../confluent/tools/tool-metadata-handler.js";
+import { ServerRuntime } from "../../../../server-runtime.js";
+/**
+ * Discovery tool: the per-connection counterpart to `list-configured-connections`.
+ * Given one `connectionId`, returns its non-secret config card plus which
+ * connection-routable tools are enabled on it and, for those that aren't, the
+ * reason each is gated off.
+ *
+ * The enabled/disabled split is read from each handler's
+ * {@link import("../../../../confluent/tools/base-tools.js").ToolHandler.connectionVerdicts}
+ * indexed at the requested connection — the same source `explain-disabled-tools`
+ * consumes. The read-only overlay therefore needs no special-casing here: a
+ * mutating tool on a `read_only` connection surfaces in the
+ * {@link ToolDisabledReason.ReadOnlyConnection} bucket automatically, kept
+ * distinct from the service-block-missing buckets, and the text summary renders
+ * that bucket affirmatively as the set of writes the flag suppresses.
+ *
+ * Always enabled (predicate is `alwaysEnabled`) so an operator can introspect a
+ * connection even when its config left every routable tool disabled. The
+ * connection-routability filter and the catalog thunk both come from
+ * {@link ToolMetadataHandler}.
+ */
+export declare class DescribeConfiguredConnectionHandler extends ToolMetadataHandler {
+    handle(runtime: ServerRuntime, toolArguments?: Record<string, unknown>): CallToolResult;
+    getToolConfig(): ToolConfig;
+    readonly category = ToolCategory.McpServerDiagnostics;
+    readonly predicate: import("../../../../confluent/tools/connection-predicates.js").ConnectionPredicate;
+}
+//# sourceMappingURL=describe-configured-connection-handler.d.ts.map

package/dist/confluent/tools/handlers/diagnostics/describe-configured-connection-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-configured-connection-handler.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/diagnostics/describe-configured-connection-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAEL,YAAY,EACZ,UAAU,EACX,MAAM,oCAAoC,CAAC;AAM5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AAEpF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AA8BvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mCAAoC,SAAQ,mBAAmB;IAC1E,MAAM,CACJ,OAAO,EAAE,aAAa,EACtB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,cAAc;IAmDjB,aAAa,IAAI,UAAU;IAU3B,QAAQ,CAAC,QAAQ,qCAAqC;IACtD,QAAQ,CAAC,SAAS,8EAAiB;CACpC"}

package/dist/confluent/tools/handlers/diagnostics/describe-configured-connection-handler.js

@@ -0,0 +1,116 @@
+import { READ_ONLY, ToolCategory, } from "../../../../confluent/tools/base-tools.js";
+import { alwaysEnabled, ToolDisabledReason, } from "../../../../confluent/tools/connection-predicates.js";
+import { buildConnectionCard } from "../../../../confluent/tools/handlers/diagnostics/describe-fields.js";
+import { ToolMetadataHandler } from "../../../../confluent/tools/tool-metadata-handler.js";
+import { ToolName } from "../../../../confluent/tools/tool-name.js";
+import { quoteJoinIds } from "../../../../utils/quote-join-ids.js";
+import { z } from "zod";
+const describeConfiguredConnectionArguments = z.object({
+    connectionId: z
+        .string()
+        .min(1, "connectionId cannot be empty")
+        .describe("The id of the configured connection to describe. One of the keys reported by 'list-configured-connections'."),
+});
+/**
+ * Discovery tool: the per-connection counterpart to `list-configured-connections`.
+ * Given one `connectionId`, returns its non-secret config card plus which
+ * connection-routable tools are enabled on it and, for those that aren't, the
+ * reason each is gated off.
+ *
+ * The enabled/disabled split is read from each handler's
+ * {@link import("../../../../confluent/tools/base-tools.js").ToolHandler.connectionVerdicts}
+ * indexed at the requested connection — the same source `explain-disabled-tools`
+ * consumes. The read-only overlay therefore needs no special-casing here: a
+ * mutating tool on a `read_only` connection surfaces in the
+ * {@link ToolDisabledReason.ReadOnlyConnection} bucket automatically, kept
+ * distinct from the service-block-missing buckets, and the text summary renders
+ * that bucket affirmatively as the set of writes the flag suppresses.
+ *
+ * Always enabled (predicate is `alwaysEnabled`) so an operator can introspect a
+ * connection even when its config left every routable tool disabled. The
+ * connection-routability filter and the catalog thunk both come from
+ * {@link ToolMetadataHandler}.
+ */
+export class DescribeConfiguredConnectionHandler extends ToolMetadataHandler {
+    handle(runtime, toolArguments) {
+        const { connectionId } = describeConfiguredConnectionArguments.parse(toolArguments ?? {});
+        const conn = runtime.config.connections[connectionId];
+        if (conn === undefined) {
+            return this.createResponse(`Unknown connection id "${connectionId}". Configured connections: ${quoteJoinIds(runtime.config.getConnectionIds()) || "none"}.`, true);
+        }
+        const { scalars, blocks } = buildConnectionCard(conn);
+        const enabledTools = [];
+        const disabledTools = {};
+        for (const [name, handler] of this.connectionRoutableTools(runtime)) {
+            // Every configured connection has a verdict (connectionVerdicts iterates
+            // runtime.config.connections), so the lookup is always defined.
+            const verdict = handler.connectionVerdicts(runtime).get(connectionId);
+            if (verdict.enabled) {
+                enabledTools.push(name);
+            }
+            else {
+                const bucket = disabledTools[verdict.reason] ?? [];
+                disabledTools[verdict.reason] = bucket;
+                bucket.push(name);
+            }
+        }
+        enabledTools.sort((a, b) => a.localeCompare(b));
+        for (const tools of Object.values(disabledTools)) {
+            tools.sort((a, b) => a.localeCompare(b));
+        }
+        const description = {
+            connectionId,
+            ...scalars,
+            readOnly: conn.read_only === true,
+            blocks,
+            enabledTools,
+            disabledTools,
+        };
+        return this.createStructuredResponse(renderCard(description, conn.type), description);
+    }
+    getToolConfig() {
+        return {
+            name: ToolName.DESCRIBE_CONFIGURED_CONNECTION,
+            description: "Describe one configured connection by id: its non-secret config (type, endpoints, resource ids — never credentials), whether it is read-only, the tools you can invoke against it, and, for tools that are unavailable on it, the config gap or policy keeping each one off. Pass the connection id from 'list-configured-connections'. Call this to learn what a specific connection supports before routing a tool call to it.",
+            inputSchema: describeConfiguredConnectionArguments.shape,
+            annotations: READ_ONLY,
+        };
+    }
+    category = ToolCategory.McpServerDiagnostics;
+    predicate = alwaysEnabled;
+}
+/**
+ * Human-readable summary of the connection card. The structured payload is
+ * authoritative; this text is the at-a-glance view. The read-only suppressed
+ * line reads the {@link ToolDisabledReason.ReadOnlyConnection} bucket directly,
+ * so it surfaces with no enum-specific branching beyond that one key.
+ */
+function renderCard(card, type) {
+    const lines = [];
+    const readOnlyMarker = card.readOnly ? ", read-only" : "";
+    lines.push(`Connection "${card.connectionId}" (${type}${readOnlyMarker})`);
+    const description = card.description;
+    if (typeof description === "string") {
+        lines.push(`Description: ${description}`);
+    }
+    const blockNames = Object.keys(card.blocks).sort((a, b) => a.localeCompare(b));
+    if (blockNames.length > 0) {
+        lines.push(`Configured blocks: ${blockNames.join(", ")}`);
+    }
+    const enabledCount = card.enabledTools.length;
+    lines.push(`${enabledCount} tool${enabledCount === 1 ? "" : "s"} enabled${enabledCount > 0 ? `: ${card.enabledTools.join(", ")}` : ""}`);
+    const suppressed = card.disabledTools[ToolDisabledReason.ReadOnlyConnection];
+    if (card.readOnly && suppressed !== undefined && suppressed.length > 0) {
+        lines.push(`${suppressed.length} mutating tool${suppressed.length === 1 ? "" : "s"} suppressed by read_only: ${suppressed.join(", ")}`);
+    }
+    const disabledEntries = Object.entries(card.disabledTools).sort(([a], [b]) => a.localeCompare(b));
+    if (disabledEntries.length > 0) {
+        const disabledCount = disabledEntries.reduce((sum, [, tools]) => sum + tools.length, 0);
+        lines.push(`${disabledCount} tool${disabledCount === 1 ? "" : "s"} disabled:`);
+        for (const [reason, tools] of disabledEntries) {
+            lines.push(`  ${reason} (${tools.length}): ${tools.join(", ")}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=describe-configured-connection-handler.js.map

package/dist/confluent/tools/handlers/diagnostics/describe-configured-connection-handler.js.map

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

package/dist/confluent/tools/handlers/diagnostics/describe-fields.d.ts

@@ -0,0 +1,52 @@
+import type { ConfluentCloudDirectConfig, ConnectionConfig, DirectConnectionConfig, FlinkDirectConfig, KafkaDirectConfig, OAuthConnectionConfig, SchemaRegistryDirectConfig, TableflowDirectConfig, TelemetryDirectConfig } from "../../../../config/models.js";
+/**
+ * How the `describe-configured-connection` card treats one connection-config
+ * field. The visibility maps below are keyed `Record<keyof T, FieldVisibility>`
+ * over each connection arm and service block, so adding a config field fails
+ * `tsc --noEmit` (which runs in the pre-push hook and CI) until it is
+ * classified here — a new knob can never ship without a deliberate
+ * surface/withhold decision, and a secret-leak audit stays a single-file review.
+ *
+ * - `public` — non-secret scalar; surfaced in the card.
+ * - `secret` — credential material (`auth` blocks); never surfaced. Audit these.
+ * - `withheld` — non-secret but deliberately not surfaced: either a structured /
+ *   opaque value (`extra_properties`) or one the card surfaces by other means
+ *   (`read_only`, echoed as the coerced top-level `readOnly` boolean instead).
+ * - `block` — a nested service block; surfaced via its own map in
+ *   {@link SERVICE_BLOCK_VISIBILITY}. Only appears at the connection level.
+ */
+export type FieldVisibility = "public" | "secret" | "withheld" | "block";
+export declare const KAFKA_FIELD_VISIBILITY: Readonly<Record<keyof KafkaDirectConfig, FieldVisibility>>;
+export declare const SCHEMA_REGISTRY_FIELD_VISIBILITY: Readonly<Record<keyof SchemaRegistryDirectConfig, FieldVisibility>>;
+export declare const CONFLUENT_CLOUD_FIELD_VISIBILITY: Readonly<Record<keyof ConfluentCloudDirectConfig, FieldVisibility>>;
+export declare const TABLEFLOW_FIELD_VISIBILITY: Readonly<Record<keyof TableflowDirectConfig, FieldVisibility>>;
+export declare const TELEMETRY_FIELD_VISIBILITY: Readonly<Record<keyof TelemetryDirectConfig, FieldVisibility>>;
+export declare const FLINK_FIELD_VISIBILITY: Readonly<Record<keyof FlinkDirectConfig, FieldVisibility>>;
+export declare const DIRECT_CONNECTION_FIELD_VISIBILITY: Readonly<Record<keyof DirectConnectionConfig, FieldVisibility>>;
+export declare const OAUTH_CONNECTION_FIELD_VISIBILITY: Readonly<Record<keyof OAuthConnectionConfig, FieldVisibility>>;
+/**
+ * Field-visibility map for each direct-connection service block, keyed by the
+ * block's connection-field name. The keys are exactly the
+ * {@link DIRECT_CONNECTION_FIELD_VISIBILITY} entries classified `"block"`
+ * (pinned by the drift-catch test in `describe-fields.test.ts`).
+ */
+export declare const SERVICE_BLOCK_VISIBILITY: Readonly<Record<string, Readonly<Record<string, FieldVisibility>>>>;
+/**
+ * The config-derived portion of a `describe-configured-connection` card:
+ * `scalars` holds the connection's `public` connection-level fields (e.g.
+ * `type`, `description`, and OAuth's `ccloud_env` / `kafka_debug`); `blocks`
+ * maps each present service block to its `public` fields. Secrets and
+ * `withheld` fields never appear in either.
+ */
+export interface ConnectionCard {
+    readonly scalars: Record<string, unknown>;
+    readonly blocks: Record<string, Record<string, unknown>>;
+}
+/**
+ * Project a connection into its non-secret card, driven entirely by the
+ * visibility maps. OAuth connections carry no service blocks, so `blocks` is
+ * empty for them; the `public`/`secret`/`withheld`/`block` switch is the single
+ * place the surface/withhold decision is enforced at runtime.
+ */
+export declare function buildConnectionCard(conn: ConnectionConfig): ConnectionCard;
+//# sourceMappingURL=describe-fields.d.ts.map

package/dist/confluent/tools/handlers/diagnostics/describe-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-fields.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/diagnostics/describe-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAEzE,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAC3C,MAAM,CAAC,MAAM,iBAAiB,EAAE,eAAe,CAAC,CAUjD,CAAC;AAEF,eAAO,MAAM,gCAAgC,EAAE,QAAQ,CACrD,MAAM,CAAC,MAAM,0BAA0B,EAAE,eAAe,CAAC,CAI1D,CAAC;AAEF,eAAO,MAAM,gCAAgC,EAAE,QAAQ,CACrD,MAAM,CAAC,MAAM,0BAA0B,EAAE,eAAe,CAAC,CAK1D,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAC/C,MAAM,CAAC,MAAM,qBAAqB,EAAE,eAAe,CAAC,CAGrD,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAC/C,MAAM,CAAC,MAAM,qBAAqB,EAAE,eAAe,CAAC,CAIrD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAC3C,MAAM,CAAC,MAAM,iBAAiB,EAAE,eAAe,CAAC,CASjD,CAAC;AAEF,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CACvD,MAAM,CAAC,MAAM,sBAAsB,EAAE,eAAe,CAAC,CAatD,CAAC;AAEF,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CACtD,MAAM,CAAC,MAAM,qBAAqB,EAAE,eAAe,CAAC,CAOrD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAC7C,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAQ1D,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,cAAc,CAmC1E"}

package/dist/confluent/tools/handlers/diagnostics/describe-fields.js

@@ -0,0 +1,114 @@
+export const KAFKA_FIELD_VISIBILITY = {
+    bootstrap_servers: "public",
+    rest_endpoint: "public",
+    cluster_id: "public",
+    env_id: "public",
+    auth: "secret",
+    // Free-form librdkafka property bag; can carry credential-ish values, so it
+    // stays unsurfaced even though it is not inherently a secret.
+    extra_properties: "withheld",
+};
+export const SCHEMA_REGISTRY_FIELD_VISIBILITY = {
+    endpoint: "public",
+    auth: "secret",
+};
+export const CONFLUENT_CLOUD_FIELD_VISIBILITY = {
+    endpoint: "public",
+    organization_id: "public",
+    auth: "secret",
+};
+export const TABLEFLOW_FIELD_VISIBILITY = {
+    auth: "secret",
+};
+export const TELEMETRY_FIELD_VISIBILITY = {
+    endpoint: "public",
+    auth: "secret",
+};
+export const FLINK_FIELD_VISIBILITY = {
+    endpoint: "public",
+    environment_id: "public",
+    organization_id: "public",
+    compute_pool_id: "public",
+    catalog_name: "public",
+    database_name: "public",
+    auth: "secret",
+};
+export const DIRECT_CONNECTION_FIELD_VISIBILITY = {
+    type: "public",
+    description: "public",
+    // Echoed as the coerced top-level `readOnly` boolean by the handler, so the
+    // raw snake_case field is withheld from the generic scalar pass.
+    read_only: "withheld",
+    kafka: "block",
+    schema_registry: "block",
+    confluent_cloud: "block",
+    tableflow: "block",
+    telemetry: "block",
+    flink: "block",
+};
+export const OAUTH_CONNECTION_FIELD_VISIBILITY = {
+    type: "public",
+    description: "public",
+    read_only: "withheld",
+    ccloud_env: "public",
+    kafka_debug: "public",
+};
+/**
+ * Field-visibility map for each direct-connection service block, keyed by the
+ * block's connection-field name. The keys are exactly the
+ * {@link DIRECT_CONNECTION_FIELD_VISIBILITY} entries classified `"block"`
+ * (pinned by the drift-catch test in `describe-fields.test.ts`).
+ */
+export const SERVICE_BLOCK_VISIBILITY = {
+    kafka: KAFKA_FIELD_VISIBILITY,
+    schema_registry: SCHEMA_REGISTRY_FIELD_VISIBILITY,
+    confluent_cloud: CONFLUENT_CLOUD_FIELD_VISIBILITY,
+    tableflow: TABLEFLOW_FIELD_VISIBILITY,
+    telemetry: TELEMETRY_FIELD_VISIBILITY,
+    flink: FLINK_FIELD_VISIBILITY,
+};
+/**
+ * Project a connection into its non-secret card, driven entirely by the
+ * visibility maps. OAuth connections carry no service blocks, so `blocks` is
+ * empty for them; the `public`/`secret`/`withheld`/`block` switch is the single
+ * place the surface/withhold decision is enforced at runtime.
+ */
+export function buildConnectionCard(conn) {
+    const connectionMap = conn.type === "oauth"
+        ? OAUTH_CONNECTION_FIELD_VISIBILITY
+        : DIRECT_CONNECTION_FIELD_VISIBILITY;
+    const fields = conn;
+    const scalars = {};
+    const blocks = {};
+    for (const [key, visibility] of Object.entries(connectionMap)) {
+        const value = fields[key];
+        switch (visibility) {
+            case "public":
+                if (value !== undefined)
+                    scalars[key] = value;
+                break;
+            case "block":
+                if (value !== undefined) {
+                    blocks[key] = projectBlock(SERVICE_BLOCK_VISIBILITY[key], value);
+                }
+                break;
+            case "secret":
+            case "withheld":
+                break;
+            default:
+                throw new Error(`Wacky -- unhandled field visibility "${visibility}" for connection field "${key}"`);
+        }
+    }
+    return { scalars, blocks };
+}
+/** Project one service block to the `public` fields it actually carries. */
+function projectBlock(blockMap, blockValue) {
+    const out = {};
+    for (const [field, visibility] of Object.entries(blockMap)) {
+        if (visibility === "public" && blockValue[field] !== undefined) {
+            out[field] = blockValue[field];
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=describe-fields.js.map

package/dist/confluent/tools/handlers/diagnostics/describe-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-fields.js","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/diagnostics/describe-fields.ts"],"names":[],"mappings":"AA8BA,MAAM,CAAC,MAAM,sBAAsB,GAE/B;IACF,iBAAiB,EAAE,QAAQ;IAC3B,aAAa,EAAE,QAAQ;IACvB,UAAU,EAAE,QAAQ;IACpB,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,QAAQ;IACd,4EAA4E;IAC5E,8DAA8D;IAC9D,gBAAgB,EAAE,UAAU;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,gCAAgC,GAEzC;IACF,QAAQ,EAAE,QAAQ;IAClB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,gCAAgC,GAEzC;IACF,QAAQ,EAAE,QAAQ;IAClB,eAAe,EAAE,QAAQ;IACzB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAEnC;IACF,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAEnC;IACF,QAAQ,EAAE,QAAQ;IAClB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAE/B;IACF,QAAQ,EAAE,QAAQ;IAClB,cAAc,EAAE,QAAQ;IACxB,eAAe,EAAE,QAAQ;IACzB,eAAe,EAAE,QAAQ;IACzB,YAAY,EAAE,QAAQ;IACtB,aAAa,EAAE,QAAQ;IACvB,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,kCAAkC,GAE3C;IACF,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,QAAQ;IACrB,4EAA4E;IAC5E,iEAAiE;IACjE,SAAS,EAAE,UAAU;IACrB,KAAK,EAAE,OAAO;IACd,eAAe,EAAE,OAAO;IACxB,eAAe,EAAE,OAAO;IACxB,SAAS,EAAE,OAAO;IAClB,SAAS,EAAE,OAAO;IAClB,KAAK,EAAE,OAAO;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,iCAAiC,GAE1C;IACF,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,QAAQ;IACrB,SAAS,EAAE,UAAU;IACrB,UAAU,EAAE,QAAQ;IACpB,WAAW,EAAE,QAAQ;CACtB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAEjC;IACF,KAAK,EAAE,sBAAsB;IAC7B,eAAe,EAAE,gCAAgC;IACjD,eAAe,EAAE,gCAAgC;IACjD,SAAS,EAAE,0BAA0B;IACrC,SAAS,EAAE,0BAA0B;IACrC,KAAK,EAAE,sBAAsB;CAC9B,CAAC;AAcF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,MAAM,aAAa,GACjB,IAAI,CAAC,IAAI,KAAK,OAAO;QACnB,CAAC,CAAC,iCAAiC;QACnC,CAAC,CAAC,kCAAkC,CAAC;IACzC,MAAM,MAAM,GAAG,IAA0C,CAAC;IAE1D,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,MAAM,MAAM,GAA4C,EAAE,CAAC;IAE3D,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,QAAQ,UAAU,EAAE,CAAC;YACnB,KAAK,QAAQ;gBACX,IAAI,KAAK,KAAK,SAAS;oBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAC9C,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CACxB,wBAAwB,CAAC,GAAG,CAAE,EAC9B,KAAgC,CACjC,CAAC;gBACJ,CAAC;gBACD,MAAM;YACR,KAAK,QAAQ,CAAC;YACd,KAAK,UAAU;gBACb,MAAM;YACR;gBACE,MAAM,IAAI,KAAK,CACb,wCAAwC,UAAoB,2BAA2B,GAAG,GAAG,CAC9F,CAAC;QACN,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED,4EAA4E;AAC5E,SAAS,YAAY,CACnB,QAAmD,EACnD,UAAmC;IAEnC,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC,KAAK,SAAS,EAAE,CAAC;YAC/D,GAAG,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/confluent/tools/handlers/diagnostics/explain-disabled-tools-handler.d.ts

@@ -1,55 +1,32 @@
 import { CallToolResult } from "../../../../confluent/schema.js";
-import { BaseToolHandler, ToolCategory, ToolConfig, ToolHandler } from "../../../../confluent/tools/base-tools.js";
-import { ToolName } from "../../../../confluent/tools/tool-name.js";
+import { ToolCategory, ToolConfig } from "../../../../confluent/tools/base-tools.js";
+import { ToolMetadataHandler } from "../../../../confluent/tools/tool-metadata-handler.js";
 import { ServerRuntime } from "../../../../server-runtime.js";
 /**
- * Diagnostic tool that surfaces *why* tools are absent from `tools/list`.
+ * Diagnostic tool that surfaces *why* tools are absent from `tools/list` or
+ * unavailable on a given connection.
  *
- * The MCP protocol already advertises the enabled tool set via `tools/list`;
- * what it does not surface is the predicate-driven decision behind every
- * absence — which config piece is missing, and which tools each gap would
- * unlock. This handler returns that view.
+ * `tools/list` advertises the enabled tool set but not the predicate-driven
+ * decision behind every absence. This handler returns that view, shaped around
+ * connections: one section per configured connection listing the tools
+ * disabled on it (bucketed by the missing config piece, or by functional area
+ * under `group_by="category"`). A tool enabled on one connection and disabled
+ * on another shows up in the latter's section, so the cross-connection
+ * asymmetry is readable by comparing sections. A zero-connection config
+ * collapses to a dedicated summary; a single-connection config is simply one
+ * section. Connection-independent tools are advertised everywhere and never
+ * appear in a section.
  *
- * v1 scope (today's release): the server enforces a single configured
- * connection (see `enforceSingleConnectionOnly()` in
- * `src/config/models.ts`), so the output is a flat list of disabled tools
- * grouped by the missing config piece (kafka block, flink block, schema
- * registry block, …). Tools enabled on the active connection are
- * intentionally absent — `tools/list` already advertises them.
- *
- * v2 plan (when multi-connection support lands — issue #151's follow-ups):
- * regrow output around connections. The text body becomes one block per
- * connection (header + per-connection gaps) plus a `Cross-connection
- * deltas` section that surfaces tools enabled on some connections but not
- * others — the canonical "what does connection B need to reach parity with
- * connection A?" view. The structured `_meta` shape mirrors that change;
- * see the {@linkcode ToolGatingReport} JSDoc in `tool-availability.ts` for
- * the exact target type.
- *
- * Until v2 lands, the helper accepts a multi-connection runtime without
- * crashing, but the v1 flatten is *lossy*: a tool whose predicate is
- * enabled on at least one configured connection is reported as enabled
- * (and therefore omitted from `disabledGroups` entirely), and a tool
- * disabled on multiple connections with different reasons is bucketed
- * under the first disabled verdict its iteration produces — the
- * cross-connection asymmetry vanishes from the output. Today's
- * single-connection invariant means neither lossy case can fire in
- * production; this paragraph exists so a future reader does not mistake
- * defensive iteration for parity reporting.
+ * The structured `_meta` mirrors the rendered text; see the
+ * {@linkcode ToolGatingReport} JSDoc in `tool-availability.ts`.
  *
  * Always enabled (predicate is `alwaysEnabled`) so an operator can call it
  * to diagnose a config that left every other tool disabled.
  *
- * The handlers iterable is supplied at construction time via a thunk so
- * this module does not need to import `ToolHandlerRegistry`. Importing the
- * registry from a registered handler would create an ESM cycle, leaving
- * the registry's static initializer running before this class's binding
- * is set. The thunk is invoked at request time, after every module is
- * fully loaded, sidestepping the cycle entirely.
+ * The tool catalog is supplied through the thunk that {@link
+ * ToolMetadataHandler} owns, for the ESM-cycle reason documented there.
  */
-export declare class ExplainDisabledToolsHandler extends BaseToolHandler {
-    private readonly listHandlers;
-    constructor(listHandlers: () => Iterable<readonly [ToolName, ToolHandler]>);
+export declare class ExplainDisabledToolsHandler extends ToolMetadataHandler {
     handle(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined): CallToolResult;
     getToolConfig(): ToolConfig;
     readonly category = ToolCategory.McpServerDiagnostics;

package/dist/confluent/tools/handlers/diagnostics/explain-disabled-tools-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain-disabled-tools-handler.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/diagnostics/explain-disabled-tools-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,eAAe,EAEf,YAAY,EACZ,UAAU,EACV,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAQ5C,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAYvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,2BAA4B,SAAQ,eAAe;IAC9D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAE3B;gBAEU,YAAY,EAAE,MAAM,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAK1E,MAAM,CACJ,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACjD,cAAc;IAYjB,aAAa,IAAI,UAAU;IAU3B,QAAQ,CAAC,QAAQ,qCAAqC;IACtD,QAAQ,CAAC,SAAS,8EAAiB;CACpC"}
+{"version":3,"file":"explain-disabled-tools-handler.d.ts","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/diagnostics/explain-disabled-tools-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAEL,YAAY,EACZ,UAAU,EACX,MAAM,oCAAoC,CAAC;AAY5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AAEpF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAYvD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,2BAA4B,SAAQ,mBAAmB;IAClE,MAAM,CACJ,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACjD,cAAc;IAYjB,aAAa,IAAI,UAAU;IAU3B,QAAQ,CAAC,QAAQ,qCAAqC;IACtD,QAAQ,CAAC,SAAS,8EAAiB;CACpC"}