内容
# 내려(naeryeo CLI/MCP)
<p align="center">
<img src="./naeryeo.png" alt="naeryeo" width="320">
</p>
Claude Desktop, Claude Code 等 MCP 客户端中可以通过自然语言询问 대한민국 公共交通路线。
naeryeo 可以通过两种方式使用：
- **Skills & CLI** — 使用 SKILLS，AI 代理将在需要时将其作为上下文。（推荐）
- **MCP 服务器** — 支持 stdio MCP 服务器，适用于熟悉 MCP 服务器的用户。
这两种方式都需要 `naeryeo` 二进制文件和 ODsay API 密钥。
---
## 1. Skills & CLI
### 1-1. 安装
**安装 SKILL**
在 [skills.sh](https://skills.sh) 上搜索 naeryeo 或执行以下命令：
```bash
npx skills add GyeongHoKim/naeryeo
```
或者，您可以复制 skills 文件夹下的 SKILL.md 文件并将其粘贴到所需位置。
**安装二进制文件**
如果 SKILL 已正确安装，AI 代理将把 `naeryeo` 命令用作 CLI。因此，在此之前，请执行以下命令安装二进制文件：
```bash
# macOS / Linux 用户（Homebrew）
brew install --cask GyeongHoKim/tap/naeryeo
```
```powershell
# Windows 用户（Scoop）
scoop bucket add naeryeo https://github.com/GyeongHoKim/scoop-bucket
scoop install naeryeo
```
```bash
# 如果您想使用 npm 安装
npm install -g @gyeonghokim/naeryeo
```
如果您想在 Web 浏览器中下载二进制文件，可以从 [GitHub Release](https://github.com/GyeongHoKim/naeryeo/releases) 获取每个平台的存档。但是，在这种情况下，您需要将二进制文件设置为机器的 OS 路径，或者将二进制文件移动到 OS 默认路径中。
### 1-2. API 密钥注册
路径搜索需要 ODsay API 密钥。在 [ODsay](https://lab.odsay.com) 上获取应用密钥后：
```bash
naeryeo setup
```
```
ODsay API Key: ****************
保存到 OS 密钥链中
```
API 密钥仅存储在 OS 密钥链（macOS 密钥链 / Windows 凭证管理器 / Linux 机密服务）中，不存储在纯文本文件中，也不会传输到外部。
**（可选）建筑物名称和地址搜索密钥** - 请参阅下面的 1-4。
### 1-3. 使用
```bash
naeryeo route --from "江南站" --to "弘大入口站"
```
```
江南站 → 弘大入口站（约 42 分钟，换乘 1 次）
1. 在江南站乘坐 2 号线（开往 龟浦数字园区方向）
2. 在 新道林站换乘 2 号线 → 京义中央线
3. 在 弘大入口站下车
费用：1,500 韩元
```
### 1-4. 使用建筑物名称和地址搜索（可选）
路径搜索引擎（ODsay）**仅识别站点和车站名称**。诸如“XXX 롯데시네마”之类的建筑物名称或道路名称和地号地址需要单独的位置搜索服务。（此设置适用于 CLI 和 MCP 两种模式。）
- **不需要的情况**：如果您只询问站点名称，例如“江南站”，“逆三”，则不需要此设置。即使没有位置搜索密钥，站点/车站搜索仍将正常工作。
- **想使用的情况**：
1. 在 [Kakao Developers](https://developers.kakao.com) 上创建应用程序并获取 **REST API 密钥**，然后启用应用程序的 **Kakao Map（本地）服务**。
2. 注册密钥：
```bash
naeryeo setup --geocoder
```
```
Kakao REST API Key: ****************
保存到 OS 密钥链中
```
位置搜索密钥将作为 **单独的项目** 存储在 OS 密钥链中，与 ODsay 密钥分开。
3. 现在，您也可以使用建筑物名称和地址搜索：
```bash
naeryeo route --from "XXX 롯데시네마" --to "江南站"
```
- **未设置时**：如果您输入建筑物名称或地址，但没有位置搜索密钥，则会显示“找不到”并提示您使用 `naeryeo setup --geocoder` 设置密钥。
- **删除**：您可以使用 `naeryeo logout --geocoder` 删除位置搜索密钥（保留 ODsay 密钥）。
---
## 2. MCP 服务器（stdio）
这是适用于 Claude Desktop 等 MCP 客户端的，自然语言询问公共交通路线的方法。
### 2-1. 安装和密钥注册
二进制文件安装和 API 密钥注册与 **[1-1 安装](#1-1-安装)·[1-2 API 密钥注册](#1-2-api-密钥注册)** 相同（安装 `naeryeo` 二进制文件后，执行 `naeryeo setup`）。如果需要建筑物名称和地址搜索，请同时注册 [1-4](#1-4-使用建筑物名称和地址搜索可选) 的 `naeryeo setup --geocoder`。
### 2-2. 连接
在 `claude_desktop_config.json` 中添加以下内容：
**安装二进制文件的情况**（Homebrew · Scoop · npm 全局安装 - `naeryeo` 在 PATH 中）：
```json
{
"mcpServers": {
"naeryeo": {
"command": "naeryeo",
"args": ["mcp"]
}
}
}
```
**不全局安装 npm 而是每次运行的情况**（npx）：
```json
{
"mcpServers": {
"naeryeo": {
"command": "npx",
"args": ["-y", "@gyeonghokim/naeryeo", "mcp"]
}
}
}
```
在配置文件中不添加 API 密钥 - 无论哪种方式，都使用通过 `naeryeo setup` 存储在 OS 密钥链中的值。
### 2-3. 使用
注册后，您可以在 Claude Desktop 上这样询问：
> “现在从江南站到弘大入口站怎么走？”
---
## 命令
| 命令 | 说明 |
| --- | --- |
| `naeryeo setup` | ODsay（路径搜索）API 密钥注册 |
| `naeryeo setup --geocoder` | 位置搜索（Kakao）API 密钥注册 - 用于建筑物名称和地址搜索（可选） |
| `naeryeo logout` | 删除已保存的 ODsay API 密钥 |
| `naeryeo logout --geocoder` | 删除已保存的位置搜索 API 密钥 |
| `naeryeo route --from <起点> --to <终点>` | 路径搜索（CLI 模式） |
| `naeryeo mcp` | 启动为 MCP stdio 服务器 |
| `naeryeo --version` | 版本确认 |
## 架构
```
naeryeo/
cmd/naeryeo/ # 子命令入口点（setup, route, mcp）
internal/core/ # 路径搜索逻辑（ODsay 客户端，公共领域模型，Geocoder 接口）
internal/geocode/ # 位置搜索（地理编码）互操作 - 建筑物名称/地址 → 坐标（Kakao）
internal/config/ # OS 密钥链互操作（go-keyring）基于 API 密钥存储/检索
```
CLI 和 MCP 模式共享相同的 `internal/core` 逻辑，但入口点不同。
## 使用的 API
- **公共交通路线搜索**：使用 [ODsay API](https://lab.odsay.com)。由于 Kakao 和 Naver 地图 API 不支持公共交通路线搜索，而 Google Directions API 因国内地图导出法规（「空间信息建设及管理等に関する法律」）无法用于国内公共交通路线搜索，因此使用 ODsay API。
- **建筑物名称/地址 → 坐标（地理编码，可选）**：ODsay 没有将建筑物名称/地址转换为坐标的功能，因此对于非站点名称，使用 [Kakao Local 关键词搜索](https://developers.kakao.com/docs/latest/en/local/dev-guide) 获取坐标。此步骤仅用于名称 → 坐标解释，不用于路径搜索。如果未注册位置搜索密钥，则此步骤将被禁用。
## 许可
MIT
