企业官网建设流程全解析

Higress 配置驱动 MCP Server 实战：Shebao Tools 社保、公积金、个税与工伤计算工具

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress

本文以 Higress 仓库中的mcp-shebao-toolsMCP Server 为例，完整解析一个纯配置驱动（REST-to-MCP）MCP Server 的设计与落地：它不编写任何 Go 代码，仅凭一份mcp-server.yaml就将社保、公积金、残保金、个人所得税、工伤赔付与工亡赔付等 17 类计算服务转化为 AI 可直接调用的 MCP 工具。读完本文，你能掌握 REST-to-MCP 配置格式的每个字段含义（server、tools、args、requestTemplate）、模板变量的渲染机制，以及知识库导入与 MCP Client 集成等完整操作步骤，并能照此为任意 REST API 编写同类 MCP Server。

一、这是什么：一个无需写代码的 MCP Server

mcp-shebao-tools是一个模型上下文协议（MCP）Server 实现，集成了社保、公积金、残保金、个税、工伤赔付和工亡赔付的计算功能。它的目录结构非常简洁，只包含 4 个文件：

plugins/wasm-go/mcp-servers/mcp-shebao-tools/ ├── README.md # 英文说明文档 ├── README_ZH.md # 中文说明文档 ├── city_data.xls # 城市数据知识库文件 └── mcp-server.yaml # 核心：REST-to-MCP 工具定义

与 amap-tools 这类需要用 Go 语言实现Description()、InputSchema()、Create()、Call()四个方法的传统 MCP Server 不同，mcp-shebao-tools完全没有 Go 源码。它依赖的是 Higress 内置的REST-to-MCP 能力：在插件配置中用 YAML 声明工具的名称、描述、入参和请求模板，网关即可自动把 REST API 转成 MCP 工具，供 AI 助手调用。这一机制实现在 rest_server.go 中，且“内置于所有 MCP server，可与 all-in-one 插件配合使用”（见 MCP Server 实现指南）。

从能力上看，该 Server 覆盖五大类计算场景：

• 社保与公积金：输入城市与薪资信息，返回缴费明细；
• 残保金（残疾人就业保障金）：输入企业员工数量与平均薪资，返回应缴金额与优化建议；
• 个人所得税：输入工资/劳务报酬，返回应缴税额；
• 工伤赔付：输入伤残等级与薪资信息，返回各项赔付金额；
• 工亡赔付：输入相关城市与工资信息，返回赔偿金。

二、工具全览：17 个 MCP 工具及其用途

README.md 与 mcp-server.yaml 中列出的工具清单如下（按 README 编号）：

需要留意两处文档与配置的事实差异（以 mcp-server.yaml 实际内容为准）：

1. README 清单中列出了calcCityYearEndBonus（全年一次性奖金计税），但当前 YAML 中并未定义该工具，实际生效的工具为 16 个；
2. calcCityLaobar的描述是“计算一次性劳务报酬应缴纳税额”，但其requestTemplate.url指向的是/agent/tools/shebao/getInsOrg路径，与getCityIns、getshebaoInsOrg共用同一后端接口。从源码结构看，这几个查询类工具复用了同一个社保政策查询端点，实际劳务报酬计税可能需要后端依据参数自行路由，部署前建议以真实调用验证为准。

三、mcp-server.yaml 配置全解析

整个 Server 的行为完全由 mcp-server.yaml 决定，其结构分为server（Server 元信息）与tools（工具列表）两大块。

3.1 server 段：名称与鉴权凭据

server: name: shebao-tools-api-server config: apikey: ""

• name：MCP Server 的名称，本例为shebao-tools-api-server。按 MCP Server 实现指南 的说明，name字段是系统识别并路由请求到目标 MCP Server 的依据，必须与加载侧使用的名称完全一致；
• config.apikey：第三方后端服务（agent-tools.jrit.top）的 API 密钥占位符。所有工具的请求模板都通过{{.config.apikey}}引用它，密钥因此集中管理、不出现在工具参数中，避免了密钥被 AI 侧透传泄露。

3.2 tools 段：以 calcCityNormal 为例的参数定义

calcCityNormal（根据工资计算该城市个税缴纳明细）是参数最多的工具，最能体现参数声明的写法：

