Amap (Gaode Maps) MCP Server

Instructions

Implementation Reference

• src/build_mcp/services/server.py:87-127 (handler)

  MCP tool handler for 'search_nearby'. Registers the tool with @mcp.tool and implements the logic by calling the underlying GdSDK.search_nearby method, handles errors, and wraps response in ApiResponse.

  @mcp.tool(name="search_nearby", description="根据经纬度和关键词进行周边搜索，返回指定半径内的 POI 列表。")
  async def search_nearby(
          location: Annotated[str, Field(description="中心点经纬度，格式为 'lng,lat'，如 '116.397128,39.916527'")],
          keywords: Annotated[str, Field(description="搜索关键词，例如: '餐厅'。", min_length=0)] = "",
          types: Annotated[str, Field(description="POI 分类码，多个分类用逗号分隔")] = "",
          radius: Annotated[int, Field(description="搜索半径（米），最大50000", ge=0, le=50000)] = 1000,
          page_num: Annotated[int, Field(description="页码，从1开始", ge=1)] = 1,
          page_size: Annotated[int, Field(description="每页数量，最大25", ge=1, le=25)] = 20,
  ) -> ApiResponse:
    """
     周边搜索。
  
     Args:
         location (str): 中心点经纬度，格式为 "lng,lat"。
         keywords (str, optional): 搜索关键词，默认为空。
         types (str, optional): POI 分类，默认为空。
         radius (int, optional): 搜索半径（米），最大 50000，默认为 1000。
         page_num (int, optional): 页码，默认为 1。
         page_size (int, optional): 每页数量，最大 25，默认为 10。
  
     Returns:
         dict: 包含搜索结果的字典。
    """
    logger.info(f"Searching nearby: location={location}, keywords={keywords}, types={types}, radius={radius}, page_num={page_num}, page_size={page_size}")
    try:
      result = await sdk.search_nearby(location=location, keywords=keywords, types=types, radius=radius, page_num=page_num, page_size=page_size)
      if not result:
        return ApiResponse.fail("搜索结果为空，请检查日志，系统异常请检查相关日志，日志默认路径为/var/log/build_mcp。")
      logger.info(f"Search nearby result: {result}")
      return ApiResponse.ok(data=result, meta={
        "location": location,
        "keywords": keywords,
        "types": types,
        "radius": radius,
        "page_num": page_num,
        "page_size": page_size
      })
    except Exception as e:
      logger.error(f"Error searching nearby: {e}")
      return ApiResponse.fail(str(e))

• src/build_mcp/services/server.py:29-42 (schema)

  Pydantic model defining the output schema for the tool responses, used by search_nearby handler.

  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)

• src/build_mcp/services/gd_sdk.py:154-192 (helper)

  Supporting utility in GdSDK class that performs the actual HTTP request to Amap API for nearby POI search, with retry logic.

  async def search_nearby(self, location: str, keywords: str = "", types: str = "", radius: int = 1000, page_num: int = 1, page_size: int = 20) -> dict | None:
    """
    周边搜索（新版 POI）
    https://lbs.amap.com/api/webservice/guide/api-advanced/newpoisearch#t4
  
    Args:
        location (str): 中心点经纬度，格式为 "lng,lat"
        keywords (str, optional): 搜索关键词
        types (str, optional): POI 分类
        radius (int, optional): 搜索半径（米），最大 50000，默认 1000
        page_num (int, optional): 页码，默认 1
        page_size (int, optional): 每页数量，默认 20，最大 25
  
    Returns:
        dict | None: 搜索结果，失败时返回 None
    """
    url = f"{self.base_url}/v5/place/around"
    params = {
      "key": self.api_key,
      "location": location,
      "keywords": keywords,
      "types": types,
      "radius": radius,
      "page_num": page_num,
      "page_size": page_size,
    }
  
    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"周边搜索失败: {result}")
      return None