locate_ip
Find geographic location details including province, city, coordinates, and district for any IP address using Amap's geolocation service.
Instructions
获取用户的 IP 地址定位信息，返回省市区经纬度等信息。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ip | No | 用户的ip地址 |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| meta | No | ||
| error | No | ||
| success | Yes |
Implementation Reference
- src/build_mcp/services/server.py:59-80 (handler)MCP tool handler for 'locate_ip': decorated function that takes optional IP, calls GdSDK.locate_ip, logs, and returns ApiResponse with location data or error.
@mcp.tool(name="locate_ip", description="获取用户的 IP 地址定位信息，返回省市区经纬度等信息。") async def locate_ip(ip: Annotated[Optional[str], Field(description="用户的ip地址")] = None) -> ApiResponse: """ 根据 IP 地址定位位置。 Args: ip (str): 要定位的 IP 地址。 Returns: dict: 包含定位结果的字典。 """ logger.info(f"Locating IP: {ip}") try: result = await sdk.locate_ip(ip) if not result: ApiResponse.fail("定位结果为空，请检查日志，系统异常请检查相关日志，日志默认路径为/var/log/build_mcp。") logger.info(f"Locate IP result: {result}") return ApiResponse.ok(data=result, meta={"ip": ip}) except Exception as e: logger.error(f"Error locating IP {ip}: {e}") return ApiResponse.fail(str(e)) - Pydantic BaseModel defining the ApiResponse schema used for input validation and output typing in the locate_ip tool.
T = TypeVar("T") class ApiResponse(BaseModel, Generic[T]): success: bool data: Optional[T] = None error: Optional[str] = None meta: Optional[Dict[str, Any]] = None @classmethod def ok(cls, data: T, meta: Dict[str, Any] = None) -> "ApiResponse[T]": return cls(success=True, data=data, meta=meta) @classmethod def fail(cls, error: str, meta: Dict[str, Any] = None) -> "ApiResponse[None]": return cls(success=False, error=error, meta=meta) - GdSDK helper method implementing the actual IP geolocation API call to Amap with retry logic.
async def locate_ip(self, ip: str = None) -> Any | None: """ IP定位接口 https://lbs.amap.com/api/webservice/guide/api/ipconfig Args: ip (str, optional): 要查询的 IP，若为空，则使用请求方公网 IP。 Returns: dict: 定位结果，若失败则返回 None。 """ url = f"{self.base_url}/v3/ip" params = { "key": self.api_key, } if ip: params["ip"] = ip result = await self._request_with_retry( method="GET", url=url, params=params ) if result and result.get("status") == "1": return result else: self.logger.error(f"IP定位失败: {result}") return None