- name: calcCityNormal description: |+ 根据工资计算该城市个税缴纳明细。 - 输入税前工资、城市名称、城市编码、城市ID等信息。 - 考虑社保、公积金、专项附加扣除等因素。 - 返回个税缴纳明细。 args: - name: salaryPay description: 税前工资 type: integer required: true - name: areaName description: 城市名称 type: string required: true - name: areaCode description: 城市编码 type: string required: true - name: areaId description: 城市ID type: integer required: true - name: sbFlag description: 是否缴纳社保 type: integer required: false # ……其余可选参数：gjjFlag、sbCode、sbBase、gjjCode、gjjBase、 # znjyCount（子女教育数量）、znjyCode（子女教育扣除方式）、 # zfzjCode（住房租金）、zfdkCode（住房贷款利息）、 # jxjyCode（继续教育）、sylrCode（赡养老人）、sylrFee（赡养老人数量）、 # yyzhCount（三岁以下婴幼儿照护数量）、yyzhCode（婴幼儿照护扣除方式）、 # avgMonthYanglaoFee（平均每月个人养老金） requestTemplate: argsToUrlParam: true url: https://agent-tools.jrit.top/agent/tools/geshui/calcNormal?jr-api-key={{.config.apikey}} method: POST headers: - key: Content-Type value: application/json

参数声明的要点：

• type支持string、integer、number、object等 JSON Schema 类型。如工伤计算工具getCityCalcInjury的initInjuryCYiLiaoFeiInfo（医疗费）等十余个费用项均为object类型嵌套入参；
• required: true/false决定 AI 端调用时的必填校验；本例中几乎所有工具都要求“城市三元组”（areaName、areaCode、areaId）作为必填项，以精确定位到城市政策数据；
• description直接写入 MCP 工具的 inputSchema 描述中，AI 依赖这些中文描述决定传参，因此描述质量直接影响工具调用成功率。

3.3 各工具入参速查

结合 YAML 定义，各工具的必填参数整理如下：

3.4 requestTemplate：请求如何被构造

每个工具末尾的requestTemplate描述了“MCP 工具调用如何变成一次真实的 HTTP 请求”，全部 16 个工具遵循统一模式：

requestTemplate: argsToUrlParam: true # 将工具参数拼接到 URL 查询参数 url: https://agent-tools.jrit.top/agent/tools/...?jr-api-key={{.config.apikey}} method: POST headers: - key: Content-Type value: application/json

• argsToUrlParam: true：把 AI 传入的所有工具参数自动拼到 URL 查询串上；
• {{.config.apikey}}：Go template 变量，取自server.config段，渲染后追加为jr-api-key查询参数；
• 唯一的例外是getCityPersonDeductRules，其headers: []为空列表，且不设置 Content-Type。

这些字段并非随意约定，而是由 REST-to-MCP 引擎的结构体精确解析。在 rest_server.go 中可以确认对应定义：

// RestToolRequestTemplate defines how to construct the HTTP request type RestToolRequestTemplate struct { URL string `json:"url"` Method string `json:"method"` Headers []RestToolHeader `json:"headers"` Body string `json:"body"` ArgsToJsonBody bool `json:"argsToJsonBody,omitempty"` // Use args as JSON body ArgsToUrlParam bool `json:"argsToUrlParam,omitempty"` // Add args to URL parameters ArgsToFormBody bool `json:"argsToFormBody,omitempty"` // Use args as form-urlencoded body Security SecurityRequirement `json:"security,omitempty"` } // RestToolResponseTemplate defines how to transform the HTTP response type RestToolResponseTemplate struct { Body string `json:"body"` PrependBody string `json:"prependBody,omitempty"` // Text to insert before the response body AppendBody string `json:"appendBody,omitempty"` // Text to insert after the response body }

由此可知本例配置的能力边界：YAML 中只用了ArgsToUrlParam，此外引擎还支持ArgsToJsonBody（参数转 JSON 请求体）、ArgsToFormBody（转 form-urlencoded 请求体）以及responseTemplate（用 GJSON Template 把后端 JSON 响应渲染成对 AI 友好的文本）。shebao 系列工具未配置responseTemplate，意味着后端返回的 JSON 会原样作为工具结果交给 AI 消费——对于结构化计算结果（金额、明细）这种用法是合理的。

