# 高德地图 MCP Server

一个基于 Model Context Protocol (MCP) 的高德地图服务器，为 AI 应用提供地理编码、搜索、路径规划等地图服务功能。

## 功能特性

### 🗺️ 地理编码服务
- **地理编码**：将地址转换为经纬度坐标
- **逆地理编码**：将经纬度坐标转换为详细地址信息

### 🔍 搜索服务
- **关键字搜索**：根据关键字搜索 POI 信息
- **周边搜索**：在指定位置周围搜索 POI
- **多边形搜索**：在多边形区域内搜索 POI
- **ID 查询**：根据 POI ID 获取详细信息

### 🛣️ 路径规划
- **驾车路径规划**：计算最优驾车路线
- **步行路径规划**：计算步行路线
- **公交路径规划**：查询公交换乘方案
- **距离计算**：计算两点间的直线距离和行驶距离

### 💡 输入提示
- **智能提示**：根据用户输入提供地点建议

### 🌍 坐标转换
- **坐标系转换**：支持 GPS、百度、MapBar 等坐标系转换为高德坐标

## 快速开始

### 1. 获取高德地图 API Key

1. 访问 [高德开放平台](https://console.amap.com/)
2. 注册并登录账号
3. 创建应用并申请 "Web 服务 API" Key

### 2. 安装依赖

```bash
npm install
```

### 3. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的高德地图 API Key：

```env
AMAP_API_KEY=your_amap_api_key_here
```

### 4. 构建项目

```bash
npm run build
```

### 5. 启动服务器

```bash
npm start
```

或者开发模式：

```bash
npm run dev
```

## MCP 工具说明

### 地理编码工具

#### `geocode`
将地址转换为经纬度坐标

**参数：**
- `address` (string): 要转换的地址
- `city` (string, 可选): 指定城市，提高准确性

#### `reverse_geocode`
将经纬度坐标转换为地址信息

**参数：**
- `location` (string): 经纬度坐标，格式："经度,纬度"
- `radius` (number, 可选): 搜索半径，默认 1000 米

### 搜索工具

#### `search_poi`
根据关键字搜索 POI

**参数：**
- `keywords` (string): 搜索关键字
- `city` (string, 可选): 指定城市
- `types` (string, 可选): POI 类型代码
- `page_size` (number, 可选): 每页结果数，默认 20
- `page_num` (number, 可选): 页码，默认 1

#### `search_around`
周边搜索

**参数：**
- `location` (string): 中心点坐标，格式："经度,纬度"
- `keywords` (string, 可选): 搜索关键字
- `types` (string, 可选): POI 类型代码
- `radius` (number, 可选): 搜索半径，默认 3000 米
- `page_size` (number, 可选): 每页结果数，默认 20

### 路径规划工具

#### `driving_route`
驾车路径规划

**参数：**
- `origin` (string): 起点坐标，格式："经度,纬度"
- `destination` (string): 终点坐标，格式："经度,纬度"
- `waypoints` (string, 可选): 途经点，多个点用 ";" 分隔
- `strategy` (number, 可选): 路径策略，默认 0（速度优先）

#### `walking_route`
步行路径规划

**参数：**
- `origin` (string): 起点坐标
- `destination` (string): 终点坐标

#### `transit_route`
公交路径规划

**参数：**
- `origin` (string): 起点坐标
- `destination` (string): 终点坐标
- `city` (string): 城市名称
- `strategy` (number, 可选): 公交策略，默认 0（最快捷）

### 其他工具

#### `input_tips`
输入提示

**参数：**
- `keywords` (string): 输入关键字
- `city` (string, 可选): 指定城市
- `datatype` (string, 可选): 返回数据类型，默认 "all"

#### `coordinate_convert`
坐标转换

**参数：**
- `locations` (string): 要转换的坐标，多个坐标用 ";" 分隔
- `coordsys` (string): 原坐标系类型（gps, mapbar, baidu）

#### `distance_calculate`
距离计算

**参数：**
- `origins` (string): 起点坐标，多个点用 ";" 分隔
- `destination` (string): 终点坐标
- `type` (number, 可选): 距离类型，1=直线距离，3=驾车距离

## 在 Claude Desktop 中使用

1. 确保 MCP 服务器正在运行
2. 在 Claude Desktop 的配置文件中添加服务器配置：

```json
{
  "mcpServers": {
    "amap": {
      "command": "node",
      "args": ["/path/to/mcp-amap/dist/index.js"],
      "env": {
        "AMAP_API_KEY": "your_amap_api_key_here"
      }
    }
  }
}
```

3. 重启 Claude Desktop
4. 现在你可以在对话中使用高德地图功能了！

## 示例用法

```
用户：帮我查找北京市朝阳区附近的咖啡厅
AI：我来帮你搜索北京市朝阳区附近的咖啡厅...

用户：计算从天安门到故宫的步行路线
AI：我来为你规划从天安门到故宫的步行路线...

用户：这个坐标 116.397499,39.908722 是什么地方？
AI：我来查询这个坐标对应的地址信息...
```

## 开发

### 项目结构

```
mcp-amap/
├── src/
│   ├── index.ts          # 主入口文件
│   ├── server.ts         # MCP 服务器实现
│   ├── tools/            # 工具实现
│   │   ├── geocoding.ts  # 地理编码工具
│   │   ├── search.ts     # 搜索工具
│   │   ├── routing.ts    # 路径规划工具
│   │   └── utils.ts      # 通用工具
│   ├── types/            # 类型定义
│   │   └── amap.ts       # 高德地图 API 类型
│   └── utils/            # 工具函数
│       ├── api.ts        # API 客户端
│       └── logger.ts     # 日志工具
├── dist/                 # 编译输出
├── package.json
├── tsconfig.json
└── README.md
```

### 添加新功能

1. 在 `src/tools/` 目录下创建新的工具文件
2. 在 `src/server.ts` 中注册新工具
3. 更新类型定义和文档

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 相关链接

- [高德开放平台](https://lbs.amap.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/)