企业官网建设流程全解析

Higress stock-helper MCP Server：基于 REST-to-MCP 将云市场股票行情 API 暴露给 AI 的完整实现

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

stock-helper 是 Higress 仓库中mcp-servers目录下基于REST-to-MCP机制实现的 MCP Server 示例：它把阿里云云市场上"股票实时行情查询"类 API（覆盖 A 股、港股、美股、全球指数、内外盘期货与外汇）转换为 21 个 MCP 工具，让 AI Agent 可以通过标准的tools/list/tools/call协议直接获取 K 线、报价、排行等行情数据。本文基于 mcp-stock-helper 中文文档、mcp-server.yaml 与 api.json 三个核心文件展开，带你完整掌握其订阅配置、工具参数体系与底层请求/响应模板的实现原理。

一、背景：什么是云市场 API MCP 服务

按照 README_ZH.md 的定义：

• 阿里云云市场是生态伙伴的交易服务平台，为合作伙伴提供覆盖上云、商业化和售卖的全链路服务，帮助客户高效获取、部署和管理优质生态产品。其 API 服务涵盖应用开发、身份验证与金融、车辆交通与物流、企业服务、短信与运营商、AI 应用与 OCR、生活服务等多个类目。
• 云市场 API 依托 Higress 提供 MCP 服务：用户只需在云市场完成订阅并获取 AppCode，再把 AppCode 配置到 Higress MCP Server 中，即可将云市场 API 无缝集成进 MCP 工具生态。

对 stock-helper 而言，其上游数据源就是云市场上【聚美智数】的"股票实时行情查询"API。这一点可以从 api.json 的 OpenAPI 3.0.1 定义中确认：该文件声明了 19 个POST接口（路径形如/finance/a-shares-kline、/finance/hk-stocks-price），请求体统一为application/x-www-form-urlencoded，响应为application/json，与 mcp-server.yaml 中 21 个工具的requestTemplate.url一一对应。

二、准备工作：订阅 API 并获取 AppCode

文档给出的接入步骤是本文所有配置的前提：

1. 进入云市场 API 详情页，订阅该 API（可优先使用免费试用）；
2. 使用阿里云账号登录云市场用户控制台，查看已订阅 API 服务的AppCode，并配置到 Higress MCP Server 的配置中。注意：订阅 API 服务后获得的 AppCode 对该账号订阅的所有 API 服务是相同的，一个 AppCode 即可访问全部已订阅服务；
3. 云市场用户控制台会实时展示已订阅的预付费 API 服务可用额度，免费试用额度用完后可以重新订阅。

拿到 AppCode 后，它在配置体系中的位置就是下面server.config.appCode：

server: name: stock-helper config: appCode: "" # 填入你在云市场获取的 AppCode

server.name必须与插件内注册的 MCP Server 名一致（REST-to-MCP 的机制详见 MCP Server 实现指南），网关据此把请求路由到正确的 Server。使用 MCP Server 类插件需要Higress 2.1.0 及以上版本（见 mcp-server 插件说明）。

三、工具总览：21 个行情工具的参数体系

stock-helper 覆盖了股票、期货与外汇三大市场的多类查询能力。以下参数说明完整继承自 README_ZH.md，并依据 mcp-server.yaml 补全了type（K 线周期）等枚举值和必填/可选标记。

3.1 A 股（4 个工具）

3.2 全球指数（2 个工具）

3.3 内盘期货（3 个工具）

注：yaml 中该工具名实际拼写为chinna-futures-contract（见 mcp-server.yaml 第 431 行），调用时需使用配置中的原始名称。

3.4 外盘期货与外汇（5 个工具）

3.5 港股（3 个工具）

3.6 美股（4 个工具）

四、配置深度解析：mcp-server.yaml 的 REST-to-MCP 结构

mcp-server.yaml 是整个 stock-helper 的核心交付物，它不需要写一行 Go 代码，纯靠声明式配置完成"REST API → MCP 工具"的转换。以china-stock-candlestick（A 股 K 线）为例，其完整结构如下：

server: name: stock-helper config: appCode: "" tools: - name: china-stock-candlestick description: 中国A股K线查询 args: - name: limit description: 返回条数，默认10 type: string position: body - name: symbol description: 股票代码，交易所标识需要小写后放在数字之前 type: string required: true position: body - name: type description: k线类型，1:1分钟，5:五分钟；15:15分钟；30:30分钟，60:60分钟，120:120分钟，240:日K，1200:周K，7200:月K，86400:年K type: string required: true position: body requestTemplate: url: https://jmqqgphqcx.market.alicloudapi.com/finance/a-shares-kline method: POST headers: - key: Content-Type value: application/x-www-form-urlencoded - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: '{{uuidv4}}' responseTemplate: prependBody: |+ # API Response Information Below is the response from an API call. ... ## Response Structure > Content-Type: application/json - **code**: 返回码，详见返回码说明 (Type: integer) - **data**: (Type: object) - **data.list[].close**: 当前收盘价 (Type: string) - **data.list[].day**: 数据时间 (Type: string) ... ## Original Response

各字段的作用可逐条对应到源码与文档：

