xiaozhi-client 1.6.11 → 1.6.13-beta.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xiaozhi-client",
-  "version": "1.6.11",
+  "version": "1.6.13-beta.0",
   "description": "小智 AI 客户端 命令行工具",
   "type": "module",
   "main": "dist/cli.js",
@@ -61,7 +61,7 @@
     "dotenv": "^17.2.1",
     "eventsource": "^4.0.0",
     "express": "^5.1.0",
-    "hono": "^4.8.10",
+    "hono": "^4.9.6",
     "json5": "^2.2.3",
     "json5-writer": "^0.2.0",
     "jsonc-parser": "^3.3.1",

package/docs/mcp-tool-calling.md

@@ -2,7 +2,17 @@
 
 ## 概述
 
-`xiaozhi mcp call` 命令用于调用已配置的 MCP (Model Context Protocol) 服务中的工具。该命令通过 HTTP API 与后台服务通信，实现对各种 MCP 工具的统一调用接口。
+`xiaozhi mcp call` 命令用于调用已配置的 MCP (Model Context Protocol) 服务中的工具，以及自定义的 customMCP 工具。该命令通过 HTTP API 与后台服务通信，实现对各种 MCP 工具和 customMCP 工具的统一调用接口。
+
+### 支持的工具类型
+
+1. **标准 MCP 工具**：通过 MCP 协议连接的外部服务工具
+2. **customMCP 工具**：在配置文件中直接定义的自定义工具，支持多种处理器类型：
+   - **proxy**：代理调用第三方平台（如 Coze、Dify、n8n）
+   - **http**：直接 HTTP API 调用
+   - **function**：JavaScript 函数执行
+   - **script**：脚本执行（Node.js、Python 等）
+   - **chain**：链式工具调用
 
 ## 前置条件
 
@@ -12,7 +22,7 @@
    ```bash
    # 启动后台服务
    xiaozhi start -d
-   
+
    # 检查服务状态
    xiaozhi status
    ```
@@ -22,20 +32,31 @@
 
 ## 命令语法
 
+### 标准 MCP 工具调用
+
 ```bash
 xiaozhi mcp call <服务名称> <工具名称> [选项]
 ```
 
+### customMCP 工具调用
+
+```bash
+xiaozhi mcp call customMCP <工具名称> [选项]
+```
+
 ### 参数说明
 
 #### 必需参数
 
-- `<服务名称>`：MCP 服务的名称，在配置文件中定义
+- `<服务名称>`：
+  - 对于标准 MCP 工具：MCP 服务的名称，在配置文件中定义
+  - 对于 customMCP 工具：固定使用 `customMCP`
 - `<工具名称>`：要调用的工具名称
 
 #### 可选参数
 
 - `--args <JSON>`：工具参数，JSON 格式字符串（默认值：`{}`）
+  - customMCP 工具支持基于 JSON Schema 的参数验证
 
 ### 选项格式
 
@@ -45,7 +66,7 @@ xiaozhi mcp call <服务名称> <工具名称> [选项]
 
 ## 使用示例
 
-### 基础示例
+### 标准 MCP 工具示例
 
 #### 1. 调用计算器工具
 
@@ -69,6 +90,39 @@ xiaozhi mcp call datetime get_current_date
 xiaozhi mcp call datetime add_time --args '{"date": "2024-01-01", "days": 7}'
 ```
 
+### customMCP 工具示例
+
+#### 3. 调用 Coze 工作流工具
+
+```bash
+# 调用 Coze 工作流进行文本分析
+xiaozhi mcp call customMCP coze_workflow_analyzer --args '{"input": "这是一段需要分析的文本内容"}'
+```
+
+**输出示例：**
+```
+✔ customMCP/coze_workflow_analyzer: {"content":[{"type":"text","text":"分析结果：这是一段中性情感的文本..."}]}
+```
+
+#### 4. 调用 HTTP API 工具
+
+```bash
+# 获取天气信息
+xiaozhi mcp call customMCP weather_api --args '{"city": "北京", "units": "metric"}'
+```
+
+#### 5. 调用函数处理器工具
+
+```bash
+# 文本处理
+xiaozhi mcp call customMCP text_processor --args '{"text": "Hello World", "operation": "uppercase"}'
+```
+
+**输出示例：**
+```
+✔ customMCP/text_processor: {"content":[{"type":"text","text":"HELLO WORLD"}]}
+```
+
 ### 复杂参数示例
 
 #### 3. 多参数工具调用
@@ -180,6 +234,52 @@ xiaozhi mcp call service tool --args {"param": "value"}  # 缺少引号
 xiaozhi mcp call service tool --args '{"param": value}'  # 值缺少引号
 ```
 
