# 公交查询 MCP 服务

提供公交线路搜索、公交位置查询和线路基本信息查询功能的 MCP (Model Context Protocol) 服务。

## 功能特性

- 搜索可用的公交线路
- 查询公交车的实时位置（包括车牌号和所在站点）
- 查询公交线路的基本信息（起点站、终点站、首末班时间、票价等）
- 支持多个同名线路的选择（如67路、67路区间等）
- 支持上行/下行方向查询

## 安装

```bash
pip install bus-query-mcp
```

或使用 uv:

```bash
uv pip install bus-query-mcp
```

## 使用方法

### 启动 MCP 服务器

```bash
bus-query-mcp
```

### 可用工具

#### 1. search_bus_routes_tool

搜索可用的公交线路。

**参数:**
- `key` (str): 搜索关键词，如 '67' 表示67路公交

**返回:**
- 匹配的线路列表，包含线路名称和详情页链接

**示例:**
```json
{
  "success": true,
  "key": "67",
  "routes": [
    {
      "line_name": "67路",
      "url": "./index.php?i=5&c=entry&linename=67路&search=search&do=line&m=ytbus"
    },
    {
      "line_name": "67路区间1",
      "url": "./index.php?i=5&c=entry&linename=67路区间1&search=search&do=line&m=ytbus"
    }
  ]
}
```

#### 2. get_bus_location_tool

查询指定公交线路的实时位置信息。

**参数:**
- `detail_url` (str): 从 search_bus_routes_tool 获取的详情页链接，用于精确查询
- `direction` (str, 可选): 公交方向，'上行'或'下行'，默认为'上行'

**返回:**
- 车辆位置信息，包含车牌号和所在站点的对应关系

**示例:**
```json
{
  "success": true,
  "line_name": "67路区间1",
  "direction": "上行",
  "bus_count": 3,
  "bus_locations": [
    {
      "license_plate": "鲁F12345D",
      "station": "火车站",
      "direction": "上行"
    },
    {
      "license_plate": "鲁F67890D",
      "station": "市政府",
      "direction": "上行"
    }
  ]
}
```

#### 3. get_bus_line_info_tool

查询公交线路的基本信息。

**参数:**
- `detail_url` (str): 从 search_bus_routes_tool 获取的详情页链接，用于精确查询

**返回:**
- 线路基本信息，包含起点站、终点站、首末班时间、票价等

**示例:**
```json
{
  "success": true,
  "line_name": "50路",
  "line_info": {
    "线路名称": "50路",
    "起点站": "桐林路南口",
    "终点站": "火车站",
    "运行季节": "夏季（5月1日起）冬季（11月1日起）",
    "首班时间": "首班：05:30",
    "末班时间": "末班：22:00",
    "票价": "票价1.00元"
  }
}
```

## 使用流程

1. 使用 `search_bus_routes_tool` 搜索线路
2. 如果返回多个线路，让用户选择需要查询的线路
3. 使用 `get_bus_line_info_tool` 查询选中线路的基本信息（起点、终点、票价等）
4. 使用 `get_bus_location_tool` 查询选中线路的实时位置

## 示例对话

**用户**: 查询50路公交

**助手**: 搜索到以下线路：
1. 50路
2. 50路区间

请选择要查询的线路。

**用户**: 选择50路

**助手**: 50路基本信息：
- 起点: 桐林路南口
- 终点: 火车站
- 首班: 05:30
- 末班: 22:00
- 票价: 1.00元

50路（上行）当前有3辆车在运行：
- 鲁F06677D 在 火车站东站
- 鲁F06303D 在 迟家站
- 鲁F06820D 在 美迎美家家居广场站

## 依赖

- Python >= 3.10
- aiohttp >= 3.9.0
- mcp >= 0.9.0
- beautifulsoup4 >= 4.12.0

## 开发

### 克隆仓库

```bash
git clone https://github.com/yourusername/bus-query-mcp.git
cd bus-query-mcp
```

### 安装依赖

```bash
pip install -e .
```

或使用 uv:

```bash
uv pip install -e .
```

### 运行测试

```bash
python -m bus_query_mcp.main
```

## 发布

参见 [pythonMCP发布步骤.md](../pythonMCP发布步骤.md)

## 许可证

MIT License

## 数据来源

本服务使用的数据来自烟台公交系统 (https://ytbus.edong500.com)。

## 注意事项

- 本服务仅供学习和个人使用
- 请勿频繁请求，以免给服务器造成压力
- 数据仅供参考，实际乘车请以站牌信息为准