# Easy Search Along The Way

一个最小可用的 **MCP Server**，只做两件事：

1. **周边搜索** —— 给一个位置，查周边有哪些商店 / POI。
2. **沿途搜索** —— 给起点、终点、沿途半径、目标类型，查这条路线沿途的目标。

底层调用**高德地图 Web 服务 API**。为方便发布后试用，内置了一个**高德 Key 录入与校验**工具。

---

## 一、两个工具

### 1. `search_nearby` —— 周边搜索

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `location` | string | ✅ | - | 中心点。地址文本（`济南市历下区泉城路`）或坐标（`117.120128,36.652069`） |
| `keyword` | string | | `商店` | 搜索关键词：商店 / 超市 / 加油站 / 山姆超市 / 便利店 / 充电站 … |
| `radius` | number | | `1000` | 搜索半径，单位**米**，最大 50000 |
| `limit` | number | | `20` | 最多返回条数，最大 50 |
| `city` | string | | - | 城市名，地址有歧义时指定 |

**返回**：`{ summary, center, keyword, count, items[] }`，`items` 按距离由近到远排序，每条含 `name / address / distance / tel / type / location`。

---

### 2. `search_along_route` —— 沿途搜索

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `origin` | string | ✅ | - | 起点。地址文本或坐标 |
| `destination` | string | ✅ | - | 终点。地址文本或坐标 |
| `distance` | number | | `1000` | **沿途搜索半径**，单位米。以驾车路线为中心线，向两侧各扩 `distance` 米 |
| `target` | string | ✅ | - | 沿途要找的目标：加油站 / 商店 / 山姆超市 / 服务区 / 充电站 … |
| `limit` | number | | `30` | 最多返回条数，最大 100 |
| `city` | string | | - | 城市名，地址有歧义时指定 |

**返回**：`{ summary, route, target, corridorRadius, count, items[] }`

- `route`：起终点、驾车总里程、耗时、采样点数量、采样间隔
- `items`：按 **`alongRouteDistance`（沿路线距起点的路程）** 从近到远排序，每条含：
  - `name` / `address` / `tel` / `type` / `location`
  - `alongRouteDistance`：沿驾车路线从起点到该目标的里程
  - `distanceToRoute`：该目标到路线的**垂直距离**（把目标投影到路线折线上计算）

结果已经过滤：超出 `distance` 范围的目标会被丢弃。

---

### 3. `set_amap_key` —— 录入高德 Key（认证）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `key` | string | ✅ | 高德开放平台「**Web服务**」类型的 Key |

会**先真实调用一次高德接口做校验**，通过才写入本地配置文件。写完后不需要重启客户端，直接就能查询。

---

## 二、5 分钟跑起来

### 第 1 步：申请高德 Key

1. 打开 https://console.amap.com/dev/key/app
2. 注册 / 登录 → 控制台 → 应用管理 → 我的应用 → 创建新应用
3. 添加 Key，**服务平台务必选「Web服务」**（不是「Web端(JS API)」，也不是「iOS/Android」）
4. 复制生成的 32 位 Key

> 免费额度：个人开发者 Web 服务接口每天有免费调用量，日常测试完全够用。具体额度以高德控制台为准。

### 第 2 步：配置到 MCP 客户端

**方式 A：通过 env 传入（推荐）**

在你的 MCP 客户端配置里加上：

```json
{
  "mcpServers": {
    "easy-search-along-the-way": {
      "command": "npx",
      "args": ["-y", "github:KevinWangKaiYu/Easy-search-along-the-way"],
      "env": {
        "AMAP_KEY": "你的高德Web服务Key"
      }
    }
  }
}
```

**方式 B：不填 env，由工具录入**

配置里只写 command / args，然后对 AI 说「把我的高德 Key 设置成 xxx」，AI 会调用 `set_amap_key` 完成校验与保存。

两种方式的优先级：**env 变量 > 本地配置文件**。

