# gaode_mcp

**Repository Path**: freespace/gaode_mcp

## Basic Information

- **Project Name**: gaode_mcp
- **Description**: 高德地图 MCP Server
基于 Spring Boot 开发的高德地图 Model Context Protocol (MCP) 服务器实现。

提供 REST API 接口，支持 JSON-RPC 2.0 协议。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-01
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 高德地图 MCP Server

基于 Spring Boot 开发的高德地图 Model Context Protocol (MCP) 服务器实现。

提供 REST API 接口，支持 JSON-RPC 2.0 协议。

## 功能特性

本 MCP Server 提供以下高德地图服务：

1. **地址转经纬度坐标** (`geocode`) - 将地址转换为经纬度坐标
2. **经纬度转行政区地址** (`reverse_geocode`) - 将经纬度坐标转换为地址，包含完整的行政区信息
3. **IP定位查询** (`ip_location`) - 根据IP地址查询地理位置信息
4. **城市天气查询** (`weather`) - 查询指定城市的天气信息
5. **驾车路径规划** (`driving_route`) - 计算两点之间的驾车路径规划
6. **步行路径规划** (`walking_route`) - 计算两点之间的步行路径规划
7. **骑行路径规划** (`bicycling_route`) - 计算两点之间的骑行路径规划
8. **公共交通路径规划** (`transit_route`) - 计算两点之间的公共交通路径规划（公交、地铁等）
9. **关键词POI搜索** (`search_poi_by_keyword`) - 根据关键词搜索兴趣点
10. **周边半径搜索** (`search_poi_around`) - 在指定位置周边半径范围内搜索POI
11. **POI详情查询** (`get_poi_detail`) - 根据POI ID查询详细信息

## 前置要求

- Java 11 或更高版本
- Maven 3.6 或更高版本
- 高德地图 API Key（可在[高德开放平台](https://lbs.amap.com/)申请）

## 安装与配置

### 1. 克隆项目

```bash
git clone <repository-url>
cd gaode_ncp
```

### 2. 配置 API Key

有两种方式配置高德地图 API Key：

**方式一：环境变量（推荐）**

```bash
export GAODE_API_KEY=your_api_key_here
```

**方式二：配置文件**

编辑 `src/main/resources/application.yml` 文件：

```yaml
gaode:
  api:
    key: your_api_key_here
    base-url: https://restapi.amap.com/v3
    timeout: 30
```

### 3. 编译项目

```bash
mvn clean package
```

编译完成后，会在 `target` 目录下生成 `gaode-mcp-server-1.0.0.jar` 文件。

## 使用方法

### 启动服务

启动 Spring Boot Web 应用：

```bash
java -jar target/gaode-mcp-server-1.0.0.jar
```

或者使用 Maven：

```bash
mvn spring-boot:run
```

服务器将在 `http://localhost:8080` 启动。

### API 端点

- `POST /mcp` - 处理 JSON-RPC 请求（HTTP 模式）
- `GET /mcp/health` - 健康检查
- `GET /mcp/sse` - 建立 SSE 连接（用于 MCP CLI）
- `POST /mcp/sse/message` - SSE 模式下的消息处理

### 快速测试

```bash
# 健康检查
curl http://localhost:8080/mcp/health

# 发送 JSON-RPC 请求
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
```

### 与 MCP 客户端集成

使用 HTTP POST 请求发送 JSON-RPC 2.0 格式的请求到 `/mcp` 端点。

### API 调用示例

#### 1. 初始化

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'
```

#### 2. 列出所有工具

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

#### 3. 地址转经纬度坐标

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "geocode",
      "arguments": {
        "address": "北京市朝阳区"
      }
    }
  }'
```

#### 4. 经纬度转行政区地址

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "reverse_geocode",
      "arguments": {
        "location": "116.397428,39.90923"
      }
    }
  }'
```

#### 5. IP定位查询

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "ip_location",
      "arguments": {}
    }
  }'
```

#### 6. 城市天气查询

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "weather",
      "arguments": {
        "city": "北京"
      }
    }
  }'
```

#### 7. 驾车路径规划

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "driving_route",
      "arguments": {
        "origin": "116.397428,39.90923",
        "destination": "116.407526,39.904030",
        "strategy": "0"
      }
    }
  }'
```

**驾车路径策略说明：**
- `0` - 速度优先
- `1` - 费用优先
- `2` - 距离优先
- `3` - 不走高速

#### 8. 步行路径规划

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "walking_route",
      "arguments": {
        "origin": "116.397428,39.90923",
        "destination": "116.407526,39.904030"
      }
    }
  }'
```

#### 9. 骑行路径规划

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "bicycling_route",
      "arguments": {
        "origin": "116.397428,39.90923",
        "destination": "116.407526,39.904030",
        "city": "北京"
      }
    }
  }'
```

