add docs

Author: freeznet

README.md

@@ -233,6 +233,7 @@ The StreamNative MCP Server allows you to enable or disable specific groups of f
 | Feature              | Description                                                      | Docs |
 |---------------------|------------------------------------------------------------------|------|
 | `streamnative-cloud`| Manage StreamNative Cloud context and check resource logs         | [streamnative_cloud.md](docs/tools/streamnative_cloud.md) |
+| `functions-as-tools`     | Dynamically exposes deployed Pulsar Functions as invokable MCP tools, with automatic input/output schema handling. | [functions_as_tools.md](docs/tools/functions_as_tools.md)  |
 
 You can combine these features as needed using the `--features` flag. For example, to enable only Pulsar client features:
 ```bash

docs/tools/functions_as_tools.md

@@ -0,0 +1,76 @@
+# 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.
+
+## How it Works
+
+### 1. Function Discovery
+The MCP Server automatically discovers Pulsar Functions available in the connected Pulsar cluster. It periodically polls for functions and identifies those suitable for exposure as tools.
+
+By default, if no custom name is provided (see Customizing Tool Properties), the MCP tool name might be derived from the Function's Fully Qualified Name (FQN), such as `pulsar_function_$tenant_$namespace_$name`.
+
+### 2. Schema Conversion
+For each discovered function, the MCP Server attempts to extract its input and output schema definitions. Pulsar Functions can be defined with various schema types for their inputs and outputs (e.g., primitive types, AVRO, JSON).
+
+The server then converts these native Pulsar schemas into a format compatible with MCP tools. This allows the AI agent to understand the expected input parameters and the structure of the output.
+
+Supported Pulsar schema types for automatic conversion include:
+*   Primitive types (String, Boolean, Numbers like INT8, INT16, INT32, INT64, FLOAT, DOUBLE)
+*   AVRO
+*   JSON
+
+If a function uses an unsupported schema type for its input or output, or if schemas are not clearly defined, it might not be exposed as an MCP tool.
+
+## Enabling the Feature
+To enable this functionality, you need to specific the default `--pulsar-instance` and `--pulsar-cluster`, and include `functions-as-tools` in the `--features` flag when starting the StreamNative MCP Server.
+
+Example:
+```bash
+snmcp stdio --organization my-org --key-file /path/to/key-file.json --features pulsar-admin,pulsar-client,functions-as-tools --pulsar-instance instance --pulsar-cluster cluster
+```
+If `functions-as-tools` is part of a broader feature set like `all` and `streamnative-cloud`, enabling `all` or `streamnative-cloud` would also activate this feature.
+
+## Customizing Tool Properties
+You can customize how your Pulsar Functions appear as MCP tools (their name and description) by providing specific runtime options when deploying or updating your functions. This is done using the `--custom-runtime-options` flag with `pulsar-admin functions create` or `pulsar-admin functions update`.
+
+The MCP Server looks for the following environment variables within the custom runtime options:
+*   `MCP_TOOL_NAME`: Specifies the desired name for the MCP tool.
+*   `MCP_TOOL_DESCRIPTION`: Provides a description for the MCP tool, which helps the AI agent understand its purpose.
+
+**Format for `--custom-runtime-options`**:
+The options should be a JSON string where you define an `env` map containing `MCP_TOOL_NAME` and `MCP_TOOL_DESCRIPTION`.
+
+**Example**:
+When deploying a Pulsar Function, you can set these properties as follows:
+```bash
+pulsar-admin functions create \
+  --tenant public \
+  --namespace default \
+  --name my-custom-logic-function \
+  --inputs "persistent://public/default/input-topic" \
+  --output "persistent://public/default/output-topic" \
+  --py my_function.py \
+  --classname my_function.MyFunction \
+  --custom-runtime-options \
+  '''
+  {
+    "env": {
+      "MCP_TOOL_NAME": "CustomObjectFunction",
+      "MCP_TOOL_DESCRIPTION": "Takes an input number and returns the value incremented by 100."
+    }
+  }
+  '''
+```
+In this example:
+- The MCP tool derived from `my-custom-logic-function` will be named `CustomObjectFunction`.
+- Its description will be "Takes an input number and returns the value incremented by 100."
+
+If these custom options are not provided, the MCP tool name might default to a derivative of the function's FQN, and the description might be generic and cannot help AI Agent to understand the purpose of the MCP tool.
+
+## Considerations and Limitations
+
+*   **Schema Definition**: For reliable schema conversion, ensure your Pulsar Functions have clearly defined input and output schemas using Pulsar's schema registry capabilities. Functions with ambiguous or `BYTES` schemas might not be converted effectively or might default to generic byte array inputs/outputs.
+*   **Function State**: This feature primarily focuses on the stateless request/response invocation pattern of functions.
+*   **Discovery Latency**: There might be a slight delay between deploying/updating a function and it appearing as an MCP tool, due to the server's polling interval for function discovery.
+*   **Error Handling**: The MCP Server will attempt to relay errors from function executions, but the specifics might vary.
+*   **Security**: Ensure that only intended functions are exposed by managing permissions within your Pulsar cluster. The MCP Server will operate with the permissions of its Pulsar client.

pkg/mcp/pulsar_functions_as_tools.go

@@ -30,14 +30,11 @@ import (
 	"github.com/streamnative/streamnative-mcp-server/pkg/pftools"
 )
 
-// 管理器跟踪
 var (
 	functionManagers     = make(map[string]*pftools.PulsarFunctionManager)
 	functionManagersLock sync.RWMutex
 )
 
-// StopAllPulsarFunctionManagers 停止所有注册的Pulsar Function管理器
-// 可在程序退出前调用
 func StopAllPulsarFunctionManagers() {
 	functionManagersLock.Lock()
 	defer functionManagersLock.Unlock()
@@ -48,26 +45,22 @@ func StopAllPulsarFunctionManagers() {
 		delete(functionManagers, id)
 	}
 
-	// 给一些时间让管理器清理资源
 	if len(functionManagers) > 0 {
 		time.Sleep(500 * time.Millisecond)
 	}
 
 	log.Println("All Pulsar Function managers stopped")
 }
 
-// PulsarFunctionManagedMcpTools 将运行中的Pulsar Functions集成为MCP工具
 func PulsarFunctionManagedMcpTools(s *server.MCPServer, readOnly bool, features []string) {
 	if !slices.Contains(features, string(FeatureAll)) &&
 		!slices.Contains(features, string(FeatureFunctionsAsTools)) &&
 		!slices.Contains(features, string(FeatureStreamNativeCloud)) {
 		return
 	}
 
-	// 创建新的管理器选项
 	options := pftools.DefaultManagerOptions()
 
-	// 从环境变量读取配置
 	if pollIntervalStr := os.Getenv("PULSAR_FUNCTIONS_POLL_INTERVAL"); pollIntervalStr != "" {
 		if seconds, err := strconv.Atoi(pollIntervalStr); err == nil && seconds > 0 {
 			options.PollInterval = time.Duration(seconds) * time.Second
@@ -96,23 +89,19 @@ func PulsarFunctionManagedMcpTools(s *server.MCPServer, readOnly bool, features
 		}
 	}
 
-	// 设置要监听的租户和命名空间
 	if tenantNamespacesStr := os.Getenv("PULSAR_FUNCTIONS_TENANT_NAMESPACES"); tenantNamespacesStr != "" {
 		options.TenantNamespaces = strings.Split(tenantNamespacesStr, ",")
 		log.Printf("Setting Pulsar Functions tenant namespaces to %v", options.TenantNamespaces)
 	}
 
-	// 创建管理器
 	manager, err := pftools.NewPulsarFunctionManager(s, readOnly, options)
 	if err != nil {
 		log.Printf("Failed to create Pulsar Function manager: %v", err)
 		return
 	}
 
-	// 启动管理器
 	manager.Start()
 
-	// 将管理器添加到全局跟踪中
 	managerID := "pulsar_functions_manager_" + strconv.FormatInt(time.Now().UnixNano(), 10)
 	functionManagersLock.Lock()
 	functionManagers[managerID] = manager