py_xiaozhi/documents/docs/mcp/amap.md

高德地图工具 (Amap Tools)

高德地图工具是基于高德地图 Web API 的 MCP 工具集，提供了丰富的地理位置服务功能。

自然语言使用方式

路线规划

• "从云升科学园到科学城地铁站怎么走"
• "去天河城的路线"
• "开车从A到B要多久"

最近地点查询

• "最近的奶茶店怎么走"
• "最近的餐厅在哪里"
• "最近的地铁站"
• "最近的银行"

附近地点搜索

• "附近有哪些奶茶店"
• "附近的餐厅"
• "周边的超市"
• "附近2公里内的银行"

智能导航

• "去天河城"
• "导航到广州塔"
• "怎么去白云机场"

出行方式对比

• "从A到B，开车和坐地铁哪个快"
• "比较一下去机场的各种方式"
• "哪种方式最快"

MCP 工具介绍

智能工具（推荐使用）

1. route_planning - 智能路线规划

支持自然语言地址输入的路线规划，自动处理地址转换和坐标解析。

参数:

• origin (必需): 起点地址名称
• destination (必需): 终点地址名称
• city (可选): 所在城市，默认广州
• travel_mode (可选): 出行方式，walking(步行)、driving(驾车)、bicycling(骑行)、transit(公交)，默认步行

2. find_nearest - 最近地点查找

找到最近的某类地点并提供详细的步行路线。

参数:

• keywords (必需): 搜索关键词，如"奶茶店"、"餐厅"、"地铁站"、"银行"
• radius (可选): 搜索半径（米），默认5000米
• user_location (可选): 用户位置，不提供则自动定位

3. find_nearby - 附近地点搜索

搜索附近的多个地点，按距离排序展示。

参数:

• keywords (必需): 搜索关键词，如"奶茶店"、"餐厅"、"超市"
• radius (可选): 搜索半径（米），默认2000米
• user_location (可选): 用户位置，不提供则自动定位

4. navigation - 智能导航

提供到目的地的多种出行方式对比和推荐。

参数:

• destination (必需): 目的地名称
• city (可选): 所在城市，默认广州
• user_location (可选): 用户位置，不提供则自动定位

5. get_location - 当前位置获取

基于IP地址的智能定位服务。

参数:

• user_ip (可选): 用户IP地址，不提供则自动获取

6. compare_routes - 路线对比

比较不同出行方式的时间、距离和适用性。

参数:

• origin (必需): 起点地址名称
• destination (必需): 终点地址名称
• city (可选): 所在城市，默认广州

基础工具（二次开发使用）

地理编码工具

• maps_geo - 地址转坐标
• maps_regeocode - 坐标转地址
• maps_ip_location - IP定位

路径规划工具

• maps_direction_walking - 步行路径规划
• maps_direction_driving - 驾车路径规划
• maps_bicycling - 骑行路径规划
• maps_direction_transit_integrated - 公交路径规划

搜索工具

• maps_text_search - 关键词搜索
• maps_around_search - 周边搜索
• maps_search_detail - POI详情查询

其他工具

• maps_weather - 天气查询
• maps_distance - 距离测量

使用示例

智能工具示例

# 智能路线规划
result = await mcp_server.call_tool("route_planning", {
    "origin": "云升科学园",
    "destination": "科学城地铁站",
    "travel_mode": "walking"
})

# 最近地点查找
result = await mcp_server.call_tool("find_nearest", {
    "keywords": "奶茶店",
    "radius": "5000"
})

# 附近地点搜索
result = await mcp_server.call_tool("find_nearby", {
    "keywords": "餐厅",
    "radius": "2000"
})

基础工具示例

# 地址转坐标
result = await mcp_server.call_tool("maps_geo", {
    "address": "北京市天安门广场",
    "city": "北京"
})

# 步行路径规划
result = await mcp_server.call_tool("maps_direction_walking", {
    "origin": "116.397428,39.90923",
    "destination": "116.390813,39.904368"
})

二次开发说明

工具架构

高德地图工具采用分层架构设计：

1. 智能工具层 (MCP 适配)

• AmapToolsManager: 适配 MCP 服务器的管理器
• 智能工具注册: 自动注册用户友好的智能工具
• 参数验证: 完整的参数类型和格式验证
• 结果格式化: 用户友好的结果展示

2. 业务逻辑层 (AmapManager)

• 智能路线规划: 支持自然语言地址输入
• 自动定位: 多策略IP定位和城市识别
• 组合功能: 将多个API调用组合成高级功能
• 错误处理: 完善的异常处理和容错机制

3. API 客户端层 (AmapClient)

• HTTP 客户端: 基于 aiohttp 的异步HTTP客户端
• API 封装: 所有高德地图API的完整封装
• 响应解析: 自动解析API响应并转换为数据模型
• 错误处理: API级别的错误处理和重试

4. 数据模型层 (Models)

• 结构化数据: 使用 dataclass 定义的数据结构
• 类型安全: 完整的类型注解和验证
• 格式转换: 坐标、地址等格式的自动转换
• 数据一致性: 统一的数据格式和命名规范

智能功能特性

自动定位策略

1. 优先使用高德API自动IP识别
2. 如果失败，尝试第三方IP服务
3. 验证定位结果的有效性
4. 回退到城市中心坐标

地址智能解析

• 支持自然语言地址输入: "天安门广场"
• 支持坐标格式: "116.397428,39.90923"
• 支持复合地址: "北京市东城区天安门广场1号"

结果智能格式化

• 用户友好的输出格式
• 多种出行方式对比展示
• 详细的步行路线指引

配置说明

API 密钥配置

高德地图工具需要配置 API 密钥才能正常使用。

获取 API 密钥:

1. 访问 高德开放平台
2. 注册开发者账号
3. 创建应用，获取 API Key

配置方式: 目前 API 密钥在 src/mcp/tools/amap/__init__.py 中硬编码：

AMAP_API_KEY = "your_api_key_here"

建议配置方式: 将 API 密钥配置到 config/config.json 中：

{
  "amap": {
    "api_key": "your_api_key_here"
  }
}

扩展开发

添加新的智能工具

1. 在 AmapManager 中实现业务逻辑
2. 在 AmapToolsManager 中注册新工具
3. 在 AmapTools 中添加工具定义
4. 更新测试用例

添加新的基础工具

1. 在 AmapClient 中封装API调用
2. 在 AmapManager 中实现业务逻辑
3. 在 AmapTools 中添加工具定义
4. 更新数据模型（如需要）

数据结构

@dataclass
class Location:
    longitude: float  # 经度
    latitude: float   # 纬度

@dataclass
class POI:
    id: str              # POI ID
    name: str            # 名称
    address: str         # 地址
    location: Location   # 坐标
    type_code: str       # 类型代码

最佳实践

1. 优先使用智能工具: 自动处理复杂逻辑，用户友好
2. 合理设置参数: 指定城市、半径等参数提高精度
3. 错误处理: 处理网络异常和API错误
4. 缓存策略: 对频繁查询的结果进行缓存
5. 异步调用: 使用异步方式提高性能

通过高德地图工具，您可以轻松地为应用添加强大的地理位置服务功能，提供更好的用户体验。