**注意**：如果返回 `SERVICE_NOT_AVAILABLE` 错误，请检查：
1. API Key 是否开通了骑行路径规划服务权限
2. 该地区是否支持骑行路径规划
3. 建议提供 `city` 参数以提高准确性

#### 10. 公共交通路径规划

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "transit_route",
      "arguments": {
        "origin": "116.397428,39.90923",
        "destination": "116.407526,39.904030",
        "city": "北京"
      }
    }
  }'
```

#### 11. 关键词POI搜索

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "search_poi_by_keyword",
      "arguments": {
        "keywords": "餐厅",
        "city": "北京"
      }
    }
  }'
```

#### 12. 周边半径搜索

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 11,
    "method": "tools/call",
    "params": {
      "name": "search_poi_around",
      "arguments": {
        "location": "116.397428,39.90923",
        "radius": 3000,
        "keywords": "餐厅"
      }
    }
  }'
```

#### 13. POI详情查询

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 12,
    "method": "tools/call",
    "params": {
      "name": "get_poi_detail",
      "arguments": {
        "poi_id": "B0FFG8Y4XJ"
      }
    }
  }'
```

## 项目结构

```
gaode_ncp/
├── pom.xml                          # Maven 配置文件
├── README.md                        # 项目说明文档
├── TEST.md                          # 测试指南
└── src/
    └── main/
        ├── java/
        │   └── com/
        │       └── gaode/
        │           └── mcp/
        │               └── server/
        │                   ├── GaodeMcpServerApplication.java  # Spring Boot 主启动类
        │                   ├── config/
        │                   │   └── GaodeProperties.java        # 配置属性类
        │                   ├── controller/
        │                   │   └── McpController.java          # REST API 控制器
        │                   ├── gaode/
        │                   │   └── GaodeApiClient.java         # 高德地图 API 客户端
        │                   └── mcp/
        │                       └── McpServer.java              # MCP Server 核心实现
        └── resources/
            └── application.yml      # Spring Boot 配置文件
```

## 技术栈

- **Java 11** - 编程语言
- **Spring Boot 2.7.18** - Web 框架
- **Maven** - 构建工具
- **Jackson** - JSON 处理
- **OkHttp** - HTTP 客户端
- **SLF4J + Logback** - 日志框架
- **Spring Boot Configuration** - 配置管理

## 开发

### 运行测试

```bash
mvn test
```

### 代码格式化

项目使用标准的 Java 代码风格，建议使用 IDE 的自动格式化功能。

## 日志

日志文件默认保存在 `logs/gaode-mcp-server.log`，同时也会输出到控制台。

日志级别可以通过修改 `src/main/resources/application.yml` 中的 `logging.level` 配置进行调整。

## 许可证

本项目采用开源许可证，允许个人和非商业用途自由使用。

**使用条款：**
- ✅ 个人学习和研究使用
- ✅ 非商业项目使用
- ❌ **商业用途需要联系作者获得授权**

**商用授权：**
如需将本项目用于商业用途，请通过以下方式联系作者：
- 提交 Issue 说明使用场景
- 或通过其他方式联系项目维护者

未经授权的商业使用将被视为侵权行为。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 参考资源

- [高德开放平台](https://lbs.amap.com/)
- [MCP 协议规范](https://modelcontextprotocol.io/)
- [JSON-RPC 2.0 规范](https://www.jsonrpc.org/specification)

## 常见问题

### Q: 如何获取高德地图 API Key？

A: 访问[高德开放平台](https://lbs.amap.com/)，注册账号并创建应用，即可获取 API Key。

### Q: API 调用失败怎么办？

A: 请检查：
1. API Key 是否正确配置
2. API Key 是否有相应的服务权限
3. 网络连接是否正常
4. 查看日志文件获取详细错误信息

### Q: 支持哪些高德地图服务？

A: 目前支持以下11项服务：
1. 地址转经纬度坐标
2. 经纬度转行政区地址
3. IP定位查询
4. 城市天气查询
5. 驾车路径规划
6. 步行路径规划
7. 骑行路径规划
8. 公共交通路径规划
9. 关键词POI搜索
10. 周边半径搜索
11. POI详情查询

更多服务可以根据需要添加。

## 更新日志

### v1.0.0 (2024-12-XX)
- 初始版本发布
  - 支持11项核心功能：
    - 地址转经纬度坐标
    - 经纬度转行政区地址（包含完整行政区信息）
    - IP定位查询
    - 城市天气查询
    - 驾车路径规划（支持多种策略）
    - 步行路径规划
    - 骑行路径规划
    - 公共交通路径规划（公交、地铁等）
    - 关键词POI搜索
    - 周边半径搜索
    - POI详情查询
## 📞 联系方式

如有问题或建议，欢迎通过以下方式联系：
- 提交 Issue
- 发送邮件：yjw3160p@163.com
- 微信二维码：

<img src="screenshots/wx.png" alt="微信二维码" width="150" style="display: block; margin: 0 auto;">