《AI MCP Gateway》第3-8节：ToolsList 工具列表协议处理——从 HTTP 接口描述到 MCP 工具能力

文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载本篇聚焦 AI MCP Gateway 网关服务系统项目总览中的ToolsList工具列表协议处理实现网关如何把录入到数据库的 HTTP 接口描述按网关 ID 查询出来再按照 MCPModel Context ProtocolJSON-RPC2 标准协议结构组装成tools/list响应告诉 AI 客户端这套网关对外提供了哪些工具能力。读完本篇你将掌握 ToolsListHandler 的完整处理链路、buildTools 的工具元素拆分组装逻辑以及 buildProperty 对父子字段的递归拆解原理并能把同样的思路扩展到 RPC、MQ、数据库等更多资源的协议转换。一、本章诉求把 HTTP 接口描述转成 MCP 工具能力在 AI Agent 应用场景中公司往往有成百上千个存量业务接口日志、监控、交易、结算、营销等需要被 AI 智能体识别和调用。逐个为每个接口手写一套 MCP 服务显然不现实因此 AI MCP Gateway 网关的核心定位是通过一键配置的方式把各类业务接口转换为 MCP 协议类型的接口。落到本节的技术诉求上要解决的核心问题是一个完整的 HTTP 请求的接口描述接口地址、请求方式、出入参结构等需要先拆解后录入数据库网关配置表 工具字段配置表当 AI 客户端向网关发起tools/list请求时网关根据网关 IDgatewayId查询数据库配置再按照 MCP 协议结构组装向 AI 客户端返回工具能力清单。简单说就是从HTTP 接口到 MCP 协议的映射落地为库表数据 → MCP 协议结构数据的转换过程。这是整套网关协议化能力中最基础、也最核心的一环后续的tools/call工具调用依赖的正是这里产出的工具清单与参数描述。二、MCP tools/list 协议与网关中的消息策略在展开 ToolsListHandler 实现之前有必要把它放到整个网关的消息处理体系中定位。在会话层的消息处理策略中AI 客户端与 MCP 服务端的交互主要包括四类消息详见《第3-4节会话消息结构设计》处理器职责InitializeHandler协议握手初始化会话ResourcesListHandler返回可用资源列表ToolsListHandler返回服务器支持的工具列表ToolsCallHandler执行指定的工具调用这些处理器通过策略模式统一编排消息策略结构设计见《第3-4节会话消息结构设计》后续各节会逐步完成具体功能实现与服务编排以便后续支持 MCP 协议更多动作类型的扩展。本节要处理的 ToolsListHandler 在整个链路中的位置是在 Initialize 握手完成之后把网关配置的 HTTP 接口描述翻译成 AI 客户端可识别的工具列表。三、流程设计ToolsListHandler 的处理链路如图是整个 Tool/List 工具列表协议处理的流程设计从图中可以看到一条清晰的单向数据流链路ToolsListHandler.handle(gatewayId, message) → 查询网关配置queryMcpGatewayConfigByGatewayId → 查询工具字段配置列表queryMcpGatewayToolConfigListByGatewayId → buildTools(gatewayConfig, toolConfigs) 完成字段到工具列表的转换 → 封装 JSONRPCResponse { tools: toolsList } 返回3.1 数据获取网关配置与工具字段配置流程的第一步是根据网关 IDgatewayId从数据库中获取两份数据网关配置通过queryMcpGatewayConfigByGatewayId(gatewayId)查询获取该网关的基础配置信息网关身份、服务能力等HTTP 工具字段配置列表通过queryMcpGatewayToolConfigListByGatewayId(gatewayId)查询获取该网关下所有工具及其字段的配置。这部分数据本质上就是把 HTTP 请求结构体拆解后存进数据库表的行记录现在再查询出来按照 MCP 协议结构重新组装使用。这也是库表驱动业务的核心思想——配置进数据库能力从数据库来库表设计的完整说明见《第1-3节网关协议表》与《第1-4节升级网关库表》。3.2 buildTools工具元素的拆分与组装流程的第二步是对buildTools 工具细节的处理。这部分是整个转换的核心负责对元素进行拆分和组装把查询到的零散字段配置每条记录代表一个字段的元数据组装为标准 MCP 工具列表 入参 JSON Schema。从流程设计图可见buildTools(gatewayConfig, toolConfigs)接收两份入参gatewayConfig网关配置toolConfigs工具字段配置集合每个元素是McpGatewayToolConfigVO存储单个字段的元数据如field_name、mcp_path、mcp_type、mcp_desc、必填标记等。3.3 输出JSONRPCResponse 工具列表组装完成后结果以JSONRPCResponse { tools: toolsList }的协议结构返回给 AI 客户端。AI 客户端拿到这份工具清单后才能知道该网关能提供哪些能力、每个工具的入参长什么样从而在后续tools/call时按约定参数发起调用。四、buildProperty父子字段的递归拆解工具字段配置并不是扁平的——一个 HTTP 请求的入参往往存在嵌套结构。比如一个字段下面还挂着另一个字段xxxRequest01 - xxxRequest01.city的映射关系。这正是映射数据库表mcp_protocol_mapping中记录的父子字段关系。如图是 buildTools 中关于 buildProperty 递归组装的细节处理4.1 字段的层级关系如何表达在工具字段配置表对应mcp_protocol_mapping拆解后的字段记录中字段的层级关系通过以下字段表达字段含义gateway_id所属网关 IDtool_id所属工具 IDparent_path父节点路径根节点为 NULLfield_name字段名称mcp_path子节点关联用的主键即当前节点自身的路径标识mcp_typeMCP 协议中的字段类型mcp_desc字段描述必填标记标记该字段是否为必填其中parent_path与mcp_path构成了树状结构的拼接规则mcp_path是当前节点的路径主键parent_path指向其父节点的mcp_path。例如一条记录xxxRequest01其下的city字段记录parent_path xxxRequest01就表达了xxxRequest01 - xxxRequest01.city的从属关系。4.2 buildProperty 的递归逻辑buildProperty(current, childrenMap)的目标是将单个字段节点McpGatewayToolConfigVO转换为 JSON Schema 的property属性对象。其处理过程分为四步初始化以当前字段节点current为基础初始化一个属性节点填充字段名、类型、描述等元数据判断子节点通过childrenMap父路径与子节点集合的映射字典用于维护字段之间的层级关联判断当前节点是否存在子节点递归构建若存在子节点则对子节点排序后递归调用buildProperty组装子属性若无子节点则直接返回当前属性组装 Schema 属性将递归得到的子属性挂载到父节点的属性下并追加必填字段标记最终返回完整的属性对象。之所以需要一层一层地递归循环正是因为 HTTP 入参可能嵌套多层结构如请求体 - 地址对象 - 城市 - 名称只有逐层拆解才能还原完整的层级组装出符合 MCP 协议要求的嵌套 JSON Schema让 AI 客户端能准确理解并构造入参。五、库表设计的演进从协议注册到工具/协议拆分ToolsListHandler 之所以能通过一个gatewayId拿到网关配置 工具字段配置两份数据背后是库表设计的两次演进支撑旧版设计mcp_protocol_registry协议注册表一个表中同时包含工具描述和 HTTP 接口协议信息。功能理解和编码实现直观适合上手学习但一个网关对应工具能力扩展受限。新版设计详见《第1-4节升级网关库表》拆分出tool 工具表实现一个网关mcp_gateway对应多个 tool1:ntool 表可以单独配置对应的协议信息HTTP也可以是其他协议后续扩展时增加新表即可并在 tool 上设计协议类型以便于扩展支持不同的协议对接。对应的代码侧改造在《第3-10节评审库表升级代码》中以代码评审的方式逐项讲解其中与本节直接相关的变更点是ToolsListHandler 旧版从McpGatewayToolConfigVO定义的工具和映射拿到 list 数据后做拆分新版定义了McpToolConfigVO工具部分与McpToolProtocolConfigVO协议部分两个值对象由工具引入协议信息。也就是说新版数据模型把工具本身和工具的协议类型解耦工具清单的组装buildTools关注工具部分协议细节HTTP 还是 RPC由协议部分承载为后续 ToolsCall 按协议类型做策略调用打下基础。六、与 Initialize、ToolsCall 的衔接ToolsList 在整条 MCP 消息链中起着承上启下的作用承上AI 客户端接入时先经过 InitializeHandler 完成协议握手见《第3-7节协议消息处理-Initialize》把原来硬编码的案例操作改为通过网关 ID 与数据库配置数据关联启下AI 客户端拿到 tools/list 返回的工具清单后用户发起请求时网关进入 ToolsCallHandler接收 AI 客户端传来的根据工具列表说明格式化好的参数解析请求参数并做协议调用见《第3-9节协议消息处理-ToolsCall》。需要注意的是当前章节 gateway → tool 还是1:1的结构先用一个简单结构把整个流程跑通有了基础后再深入拆分理解会更好。这也符合整个课程先跑通主链路、再细化拆分的推进节奏。七、协议扩展HTTP 之外的能力本节虽然以 HTTP 接口为例讲解 ToolsList 的转换实现但方案本身具有很强的扩展性像是 HTTP 可以做那么 RPC、MQ、数据库等各类资源你也可以转换为 MCP 服务协议进行使用。从源码结构看这种扩展能力正是由工具表 协议类型的模型设计支撑的网关的协议转换逻辑与具体协议实现解耦新增一种协议时只需新增对应的协议类型与协议处理策略而无须改动工具列表的组装骨架。此外这套网关能力甚至还可以对接硬件设备如 rs232 串口通信让 MCP 服务管理硬件设备。小结ToolsList 协议处理是 AI MCP Gateway 网关库表驱动协议转换的关键落地环节它以网关 ID 为入口查询网关配置与工具字段配置通过 buildTools 完成工具元素拆分组装再由 buildProperty 以递归方式还原mcp_protocol_mapping中的父子字段层级最终以JSONRPCResponse { tools: toolsList }的 MCP 协议结构交付给 AI 客户端。理解这一节你就掌握了网关对外能力声明的实现原理也为后续 ToolsCall 的工具调用、以及 RPC/MQ/数据库等更多协议的接入打下了基础。赞分享文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载相关推荐AI MCP Gateway 网关ToolsCall 工具调用协议消息处理与 HTTP 接口对接实战AI MCP Gateway 网关ToolsCall 工具调用协议消息处理与 HTTP 接口对接实战 output_article AI MCP Gatew文档教程后端《AI MCP Gateway 网关服务系统》第3-14节实战解析 Swagger 标准 OpenAPI 协议把 HTTP 接口一键导入为 MCP 网关协议《AI MCP Gateway 网关服务系统》第3 14节实战解析 Swagger 标准 OpenAPI 协议把 HTTP 接口一键导入为 MCP 网关协议文档教程后端AI MCP Gateway 协议域协议存储处理从协议解析、落库到 MCP 识别链路验证实战AI MCP Gateway 协议域协议存储处理从协议解析、落库到 MCP 识别链路验证实战 导读 本文围绕 AI MCP Gateway 网关服务系统中的文档教程后端上一篇京东NutUI80组件打造企业级多端移动开发终极方案下一篇OpenResume图像优化插件Webpack与Vite集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考