# amap-location-mcp

一个基于高德开放平台 Web 服务 API 的只读 MCP Server。它的主要用途是让 AstrBot、RikkaHub 等 AI 客户端回答“从这里怎么回家”“从北京南站到故宫怎么走”这类问题：输入起点和终点，自动解析真实高德地点，同时比较步行、驾车和公交，给出距离、预计耗时、关键步骤和推荐交通方式。

它参考了 [SHowGS/SillyTavern-RealMap](https://github.com/SHowGS/SillyTavern-RealMap) 的“真实地点 + 周边环境 + 路线 + 位置来源”思路，但代码为独立实现，没有复制该项目源码。

## 优先考虑高德官方 MCP

高德开放平台现已提供官方 MCP Server。对 Cherry Studio、RikkaHub、Cursor、AstrBot 等支持 Streamable HTTP 的客户端，建议优先直连官方服务；官方当前提供 POI 搜索、地理编码、驾车/公交/步行/骑行、距离、天气、导航与打车链接等完整工具：

```json
{
  "mcpServers": {
    "AmapOfficial": {
      "url": "https://mcp.amap.com/mcp?key=你的高德Web服务Key"
    }
  }
}
```

申请 Key 时仍需在[高德开放平台控制台](https://console.amap.com/dev/key/app)选择“Web 服务”。官方接入说明见[快速接入高德地图 MCP Server](https://lbs.amap.com/api/mcp-server/gettingstarted)。Key 位于 URL 查询参数中，请只保存到私有客户端配置，不要提交到 Git。

本仓库继续保留，适合需要以下能力的场景：只向模型暴露一个综合路线工具以减少上下文、在服务端统一 Bearer 鉴权、控制字段裁剪，或自行托管兼容入口。地点容易重名时，无论使用官方还是本项目，都建议给助手加入 [`navigation-guard-prompt.example.txt`](./navigation-guard-prompt.example.txt) 中的约束。

## 定位边界

- 可以把地址/POI 解析为高德真实 GCJ-02 坐标。
- 可以把调用方主动提供的 WGS84/GPS 坐标转换为 GCJ-02，再查询地址和周边 POI。
- 可以对明确传入的公网 IPv4 做省市级粗定位。
- 不能自行读取电脑、手机或浏览器的 GPS。要获得设备实况位置，需要前端在用户授权后把坐标传给 MCP，并设置 `coordinate_source: "device_gps"`。
- 不会把 POI 推测、IP 出口或 MCP 服务器位置伪装成用户的设备定位。

每次成功结果都包含：

```json
{
  "source": "amap_reverse_geocode",
  "coordinate_system": "GCJ-02",
  "precision": "point_of_interest",
  "confidence": 0.9,
  "is_device_location": false,
  "observed_at": "...",
  "warnings": []
}
```

## 工具

| 工具 | 用途 |
| --- | --- |
| `amap_get_directions` | **主要入口**：输入起点、终点地址或地点，同时查询步行、驾车、公交并推荐交通方式 |
| `amap_resolve_location` | 地点/地址解析、候选排序和城市消歧 |
| `amap_reverse_geocode` | GCJ-02/WGS84 坐标转结构化地址和附近 POI |
| `amap_search_nearby` | 按半径、关键词或 POI 类型搜索周边 |
| `amap_convert_coordinates` | WGS84、百度、Mapbar 坐标转高德 GCJ-02 |
| `amap_locate_ip` | 定位明确传入的 IPv4，结果仅为省市级粗定位 |
| `amap_plan_route` | 步行、驾车、公交路线规划 |
| `amap_build_location_context` | 一次组合地点解析、地址和周边证据，供 AI 直接使用 |

面向 AstrBot/RikkaHub 的导航专用部署建议设置 `MCP_TOOL_PROFILE=directions`。该模式只向客户端暴露 `amap_get_directions`，其余能力仍由这个综合工具在服务端内部完成，避免 8 份工具定义长期占用模型上下文。

## 密钥要求

本项目不会提供或内置高德 Key。使用前必须访问[高德地图开放平台](https://lbs.amap.com/)，登录后进入[控制台](https://console.amap.com/dev/key/app)创建应用并申请 API Key：

- 服务平台：`Web服务`

下面两种凭证不能用于本项目：

- `Web端（JS API）Key`
- `securityJsCode / 安全密钥`

密钥只从环境变量 `AMAP_WEB_SERVICE_KEY` 读取，不写入源码或配置模板。JS API 凭证不应放入 `.env`。

## 最简单的调用方式

通常只需要让 AI 调用 `amap_get_directions`：

```json
{
  "origin": "北京南站",
  "destination": "故宫博物院",
  "origin_city": "北京",
  "destination_city": "北京",
  "modes": ["walking", "driving", "transit"]
}
```

返回内容包括：

- 起点和终点实际匹配到的高德 POI、地址及 GCJ-02 坐标；
- 每种可用交通方式的总距离、预计耗时和关键步骤；
- `recommended_mode` 与中文推荐理由；
- 某一种路线查询失败时，仍保留其他可用方案。

如果地点重名，传入 `origin_city` / `destination_city` 可以减少歧义。`modes` 可只保留需要比较的方式。

## 本地安装和 stdio 运行

要求 Node.js 22 或更高版本。

```powershell
git clone https://github.com/188zjl/amap-location-mcp.git
cd amap-location-mcp
npm install
npm run build
$env:AMAP_WEB_SERVICE_KEY="你的 Web服务 Key"
npm start
```

本地开发可复制 `.env.example` 为 `.env`，再运行 `npm run dev`。`.env` 已被 Git 忽略。

## 服务器 Streamable HTTP 模式

AstrBot 和 RikkaHub 可以共用部署在服务器上的兼容入口。服务本身默认只监听 `127.0.0.1:3000`，应由 Nginx、Nginx Proxy Manager 或 Caddy 提供 HTTPS：

```bash
export AMAP_WEB_SERVICE_KEY="你的 Web服务 Key"
export MCP_TRANSPORT="http"
export MCP_AUTH_TOKEN="至少16位的随机访问令牌"
export MCP_TOOL_PROFILE="directions"
export MCP_ALLOWED_HOSTS="map-mcp.example.com"
npm start
```

MCP 地址为 `http://127.0.0.1:3000/mcp`，健康检查为 `http://127.0.0.1:3000/health`。反向代理时需要：

- 将公网 `https://map-mcp.example.com/mcp` 转发到 `http://127.0.0.1:3000/mcp`；
- 保留 `Authorization` 请求头；
- 将真实公网域名写入 `MCP_ALLOWED_HOSTS`；
- 不要直接把 Node 端口暴露到公网；
- `/health` 只说明 HTTP 服务存活，最终应以真实 `tools/list` 和 `amap_get_directions` 调用为准。

可选变量见 [.env.example](./.env.example)。HTTP 模式强制 Bearer Token，且令牌至少 16 个字符。

## AstrBot 配置

在 AstrBot 面板的“扩展/工具 → MCP Servers → 添加服务器”中使用 Streamable HTTP，并填入：

```json
{
  "transport": "streamable_http",
  "url": "https://map-mcp.example.com/mcp",
  "headers": {
    "Authorization": "Bearer 你的访问令牌"
  },
  "timeout": 10,
  "sse_read_timeout": 300
}
```

## RikkaHub 配置

复制仓库中的 [`rikkahub-amap-directions.example.json`](./rikkahub-amap-directions.example.json)，替换域名和访问令牌后即可导入 RikkaHub：

```json
{
  "mcpServers": {
    "AmapDirections": {
      "type": "streamable_http",
      "url": "https://map-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer 你的访问令牌"
      }
    }
  }
}
```

注意：AstrBot 使用字段 `transport`，RikkaHub 使用字段 `type`。

## 其他本地 MCP 客户端配置

Codex 的 `config.toml` 示例：

```toml
[mcp_servers.amap-location]
command = "node"
args = ["C:\\path\\to\\amap-location-mcp\\dist\\index.js"]
env = { AMAP_WEB_SERVICE_KEY = "你的 Web服务 Key" }
```

使用 JSON 配置的 MCP 客户端可写成：

```json
{
  "mcpServers": {
    "amap-location": {
      "command": "node",
      "args": ["C:\\path\\to\\amap-location-mcp\\dist\\index.js"],
      "env": {
        "AMAP_WEB_SERVICE_KEY": "你的 Web服务 Key"
      }
    }
  }
}
```

## 其他调用示例

解析地点：

```json
{
  "query": "北京大学",
  "city": "北京",
  "current_location": {
    "longitude": 116.31,
    "latitude": 39.99
  }
}
```

设备授权后传入 WGS84 GPS 坐标：

```json
{
  "location": {
    "longitude": 116.397,
    "latitude": 39.908
  },
  "coordinate_system": "WGS84",
  "coordinate_source": "device_gps",
  "include_nearby_pois": true
}
```

构建 AI 位置上下文：

```json
{
  "query": "北京大学",
  "city": "北京",
  "nearby_keywords": "咖啡",
  "radius": 800,
  "nearby_limit": 8
}
```

## 验证

```powershell
npm run check
```

验证内容包括 TypeScript 构建、mock 高德响应、候选排序、WGS84 转换、逆地理编码、组合上下文、路线归一化，以及 MCP stdio 的旧版与 `2026-07-28` 协议握手、`tools/list` 和 `tools/call`。

## 高德官方文档

- [高德地图 MCP Server 快速接入](https://lbs.amap.com/api/mcp-server/gettingstarted)
- [地理/逆地理编码](https://lbs.amap.com/api/webservice/guide/api/georegeo)
- [POI 搜索](https://lbs.amap.com/api/webservice/guide/api/search)
- [IP 定位](https://lbs.amap.com/api/webservice/guide/api/ipconfig)
- [坐标转换](https://lbs.amap.com/api/webservice/guide/api/convert)
- [路径规划](https://lbs.amap.com/api/webservice/guide/api/direction)

## 开源许可

本项目使用 [MIT License](./LICENSE) 开源。