feat: split MCP tools for Claude connector

README.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 |

docs/tools/functions_as_tools.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/kafka_admin_connect.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_groups.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_partitions.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_schema_registry.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_topics.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_client_consume.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_produce.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.

docs/tools/pulsar_admin_broker_stats.md

@@ -4,16 +4,16 @@ Unified tool for retrieving Apache Pulsar broker statistics.
 
 - **monitoring_metrics**
   - **get**: Get broker monitoring metrics
-    
+
 - **mbeans**
   - **get**: Get JVM MBeans statistics from broker
-    
+
 - **topics**
   - **get**: Get statistics for all topics managed by the broker
-    
+
 - **allocator_stats**
   - **get**: Get memory allocator statistics
     - `allocator_name` (string, required): Name of the allocator
-    
+
 - **load_report**
-  - **get**: Get broker load report 
+  - **get**: Get broker load report

docs/tools/pulsar_admin_brokers.md

@@ -1,14 +1,17 @@
 #### pulsar_admin_brokers
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_brokers_read` (`list`, `get`) and `pulsar_admin_brokers_write` (`update`, `delete` broker dynamic configuration).
+
+
 Unified tool for managing Apache Pulsar broker resources.
 
 - **brokers**
   - **list**: List all active brokers in a cluster
     - `clusterName` (string, required): The cluster name
-    
+
 - **health**
   - **get**: Check the health status of a broker
-    
+
 - **config**
   - **get**: Get broker configuration
     - `configType` (string, required): Configuration type, available options:
@@ -21,7 +24,7 @@ Unified tool for managing Apache Pulsar broker resources.
     - `configValue` (string, required): Configuration parameter value
   - **delete**: Delete broker configuration
     - `configName` (string, required): Configuration parameter name
-    
+
 - **namespaces**
   - **get**: Get namespaces managed by a broker
-    - `brokerUrl` (string, required): Broker URL, e.g., '127.0.0.1:8080' 
+    - `brokerUrl` (string, required): Broker URL, e.g., '127.0.0.1:8080'

docs/tools/pulsar_admin_clusters.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_cluster
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_cluster_read` (`list`, `get`) and `pulsar_admin_cluster_write` (`create`, `update`, `delete`).
+
+
 Unified tool for managing Apache Pulsar clusters.
 
 - **cluster**
@@ -18,14 +21,14 @@ Unified tool for managing Apache Pulsar clusters.
     - Same optional parameters as create
   - **delete**: Delete a cluster
     - `cluster_name` (string, required): The cluster name
-    
+
 - **peer_clusters**
   - **get**: Get list of peer clusters
     - `cluster_name` (string, required): The cluster name
   - **update**: Update peer clusters list
     - `cluster_name` (string, required): The cluster name
     - `peer_cluster_names` (array, required): List of peer cluster names
-    
+
 - **failure_domain**
   - **list**: List all failure domains in a cluster
     - `cluster_name` (string, required): The cluster name
@@ -42,4 +45,4 @@ Unified tool for managing Apache Pulsar clusters.
     - `brokers` (array, required): List of brokers in the domain
   - **delete**: Delete a failure domain
     - `cluster_name` (string, required): The cluster name
-    - `domain_name` (string, required): The failure domain name 
+    - `domain_name` (string, required): The failure domain name

docs/tools/pulsar_admin_functions.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_functions
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_functions_read` (`list`, `get`, `status`, `stats`, `querystate`) and `pulsar_admin_functions_write` (`create`, `update`, `delete`, `download`, `start`, `stop`, `restart`, `putstate`, `trigger`, `upload`).
+
+
 Manage Apache Pulsar Functions for stream processing. Pulsar Functions are lightweight compute processes that can consume messages from one or more Pulsar topics, apply user-defined processing logic, and produce results to another topic. Functions support Java, Python, and Go runtimes, enabling complex event processing, data transformations, filtering, and integration with external systems.
 
 This tool provides a comprehensive set of operations to manage the entire function lifecycle:

docs/tools/pulsar_admin_namespaces.md

@@ -1,37 +1,40 @@
 #### pulsar_admin_namespace
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_namespace_read` (`list`, `get_topics`) and `pulsar_admin_namespace_write` (`create`, `delete`, `clear_backlog`, `unsubscribe`, `unload`, `split_bundle`).
+
+
 Manage Pulsar namespaces with various operations.
 
 - **list**: List all namespaces for a tenant
   - `tenant` (string, required): The tenant name
-  
+
 - **get_topics**: Get all topics within a namespace
   - `namespace` (string, required): The namespace name (format: tenant/namespace)
-  
+
 - **create**: Create a new namespace
   - `namespace` (string, required): The namespace name (format: tenant/namespace)
   - `bundles` (string, optional): Number of bundles to activate
   - `clusters` (array, optional): List of clusters to assign
-  
+
 - **delete**: Delete a namespace
   - `namespace` (string, required): The namespace name (format: tenant/namespace)
-  
+
 - **clear_backlog**: Clear backlog for all topics in a namespace
   - `namespace` (string, required): The namespace name (format: tenant/namespace)
   - `subscription` (string, optional): Subscription name
   - `bundle` (string, optional): Bundle name or range
   - `force` (string, optional): Force clear backlog (true/false)
-  
+
 - **unsubscribe**: Unsubscribe from a subscription for all topics in a namespace
   - `namespace` (string, required): The namespace name (format: tenant/namespace)
   - `subscription` (string, required): Subscription name
   - `bundle` (string, optional): Bundle name or range
-  
+
 - **unload**: Unload a namespace from the current serving broker
   - `namespace` (string, required): The namespace name (format: tenant/namespace)
   - `bundle` (string, optional): Bundle name or range
-  
+
 - **split_bundle**: Split a namespace bundle
   - `namespace` (string, required): The namespace name (format: tenant/namespace)
   - `bundle` (string, required): Bundle name or range
-  - `unload` (string, optional): Unload newly split bundles (true/false) 
+  - `unload` (string, optional): Unload newly split bundles (true/false)

docs/tools/pulsar_admin_nsisolationpolicy.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_nsisolationpolicy
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_nsisolationpolicy_read` (`get`, `list`) and `pulsar_admin_nsisolationpolicy_write` (`set`, `delete`).
+
+
 Manage namespace isolation policies in a Pulsar cluster. Namespace isolation policies enable physical isolation of namespaces by controlling which brokers specific namespaces can use. This helps provide predictable performance and resource isolation, especially in multi-tenant environments.
 
 This tool provides operations across three resource types:
@@ -29,4 +32,4 @@ This tool provides operations across three resource types:
 
 - **brokers** (All brokers with isolation policies):
   - **list**: List all brokers with their isolation policies
-    - `cluster` (string, required): The cluster name 
+    - `cluster` (string, required): The cluster name

docs/tools/pulsar_admin_packages.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_package
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_package_read` (`list`, `get`, `download`) and `pulsar_admin_package_write` (`update`, `delete`, `upload`).
+
+
 Manage packages in Apache Pulsar. Packages are reusable components that can be shared across functions, sources, and sinks. The system supports package schemes including `function://`, `source://`, and `sink://` for different component types.
 
 This tool provides operations across two resource types:
@@ -29,4 +32,4 @@ This tool provides operations across two resource types:
 - **packages** (Packages of a specific type):
   - **list**: List all packages of a specific type in a namespace
     - `type` (string, required): Package type (function, source, sink)
-    - `namespace` (string, required): The namespace name 
+    - `namespace` (string, required): The namespace name