+### 6. customMCP 工具不存在错误
+
+**错误信息：**
+```
+错误: customMCP 工具 'unknown_tool' 不存在。可用的 customMCP 工具: coze_workflow, text_processor。请使用 'xiaozhi mcp list' 查看所有可用工具。
+```
+
+**解决方法：**
+- 检查工具名称拼写是否正确
+- 使用 `xiaozhi mcp list --tools` 查看所有可用的 customMCP 工具
+- 确认工具已在 `xiaozhi.config.json` 的 `customMCP.tools` 中正确定义
+
+### 7. customMCP 参数验证失败
+
+**错误信息：**
+```
+错误: 参数验证失败: 缺少必需参数: input
+```
+
+**解决方法：**
+- 检查工具的 `inputSchema` 定义，了解必需参数
+- 确保提供所有必需参数
+- 验证参数类型是否正确
+
+**示例：**
+```bash
+# 错误：缺少必需参数
+xiaozhi mcp call customMCP text_processor --args '{}'
+
+# 正确：提供所有必需参数
+xiaozhi mcp call customMCP text_processor --args '{"text": "Hello", "operation": "uppercase"}'
+```
+
+### 8. customMCP 配置错误
+
+**错误信息：**
+```
+错误: customMCP 工具 'my_tool' 配置验证失败。请检查配置文件中的工具定义。
+```
+
+**解决方法：**
+- 检查 `xiaozhi.config.json` 中的 customMCP 配置语法
+- 确认 handler 类型和配置参数正确
+- 验证环境变量是否已设置（如 API 密钥）
+- 参考 [customMCP 配置示例文档](./custom-mcp-handlers-examples.md)
+
 ## 相关命令
 
 ### 服务管理命令
@@ -191,9 +291,10 @@ xiaozhi mcp call service tool --args '{"param": value}'  # 值缺少引号
 
 ### MCP 相关命令
 
-- `xiaozhi mcp list`：列出所有可用的 MCP 服务和工具
-- `xiaozhi mcp tool <服务名> <工具名> <enable|disable>`：启用或禁用工具
-- `xiaozhi config show`：查看当前配置
+- `xiaozhi mcp list`：列出所有可用的 MCP 服务和 customMCP 工具
+- `xiaozhi mcp list --tools`：显示详细的工具列表，包括 customMCP 工具
+- `xiaozhi mcp tool <服务名> <工具名> <enable|disable>`：启用或禁用标准 MCP 工具
+- `xiaozhi config show`：查看当前配置，包括 customMCP 配置
 
 ## 技术架构说明
 
@@ -211,11 +312,40 @@ xiaozhi mcp call service tool --args '{"param": value}'  # 值缺少引号
 
 ## 最佳实践
 
+### 通用最佳实践
+
 1. **参数验证**：调用前确认参数格式和内容正确
 2. **错误处理**：根据错误信息进行相应的故障排除
 3. **服务监控**：定期检查服务状态确保正常运行
 4. **配置管理**：保持 MCP 服务配置的准确性和时效性
 
+### customMCP 工具最佳实践
+
+1. **配置验证**：
+   - 使用 `xiaozhi mcp list` 验证 customMCP 工具是否正确加载
+   - 定期检查配置文件语法和结构
+   - 确保环境变量正确设置
+
+2. **参数设计**：
+   - 为 customMCP 工具定义清晰的 `inputSchema`
+   - 使用适当的参数类型和验证规则
+   - 提供有意义的参数描述
+
+3. **错误处理**：
+   - 实现适当的超时和重试机制
+   - 为不同的 handler 类型配置合适的错误处理策略
+   - 监控外部 API 调用的成功率
+
+4. **性能优化**：
+   - 合理设置超时时间，避免长时间等待
+   - 对于频繁调用的工具，考虑缓存机制
+   - 监控工具调用的响应时间
+
+5. **安全考虑**：
+   - 使用环境变量存储敏感信息（API 密钥等）
+   - 定期轮换 API 密钥和访问令牌
+   - 限制工具的访问权限和操作范围
+
 ## 故障排除检查清单
 
 遇到问题时，请按以下顺序检查：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xiaozhi-client",
-  "version": "1.6.11",
+  "version": "1.6.13-beta.0",
   "description": "小智 AI 客户端 命令行工具",
   "type": "module",
   "main": "dist/cli.js",
@@ -61,7 +61,7 @@
     "dotenv": "^17.2.1",
     "eventsource": "^4.0.0",
     "express": "^5.1.0",
-    "hono": "^4.8.10",
+    "hono": "^4.9.6",
     "json5": "^2.2.3",
     "json5-writer": "^0.2.0",
     "jsonc-parser": "^3.3.1",