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进入阿里云云市场该 API 的详情页订阅该 API可优先使用免费试用前往云市场用户控制台使用阿里云账号登录后查看已订阅 API 服务的AppCode并配置到 Higress MCP Server 配置中。注意订阅 API 服务后获得的 AppCode 对该账号订阅的所有 API 服务通用一个 AppCode 即可访问所有已订阅服务控制台会实时展示已订阅预付费 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-queryIP 地址查询升级版用途允许用户输入一个 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-versionIP 地址查询精准版用途在基本地理位置之外增加更多维度信息如运营商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.jsonoperationId: IP地址查询精准版该接口响应data对象包含以下字段字段类型含义longitude/latitudestring经度 / 纬度IPv4 不返回continentstring大洲nationstring国家provincestring省份citystring市codestring行政区划代码areaCodestring国家编码timezonestring时区zipcodestring邮编ownerstring所属机构ispstring运营商radiusstring无额外描述的定位精度相关字段“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 的优先级为优先读取X-Forwarded-For请求头经过网关/代理链路的真实客户端 IPparseIP会取该头中逗号分隔的第一个 IP回退到 Wasm 插件运行时属性source.address即 Envoy 记录的 socket 对端地址两者都取不到时返回空串。辅助函数parseIPrest_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.yamlMCP 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。使用限制与注意事项必须配置 AppCodeserver.config.appCode为空时Authorization头将携带空值云市场 API 会鉴权失败因此上线前必须填入订阅获得的 AppCode免费额度云市场 API 存在免费试用额度额度用尽后需重新订阅控制台实时展示可用额度IPv4 与 IPv6 的差异精准版对 IPv4 不返回经纬度若业务强依赖经纬度坐标应优先使用升级版ip-address-query查不到时再用精准版兜底自动获取 IP 的前提getRealIP依赖请求经过 Higress 网关且能取到X-Forwarded-For或 socket 地址若两者均不可得将向 API 传入空值导致查询失败此时应由 LLM 显式传入ip参数。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考