@confluentinc/mcp-confluent 1.3.0 → 1.5.0

package/dist/confluent/tools/handlers/diagnostics/config-help-handler.js

@@ -0,0 +1,297 @@
+import { READ_ONLY, ToolCategory, } from "../../../../confluent/tools/base-tools.js";
+import { alwaysEnabled, ToolDisabledReason, } from "../../../../confluent/tools/connection-predicates.js";
+import { ToolMetadataHandler } from "../../../../confluent/tools/tool-metadata-handler.js";
+import { ToolName } from "../../../../confluent/tools/tool-name.js";
+import { z } from "zod";
+const configHelpArguments = z.object({
+    tool: z
+        .string()
+        .trim()
+        .min(1, "tool cannot be empty")
+        .describe("The tool name exactly as it appears in tools/list (e.g. 'list-tableflow-topics', 'create-flink-statement') that you want to enable. config-help inspects every configured connection, finds the config gap each one is missing for this tool, and returns the YAML block to add to unlock it."),
+});
+/**
+ * Config-coaching tool: given a tool name, returns the YAML each configured
+ * connection is missing to enable it.
+ *
+ * Where {@link ExplainDisabledToolsHandler} answers "which tools are off and
+ * why?" across the whole catalog, this tool inverts the question — "I want
+ * *this* tool; what do I add to my config?" — and hands back a ready-to-paste
+ * YAML fragment derived from the gap between the connection's current shape and
+ * the tool's predicate requirement.
+ *
+ * The mechanism is the same verdict map every diagnostic surface reads:
+ * {@link BaseToolHandler.connectionVerdicts} turns the target handler's
+ * `predicate` into a per-connection `PredicateResult`; a disabled verdict
+ * carries a {@link ToolDisabledReason}, which {@link adviceForReason} maps to
+ * the YAML that closes that specific gap. The tool only suggests — it never
+ * mutates config, and (per the issue's out-of-scope note) it assumes the
+ * schema in `models.ts` keeps the suggested YAML valid rather than re-parsing
+ * it.
+ *
+ * Always enabled (predicate = `alwaysEnabled`): an operator must be able to ask
+ * how to fix a config that left the tool they want disabled.
+ *
+ * The tool catalog is supplied through the thunk that {@link
+ * ToolMetadataHandler} owns, for the ESM-cycle reason documented there.
+ */
+export class ConfigHelpHandler extends ToolMetadataHandler {
+    handle(runtime, toolArguments) {
+        const { tool } = configHelpArguments.parse(toolArguments ?? {});
+        const handler = this.findHandler(tool);
+        if (handler === undefined) {
+            return this.createResponse(`Unknown tool "${tool}". Pass a tool name exactly as it appears in tools/list (e.g. "list-tableflow-topics"). Call list-configured-connections or explain-disabled-tools to discover tool names.`, true);
+        }
+        const verdicts = handler.connectionVerdicts(runtime);
+        const connections = {};
+        let alreadyEnabled = false;
+        for (const [connId, verdict] of verdicts) {
+            if (verdict.enabled) {
+                alreadyEnabled = true;
+                connections[connId] = { enabled: true };
+                continue;
+            }
+            const advice = adviceForReason(verdict.reason, connId);
+            connections[connId] = {
+                enabled: false,
+                currentState: verdict.reason,
+                ...advice,
+            };
+        }
+        const payload = {
+            tool,
+            alreadyEnabled,
+            connections,
+        };
+        return this.createStructuredResponse(renderAdvice(payload), { ...payload });
+    }
+    getToolConfig() {
+        return {
+            name: ToolName.CONFIG_HELP,
+            description: 'Call when the user wants to enable or unlock a specific tool (e.g. "how do I enable the tableflow tools?", "what config does create-flink-statement need?", "why isn\'t list-topics showing up — fix it"). Given a tool name, returns a copy-pasteable YAML snippet, per connection, that closes the gap between the current config and what that tool requires. Suggests only — it never edits your config file. Prefer explain-disabled-tools when the question is "what\'s off and why?" across all tools; prefer this when the user has a target tool in mind and wants the exact YAML to add.',
+            inputSchema: configHelpArguments.shape,
+            annotations: READ_ONLY,
+        };
+    }
+    /**
+     * Resolve a tool name (the `tools/list` string, i.e. a {@link ToolName}
+     * enum *value*) to its handler. Linear scan over the catalog; the catalog is
+     * small and this runs once per invocation.
+     */
+    findHandler(tool) {
+        for (const [name, handler] of this.getToolNamesAndHandlers()) {
+            if (name === tool)
+                return handler;
+        }
+        return undefined;
+    }
+    category = ToolCategory.McpServerDiagnostics;
+    predicate = alwaysEnabled;
+}
+/** Body of an `auth` block (api_key flavor) at the given indentation. */
+function apiKeyAuth(indent, keyVar, secretVar) {
+    return [
+        `${indent}auth:`,
+        `${indent}  type: api_key`,
+        `${indent}  key: "\${${keyVar}}"`,
+        `${indent}  secret: "\${${secretVar}}"`,
+    ].join("\n");
+}
+/**
+ * Render a connection id as a YAML mapping key. Connection ids are only
+ * constrained to non-empty trimmed strings (`mcpConfigSchema`), so an id
+ * containing `:`, spaces, or other YAML-significant characters would produce an
+ * invalid key if emitted bare. Plain ids (e.g. `default`) stay unquoted to keep
+ * the snippet readable; anything else is double-quoted with embedded quotes and
+ * backslashes escaped.
+ */
+function yamlKey(connId) {
+    if (/^[A-Za-z0-9_-]+$/.test(connId))
+        return connId;
+    // A YAML double-quoted scalar accepts the same C-style escapes JSON uses
+    // (\\, \", \n, \t, \uXXXX), so JSON.stringify produces a valid quoted key.
+    return JSON.stringify(connId);
+}
+/**
+ * Wrap a connection-scoped block body in the `connections.<connId>` envelope so
+ * the snippet can be pasted at the top level of a config YAML file. `blockBody`
+ * lines are expected to start at four-space indentation (one level under
+ * `  <connId>:`).
+ */
+function wrap(connId, blockBody) {
+    return `connections:\n  ${yamlKey(connId)}:\n${blockBody}`;
+}
+/**
+ * Map a {@link ToolDisabledReason} to the config change that resolves it. A
+ * block- or field-shaped gap maps to a paste-ready YAML snippet mirroring
+ * `config.example.yaml`. The non-block reasons carry a `note` instead:
+ *   - OAuth reasons — OAuth connections have no service blocks; the fix is a
+ *     different connection type, not a block to add.
+ *   - {@link ToolDisabledReason.ReadOnlyConnection} — the service is reachable;
+ *     `read_only` is what blocks a mutating tool, so the fix is removing
+ *     `read_only: true`.
+ *   - {@link ToolDisabledReason.NoConnectionsConfigured} and
+ *     {@link ToolDisabledReason.OperatorBlocked} — emitted by
+ *     `buildToolGatingReport`, not the per-connection verdict map this handler
+ *     walks, so they can't reach here; they get a `note` only to keep the
+ *     switch exhaustive.
+ *
+ * Exhaustive over `ToolDisabledReason`: every arm returns, and the `default`
+ * arm pins `reason` to `never`, so a new reason added to the enum fails
+ * `tsc --noEmit` here until it gets a case. The `default` also throws at
+ * runtime as a belt-and-suspenders guard against an unmapped reason reaching
+ * the spread in `handle()`.
+ */
+function adviceForReason(reason, connId) {
+    switch (reason) {
+        case ToolDisabledReason.MissingKafkaBlock:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    kafka:`,
+                    `      bootstrap_servers: "\${BOOTSTRAP_SERVERS}"`,
+                    apiKeyAuth("      ", "KAFKA_API_KEY", "KAFKA_API_SECRET"),
+                ].join("\n")),
+            };
+        case ToolDisabledReason.MissingKafkaBootstrap:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    kafka:`,
+                    `      bootstrap_servers: "\${BOOTSTRAP_SERVERS}"`,
+                ].join("\n")),
+            };
+        case ToolDisabledReason.MissingKafkaAuth:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    kafka:`,
+                    apiKeyAuth("      ", "KAFKA_API_KEY", "KAFKA_API_SECRET"),
+                ].join("\n")),
+            };
+        case ToolDisabledReason.MissingKafkaRestEndpoint:
+            return {
+                suggestedYaml: wrap(connId, [`    kafka:`, `      rest_endpoint: "\${KAFKA_REST_ENDPOINT}"`].join("\n")),
+            };
+        case ToolDisabledReason.MissingSchemaRegistryBlock:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    schema_registry:`,
+                    `      endpoint: "\${SCHEMA_REGISTRY_ENDPOINT}"`,
+                    apiKeyAuth("      ", "SCHEMA_REGISTRY_API_KEY", "SCHEMA_REGISTRY_API_SECRET"),
+                ].join("\n")),
+            };
+        case ToolDisabledReason.MissingSchemaRegistryApiKeyAuth:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    schema_registry:`,
+                    apiKeyAuth("      ", "SCHEMA_REGISTRY_API_KEY", "SCHEMA_REGISTRY_API_SECRET"),
+                ].join("\n")),
+            };
+        case ToolDisabledReason.MissingConfluentCloudBlock:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    confluent_cloud:`,
+                    apiKeyAuth("      ", "CONFLUENT_CLOUD_API_KEY", "CONFLUENT_CLOUD_API_SECRET"),
+                ].join("\n")),
+            };
+        case ToolDisabledReason.MissingFlinkBlock:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    flink:`,
+                    `      endpoint: "\${FLINK_REST_ENDPOINT}"`,
+                    apiKeyAuth("      ", "FLINK_API_KEY", "FLINK_API_SECRET"),
+                    `      organization_id: "\${FLINK_ORG_ID}"`,
+                    `      environment_id: "\${FLINK_ENV_ID}"`,
+                    `      compute_pool_id: "\${FLINK_COMPUTE_POOL_ID}"`,
+                ].join("\n")),
+            };
+        case ToolDisabledReason.MissingTelemetryBlock:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    telemetry:`,
+                    apiKeyAuth("      ", "TELEMETRY_API_KEY", "TELEMETRY_API_SECRET"),
+                ].join("\n")),
+            };
+        case ToolDisabledReason.MissingTableflowBlock:
+            return {
+                suggestedYaml: wrap(connId, [
+                    `    tableflow:`,
+                    apiKeyAuth("      ", "TABLEFLOW_API_KEY", "TABLEFLOW_API_SECRET"),
+                ].join("\n")),
+            };
+        case ToolDisabledReason.OAuthNoServiceBlocks:
+            return {
+                note: `Connection "${connId}" is an OAuth connection, which carries no service blocks. This tool reads a service block that OAuth cannot provide, so it is not reachable on an OAuth connection — add a direct (api_key) connection with the required block instead.`,
+            };
+        case ToolDisabledReason.OAuthNotDirectCapable:
+            return {
+                note: `Connection "${connId}" is an OAuth connection. This tool requires a direct (api_key) connection and cannot run against OAuth — switch to a direct connection carrying the required block.`,
+            };
+        case ToolDisabledReason.ReadOnlyConnection:
+            return {
+                note: `Connection "${connId}" reaches this tool's service but is marked read_only, which blocks state-mutating tools. Remove "read_only: true" to enable it.`,
+            };
+        case ToolDisabledReason.NoConnectionsConfigured:
+            return {
+                note: `No connections are configured, so there is nothing to enable this tool against. Add a connection to your config first.`,
+            };
+        case ToolDisabledReason.OperatorBlocked:
+            return {
+                note: `This tool is excluded by the operator's allow/block-list, which is set at server launch rather than in connection config. Ask whoever runs the MCP server to adjust the tool allow/block-list.`,
+            };
+        default: {
+            const exhaustive = reason;
+            throw new Error(`Unmapped ToolDisabledReason: ${String(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Human-readable rendering of the advice payload. The structured payload is
+ * authoritative; this text is the at-a-glance view. Handler tests pin the
+ * already-enabled and per-connection headers so the format stays stable.
+ */
+function renderAdvice(payload) {
+    const { tool, connections } = payload;
+    const entries = Object.entries(connections);
+    if (entries.length === 0) {
+        return `No connections are configured, so there is nothing to enable "${tool}" against. Add a connection to your config first.`;
+    }
+    const enabledIds = entries
+        .filter(([, advice]) => advice.enabled)
+        .map(([id]) => id)
+        .sort((a, b) => a.localeCompare(b));
+    const disabledEntries = entries.filter(([, advice]) => !advice.enabled);
+    // Fully enabled: every connection already runs the tool, so there's
+    // genuinely nothing to change.
+    if (disabledEntries.length === 0) {
+        return `Tool "${tool}" is already enabled on connection(s): ${enabledIds.join(", ")}. No config change needed.`;
+    }
+    const blocks = disabledEntries.map(([connId, advice]) => {
+        const header = `  connection "${connId}" — ${advice.currentState ?? "disabled"}`;
+        if (advice.suggestedYaml !== undefined) {
+            // Indent the YAML two spaces so it reads as a nested block under the
+            // connection header rather than as top-level config.
+            const indented = advice.suggestedYaml
+                .split("\n")
+                .map((line) => (line.length > 0 ? `    ${line}` : line))
+                .join("\n");
+            return `${header}\n  Add to your config YAML:\n\n${indented}`;
+        }
+        return `${header}\n  ${advice.note ?? ""}`;
+    });
+    // Partially enabled: enabled on some connections but still missing config on
+    // others. Don't claim "no config change needed" — name the enabled ones, then
+    // give the YAML for the connections that still need it.
+    if (enabledIds.length > 0) {
+        return [
+            `Tool "${tool}" is already enabled on connection(s): ${enabledIds.join(", ")}, but still disabled on ${disabledEntries.length} other connection(s). To enable it there too:`,
+            "",
+            blocks.join("\n\n"),
+        ].join("\n");
+    }
+    // Disabled everywhere.
+    return [
+        `Tool "${tool}" is disabled on all ${entries.length} configured connection(s). To enable it:`,
+        "",
+        blocks.join("\n\n"),
+    ].join("\n");
+}
+//# sourceMappingURL=config-help-handler.js.map

package/dist/confluent/tools/handlers/diagnostics/config-help-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-help-handler.js","sourceRoot":"","sources":["../../../../../src/confluent/tools/handlers/diagnostics/config-help-handler.ts"],"names":[],"mappings":"AACA,OAAO,EACL,SAAS,EACT,YAAY,GAGb,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAE7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,EAAE,sBAAsB,CAAC;SAC9B,QAAQ,CACP,+RAA+R,CAChS;CACJ,CAAC,CAAC;AAyBH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,iBAAkB,SAAQ,mBAAmB;IACxD,MAAM,CACJ,OAAsB,EACtB,aAAuC;QAEvC,MAAM,EAAE,IAAI,EAAE,GAAG,mBAAmB,CAAC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;QAEhE,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,cAAc,CACxB,iBAAiB,IAAI,4KAA4K,EACjM,IAAI,CACL,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,WAAW,GAAqC,EAAE,CAAC;QACzD,IAAI,cAAc,GAAG,KAAK,CAAC;QAC3B,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACpB,cAAc,GAAG,IAAI,CAAC;gBACtB,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;gBACxC,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACvD,WAAW,CAAC,MAAM,CAAC,GAAG;gBACpB,OAAO,EAAE,KAAK;gBACd,YAAY,EAAE,OAAO,CAAC,MAAM;gBAC5B,GAAG,MAAM;aACV,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAsB;YACjC,IAAI;YACJ,cAAc;YACd,WAAW;SACZ,CAAC;QACF,OAAO,IAAI,CAAC,wBAAwB,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,aAAa;QACX,OAAO;YACL,IAAI,EAAE,QAAQ,CAAC,WAAW;YAC1B,WAAW,EACT,okBAAokB;YACtkB,WAAW,EAAE,mBAAmB,CAAC,KAAK;YACtC,WAAW,EAAE,SAAS;SACvB,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,WAAW,CAAC,IAAY;QAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,uBAAuB,EAAE,EAAE,CAAC;YAC7D,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,OAAO,CAAC;QACpC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAEQ,QAAQ,GAAG,YAAY,CAAC,oBAAoB,CAAC;IAC7C,SAAS,GAAG,aAAa,CAAC;CACpC;AAED,yEAAyE;AACzE,SAAS,UAAU,CAAC,MAAc,EAAE,MAAc,EAAE,SAAiB;IACnE,OAAO;QACL,GAAG,MAAM,OAAO;QAChB,GAAG,MAAM,iBAAiB;QAC1B,GAAG,MAAM,cAAc,MAAM,IAAI;QACjC,GAAG,MAAM,iBAAiB,SAAS,IAAI;KACxC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,OAAO,CAAC,MAAc;IAC7B,IAAI,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACnD,yEAAyE;IACzE,2EAA2E;IAC3E,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,SAAS,IAAI,CAAC,MAAc,EAAE,SAAiB;IAC7C,OAAO,mBAAmB,OAAO,CAAC,MAAM,CAAC,MAAM,SAAS,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,eAAe,CACtB,MAA0B,EAC1B,MAAc;IAEd,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,kBAAkB,CAAC,iBAAiB;YACvC,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,YAAY;oBACZ,kDAAkD;oBAClD,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,kBAAkB,CAAC;iBAC1D,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,qBAAqB;YAC3C,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,YAAY;oBACZ,kDAAkD;iBACnD,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,gBAAgB;YACtC,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,YAAY;oBACZ,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,kBAAkB,CAAC;iBAC1D,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,wBAAwB;YAC9C,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN,CAAC,YAAY,EAAE,gDAAgD,CAAC,CAAC,IAAI,CACnE,IAAI,CACL,CACF;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,0BAA0B;YAChD,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,sBAAsB;oBACtB,gDAAgD;oBAChD,UAAU,CACR,QAAQ,EACR,yBAAyB,EACzB,4BAA4B,CAC7B;iBACF,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,+BAA+B;YACrD,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,sBAAsB;oBACtB,UAAU,CACR,QAAQ,EACR,yBAAyB,EACzB,4BAA4B,CAC7B;iBACF,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,0BAA0B;YAChD,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,sBAAsB;oBACtB,UAAU,CACR,QAAQ,EACR,yBAAyB,EACzB,4BAA4B,CAC7B;iBACF,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,iBAAiB;YACvC,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,YAAY;oBACZ,2CAA2C;oBAC3C,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,kBAAkB,CAAC;oBACzD,2CAA2C;oBAC3C,0CAA0C;oBAC1C,oDAAoD;iBACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,qBAAqB;YAC3C,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,gBAAgB;oBAChB,UAAU,CAAC,QAAQ,EAAE,mBAAmB,EAAE,sBAAsB,CAAC;iBAClE,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,qBAAqB;YAC3C,OAAO;gBACL,aAAa,EAAE,IAAI,CACjB,MAAM,EACN;oBACE,gBAAgB;oBAChB,UAAU,CAAC,QAAQ,EAAE,mBAAmB,EAAE,sBAAsB,CAAC;iBAClE,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACF,CAAC;QACJ,KAAK,kBAAkB,CAAC,oBAAoB;YAC1C,OAAO;gBACL,IAAI,EAAE,eAAe,MAAM,0OAA0O;aACtQ,CAAC;QACJ,KAAK,kBAAkB,CAAC,qBAAqB;YAC3C,OAAO;gBACL,IAAI,EAAE,eAAe,MAAM,sKAAsK;aAClM,CAAC;QACJ,KAAK,kBAAkB,CAAC,kBAAkB;YACxC,OAAO;gBACL,IAAI,EAAE,eAAe,MAAM,kIAAkI;aAC9J,CAAC;QACJ,KAAK,kBAAkB,CAAC,uBAAuB;YAC7C,OAAO;gBACL,IAAI,EAAE,wHAAwH;aAC/H,CAAC;QACJ,KAAK,kBAAkB,CAAC,eAAe;YACrC,OAAO;gBACL,IAAI,EAAE,gMAAgM;aACvM,CAAC;QACJ,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,UAAU,GAAU,MAAM,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,gCAAgC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,OAA0B;IAC9C,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAE5C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,iEAAiE,IAAI,mDAAmD,CAAC;IAClI,CAAC;IAED,MAAM,UAAU,GAAG,OAAO;SACvB,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;SACjB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAExE,oEAAoE;IACpE,+BAA+B;IAC/B,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,SAAS,IAAI,0CAA0C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B,CAAC;IAClH,CAAC;IAED,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE;QACtD,MAAM,MAAM,GAAG,iBAAiB,MAAM,OAAO,MAAM,CAAC,YAAY,IAAI,UAAU,EAAE,CAAC;QACjF,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACvC,qEAAqE;YACrE,qDAAqD;YACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,aAAa;iBAClC,KAAK,CAAC,IAAI,CAAC;iBACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;iBACvD,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,OAAO,GAAG,MAAM,mCAAmC,QAAQ,EAAE,CAAC;QAChE,CAAC;QACD,OAAO,GAAG,MAAM,OAAO,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAC7E,8EAA8E;IAC9E,wDAAwD;IACxD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,SAAS,IAAI,0CAA0C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,eAAe,CAAC,MAAM,+CAA+C;YAC5K,EAAE;YACF,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SACpB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,uBAAuB;IACvB,OAAO;QACL,SAAS,IAAI,wBAAwB,OAAO,CAAC,MAAM,0CAA0C;QAC7F,EAAE;QACF,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;KACpB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

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