# 🗺️ 地点检索与路线规划 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）

### 📍 推荐理由
距离近、评分高、步行即达。
```