• args：定义 MCP 工具的入参。required: true会进入工具inputSchema的required列表（对照 api.json 中各接口required: ["symbol", "type"]的定义完全一致）；position: body表示参数放入请求体。对application/x-www-form-urlencoded请求，框架会把 args 渲染进 form body。
• requestTemplate：声明式构造上游 HTTP 请求。模板引擎是GJSON Template（Go template 语法 + GJSON 路径语法，内置全部 70+ 个 Sprig 函数），支持：
  • {{.config.appCode}}：读取server.config下的配置值——这正是 AppCode 注入认证头的位置；
  • {{.args.xxx}}：读取 MCP 调用时传入的工具参数；
  • {{uuidv4}}：内置模板函数，为每次请求生成随机X-Ca-Nonce防重放头（云市场 API 的鉴权要求）。
• responseTemplate.prependBody：在原始 JSON 响应之前拼接一段"响应结构说明"。每个工具的 prependBody 都内置了该接口全部字段的中文字典（例如 A 股 K 线的close/day/high/low/ma_price5等），最后以## Original Response结尾接原始 JSON。这是面向 LLM 的关键设计：让模型在读到原始数据前先理解每个字段的含义与类型，显著提升 AI 对行情数据的解析准确性。

从源码结构看，这一机制实现在 rest_server.go：ResponseTemplate结构体定义了Body、PrependBody、AppendBody三个字段（约第 79 行），并明确校验"PrependBody/AppendBody 不能与 Body 同时使用"（约第 208-210 行）；工具调用时执行result = PrependBody + rawResponse + AppendBody（约第 912-913 行）。rest_server_test.go 中的TestPrependBodyAndAppendBody等用例验证了该拼接逻辑与"同时指定 Body 与 PrependBody 时报错"的边界行为。stock-helper 的全部 21 个工具统一采用prependBody（字段字典）+ 原始响应的模式，是这一机制的典型应用。

五、请求链路：从 MCP 调用到云市场 API

把配置、实现与协议串起来，一次完整的工具调用链路如下：

1. 发现：AI 客户端向 Higress 发送 MCPtools/list，网关根据 WasmPlugin 配置返回stock-helper下 21 个工具的名称、描述与inputSchema（schema 即由args渲染而来）；
2. 调用：客户端发送tools/call，携带如{"name": "china-stock-price", "arguments": {"symbol": "sz000002,bj430047"}}；
3. 请求构造：REST Server 按requestTemplate渲染url/method/headers/body，注入Authorization: APPCODE <你的AppCode>与随机X-Ca-Nonce，向云市场上游接口发出POST application/x-www-form-urlencoded请求；
4. 响应加工：上游返回{"code": 200, "msg": "成功", "taskNo": "...", "data": {...}}后，框架在 raw JSON 前拼上该工具专属的字段字典（prependBody）作为 MCP 工具结果返回给 AI；
5. 网关能力复用：整条链路运行在 Higress 数据面内，因此认证、限流、审计日志、可观测性等网关统一能力同样覆盖 MCP 工具调用（见 MCP Server 实现指南 中关于网关托管 MCP Server 收益的说明）。

以 api.json 中港股报价接口的示例响应为例，data以股票代码为 key（如08026、02203），每个对象包含price（实时价格）、changeRate（涨跌率）、52week_high/52week_low（52 周高低）、pe（市盈率）、update_time（数据时间戳）等字段——这与 yaml 中china-hongkong-price的 prependBody 字段说明逐一对应，code=200表示成功，taskNo为本次请求号。

六、部署与调用要点

• 载体插件：REST-to-MCP 能力内置于 MCP Server 插件。可将 stock-helper 的工具配置放入 mcp-server 类插件的 WasmPlugindefaultConfig中，或按 MCP Server 实现指南 的 All-in-One 模式将其注册进聚合插件。引用插件的标准 WasmPlugin 形态：

  apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: name: mcp-server namespace: higress-system spec: selector: matchLabels: higress: higress-system-higress-gateway url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/mcp-server:<version>

• 关键约束：

  • server.name（stock-helper）必须与插件内注册的 Server 名完全一致，否则请求无法路由到该 Server；
  • config.appCode为空时请求会被上游以鉴权失败拒绝，务必填入云市场 AppCode；
  • 若需要进一步收敛工具暴露面，可在插件配置中使用allowTools白名单只放行部分工具（如仅保留china-stock-price、china-stock-rank）；
  • 版本前提：MCP Server 类插件要求 Higress 2.1.0 及以上。

• 验证方式：部署后可用任意 MCP 客户端连接 Higress 的 MCP 端点，先tools/list确认 21 个工具及其 schema，再发起tools/call验证真实行情返回。行情类接口依赖云市场账号额度，免费试用额度用尽后需按第二节步骤重新订阅。

七、小结

stock-helper 是 Higress REST-to-MCP 机制的教科书式样本：

• 零代码集成：21 个 MCP 工具完全由 mcp-server.yaml 声明式定义，上游契约则固化在 api.json 的 OpenAPI 3.0.1 文档中，两者可交叉验证参数与必填项的一致性；
• LLM 友好的响应设计：prependBody为每个工具注入字段字典，解决"原始 JSON 对 AI 不友好"的核心问题，其拼接与互斥校验逻辑可在 rest_server.go 中溯源；
• 完整参数体系：从 A 股复权的fuquan、排行的market/sort枚举到 K 线type的分钟级/日/周/月/年周期编码，本文第三节表格可作为直接可查的参数手册；
• 网关托管收益：AppCode 集中配置于网关侧而非散落在各应用，工具调用天然复用 Higress 的认证、限流与可观测能力，符合 MCP 实现指南 所描述的托管模式。

如果你想接入自己的云市场 API，只需参照本文的requestTemplate+responseTemplate结构编写一份 mcp-server.yaml，即可复用完全相同的机制。

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