《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 查询出来，再按照 MCP（Model Context Protocol，JSON-RPC2 标准）协议结构组装成tools/list响应，告诉 AI 客户端这套网关对外提供了哪些工具能力。读完本篇，你将掌握 ToolsListHandler 的完整处理链路、buildTools 的工具元素拆分组装逻辑，以及 buildProperty 对父子字段的递归拆解原理，并能把同样的思路扩展到 RPC、MQ、数据库等更多资源的协议转换。

一、本章诉求：把 HTTP 接口描述转成 MCP 工具能力

在 AI Agent 应用场景中，公司往往有成百上千个存量业务接口（日志、监控、交易、结算、营销等）需要被 AI 智能体识别和调用。逐个为每个接口手写一套 MCP 服务显然不现实，因此 AI MCP Gateway 网关的核心定位是：通过"一键配置"的方式，把各类业务接口转换为 MCP 协议类型的接口。

落到本节的技术诉求上，要解决的核心问题是：

一个完整的 HTTP 请求的接口描述（接口地址、请求方式、出入参结构等），需要先拆解后录入数据库（网关配置表 + 工具字段配置表）；
当 AI 客户端向网关发起tools/list请求时，网关根据网关 ID（gatewayId）查询数据库配置，再按照 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 数据获取：网关配置与工具字段配置

流程的第一步，是根据网关 ID（gatewayId）从数据库中获取两份数据：

网关配置：通过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`	所属网关 ID
`tool_id`	所属工具 ID
`parent_path`	父节点路径（根节点为 NULL）
`field_name`	字段名称
`mcp_path`	子节点关联用的主键（即当前节点自身的路径标识）
`mcp_type`	MCP 协议中的字段类型
`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）对应多个 tool（1:n），tool 表可以单独配置对应的协议信息（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/数据库等更多协议的接入打下了基础。