trustgraph/docs/tech-specs/mcp-tool-arguments.zh-cn.md

layout	title	parent
default	MCP 工具参数规范	Chinese (Beta)

MCP 工具参数规范

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

概述

功能名称: MCP 工具参数支持 作者: Claude 代码助手 日期: 2025-08-21 状态: 最终

摘要

启用 ReACT 代理调用带有正确定义的参数的 MCP (模型上下文协议) 工具，通过在 MCP 工具配置中添加参数规范支持，类似于当前提示模板工具的工作方式。

问题陈述

目前，ReACT 代理框架中的 MCP 工具无法指定其预期的参数。McpToolImpl.get_arguments() 方法返回一个空列表，迫使 LLM 仅根据工具名称和描述来猜测正确的参数结构。这会导致：

• 由于参数猜测导致的不可靠工具调用
• 当工具因错误的参数而失败时，用户体验不佳
• 在执行之前无法验证工具参数
• 代理提示中缺少参数文档

目标

• 允许 MCP 工具配置指定预期的参数（名称、类型、描述）
• 更新代理管理器，通过提示向 LLM 暴露 MCP 工具参数
• 保持与现有 MCP 工具配置的向后兼容性
• 支持与提示模板工具类似的参数验证

不属于目标

• 从 MCP 服务器动态发现参数（未来增强功能）
• 参数类型验证，超出基本结构
• 复杂的参数模式（嵌套对象、数组）

背景和上下文

现状

MCP 工具在 ReACT 代理系统中配置为具有最小的元数据：

{
  "type": "mcp-tool",
  "name": "get_bank_balance",
  "description": "获取银行账户余额",
  "mcp-tool": "get_bank_balance"
}

McpToolImpl.get_arguments() 方法返回 []，因此 LLM 在提示中不会收到任何参数指导。

局限性

1. 缺少参数指定: MCP 工具无法定义预期的参数
2. LLM 参数猜测: 代理必须根据工具名称/描述推断参数
3. 提示信息缺失: 代理提示中不包含 MCP 工具的参数详情
4. 无验证: 无效参数仅在 MCP 工具执行时捕获

相关组件

• trustgraph-flow/agent/react/service.py: 工具配置加载和 AgentManager 创建
• trustgraph-flow/agent/react/tools.py: McpToolImpl 实现
• trustgraph-flow/agent/react/agent_manager.py: 使用工具参数生成提示
• tg-invoke-mcp-tool: 用于 MCP 工具管理的 CLI 工具
• Workbench: 代理工具配置的外部 UI

要求

功能要求

1. MCP 工具配置参数: MCP 工具配置 必须 支持一个可选的 arguments 数组，包含名称、类型和描述字段
2. 参数暴露: McpToolImpl.get_arguments() 必须 返回配置的参数，而不是空列表
3. 提示集成: 代理提示 必须 在指定有参数时，包含 MCP 工具参数详情
4. 向后兼容性: 没有参数的现有 MCP 工具配置 必须 保持正常工作
5. CLI 支持: 现有的 tg-invoke-mcp-tool CLI 支持参数（已实现）

非功能要求

1. 向后兼容性: 现有 MCP 工具配置零中断
2. 性能: 代理提示生成没有显著性能影响
3. 一致性: 参数处理 必须 与提示模板工具模式匹配

用户故事

1. 作为 代理开发者，我希望在配置中指定 MCP 工具参数，以便 LLM 可以使用正确的参数调用工具
2. 作为 Workbench 用户，我希望在 UI 中配置 MCP 工具参数，以便代理正确使用工具
3. 作为 ReACT 代理中的 LLM，我希望在提示中看到工具参数规范，以便我可以提供正确的参数

设计

高级架构

通过以下方式，扩展 MCP 工具配置以匹配提示模板模式：

1. 在 MCP 工具配置中添加可选的 arguments 数组，包含名称、类型和描述字段
2. 修改 McpToolImpl 以接受和返回配置的参数
3. 修改工具配置加载以处理 MCP 工具参数
4. 确保代理提示包含 MCP 工具参数信息

配置方案

