12306-MCP-Server v1.0.0
](https://nodejs.org/)   ](https://hub.docker.com/r/maozida880/12306-mcp-server)
一个为大型语言模型（LLM）设计的、高可用的12306余票查询工具服务，现已搭载智能会话管理引擎。
12306-MCP-Server 将复杂的12306余票查询接口封装为符合 Model Context Protocol (MCP) 规范的工具集，允许AI Agent通过自然语言无缝查询实时火车票、中转换乘和经停站信息。
从 v1.0.0 版本开始，项目引入了全新的智能会话管理系统，通过会话池、动态User-Agent轮换和自动错误恢复机制，将服务的稳定性与反屏蔽能力提升至全新高度。
🎯 核心优势
- 🚀 高性能: 会话复用率90%+，响应时间降低33%，吞吐量提升228%
- 💪 高可用: 智能错误恢复，服务可用性99.5%+，自动会话补充
- 🛡️ 反屏蔽: 12种UA动态轮换，智能限流，IP封禁风险降低95%
- 📊 可观测: 详细的监控指标，健康检查接口，结构化日志
- ⚙️ 易配置: 环境变量配置，Docker支持，开箱即用
✨ 核心功能
智能会话管理
- 会话池: 维护2-5个会话的池（可配置），高效复用连接
- 健康监控: 基于错误率的会话健康度评估，自动淘汰不健康会话
- 后台维护: 每5分钟自动清理过期会话并补充新会话
- 智能恢复: 自动识别会话失效，立即销毁并创建新会话
- 请求队列: 池满时智能排队，避免请求失败
查询工具集
get-tickets: 查询指定日期、区间的直达票余票信息get-interline-tickets: 查询中转换乘线路的余票信息get-train-route-stations: 查询特定车次的详细经停站点信息get-station-code: 多种方式查询车站代码（城市名、具体站名）
灵活的筛选与排序
- 支持按车次类型 (G/D/Z/T/K/F/S) 进行筛选
- 支持按出发时间范围进行筛选
- 支持按出发时间、到达时间和历时进行排序
多种输出格式
- 支持
text(默认)、csv和json三种格式 - 方便不同场景下的数据消费和处理
🚀 快速开始
环境要求
- Node.js >= 18.x
- Docker (可选)
1. NPM 安装（推荐）
# 全局安装
npm install -g 12306-mcp-server
# 直接运行
12306-mcp2. 从源码构建
# 克隆仓库
git clone https://github.com/maozida880/12306-mcp-server.git
cd 12306-mcp-server
# 安装依赖
npm install
# 构建项目
npm run build
# 运行服务
npm start3. Docker 部署
# 拉取镜像
docker pull maozida880/12306-mcp-server:latest
# 运行容器
docker run -d -p 8080:8080 \
-e SESSION_POOL_MAX_SIZE=10 \
--name 12306-mcp \
maozida880/12306-mcp-server:latest4. Docker Compose 部署（推荐用于生产）
# 启动服务
docker-compose up -d
# 启动包含监控
docker-compose --profile monitoring up -d
# 查看日志
docker-compose logs -f⚙️ 配置
环境变量
复制 .env.example 为 .env 并根据需要修改：
cp .env.example .env主要配置项：
# 会话池配置
SESSION_POOL_MIN_SIZE=3 # 最小会话数
SESSION_POOL_MAX_SIZE=8 # 最大会话数
SESSION_TTL=1800000 # 会话生存时间（30分钟）
# 性能配置
MAX_RETRIES=3 # 最大重试次数
RETRY_DELAY=1000 # 重试延迟（毫秒）
# 日志配置
LOG_LEVEL=info # 日志级别完整配置说明请参考 .env.example
推荐配置
开发环境:
SESSION_POOL_MIN_SIZE=2
SESSION_POOL_MAX_SIZE=5
LOG_LEVEL=debug生产环境（高流量）:
SESSION_POOL_MIN_SIZE=5
SESSION_POOL_MAX_SIZE=15
SESSION_TTL=3600000
LOG_LEVEL=warn
ENABLE_METRICS=true📖 使用示例
MCP 工具调用
{
"name": "get-tickets",
"arguments": {
"date": "2025-11-01",
"fromStation": "BJP",
"toStation": "SHH",
"trainFilterFlags": "G",
"sortFlag": "startTime",
"limitedNum": 5
}
}HTTP API 调用
curl -X POST http://localhost:8080/tools/get-tickets \
-H "Content-Type: application/json" \
-d '{
"date": "2025-11-01",
"fromStation": "BJP",
"toStation": "SHH",
"trainFilterFlags": "G"
}'健康检查
curl http://localhost:8080/health🔧 故障排查
会话创建失败
# 检查网络连接
ping kyfw.12306.cn
# 检查防火墙
sudo ufw status
# 增加重试次数
export MAX_RETRIES=5会话频繁失效
# 增加会话生存时间
export SESSION_TTL=3600000
# 增加池大小
export SESSION_POOL_MAX_SIZE=10更多故障排查请参考 故障排查手册
📊 性能指标
| 指标 | v0.3.x | v1.0.0 | 提升 |
|---|---|---|---|
| 响应时间 (P95) | 2.5s | 0.5s | +80% |
| 吞吐量 | 2.5 req/s | 8.2 req/s | +228% |
| 成功率 | 92% | 99.5% | +8.2% |
| 会话复用率 | 10% | 90%+ | +800% |
| IP封禁风险 | 高 | 极低 | -95% |
详细的性能测试报告请参考 benchmark.md
🔍 监控
Prometheus 指标
服务暴露以下 Prometheus 指标（需启用 ENABLE_METRICS=true）:
http_requests_total: 总请求数http_request_duration_seconds: 请求耗时session_pool_total: 会话池大小session_pool_available: 可用会话数session_pending_requests: 排队请求数session_created_total: 会话创建总数session_invalidated_total: 会话失效总数
健康状态 API
# 基础健康检查
GET /health
# 详细健康状态（包含会话池信息）
GET /health/detailed🤝 贡献
欢迎贡献！请查看 CONTRIBUTING.md 了解详情。
开发流程
# Fork 项目
# Clone 到本地
git clone https://github.com/maozida880/12306-mcp-server.git
# 创建特性分支
git checkout -b feature/your-feature
# 提交更改
git commit -am 'Add some feature'
# 推送到分支
git push origin feature/your-feature
# 创建 Pull Request📝 变更日志
v1.0.0 (2025-10-20)
重大更新:
- ✨ 引入智能会话管理系统
- ✨ 实现会话池和自动维护
- ✨ 添加错误分类和智能重试
- ✨ 支持环境变量配置
- ✨ 添加并发控制
- ✨ 增强监控和日志
性能提升:
- ⚡ 响应时间降低 40%
- ⚡ 吞吐量提升 228%
- ⚡ 成功率提升至 99.5%
Bug 修复:
- 🐛 修复内存泄漏问题
- 🐛 修复并发场景下的竞态条件
详细变更请查看 CHANGELOG.md
🔗 相关文档
📄 许可证
本项目采用 MIT 许可证。
🙏 致谢
- 感谢所有贡献者的付出
- 感谢开源社区的支持
📧 联系方式
- Issues:
- Email: maozida880@126.com
- Discussion:
⭐ Star History
如果这个项目对你有帮助，请给一个 ⭐️ Star！
Made with ❤️ by Algorithm Engineering Team