参数本身还支持声明式定位。rest_server.go 中RestToolArg的Position字段注释写明：参数可放置在query、path、header、cookie、body五个位置；Type字段遵循 JSON Schema 类型（string、number、integer、boolean、array、object），Required、Default、Enum、Items（数组元素）、Properties（对象属性）均可声明。mcp-shebao-tools 借助argsToUrlParam全局置为 query 位置，属于最简配置；若后端接口要求参数放在 body 或 header 中，可改用上述字段精细控制。

此外，同文件中的RestMCPConfig还定义了SecuritySchemes、DefaultDownstreamSecurity（客户端到网关的默认鉴权）与DefaultUpstreamSecurity（网关到后端的默认鉴权）三项安全配置，shebao 配置未启用，其上游鉴权完全靠 URL 中的jr-api-key完成。

四、使用步骤

以下步骤综合了 README.md 与 README_ZH.md 的教程内容。

4.1 获取 API Key

后端计算服务（agent-tools.jrit.top，即“聚仁人力”）需要凭据访问：

1. 注册账号（README_ZH 给出的注册地址为 check.junrunrenli.com）；
2. 联系服务方开通 MCP 社保计算工具服务并说明账号，获得 API Key。

4.2 导入城市知识库

将 city_data.xls 导入你的 AI 应用知识库。该文件是各工具areaId/areaCode/areaName参数的取值来源——AI 需要先从知识库检索出目标城市的编码与 ID，才能正确填充计算工具的必填参数。这是“RAG + 工具调用”组合的典型形态：知识库提供静态城市数据，MCP 工具提供动态计算能力。

4.3 配置 API Key

在 mcp-server.yaml 的server.config段将apikey字段设置为有效的 API 密钥：

server: name: shebao-tools-api-server config: apikey: <你的API密钥>

4.4 集成到 MCP Client

在 Higress 控制台/用户的 MCP Client 界面，将上述配置添加到 MCP Server 列表。按 MCP Server 实现指南 的插件配置约定，配置中还可以附加allowTools白名单，只放行指定工具：

server: name: shebao-tools-api-server config: apikey: <你的API密钥> allowTools: - calculator - calcCityNormal

配置生效后，MCP Client 即可通过标准 MCP 协议发现这 16 个工具（tools/list），并在对话中按需调用（tools/call），例如问“月薪 20000 在北京要缴多少社保和公积金”时，AI 可先查知识库取得北京的城市编码，再调用calculator工具获得缴费明细。

五、适用前提与注意事项

• 版本要求：MCP server 插件需要 Higress 2.1.0 及以上版本（见 MCP Server 实现指南）；
• 外部服务依赖：所有计算请求最终发往第三方后端 agent-tools.jrit.top，需要有效的jr-api-key，且网络可达该地址；apikey留空时工具调用会携带空密钥，调用将失败；
• 文档一致性：README 清单中的calcCityYearEndBonus未在当前 YAML 中实现，如需要全年一次性奖金计税功能，需参照现有条目在tools中补充定义（参照 MCP Server 实现指南 的 REST-to-MCP 配置格式，为对应 REST 端点编写requestTemplate即可，无需写代码）；
• 扩展性：REST-to-MCP 引擎内置于所有 MCP server，同样适用于 all-in-one 插件的多 Server 合并部署；模板语法（GJSON Template）支持完整的 GJSON 路径语法与 Sprig 函数集，可用于更复杂的请求构造与响应改写，具体能力边界可参考 rest_server.go 及其测试 rest_server_test.go。

六、小结

mcp-shebao-tools是 Higress “配置即 MCP Server”理念的一个完整范例：一份 YAML 定义了 16 个工具的名称、参数 Schema 与请求模板，配合一个城市数据知识库文件，就把社保公积金、残保金、个税、工伤与工亡赔付这五类专业性强的计算服务纳入了 AI 的工具调用体系。其实现路径——server.name对齐路由、config.apikey集中管理凭据、args声明入参、argsToUrlParam构造请求——对任何已有 REST API 想要接入 MCP 生态的团队，都是可直接照搬的低成本模板。

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress