企业官网建设流程全解析

Higress IP 归属地查询 MCP 服务：mcp-ip-query 配置详解与 IP 自动获取原理

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

本篇围绕 Higress 仓库中的 IP 归属地查询 MCP 服务（plugins/wasm-go/mcp-servers/mcp-ip-query）展开，覆盖该服务的功能定位、两个查询工具（升级版 / 精准版）的参数与响应结构、完整 MCP Server 配置与 OpenAPI 规范，并结合仓库源码剖析“用户未提供 IP 时自动获取真实 IP”的实现机制，帮助读者完整理解并部署一套可被 LLM 直接调用的 IP 位置查询 MCP 工具链。

服务定位：基于 IP 分析用户所在位置

该服务可以基于用户的 IP 地址分析用户所在位置，核心能力包括：

• IP 自动获取：可以无需用户主动提供 IP，基于 API 网关的能力自动获取发起请求的真实 IP（模板函数getRealIP）；
• 地理位置解析：返回国家、省份、城市、区县等归属地信息，支持 IPv4 与 IPv6；
• 时区与本地时间：位置信息还可以用于确定用户所在的时区，从而提供基于用户位置的精确本地时间。

该服务对接的是阿里云云市场（API Marketplace）上的“IP 归属地查询”API 商品（商品编号cmapi00054907，可在阿里云云市场控制台搜索并订阅）。云市场 API 依托 Higress 提供 MCP 服务：只需在云市场完成订阅并获取 AppCode，再通过 Higress MCP Server 进行配置，即可将云市场 API 无缝集成为大模型可调用工具（背景说明参见 README_ZH.md）。

准备工作：申请 AppCode

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

MCP Server 配置文件完整解析

服务的核心定义位于 mcp-server.yaml，声明了一个名为ip-query的 MCP Server 及其两个工具：

server: name: ip-query config: appCode: "" # 在阿里云云市场订阅后获得的 AppCode tools: - name: ip-address-query # 工具一：IP地址查询升级版 description: 根据IP地址查询归属地信息，包含国家、省、市等信息，可以无需主动提供IP，支持IP自动获取 args: - name: ip description: 要查询的ip，如果用户没有提供ip，可以传空字符串，该mcp服务会自动获取用户IP type: string required: true requestTemplate: url: https://jmipquery3.market.alicloudapi.com/ipv3-group/ip/address-query-v2 method: POST headers: - key: Content-Type value: application/x-www-form-urlencoded - key: Authorization value: APPCODE {{.config.appCode}} # 使用 server.config.appCode 注入认证 - key: X-Ca-Nonce value: '{{uuidv4}}' # 每次请求生成唯一 nonce，防重放 body: | ip={{ if empty .args.ip }}{{ getRealIP }}{{ else }}{{ .args.ip }}{{ end }} responseTemplate: prependBody: |+ # API Response Information ... - name: ip-address-query-precision-version # 工具二：IP地址查询精准版 ...

关键配置点说明：

• server.config.appCode：全局配置项，两个工具通过 Go 模板语法{{.config.appCode}}注入到Authorization请求头（格式为APPCODE <appCode>，这是阿里云云市场 API 的 APPCODE 认证方式）；
• X-Ca-Nonce: '{{uuidv4}}'：使用 MCP Server 框架内置的uuidv4模板函数为每次请求生成唯一随机串，满足云市场 API 网关的防重放校验要求；
• 请求体模板：ip={{ if empty .args.ip }}{{ getRealIP }}{{ else }}{{ .args.ip }}{{ end }}—— 这是“IP 自动获取”的落点，见下文源码剖析；
• responseTemplate.prependBody：在原始 API 响应前拼接一段字段说明，帮助 LLM 理解返回的 JSON 结构（机制见下文）。

responseTemplate：用字段说明增强 LLM 的响应理解

两个工具均配置了prependBody，内容为一段结构化的字段说明 + 原始响应。例如升级版工具声明了如下响应字段：

- **code**: 详见code返回码说明 (Type: integer) - **data**: (Type: object) - **data.city**: 市 (Type: string) - **data.code**: 区县编码 (Type: string) - **data.district**: 区县 (Type: string) - **data.latitude**: 纬度 (Type: string) - **data.longitude**: 经度 (Type: string) - **data.nation**: 国家 (Type: string) - **data.province**: 省份 (Type: string) - **msg**: code对应的描述 (Type: string) - **taskNo**: 本次唯一请求号 (Type: string)

从源码实现看，该机制在 rest_server.go 中执行：当工具配置了PrependBody或AppendBody时，最终返回给大模型的内容为PrependBody + 原始响应 + AppendBody的拼接结果；同时框架在 rest_server.go 中校验Body与PrependBody/AppendBody不能同时使用。相关拼接行为的测试用例可见 rest_server_test.go。

两个查询工具详解

工具一：ip-address-query（IP 地址查询升级版）

• 用途：允许用户输入一个 IP 地址（支持 IPv6），返回该地址对应的详细位置信息；
• 使用场景：适用于需要获取访客或客户端精确地理定位的应用开发，如在线广告投放、内容本地化服务等；
• 请求参数：
  • ip（必填）：待查询的 IP 地址；若用户未提供可传空字符串，MCP 服务会自动获取用户 IP；
