# 🗺️ 地点检索与路线规划 Agent
基于 **Baidu Map API + DeepSeek API + MCP工具链** 的地理信息智能助手（只在中国地区有效）
本项目实现了一个支持 **地点检索** 与 **路线规划** 的智能 Agent，并通过 MCP（Model Context Protocol）暴露一组可供任意大模型使用的地理工具。
你可以：
* 直接运行内置的 DeepSeek 驱动的 Agent
* 将 MCP 服务部署到服务器上，供任意兼容 MCP 的大模型使用
---
## ✨ 功能简介
本项目的 Agent 支持以下核心功能：
### 📍 地点检索
* 地址转坐标
* 根据经纬度搜索附近地点
* 获取用户 IP 并反查地理位置
### 🚗 多方式路线规划
基于百度地图 API，支持获取两地之间的：
* 驾车路线
* 公交路线
* 步行路线
* 骑行路线
（含距离、耗时、路线信息）
### 🤖 智能规划 Agent
* 主体运行于 `ds_model.py`
* 使用 DeepSeek Chat 作为推理模型
* 根据用户输入自动决定调用哪些 MCP 工具
* 最终以 Markdown 形式输出结构化结果（路线建议、比较、推荐等）
---
## 🔧 环境准备
### 1. 创建虚拟环境（Windows）
```bash
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```
※ 若没有 `requirements.txt`，你也可以安装：
```bash
pip install openai httpx fastmcp
```
---
## 🔑 API设置
### ▶️ **方式一：本地运行 Agent（需要两个 API Key）**
运行 `ds_model.py` 时必须设置：
| 环境变量 | 说明 |
| --------------------- | -------------------------------- |
| **BAIDU_MAP_API_KEY** | 百度地图 Web API 的 AK |
| **DEEPSEEK_API_KEY** | DeepSeek API Key，用于运行 agent 的大模型 |
### ▶️ **方式二：仅使用 MCP 工具（只需百度地图 API Key）**
如果你要把 MCP 服务接入 **第三方大模型应用**（如 OpenAI + MCP），则只需要：
```
BAIDU_MAP_API_KEY
```
因为大模型由外部提供，不需要 DeepSeek API。
---
## 🚀 运行方式
---
### ✅ **方式一：直接运行 Agent（推荐）**
运行 `ds_model.py` 前必须设置：
| 环境变量 | 说明 |
| --------------------- | -------------------------------- |
| **BAIDU_MAP_API_KEY** | 百度地图 Web API 的 AK |
| **DEEPSEEK_API_KEY** | DeepSeek API Key，用于运行 agent 的大模型 |
设置示例：
#### Windows PowerShell
```powershell
setx BAIDU_MAP_API_KEY "你的百度AK"
setx DEEPSEEK_API_KEY "你的deepseek-key"
```
---
运行agent：
```bash
python ds_model.py
```
---
### ✅ **方式二：运行 MCP 工具服务（供其他大模型调用）**
```bash
python baidu_map_search_mcp.py
```
运行后会以 **stdio transport** 的方式启动 MCP 服务
在配置时，填入 MCP 服务器路径即可，例如：
```json
{
"mcpServers": {
"search_mcp": {
"command": "<YOUR_VENV_PYTHON_PATH>",
"args": ["<YOUR_BAIDU_MAP_SEARCH_MCP_PATH>"],
"env": {
"BAIDU_MAPS_API_KEY": "<YOUR_API_KEY>"
}
}
}
}
```
---
## 🛠️ MCP 工具能力说明
`search_mcp.py` 定义了多个可被调用的工具：
| 工具 | 功能 |
| ------------------------------------------------- | ------------ |
| `get_ip()` | 获取用户公网 IP |
| `get_location_ip(ip)` | 通过 IP 获取地理位置 |
| `get_location_text(address)` | 地址转经纬度 |
| `get_places(query, location, radius)` | 附近地点搜索 |
| `get_place_driving_distance(origin, destination)` | 驾车路线规划 |
| `get_place_walking_distance(origin, destination)` | 步行路线 |
| `get_place_riding_distance(origin, destination)` | 骑行路线 |
| `get_place_transit_distance(origin, destination)` | 公交路线 |
这些能力会自动被 Agent 或第三方大模型调用，用于路线规划和地点检索。
---
## 📌 示例对话（本地运行 Agent）
**用户：**
> 帮我查一下广州塔附近有什么咖啡店？
**Agent：**
（自动执行：地址→坐标→地点搜索）
```
## ☕ 广州塔附近的咖啡店（半径1000米）
- 瑞幸咖啡（380m）
- 星巴克（520m）
- MANNER COFFEE（810m）
### 📍 推荐理由
距离近、评分高、步行即达。
```
