# 火车票查询 MCP Server（FastMCP）

用 FastMCP 实现的火车票/高铁车次查询服务，可作为远程 MCP 工具被任意 Agent（如 deepagents、LangGraph、Claude 等）调用。

## 能力

一个工具函数：`query_train_tickets(from_station, to_station, date)`

- 查询两个车站之间某天的车次、时刻、历时、可预订状态、余票情况
- 数据源：12306 公开查询接口（真实数据）；接口被风控时自动切换到**模拟数据**并明确标注来源，保证链路随时可演示

## 本地运行

```bash
pip install -r requirements.txt
python server.py        # 启动 streamable-http 服务，默认 http://127.0.0.1:8000
```

MCP 客户端配置（本地联调）：

```json
{
  "mcpServers": {
    "train": {
      "url": "http://127.0.0.1:8000/mcp/",
      "transport": "streamable_http"
    }
  }
}
```

## 部署到魔搭 MCP 广场（关键步骤）

1. 把本仓库推到 GitHub
2. 打开 [modelscope.cn/mcp](https://modelscope.cn/mcp) 登录 → 点 **「创建 MCP」**
3. 创建类型选 **「GitHub 快速创建」**；托管类型选 **「可托管部署」**
4. 填英文/中文名称、来源地址（GitHub 仓库 URL），按平台提示补全配置
5. 提交后平台生成访问地址：`https://mcp.api-inference.modelscope.net/<你的ID>/sse` 或 `/mcp`（可设置长期有效）
6. 把该地址填回 Agent 项目的 MCP 配置中即可

> 提示：平台对托管项目有启动方式要求（通常要求 Python + 启动 HTTP 服务），如遇部署失败，按平台提示调整入口（如提供 `run` 脚本或环境变量）。

## 数据源说明

- 12306 无官方开放 API，本项目使用其公开查询接口（kyfw.12306.cn/otn/leftTicket），免登录查询，仅限个人学习研究
- 接口有风控（偶发 302），代码已做会话 cookie + 模拟数据兜底
- 若需更稳定数据，可自行替换 `_fetch_12306` 为第三方数据源（可插拔）

## 目录

- `server.py` — FastMCP 服务主程序
- `test_client.py` — 本地联调脚本（直接调用工具函数 + 走 MCP 协议测试）
- `requirements.txt` — 依赖