feat: split MCP tools for Claude connector

Author: freeznet

PLAN.md

@@ -240,6 +240,8 @@ The StreamNative MCP Server allows you to enable or disable specific groups of f
 
 ---
 
+Claude connector compatibility: admin tools that previously mixed read and write operations behind one `operation` parameter are exposed as separate read/write MCP tools, for example `kafka_admin_topics_read` and `kafka_admin_topics_write`. Read tools include `annotations.readOnlyHint=true`; write or side-effectful tools include `annotations.destructiveHint=true`. In `--read-only` mode, write/destructive tools are not registered.
+
 #### Kafka Features
 
 | Feature                   | Description                                      | Docs |

README.md

@@ -1,3 +1,5 @@
+**Claude connector safety:** Safety annotation: dynamically generated Pulsar Functions-as-Tools are destructive and are not registered in read-only mode.
+
 # Functions as Tools
 
 The "Functions as Tools" feature allows the StreamNative MCP Server to dynamically discover Apache Pulsar Functions deployed in your cluster and expose them as invokable MCP tools for AI agents. This significantly enhances the capabilities of AI agents by allowing them to interact with custom business logic encapsulated in Pulsar Functions without manual tool registration for each function.
@@ -93,7 +95,7 @@ Beyond customizing individual tool properties at the function deployment level,
     *   **Example**: `public/default,my-tenant/app-functions`
     *   **Default**: Empty (meaning discover from all accessible namespaces (only on StreamNative Cloud)).
 *   `FUNCTIONS_AS_TOOLS_STRICT_EXPORT`
-    *   **Description**: Only export functions with `MCP_TOOL_NAME` and `MCP_TOOL_DESCRIPTION` defined. 
+    *   **Description**: Only export functions with `MCP_TOOL_NAME` and `MCP_TOOL_DESCRIPTION` defined.
     *   **Format**: `true` or `false`
     *   **Example**: `false`
     *   **Default**: `true`

docs/tools/functions_as_tools.md

@@ -1,5 +1,8 @@
 #### kafka-admin-connect
 
+**Claude connector safety:** Actual MCP tools: `kafka_admin_connect_read` (`list`, `get`) and `kafka_admin_connect_write` (`create`, `update`, `delete`, `restart`, `pause`, `resume`).
+
+
 Kafka Connect is a framework for integrating Kafka with external systems. The following resources and operations are supported:
 
 - **kafka-connect-cluster**
@@ -31,4 +34,4 @@ Kafka Connect is a framework for integrating Kafka with external systems. The fo
 
 - **connector-plugins**
   - **list**: List all available connector plugins
-    - _Parameters_: None 
+    - _Parameters_: None

docs/tools/kafka_admin_connect.md

@@ -1,5 +1,8 @@
 #### kafka-admin-groups
 
+**Claude connector safety:** Actual MCP tools: `kafka_admin_groups_read` (`list`, `describe`, `offsets`) and `kafka_admin_groups_write` (`remove-members`, `delete-offset`, `set-offset`).
+
+
 This tool provides access to Kafka consumer group operations including listing, describing, and managing group membership.
 
 - **groups**
@@ -21,4 +24,4 @@ This tool provides access to Kafka consumer group operations including listing,
     - `group` (string, required): The name of the Kafka Consumer Group
     - `topic` (string, required): The name of the Kafka topic
     - `partition` (number, required): The partition number
-    - `offset` (number, required): The offset value to set (use -1 for earliest, -2 for latest, or a specific value) 
+    - `offset` (number, required): The offset value to set (use -1 for earliest, -2 for latest, or a specific value)

docs/tools/kafka_admin_groups.md

@@ -1,8 +1,11 @@
 #### kafka-admin-partitions
 
+**Claude connector safety:** Actual MCP tool: `kafka_admin_partitions_write` (`update`). This write-only tool is not registered in read-only mode.
+
+
 This tool provides access to Kafka partition operations, particularly adding partitions to existing topics.
 
 - **partition**
   - **update**: Update the number of partitions for an existing Kafka topic (can only increase, not decrease)
     - `topic` (string, required): The name of the Kafka topic
-    - `new-total` (number, required): The new total number of partitions (must be greater than current) 
+    - `new-total` (number, required): The new total number of partitions (must be greater than current)

docs/tools/kafka_admin_partitions.md

@@ -1,5 +1,8 @@
 #### kafka-admin-schema-registry
 
+**Claude connector safety:** Actual MCP tools: `kafka_admin_sr_read` (`list`, `get`) and `kafka_admin_sr_write` (`set`, `create`, `delete`).
+
+
 This tool provides access to Kafka Schema Registry operations, including managing subjects, versions, and compatibility settings.
 
 - **subjects**
@@ -35,4 +38,4 @@ This tool provides access to Kafka Schema Registry operations, including managin
 
 - **types**
   - **list**: List supported schema types (e.g. AVRO, JSON, PROTOBUF)
-    - _Parameters_: None 
+    - _Parameters_: None

docs/tools/kafka_admin_schema_registry.md

@@ -1,5 +1,8 @@
 #### kafka-admin-topics
 
+**Claude connector safety:** Actual MCP tools: `kafka_admin_topics_read` (`list`, `get`, `metadata`) and `kafka_admin_topics_write` (`create`, `delete`).
+
+
 This tool provides access to various Kafka topic operations, including creation, deletion, listing, and configuration retrieval.
 
 - **topics**
@@ -15,4 +18,4 @@ This tool provides access to various Kafka topic operations, including creation,
     - `replication-factor` (number, optional): Replication factor. Default: 1
     - `configs` (array of string, optional): Topic configuration overrides as key-value strings, e.g. ["cleanup.policy=compact", "retention.ms=604800000"]
   - **delete**: Delete an existing topic
-    - `name` (string, required): The name of the Kafka topic 
+    - `name` (string, required): The name of the Kafka topic

docs/tools/kafka_admin_topics.md

@@ -1,5 +1,8 @@
 #### kafka-client-consume
 
+**Claude connector safety:** Safety annotation: `kafka_client_consume` is destructive and is not registered in read-only mode because it can commit consumer offsets.
+
+
 Consume messages from a Kafka topic. This tool allows you to read messages from Kafka topics with various consumption options.
 
 - **kafka_client_consume**
@@ -12,4 +15,4 @@ Consume messages from a Kafka topic. This tool allows you to read messages from
       - 'atend': Begin from the next message after the consumer starts
       - 'atcommitted': Begin from the last committed offset (only works with specified 'group')
     - `max-messages` (number, optional): Maximum number of messages to consume in this request. Default: 10
-    - `timeout` (number, optional): Maximum time in seconds to wait for messages. Default: 10 
+    - `timeout` (number, optional): Maximum time in seconds to wait for messages. Default: 10

docs/tools/kafka_client_consume.md

@@ -9,4 +9,4 @@ Produce messages to a Kafka topic. This tool allows you to send single or multip
     - `key` (string, optional): The key for the message. Used for partition assignment and ordering.
     - `value` (string, required if 'messages' is not provided): The value/content of the message to send.
     - `headers` (array, optional): Message headers in the format of [{"key": "header-key", "value": "header-value"}].
-    - `sync` (boolean, optional): Whether to wait for server acknowledgment before returning. Default: true. 
+    - `sync` (boolean, optional): Whether to wait for server acknowledgment before returning. Default: true.