docs/tools/pulsar_admin_resource_quotas.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_resourcequota
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_resourcequota_read` (`get`) and `pulsar_admin_resourcequota_write` (`set`, `reset`).
+
+
 Manage Apache Pulsar resource quotas for brokers, namespaces and bundles. Resource quotas define limits for resource usage such as message rates, bandwidth, and memory. These quotas help prevent resource abuse and ensure fair resource allocation across the Pulsar cluster.
 
 This tool provides operations on the following resource:
@@ -21,4 +24,4 @@ This tool provides operations on the following resource:
     - `dynamic` (boolean, optional): Whether to allow quota to be dynamically re-calculated
   - **reset**: Reset a namespace bundle's resource quota to default value
     - `namespace` (string, required): The namespace name in format 'tenant/namespace'
-    - `bundle` (string, required): The bundle range in format '{start-boundary}_{end-boundary}' 
+    - `bundle` (string, required): The bundle range in format '{start-boundary}_{end-boundary}'

docs/tools/pulsar_admin_schemas.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_schema
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_schema_read` (`get`) and `pulsar_admin_schema_write` (`upload`, `delete`).
+
+
 Manage Apache Pulsar schemas for topics.
 
 - **schema**
@@ -10,4 +13,4 @@ Manage Apache Pulsar schemas for topics.
     - `topic` (string, required): The fully qualified topic name
     - `filename` (string, required): Path to the schema definition file
   - **delete**: Delete the schema for a topic
-    - `topic` (string, required): The fully qualified topic name 
+    - `topic` (string, required): The fully qualified topic name

docs/tools/pulsar_admin_sinks.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_sinks
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_sinks_read` (`list`, `get`, `status`, `list-built-in`) and `pulsar_admin_sinks_write` (`create`, `update`, `delete`, `start`, `stop`, `restart`).
+
+
 Manage Apache Pulsar Sinks for data movement and integration. Pulsar Sinks are connectors that export data from Pulsar topics to external systems such as databases, storage services, messaging systems, and third-party applications. Sinks consume messages from one or more Pulsar topics, transform the data if needed, and write it to external systems in a format compatible with the target destination.
 
 This tool provides complete lifecycle management for sink connectors:
@@ -83,4 +86,4 @@ This tool provides complete lifecycle management for sink connectors:
 - **list-built-in**: List all built-in sink connectors available in the system
   - No parameters required
 
-Built-in sink connectors are available for common systems like Kafka, JDBC, Elasticsearch, and cloud storage. Sinks follow the tenant/namespace/name hierarchy for organization and access control, can scale through parallelism configuration, and support configurable subscription types. Sinks require proper permissions to access their input topics. 
+Built-in sink connectors are available for common systems like Kafka, JDBC, Elasticsearch, and cloud storage. Sinks follow the tenant/namespace/name hierarchy for organization and access control, can scale through parallelism configuration, and support configurable subscription types. Sinks require proper permissions to access their input topics.

docs/tools/pulsar_admin_sources.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_sources
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_sources_read` (`list`, `get`, `status`, `list-built-in`) and `pulsar_admin_sources_write` (`create`, `update`, `delete`, `start`, `stop`, `restart`).
+
+
 Manage Apache Pulsar Sources for data ingestion and integration. Pulsar Sources are connectors that import data from external systems into Pulsar topics. Sources connect to external systems such as databases, messaging platforms, storage services, and real-time data streams to pull data and publish it to Pulsar topics.
 
 This tool provides complete lifecycle management for source connectors:
@@ -72,4 +75,4 @@ This tool provides complete lifecycle management for source connectors:
 - **list-built-in**: List all built-in source connectors available in the system
   - No parameters required
 
-Built-in source connectors are available for common systems like Kafka, JDBC, AWS services, and more. Sources follow the tenant/namespace/name hierarchy for organization and access control, can scale through parallelism configuration, and support various processing guarantees. 
+Built-in source connectors are available for common systems like Kafka, JDBC, AWS services, and more. Sources follow the tenant/namespace/name hierarchy for organization and access control, can scale through parallelism configuration, and support various processing guarantees.

docs/tools/pulsar_admin_subscriptions.md

@@ -1,5 +1,8 @@
 #### pulsar_admin_subscription
 
+**Claude connector safety:** Actual MCP tools: `pulsar_admin_subscription_read` (`list`, `peek`, `get-message-by-id`) and `pulsar_admin_subscription_write` (`create`, `delete`, `skip`, `expire`, `reset-cursor`).
+
+
 Manage Pulsar topic subscriptions, which represent consumer groups reading from topics.
 
 - **list**: List all subscriptions for a topic