**方式 C：网络受限时改用压缩包直链**

`github:owner/repo` 这种写法要求客户端能访问 `github.com`。在公司内网、透明代理等环境下 `github.com` 常被拦截（表现为 `502 Bad Gateway` 或 `fetch failed`），但 `codeload.github.com` 往往仍可访问。此时把 args 换成压缩包直链即可：

```json
{
  "mcpServers": {
    "easy-search-along-the-way": {
      "command": "npx",
      "args": [
        "-y",
        "https://codeload.github.com/KevinWangKaiYu/Easy-search-along-the-way/tar.gz/refs/tags/v1.0.0"
      ],
      "env": { "AMAP_KEY": "你的高德Web服务Key" }
    }
  }
}
```

这条直链指向 `v1.0.0` 标签，内容固定不变，比指向 `main` 分支更稳定（分支会变、标签不会）。

### 第 3 步：验证

直接问 AI：

```
济南泉城路周边 1 公里内有哪些商店？
```

```
从济南泉城路开到泰安泰山大街，沿途 2 公里内的加油站有哪些？
```

---

## 三、本地开发

```bash
git clone https://github.com/KevinWangKaiYu/Easy-search-along-the-way.git
cd Easy-search-along-the-way
npm install

# 冒烟测试（会真实走一遍 MCP 协议，依次调用三个工具）
AMAP_KEY=你的key npm run smoke

# 或直接启动（stdio 模式，通常由客户端拉起来，手跑会一直挂着）
npm start
```

## 四、目录结构

```
.
├── src/
│   ├── index.js     # MCP Server 入口：工具注册 + 业务编排
│   ├── amap.js      # 高德 Web 服务 API 封装（geocode / place/around / direction/driving）
│   ├── geo.js       # 几何计算：球面距离、折线累计里程、沿线采样
│   └── config.js    # 高德 Key 的读取与持久化
├── scripts/
│   └── smoke-test.js  # 端到端冒烟测试（真实 MCP 协议）
├── mcp.example.json   # MCP 客户端配置示例
└── package.json
```

## 五、实现原理

### 周边搜索

```
location ──► /v3/geocode/geo ──► 经纬度
                                   │
                                   └──► /v3/place/around (radius) ──► POI 列表
```

### 沿途搜索

```
origin/destination ──► /v3/geocode/geo ──► 经纬度
                                            │
                                            └──► /v3/direction/driving ──► 路线折线 + 总里程
                                                     │
                          沿折线按 interval 取采样点 ──┤
                                                     │
                       每个采样点 ► /v3/place/around (radius = distance)
                                                     │
                                        按 POI id / 坐标去重
                                                     │
                       把每个 POI 投影到折线（点到线段最近点）──► 离路线多远、沿路线走到哪
                                                     │
                                    剔除超出 distance 的 → 按 alongRouteDistance 排序
```

采样间隔 `interval` 默认取你传入的 `distance`（但最小 500 米）；当路线很长导致采样点超过 60 个时，会自动拉大间隔，以保证对高德 API 的调用次数可控。

## 六、已知限制

| 限制 | 说明 |
|---|---|
| 路线很长时可能漏点 | 采样上限 60 个点。若路线特别长且 `distance` 很小，采样间隔会被拉大，corridor 可能出现空隙 |
| 投影用平面近似 | `distanceToRoute` 用局部等距圆柱投影计算，几十公里范围内误差可忽略，跨省超长路线会有轻微偏差 |
| 高德关键词匹配 | 搜不到就真没有。例如高德基本没有「司机之家」这类数据 |
| 坐标系 | 全部使用高德坐标系（GCJ-02），与 GPS 原始坐标（WGS-84）有偏移 |
| 配额 | 受高德账号的 QPS 与日调用量限制，沿途搜索一次会产生多次 API 调用 |
| 并发 | 对高德的并发请求限制为 5 |

## 七、License

MIT