内容
# IRCTC 空缺席位查询
> 向 Perplexity 或 Claude 提问： *"我正在乘坐火车 12302，已在 NDLS 登车，前往 CNB — 有任何空余的卧铺吗？"*
> 获取：一个过滤后的空余席位列表，精确匹配您的行程段，无需原始数据分析。
## 工作原理
```
用户查询
│
▼
AI 提取：train_no, date, boarded_from, travel_to, class
│
▼
MCP 工具调用 → Python 执行所有工作：
1. POST /api/trainComposition → 车厢列表（cdd 密钥）
2. GET /trnscheduleenquiry/ → 完整的车站顺序
3. POST /api/coachComposition → 每铺位的 bsd 数据 [并行，信号量-5]
4. vacant_windows_from_bsd() → 查找空隙（occupancy=False 段）
5. window_covers() → 用户段是否匹配？
6. format_result() → 紧凑的 10 行字符串
│
▼
AI 接收以下信息（从不直接处理原始数据）：
"火车 12302 (KOLKATA MAIL) | 2026-06-04
您的行程段：NDLS → CNB
找到空余卧铺：3
── 车厢 S4 (SL) ──
铺位 32 [LB] 空余 NDLS → CNB
铺位 47 [UB] 空余 NDLS → HWH
── 车厢 S6 (SL) ──
铺位 12 [SL] 空余 NDLS → CNB"
```
## 已确认的 API 端点（来自 HAR + JS 包分析）
| 端点 | 方法 | 身份验证？ |
|---|---|---|
| `/online-charts/api/trainComposition` | POST | 无 |
| `/online-charts/api/coachComposition` | POST | 无 |
| `/online-charts/api/vacantBerth` | POST | 无（备用） |
| `/eticketing/protected/mapps1/trnscheduleenquiry/{no}` | GET | 无 |
> 已验证：图表页面不需要 cookie 或令牌（在隐身模式 + HAR 中确认）。
> **但是：** Akamai WAF 阻止数据中心 IP（Azure/GCP/AWS）。请在本地运行。
## 快速入门
```bash
git clone https://github.com/bratadeepsarkar123/irctc-vacancy-mcp
cd irctc-vacancy-mcp
pip install -r requirements.txt
# HTTP 服务器（Perplexity 连接器）
cd src
uvicorn http_server:app --port 8000 --reload
# 用于公共 HTTPS URL（粘贴到 Perplexity 作为自定义连接器）：
cloudflared tunnel --url http://localhost:8000
```
## MCP 设置（Claude Desktop / Cursor / Windsurf）
将 `mcp_config.json` 内容复制到您的 IDE 的 MCP 配置中。替换 `PATH_TO_REPO`:
```json
{
"mcpServers": {
"irctc-vacancy": {
"command": "python",
"args": ["/path/to/irctc-vacancy-mcp/src/mcp_server.py"]
}
}
}
```
然后提问： *"检查火车 12302 的空余卧铺，我从 NDLS 登车，前往 CNB"*
## 部署
| 选项 | 是否有效？ | 备注 |
|---|---|---|
| 本地机器 | ✅ 始终 | 住宅 IP 通过 Akamai |
| Cloudflare Tunnel + 本地 | ✅ 最佳 | 公共 HTTPS，在本地运行 |
| Oracle Cloud 免费层 | ✅ 通常 | 较少被阻止 |
| Azure / GCP / AWS | ❌ 已阻止 | Akamai WAF 标记数据中心 IP |
## 文件结构
```
src/
irctc_api.py — API 客户端（POST 端点，重试，并行异步）
vacancy_filter.py — 纯 Python 过滤（真实 bsd 结构）
main_tool.py — 协调器（所有服务器的单一入口点）
mcp_server.py — STDIO MCP（Claude Desktop / Cursor / AI IDE）
http_server.py — FastAPI HTTP（Perplexity 连接器）
session_helper.py — Playwright cookie 提取器（如果 Akamai 阻止则使用）
tests/
test_vacancy_filter.py — 单元测试（pytest）
AGENTS.md — 架构文档，用于 Jules / AI 代理
```
## 运行测试
```bash
pip install pytest
pytest tests/ -v
```
## 如果您被阻止（403 来自 Akamai）
运行 `session_helper.py` 一次，以通过 Playwright 抓取 cookie：
```bash
pip install playwright
playwright install chromium
python src/session_helper.py
# 复制打印的 cookie 字符串，然后：
export IRCTC_COOKIE="your_cookie_string_here"
```
然后重启服务器。cookie 将自动注入。