• 接口：POST https://jmipquery3.market.alicloudapi.com/ipv3-group/ip/address-query-v2；
• 响应结构：JSON 格式，包含查询结果状态码code、地理位置信息（城市名、区县编码等）、状态消息msg及本次请求的任务编号taskNo；
• 注意点：除了基础位置信息外，还包含经纬度坐标（data.latitude/data.longitude）。

依据 api.json 中的 OpenAPI 定义（operationId: IP地址查询升级版），该接口响应示例为：

{ "code": 200, "msg": "成功", "taskNo": 69564903663951240000, "data": { "longitude": "120.298501", "latitude": "30.41875", "nation": "中国", "province": "浙江省", "city": "杭州市", "district": "余杭区", "code": "330110" } }

工具二：ip-address-query-precision-version（IP 地址查询精准版）

• 用途：在基本地理位置之外增加更多维度信息，如运营商（isp）、所属机构（owner）、时区（timezone）、邮编（zipcode）、大洲（continent）、国家编码（areaCode）等；对于IPv4 地址不返回经纬度；
• 使用场景：适合不仅关心访问者来自哪里、还需了解其网络环境特点的服务，如网络安全监控系统或全球分布式应用设计；
• 请求参数：
  • ip（必填）：需查询的 IP 地址，同样支持空字符串触发自动获取；
• 接口：POST https://jmipquery3.market.alicloudapi.com/ip/query-v3；
• 响应结构：同样为 JSON，字段从大洲到邮编均有覆盖，并保留taskNo任务标识符以便追踪；
• 特点：增强信息全面性，且对 IPv4 和 IPv6 采取不同处理（IPv4 不返回经纬度），是更灵活的选择。工具描述中还给出使用建议：“ip-address-query 如果查询不到，可以使用此工具再查询一次”，即两者构成主备查询策略。

依据 api.json（operationId: IP地址查询精准版），该接口响应data对象包含以下字段：

“IP 自动获取”能力如何落地：getRealIP 模板函数

配置中{{ getRealIP }}并非普通模板变量，而是 Higress MCP Server 框架注册的一个模板函数。从源码实现看（rest_server.go），框架在templateFuncs()中注册了两个函数：

// Get IP from header, fallback to socket if not available "getRealIP": func() string { ipStr, _ := proxywasm.GetHttpRequestHeader("x-forwarded-for") if ipStr != "" { return parseIP(ipStr, true) } // Fallback to socket IP if header is not available bs, _ := proxywasm.GetProperty([]string{"source", "address"}) if len(bs) > 0 { return parseIP(string(bs), false) } return "" },

其取 IP 的优先级为：

1. 优先读取X-Forwarded-For请求头（经过网关/代理链路的真实客户端 IP），parseIP会取该头中逗号分隔的第一个 IP；
2. 回退到 Wasm 插件运行时属性source.address（即 Envoy 记录的 socket 对端地址）；
3. 两者都取不到时返回空串。

辅助函数parseIP（rest_server.go）兼顾了 IPv4（按host:port拆分）与 IPv6（形如[::1]:port的方括号写法）两种格式，保证传给云市场 API 的是纯 IP 地址。这正是“可以无需主动提供 IP，基于 API 网关的能力自动获取”在代码层面的具体实现：LLM 调用工具时若未提供ip参数，请求模板自动代入当前 MCP 会话请求方的真实 IP，实现“查我自己（或当前用户）的归属地”这类自然语言诉求。

文件清单与延伸阅读

该服务目录下的完整文件包括：

• README.md：英文说明（本文主要来源）；
• README_ZH.md：中文说明，另补充了“云市场 API MCP 服务”概念与订阅步骤；
• mcp-server.yaml：MCP Server 完整配置（工具定义、请求/响应模板）；
• api.json：上游云市场 API 的 OpenAPI 3.0 规范（openapi: 3.0.1，服务器地址jmipquery3.market.alicloudapi.com），可据此核对两个接口的请求体与响应 schema。

框架侧的通用机制（模板函数、requestTemplate/responseTemplate解析与校验）可进一步参考 rest_server.go 与 rest_server_test.go，以及 MCP Server 目录的整体说明 plugins/wasm-go/mcp-servers/README_zh.md。

使用限制与注意事项

1. 必须配置 AppCode：server.config.appCode为空时，Authorization头将携带空值，云市场 API 会鉴权失败，因此上线前必须填入订阅获得的 AppCode；
2. 免费额度：云市场 API 存在免费试用额度，额度用尽后需重新订阅（控制台实时展示可用额度）；
3. IPv4 与 IPv6 的差异：精准版对 IPv4 不返回经纬度，若业务强依赖经纬度坐标，应优先使用升级版（ip-address-query），查不到时再用精准版兜底；
4. 自动获取 IP 的前提：getRealIP依赖请求经过 Higress 网关且能取到X-Forwarded-For或 socket 地址；若两者均不可得，将向 API 传入空值导致查询失败，此时应由 LLM 显式传入ip参数。

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