{
  "type": "mcp-tool",
  "name": "get_bank_balance", 
  "description": "获取银行账户余额",
  "mcp-tool": "get_bank_balance",
  "arguments": [
    {
      "name": "account_id",
      "type": "string", 
      "description": "银行账户标识符"
    },
    {
      "name": "date",
      "type": "string",
      "description": "查询余额的日期（可选，格式：YYYY-MM-DD）"
    }
  ]
}

数据流程

1. 配置加载: 使用参数的 MCP 工具配置通过 on_tools_config() 加载
2. 工具创建: 参数解析并传递给 McpToolImpl 通过构造函数
3. 提示生成: agent_manager.py 调用 tool.arguments 以包含在 LLM 提示中
4. 工具调用: LLM 提供参数，这些参数传递给 MCP 服务不变

API 更改

• 无外部 API 更改 - 这是一个纯粹的内部配置和参数处理

组件详情

组件 1: service.py (工具配置加载)

• 目的: 解析 MCP 工具配置并创建工具实例
• 更改要求: 解析 MCP 工具配置中的参数（类似于提示工具）
• 新功能: 从 MCP 工具配置中提取 arguments 数组，并创建 Argument 对象

组件 2: tools.py (McpToolImpl)

• 目的: MCP 工具实现包装器
• 更改要求: 接受构造函数中的参数并从 get_arguments() 中返回
• 新功能: 存储并公开配置的参数，而不是返回空列表

组件 3: Workbench (外部仓库)

• 目的: 代理工具配置的 UI
• 更改要求: 为 MCP 工具添加参数规范 UI
• 新功能: 允许用户添加/编辑/删除 MCP 工具的参数

组件 4: CLI 工具

• 目的: 命令列工具管理
• 更改要求: 支持在工具创建/更新命令中指定参数
• 新功能: 在工具配置命令中接受 arguments 参数

实施计划

阶段 1: 核心代理框架更改

• 更新 McpToolImpl 构造函数以接受 arguments 参数
• 修改 McpToolImpl.get_arguments() 以返回存储的参数，而不是空列表
• 修改 service.py 中的 MCP 工具配置解析以处理参数
• 添加 MCP 工具参数的测试
• 更新 McpToolImpl 类文档
• 添加参数解析逻辑的注释
• 更新系统架构中的参数流程文档

阶段 4: 生产部署

• 核心更改具有向后兼容性 - 无需回滚，因为功能正常
• 如果出现问题，请通过回滚 MCP 工具配置加载逻辑来禁用参数解析
• Workbench 和 CLI 更改是独立的，可以单独回滚

安全注意事项

• 没有新的攻击面: 参数是从现有配置源解析的，没有新的输入
• 参数验证: 参数传递给 MCP 工具不变 - 验证在 MCP 工具级别
• 配置完整性: 参数规范是工具配置的一部分 - 相同的安全模型适用

性能影响

• 极小的开销: 参数解析仅在配置加载期间发生，而不是请求时
• 提示大小增加: 代理提示将包含 MCP 工具参数详情，稍微增加令牌使用量
• 内存使用: 存储参数规范在对象中的增加，可以忽略不计

文档

用户文档

• 更新 MCP 工具配置指南，提供参数示例
• 在 CLI 工具的帮助文本中添加参数规范
• 创建常见 MCP 工具参数模式的示例

开发者文档

• 更新 McpToolImpl 类文档
• 添加参数解析逻辑的注释
• 文档系统架构中的参数流程

未解决的问题

1. 参数验证: 是否应该在基本结构检查之外验证参数类型/格式？
2. 动态发现: 将来增强功能，以在运行时自动从 MCP 服务器查询工具模式？

考虑的替代方案

1. 动态的 MCP 模式发现: 在运行时查询 MCP 服务器以获取工具参数模式 - 已拒绝，因为它复杂且不可靠
2. 单独的参数注册表: 将 MCP 工具参数存储在单独的配置部分中 - 已拒绝，因为与提示模板方法保持一致
3. 类型验证: JSON 模式验证参数 - 延迟，以便在初始实现中保持简单

引用

• MCP 协议规范
• 提示模板工具实现
• 当前的 MCP 工具实现