@confluentinc/mcp-confluent 1.2.2 → 1.4.0

package/dist/confluent/oauth-resource-resolvers.js

@@ -0,0 +1,65 @@
+export async function resolveKafkaBootstrap(cloudClient, clusterId, envId) {
+    const { data, error } = await cloudClient.GET("/cmk/v2/clusters/{id}", {
+        params: { path: { id: clusterId }, query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to read Kafka cluster ${clusterId} in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const bootstrap = data?.spec?.kafka_bootstrap_endpoint;
+    if (typeof bootstrap !== "string" || bootstrap.length === 0) {
+        throw new Error(`Cluster ${clusterId} in environment ${envId} has no kafka_bootstrap_endpoint`);
+    }
+    return bootstrap;
+}
+export async function resolveKafkaRestEndpoint(cloudClient, clusterId, envId) {
+    const { data, error } = await cloudClient.GET("/cmk/v2/clusters/{id}", {
+        params: { path: { id: clusterId }, query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to read Kafka cluster ${clusterId} in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const httpEndpoint = data?.spec?.http_endpoint;
+    if (typeof httpEndpoint !== "string" || httpEndpoint.length === 0) {
+        throw new Error(`Cluster ${clusterId} in environment ${envId} has no http_endpoint`);
+    }
+    return httpEndpoint;
+}
+export async function resolveSchemaRegistryEndpoint(cloudClient, clusterId, envId) {
+    const { data, error } = await cloudClient.GET("/srcm/v3/clusters/{id}", {
+        params: { path: { id: clusterId }, query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to read Schema Registry cluster ${clusterId} in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const httpEndpoint = data?.spec?.http_endpoint;
+    if (typeof httpEndpoint !== "string" || httpEndpoint.length === 0) {
+        throw new Error(`Schema Registry cluster ${clusterId} in environment ${envId} has no http_endpoint`);
+    }
+    return httpEndpoint;
+}
+export async function resolveSchemaRegistryClusterId(cloudClient, envId) {
+    const { data, error } = await cloudClient.GET("/srcm/v3/clusters", {
+        params: { query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to list Schema Registry clusters in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const clusters = data?.data ?? [];
+    if (clusters.length === 0) {
+        throw new Error(`No Schema Registry cluster found in environment ${envId}. ` +
+            `Schema Registry must be enabled on the environment in Confluent Cloud.`);
+    }
+    if (clusters.length > 1) {
+        // Defensive: CCloud's documented invariant is one SR per environment.
+        // If that ever changes, callers will need to pick a specific cluster
+        // rather than have us silently take the first.
+        throw new Error(`Multiple Schema Registry clusters found in environment ${envId} (count: ${clusters.length}). ` +
+            `Single SR per environment is assumed; multi-SR is not supported.`);
+    }
+    const id = clusters[0]?.id;
+    if (typeof id !== "string" || id.length === 0) {
+        throw new Error(`Schema Registry cluster in environment ${envId} has no id`);
+    }
+    return id;
+}
+//# sourceMappingURL=oauth-resource-resolvers.js.map

package/dist/confluent/oauth-resource-resolvers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-resource-resolvers.js","sourceRoot":"","sources":["../../src/confluent/oauth-resource-resolvers.ts"],"names":[],"mappings":"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"}

package/dist/confluent/schema-registry-helper.d.ts

@@ -36,17 +36,13 @@ export type MessageOptions = {
 };
 /**
  * Result of checking if a schema is needed for a message.
- * Can indicate:
- * - A schema is needed and provides the latest schema details
- * - No schema exists and needs to be provided
- * - No schema action is needed
+ * Returned only when schema registry is in use, the caller did not supply a
+ * schema, and no schema is registered for the subject yet — that's the one
+ * case the caller must resolve before serialization can proceed. Otherwise
+ * null: schema registry is disabled, or the caller supplied a schema
+ * (register-and-use path), or one is already registered (use-latest path).
  */
 export type SchemaCheckResult = {
-    type: "schema-needed";
-    latestSchema: string;
-    subject: string;
-    schemaType: string;
-} | {
     type: "no-schema";
     subject: string;
 } | null;

package/dist/confluent/schema-registry-helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-registry-helper.d.ts","sourceRoot":"","sources":["../../src/confluent/schema-registry-helper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAGL,YAAY,EAMZ,oBAAoB,EACpB,SAAS,EACT,UAAU,EAEX,MAAM,8BAA8B,CAAC;AAGtC;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC,IAAI,CAAC;AAET;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,CAkBZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,GACnB,YAAY,CAed;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GACzC,OAAO,CAAC,iBAAiB,CAAC,CAoB5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GAAG,IAAI,CAAC,CAiB5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GACzC,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAgE1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,OAAO,CAAC,CAOlB"}
+{"version":3,"file":"schema-registry-helper.d.ts","sourceRoot":"","sources":["../../src/confluent/schema-registry-helper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAGL,YAAY,EAMZ,oBAAoB,EACpB,SAAS,EACT,UAAU,EAEX,MAAM,8BAA8B,CAAC;AAGtC;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,CAkBZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,GACnB,YAAY,CAed;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GACzC,OAAO,CAAC,iBAAiB,CAAC,CAa5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GAAG,IAAI,CAAC,CAiB5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GACzC,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAgE1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,OAAO,CAAC,CAOlB"}

package/dist/confluent/schema-registry-helper.js

@@ -72,15 +72,7 @@ export async function checkSchemaNeeded(topicName, options, serdeType, registry)
         const latest = registry
             ? await getLatestSchemaIfExists(registry, subject)
             : null;
-        if (latest) {
-            return {
-                type: "schema-needed",
-                latestSchema: latest.schema,
-                subject,
-                schemaType: latest.schemaType,
-            };
-        }
-        else {
+        if (!latest) {
             return { type: "no-schema", subject };
         }
     }

package/dist/confluent/schema-registry-helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema-registry-helper.js","sourceRoot":"","sources":["../../src/confluent/schema-registry-helper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema-registry-helper.js","sourceRoot":"","sources":["../../src/confluent/schema-registry-helper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,gBAAgB,EAChB,cAAc,EAGd,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAElB,SAAS,GAGV,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AA6CxC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAkC,EAClC,QAA8B,EAC9B,SAAoB,EACpB,QAAiB;IAEjB,MAAM,gBAAgB,GACpB,OAAO,QAAQ,KAAK,QAAQ;QAC1B,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE;QAC3B,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;IAEjC,MAAM,WAAW,GAAG;QAClB,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,gBAAgB,CAAC;QACrE,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,gBAAgB,CAAC;QACrE,QAAQ,EAAE,GAAG,EAAE,CACb,IAAI,kBAAkB,CAAC,QAAQ,EAAE,SAAS,EAAE,gBAAgB,CAAC;KAChE,CAAC;IAEF,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,IAAI,WAAW,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,uBAAuB,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAkC,EAClC,QAA8B,EAC9B,SAAoB;IAEpB,MAAM,kBAAkB,GAAuB,EAAE,CAAC;IAElD,MAAM,aAAa,GAAG;QACpB,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,gBAAgB,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC;QACzE,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,gBAAgB,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC;QACzE,QAAQ,EAAE,GAAG,EAAE,CACb,IAAI,oBAAoB,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC;KACpE,CAAC;IAEF,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,IAAI,aAAa,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,uBAAuB,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAiB,EACjB,OAAuB,EACvB,SAAoB,EACpB,QAA0C;IAE1C,IAAI,OAAO,CAAC,iBAAiB,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACjD,MAAM,OAAO,GACX,OAAO,CAAC,OAAO;YACf,GAAG,SAAS,IAAI,SAAS,KAAK,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAClE,MAAM,MAAM,GAAG,QAAQ;YACrB,CAAC,CAAC,MAAM,uBAAuB,CAAC,QAAQ,EAAE,OAAO,CAAC;YAClD,CAAC,CAAC,IAAI,CAAC;QACT,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,QAA8B,EAC9B,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC;QAC/D,4EAA4E;QAC5E,MAAM,UAAU,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAe,CAAC;QAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAO,EAAE,UAAU,EAAE,CAAC;IAChD,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IACE,GAAG;YACH,OAAO,GAAG,KAAK,QAAQ;YACvB,QAAQ,IAAI,GAAG;YACd,GAA2B,CAAC,MAAM,KAAK,GAAG,EAC3C,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAiB,EACjB,OAAuB,EACvB,SAAoB,EACpB,QAA0C;IAE1C,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;QAC/B,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACxC,MAAM,CAAC,IAAI,CACT,2GAA2G,CAC5G,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;YACxC,CAAC,CAAC,OAAO,CAAC,OAAO;YACjB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IACD,yBAAyB;IACzB,MAAM,OAAO,GACX,OAAO,CAAC,OAAO;QACf,GAAG,SAAS,IAAI,SAAS,KAAK,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAElE,IAAI,QAA4B,CAAC;IACjC,8BAA8B;IAC9B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAChC,OAAO,EACP;gBACE,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,UAAU,EAAE,OAAO,CAAC,UAAU;aAC/B,EACD,OAAO,CAAC,SAAS,CAClB,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,0CAA0C,OAAO,MAAM,GAAG,EAAE,CAC7D,CAAC;QACJ,CAAC;IACH,CAAC;IACD,wBAAwB;IACxB,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CACb,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IACD,IAAI,UAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,UAAU,GAAG,aAAa,CACxB,OAAO,CAAC,UAAU,EAClB,QAAQ,EACR,SAAS,EACT,QAAQ,CACT,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,UAAU,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,4CAA4C,OAAO,MAAM,GAAG,EAAE,CAC/D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAa,EACb,OAAe,EACf,UAAsB,EACtB,QAA8B,EAC9B,SAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,eAAe,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;QACtE,OAAO,MAAM,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,EAAE,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC"}

package/dist/confluent/telemetry.d.ts

@@ -1,5 +1,34 @@
 export declare enum TelemetryEvent {
-    TOOL_CALL = "Tool Call"
+    /**
+     * Emitted once after successful startup so we can count boots independently
+     * of tool calls.
+     */
+    SERVER_START = "Server Start",
+    /**
+     * Emitted once for every tool call for telemetry on tool usage.
+     */
+    TOOL_CALL = "Tool Call",
+    /**
+     * Emitted once per terminal OAuth PKCE login attempt (success or failure).
+     * Refresh-token rotations are not tracked here.
+     */
+    CCLOUD_AUTHENTICATION = "CCloud Authentication",
+    /**
+     * Emitted when the user clicks "Copy" on the agent-skills install hint shown
+     * on the OAuth success page. Fired by a same-origin beacon from the callback
+     * page to the local callback server.
+     */
+    AGENT_SKILLS_HINT_COPIED = "Agent Skills Hint Copied"
+}
+/**
+ * Inputs to {@link TelemetryService.initialize}. `writeKey` is whatever the
+ * caller resolved (YAML override, build-config injected value, or undefined);
+ * the service treats `undefined`/`""` as "telemetry off" and otherwise hands
+ * the value to the Segment Analytics constructor.
+ */
+export interface TelemetryInitOptions {
+    readonly doNotTrack: boolean;
+    readonly writeKey: string | undefined;
 }
 export declare const FALLBACK_MACHINE_ID = "00000000-0000-0000-0000-000000000000";
 export declare class TelemetryService {
@@ -9,6 +38,14 @@ export declare class TelemetryService {
     private serverSessionId;
     private commonProperties;
     private constructor();
+    /**
+     * Bootstrap-time entry point. The caller (main()) is responsible for
+     * resolving `writeKey` from its sources — typically
+     * `mcpConfig.server.analytics?.write_key ?? buildConfig.TELEMETRY_WRITE_KEY`
+     * — before invoking this. A falsy `writeKey` (`undefined` or `""`) keeps
+     * analytics disabled even when `doNotTrack` is false.
+     */
+    static initialize(opts: TelemetryInitOptions): void;
     static getInstance(): TelemetryService;
     setCommonProperties(properties: Record<string, unknown>): void;
     track(event: TelemetryEvent, properties: Record<string, unknown>): void;

package/dist/confluent/telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/confluent/telemetry.ts"],"names":[],"mappings":"AAWA,oBAAY,cAAc;IACxB,SAAS,cAAc;CACxB;AAED,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAsC1E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA+B;IACtD,OAAO,CAAC,SAAS,CAAuD;IACxE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAA0B;IAElD,OAAO;IAwBP,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAOtC,mBAAmB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI9D,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IASvE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKzD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/confluent/telemetry.ts"],"names":[],"mappings":"AAIA,oBAAY,cAAc;IACxB;;;OAGG;IACH,YAAY,iBAAiB;IAC7B;;OAEG;IACH,SAAS,cAAc;IACvB;;;OAGG;IACH,qBAAqB,0BAA0B;IAC/C;;;;OAIG;IACH,wBAAwB,6BAA6B;CACtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAsC1E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA+B;IACtD,OAAO,CAAC,SAAS,CAAuD;IACxE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAA0B;IAElD,OAAO;IAoBP;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IASnD,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAStC,mBAAmB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI9D,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IASvE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKzD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}

package/dist/confluent/telemetry.js

@@ -1,9 +1,28 @@
-import { buildConfig, config, fs, os, path, segment, } from "../confluent/node-deps.js";
+import { fs, os, path, segment } from "../confluent/node-deps.js";
 import { logger } from "../logger.js";
 import { randomUUID } from "node:crypto";
 export var TelemetryEvent;
 (function (TelemetryEvent) {
+    /**
+     * Emitted once after successful startup so we can count boots independently
+     * of tool calls.
+     */
+    TelemetryEvent["SERVER_START"] = "Server Start";
+    /**
+     * Emitted once for every tool call for telemetry on tool usage.
+     */
     TelemetryEvent["TOOL_CALL"] = "Tool Call";
+    /**
+     * Emitted once per terminal OAuth PKCE login attempt (success or failure).
+     * Refresh-token rotations are not tracked here.
+     */
+    TelemetryEvent["CCLOUD_AUTHENTICATION"] = "CCloud Authentication";
+    /**
+     * Emitted when the user clicks "Copy" on the agent-skills install hint shown
+     * on the OAuth success page. Fired by a same-origin beacon from the callback
+     * page to the local callback server.
+     */
+    TelemetryEvent["AGENT_SKILLS_HINT_COPIED"] = "Agent Skills Hint Copied";
 })(TelemetryEvent || (TelemetryEvent = {}));
 export const FALLBACK_MACHINE_ID = "00000000-0000-0000-0000-000000000000";
 const CONFIG_DIR = ".mcp-confluent";
@@ -47,11 +66,8 @@ export class TelemetryService {
     machineId;
     serverSessionId;
     commonProperties;
-    constructor() {
-        // runtime env var can override the build-time value for local dev/testing
-        const writeKey = process.env.TELEMETRY_WRITE_KEY || buildConfig.TELEMETRY_WRITE_KEY;
-        const disabled = config.env.DO_NOT_TRACK;
-        const enabled = !disabled && !!writeKey;
+    constructor(opts) {
+        const enabled = !opts.doNotTrack && !!opts.writeKey;
         this.machineId = getOrCreateMachineId();
         this.serverSessionId = randomUUID();
         this.commonProperties = {
@@ -61,16 +77,29 @@ export class TelemetryService {
             osArch: os.arch(),
         };
         if (enabled) {
-            this.analytics = new segment.Analytics({ writeKey });
+            this.analytics = new segment.Analytics({ writeKey: opts.writeKey });
             logger.info("Telemetry enabled");
         }
         else {
             logger.info("Telemetry disabled");
         }
     }
+    /**
+     * Bootstrap-time entry point. The caller (main()) is responsible for
+     * resolving `writeKey` from its sources — typically
+     * `mcpConfig.server.analytics?.write_key ?? buildConfig.TELEMETRY_WRITE_KEY`
+     * — before invoking this. A falsy `writeKey` (`undefined` or `""`) keeps
+     * analytics disabled even when `doNotTrack` is false.
+     */
+    static initialize(opts) {
+        if (TelemetryService.instance) {
+            throw new Error("TelemetryService has already been initialized — initialize() must be called exactly once before getInstance()");
+        }
+        TelemetryService.instance = new TelemetryService(opts);
+    }
     static getInstance() {
         if (!TelemetryService.instance) {
-            TelemetryService.instance = new TelemetryService();
+            throw new Error("TelemetryService.initialize() must be called before getInstance()");
         }
         return TelemetryService.instance;
     }

package/dist/confluent/telemetry.js.map

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

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

@@ -1,8 +1,10 @@
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import { ClientManager } from "../../confluent/client-manager.js";
+import type { ConnectionConfig } 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 { EnvVar } from "../../env-schema.js";
+import { ServerRuntime } from "../../server-runtime.js";
 import { ZodRawShape } from "zod";
 /**
  * Standard MCP tool annotations.
@@ -11,24 +13,61 @@ import { ZodRawShape } from "zod";
 export declare const READ_ONLY: ToolAnnotations;
 export declare const CREATE_UPDATE: ToolAnnotations;
 export declare const DESTRUCTIVE: ToolAnnotations;
+/**
+ * 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(clientManager: ClientManager, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
+    handle(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
     getToolConfig(): ToolConfig;
     /**
-     * Returns an array of environment variables required for this tool to function.
-     *
-     * This method is used to conditionally enable/disable tools based on the availability
-     * of required environment variables. Tools will be disabled if any of their required
-     * environment variables are not set at process startup time.
+     * The connection predicate that gates this tool's enablement. Lifted onto
+     * the interface so the MCP tool-call wrapper can compare it against
+     * `alwaysEnabled` to skip the OAuth login gate for tools that don't touch
+     * the client manager (currently the doc-lookup tools). See
+     * {@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
+     * subset of `runtime.config.connections` keys.
      *
-     * @returns Array of environment variable names required by this tool
+     * Implementations that extend {@linkcode BaseToolHandler} (the standard
+     * path for every tool in this codebase) must not override this — declare
+     * a {@linkcode BaseToolHandler.predicate} property and let the base class
+     * derive the result.
      */
-    getRequiredEnvVars(): readonly EnvVar[];
+    enabledConnectionIds(runtime: ServerRuntime): string[];
     /**
-     * Returns true if this tool can only be used with Confluent Cloud REST APIs.
-     * Override in subclasses for cloud-only tools.
+     * Per-connection verdict map for this tool: `{ enabled: true }` for
+     * connections that satisfy its requirements, `{ enabled: false; reason }`
+     * for those that don't. Powers startup-log grouping and the
+     * `describe-tool-availability` diagnostic tool.
      */
-    isConfluentCloudOnly(): boolean;
+    connectionVerdicts(runtime: ServerRuntime): Map<string, PredicateResult>;
 }
 export interface ToolConfig {
     name: ToolName;
@@ -37,23 +76,101 @@ export interface ToolConfig {
     annotations: ToolAnnotations;
 }
 export declare abstract class BaseToolHandler implements ToolHandler {
-    abstract handle(clientManager: ClientManager, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
+    abstract handle(runtime: ServerRuntime, toolArguments: Record<string, unknown> | undefined, sessionId?: string): Promise<CallToolResult> | CallToolResult;
     abstract getToolConfig(): ToolConfig;
     /**
-     * Return an array of environment variable names required for the operation of this tool.
+     * The connection predicate that gates this tool. The single customization
+     * seam for tool enablement — declared as a one-line readonly property:
+     *
+     *     readonly predicate = hasKafka;                  // base predicate
+     *     readonly predicate = kafkaBootstrapOrOAuth;     // named composite
+     *     readonly predicate = alwaysEnabled;             // no requirement
+     *
+     * **Must reference a named export from `connection-predicates.ts`.** Do
+     * not compose with `allOf(...)` or `widenForOAuth(...)` at the use site.
+     * If no existing named export expresses the gate you need, add one —
+     * with a per-predicate test in `connection-predicates.test.ts` matching
+     * the depth of the existing `hasKafka` / `flinkWithTelemetry` blocks —
+     * and reference that. Enforced mechanically: the `predicate property`
+     * block in `tool-registry.test.ts` maintains an explicit
+     * `Readonly<Record<ToolName, ConnectionPredicate>>` (`EXPECTED_PREDICATES`)
+     * pinning every tool to its expected predicate. The `Record` over
+     * `ToolName` makes exhaustiveness a compile-time check (a missing tool
+     * is a `tsc` error, not a runtime one), and the value type rejects
+     * combinators at compile time. The `it.each` over the record fails with
+     * the offending tool name in the row label whenever a handler's
+     * `predicate` drifts from the table. New tools or rewires are a one-line
+     * table edit.
+     *
+     * Both {@linkcode enabledConnectionIds} and {@linkcode connectionVerdicts}
+     * are derived from this property and are marked `@final`; never override
+     * either method. The retired iteration helpers `connectionIdsWhere` and
+     * `connectionReasonsWhere` are no longer exported — the base class walks
+     * `runtime.config.connections` for you.
+     */
+    abstract readonly predicate: ConnectionPredicate;
+    /**
+     * 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}. A
+     * non-empty result enables the tool; an empty result disables it.
+     *
+     * Customize tool gating by declaring {@linkcode predicate}, never by
+     * replacing this derivation.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    enabledConnectionIds(runtime: ServerRuntime): string[];
+    /**
+     * Per-connection verdict map for this tool, derived from
+     * {@linkcode predicate}. Powers grouped startup logging and
+     * the diagnostic-tool surface.
+     *
+     * Customize tool gating by declaring {@linkcode predicate}, never by
+     * replacing this derivation.
      *
-     * Preferable to return a constant array of EnvVars defined in src/env-schema.ts for easier determination
-     * of which tools require which subset of env vars.
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    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).
      *
-     * If any of the required environment variables are not set at process
-     * startup time, the tool will be disabled and not returned by the tool loader.
+     * 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.
      */
-    abstract getRequiredEnvVars(): readonly EnvVar[];
+    protected resolveSoleConnection(runtime: ServerRuntime): {
+        connId: string;
+        conn: ConnectionConfig;
+        clientManager: BaseClientManager;
+    };
     /**
-     * Default implementation returns false, indicating the tool is not Confluent Cloud only.
-     * Override in subclasses for cloud-only tools.
+     * Resolves a required string from an explicit tool argument, falling back to
+     * a connection-config value. Throws if neither is present.
+     * `label` is the human-readable field name (e.g. `"Organization ID"`);
+     * the thrown message is `"${label} is required"`.
+     * The returned value is always trimmed.
      */
-    isConfluentCloudOnly(): boolean;
+    protected resolveParam(argValue: string | undefined, configValue: string | undefined, label: string): string;
+    /** 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":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,eAEd,CAAC;AAEX,eAAO,MAAM,aAAa,EAAE,eAGlB,CAAC;AAEX,eAAO,MAAM,WAAW,EAAE,eAGhB,CAAC;AAEX,MAAM,WAAW,WAAW;IAC1B,MAAM,CACJ,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAClD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;IAE5C,aAAa,IAAI,UAAU,CAAC;IAE5B;;;;;;;;OAQG;IACH,kBAAkB,IAAI,SAAS,MAAM,EAAE,CAAC;IAExC;;;OAGG;IACH,oBAAoB,IAAI,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,eAAe,CAAC;CAC9B;AAED,8BAAsB,eAAgB,YAAW,WAAW;IAC1D,QAAQ,CAAC,MAAM,CACb,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAClD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc;IAE3C,QAAQ,CAAC,aAAa,IAAI,UAAU;IAEpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,IAAI,SAAS,MAAM,EAAE;IAEhD;;;OAGG;IACH,oBAAoB,IAAI,OAAO;IAI/B,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,OAAe,EACxB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,cAAc;CAalB"}
+{"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

@@ -13,13 +13,92 @@ export const DESTRUCTIVE = {
     destructiveHint: true,
     readOnlyHint: false,
 };
+/**
+ * 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 {
     /**
-     * Default implementation returns false, indicating the tool is not Confluent Cloud only.
-     * Override in subclasses for cloud-only tools.
+     * IDs of connections that satisfy this tool's {@linkcode predicate}. A
+     * non-empty result enables the tool; an empty result disables it.
+     *
+     * Customize tool gating by declaring {@linkcode predicate}, never by
+     * replacing this derivation.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
+     */
+    enabledConnectionIds(runtime) {
+        return Object.entries(runtime.config.connections)
+            .filter(([, conn]) => this.predicate(conn).enabled)
+            .map(([id]) => id);
+    }
+    /**
+     * Per-connection verdict map for this tool, derived from
+     * {@linkcode predicate}. Powers grouped startup logging and
+     * the diagnostic-tool surface.
+     *
+     * Customize tool gating by declaring {@linkcode predicate}, never by
+     * replacing this derivation.
+     *
+     * @final — concrete on `BaseToolHandler`; subclasses must not override.
      */
-    isConfluentCloudOnly() {
-        return false;
+    connectionVerdicts(runtime) {
+        return new Map(Object.entries(runtime.config.connections).map(([id, conn]) => [
+            id,
+            this.predicate(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).
+     *
+     * 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.
+     */
+    resolveSoleConnection(runtime) {
+        const connId = this.enabledConnectionIds(runtime)[0];
+        return {
+            connId,
+            conn: runtime.config.connections[connId],
+            clientManager: runtime.clientManagers[connId],
+        };
+    }
+    /**
+     * Resolves a required string from an explicit tool argument, falling back to
+     * a connection-config value. Throws if neither is present.
+     * `label` is the human-readable field name (e.g. `"Organization ID"`);
+     * the thrown message is `"${label} is required"`.
+     * The returned value is always trimmed.
+     */
+    resolveParam(argValue, configValue, label) {
+        const resolved = argValue?.trim() || configValue?.trim();
+        if (!resolved)
+            throw new Error(`${label} is required`);
+        return resolved;
+    }
+    /** Like resolveParam but returns undefined instead of throwing when both are absent or blank. The returned value is always trimmed. */
+    resolveOptionalParam(argValue, configValue) {
+        return argValue?.trim() || configValue?.trim() || undefined;
     }
     createResponse(message, isError = false, _meta) {
         const response = {
@@ -34,5 +113,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