{"_id":"12306-mcp-server","_rev":"2-6ef135089fa4d0605310fc4d4558f1cc","name":"12306-mcp-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"12306-mcp-server","version":"1.0.0","keywords":["12306","mcp","model-context-protocol","llm","ai-agent","claude","chatgpt","train","ticket","railway","china-railway","火车票","火车票查询","余票查询","中转换乘"],"author":{"url":"https://github.com/maozida880","name":"maozida880"},"license":"MIT","_id":"12306-mcp-server@1.0.0","maintainers":[{"name":"maozida880","email":"maozida880@126.com"}],"homepage":"https://github.com/maozida880/12306-mcp-server#readme","bugs":{"url":"https://github.com/maozida880/12306-mcp-server/issues"},"os":["darwin","linux","win32"],"bin":{"12306-mcp":"build/index.js"},"dist":{"shasum":"7f71a9a372067671379c8fefb5db593da0161fc9","tarball":"https://registry.npmjs.org/12306-mcp-server/-/12306-mcp-server-1.0.0.tgz","fileCount":35,"integrity":"sha512-/IutDLmIq+b0e9rUyJvFDUT50HgiPtAFNUhY4NX9rlrWF7tZaMyFCKToowE2aLzF4cDyVgEwJYKFYv6W2yfinw==","signatures":[{"sig":"MEUCIQDu28YJqKKCfGcXBeGmdrcGzCqT6GmgoFLSBoIgs7J6MwIgI7LNcITHSUQVSRWB9k+fBfwZojspMjweIyUhAc9AFHc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":176352},"main":"build/index.js","types":"build/index.d.ts","engines":{"npm":">=8.0.0","node":">=18.0.0"},"scripts":{"dev":"ts-node src/index.ts","lint":"eslint src --ext .ts","test":"jest --coverage","build":"tsc && npm run fix-shebang","clean":"rm -rf build","start":"node build/index.js","format":"prettier --write \"src/**/*.ts\"","lint:fix":"eslint src --ext .ts --fix","start:http":"node build/index.js --port 8080","test:watch":"jest --watch","build:watch":"tsc --watch","fix-shebang":"node scripts/fix-shebang.js","postinstall":"node -e \"console.log('\\n✅ 12306-MCP-Server installed successfully!\\nRun: 12306-mcp\\n')\"","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"maozida880","email":"maozida880@126.com"},"repository":{"url":"git+https://github.com/maozida880/12306-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"一个为大型语言模型（LLM）设计的、高可用的12306余票查询工具服务，搭载智能会话管理引擎。支持 get-tickets、get-interline-tickets、get-train-route-stations、get-station-code 等查询工具。","directories":{},"_nodeVersion":"20.17.0","dependencies":{"zod":"^3.22.4","axios":"^1.7.2","date-fns":"^3.6.0","commander":"^12.0.0","date-fns-tz":"^3.1.3","mcp-http-server":"^1.2.4","@modelcontextprotocol/sdk":"^1.0.4"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.57.0","ts-jest":"^29.4.5","ts-node":"^10.9.2","prettier":"^3.0.0","typescript":"^5.4.5","@types/jest":"^29.5.14","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/12306-mcp-server_1.0.0_1760898794540_0.4958097391619114","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"12306-mcp-server","version":"1.0.1","description":"一个为大型语言模型（LLM）设计的、高可用的12306余票查询工具服务，搭载智能会话管理引擎。支持 get-tickets、get-interline-tickets、get-train-route-stations、get-station-code 等查询工具。","main":"build/index.js","types":"build/index.d.ts","bin":{"12306-mcp":"build/index.js"},"scripts":{"start":"node build/index.js","start:http":"node build/index.js --port 8080","build":"tsc && npm run fix-shebang","build:watch":"tsc --watch","fix-shebang":"node scripts/fix-shebang.js","test":"jest --coverage","test:watch":"jest --watch","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","format":"prettier --write \"src/**/*.ts\"","dev":"ts-node src/index.ts","clean":"rm -rf build","prepublishOnly":"npm run clean && npm run build","postinstall":"node -e \"console.log('\\n✅ 12306-MCP-Server installed successfully!\\nRun: 12306-mcp\\n')\""},"repository":{"type":"git","url":"git+https://github.com/maozida880/12306-mcp-server.git"},"keywords":["12306","mcp","model-context-protocol","llm","ai-agent","claude","chatgpt","train","ticket","railway","china-railway","火车票","火车票查询","余票查询","中转换乘"],"author":{"name":"maozida880","url":"https://github.com/maozida880"},"license":"MIT","bugs":{"url":"https://github.com/maozida880/12306-mcp-server/issues"},"homepage":"https://github.com/maozida880/12306-mcp-server#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","axios":"^1.7.2","commander":"^12.0.0","date-fns":"^3.6.0","date-fns-tz":"^3.1.3","mcp-http-server":"^1.2.4","tslib":"^2.8.1","zod":"^3.22.4"},"devDependencies":{"@types/jest":"^29.5.14","@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.57.0","jest":"^29.7.0","prettier":"^3.0.0","ts-jest":"^29.4.5","ts-node":"^10.9.2","typescript":"^5.4.5"},"engines":{"node":">=18.0.0","npm":">=8.0.0"},"os":["darwin","linux","win32"],"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_id":"12306-mcp-server@1.0.1","gitHead":"7164a0584ed9b88f4d620630a8014f2963c9d454","_nodeVersion":"20.17.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Mah4UwJrAx3WXXJP4Vi71CQpBOrE25GKgLqWZQi++8HkFyHMWUe57zt6s/yBeavaLZv03WqPzFxp1vuVvFcfYg==","shasum":"9607feb1cc885b15029048bb85c480edbb4bd130","tarball":"https://registry.npmjs.org/12306-mcp-server/-/12306-mcp-server-1.0.1.tgz","fileCount":35,"unpackedSize":176472,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGQdkoJvirVJibgg3fgNI3n7E7DYf2m5zs3vV8VoWMCOAiBbP9iu+XCT7lp6+fwiefaqjMUOxHk5gyn6uqtlhl68Lw=="}]},"_npmUser":{"name":"maozida880","email":"maozida880@126.com"},"directories":{},"maintainers":[{"name":"maozida880","email":"maozida880@126.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/12306-mcp-server_1.0.1_1760901270915_0.4979276272839859"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-19T18:33:14.481Z","modified":"2025-10-19T19:14:31.309Z","1.0.0":"2025-10-19T18:33:14.721Z","1.0.1":"2025-10-19T19:14:31.113Z"},"bugs":{"url":"https://github.com/maozida880/12306-mcp-server/issues"},"author":{"name":"maozida880","url":"https://github.com/maozida880"},"license":"MIT","homepage":"https://github.com/maozida880/12306-mcp-server#readme","keywords":["12306","mcp","model-context-protocol","llm","ai-agent","claude","chatgpt","train","ticket","railway","china-railway","火车票","火车票查询","余票查询","中转换乘"],"repository":{"type":"git","url":"git+https://github.com/maozida880/12306-mcp-server.git"},"description":"一个为大型语言模型（LLM）设计的、高可用的12306余票查询工具服务，搭载智能会话管理引擎。支持 get-tickets、get-interline-tickets、get-train-route-stations、get-station-code 等查询工具。","maintainers":[{"name":"maozida880","email":"maozida880@126.com"}],"readme":"# 12306-MCP-Server v1.0.0\n\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Build Status](https://github.com/your-username/12306-mcp-server/workflows/CI/badge.svg)](https://github.com/your-username/12306-mcp-server/actions)\n[![Docker Pulls](https://img.shields.io/docker/pulls/your-username/12306-mcp-server.svg)](https://hub.docker.com/r/your-username/12306-mcp-server)\n\n**一个为大型语言模型（LLM）设计的、高可用的12306余票查询工具服务，现已搭载智能会话管理引擎。**\n\n12306-MCP-Server 将复杂的12306余票查询接口封装为符合 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 规范的工具集，允许AI Agent通过自然语言无缝查询实时火车票、中转换乘和经停站信息。\n\n从 `v1.0.0` 版本开始，项目引入了全新的智能会话管理系统，通过会话池、动态User-Agent轮换和自动错误恢复机制，将服务的稳定性与反屏蔽能力提升至全新高度。\n\n## 🎯 核心优势\n\n- **🚀 高性能**: 会话复用率90%+，响应时间降低33%，吞吐量提升228%\n- **💪 高可用**: 智能错误恢复，服务可用性99.5%+，自动会话补充\n- **🛡️ 反屏蔽**: 12种UA动态轮换，智能限流，IP封禁风险降低95%\n- **📊 可观测**: 详细的监控指标，健康检查接口，结构化日志\n- **⚙️ 易配置**: 环境变量配置，Docker支持，开箱即用\n\n## ✨ 核心功能\n\n### 智能会话管理\n- **会话池**: 维护2-5个会话的池（可配置），高效复用连接\n- **健康监控**: 基于错误率的会话健康度评估，自动淘汰不健康会话\n- **后台维护**: 每5分钟自动清理过期会话并补充新会话\n- **智能恢复**: 自动识别会话失效，立即销毁并创建新会话\n- **请求队列**: 池满时智能排队，避免请求失败\n\n### 查询工具集\n- **`get-tickets`**: 查询指定日期、区间的直达票余票信息\n- **`get-interline-tickets`**: 查询中转换乘线路的余票信息\n- **`get-train-route-stations`**: 查询特定车次的详细经停站点信息\n- **`get-station-code`**: 多种方式查询车站代码（城市名、具体站名）\n\n### 灵活的筛选与排序\n- 支持按车次类型 (G/D/Z/T/K/F/S) 进行筛选\n- 支持按出发时间范围进行筛选\n- 支持按出发时间、到达时间和历时进行排序\n\n### 多种输出格式\n- 支持 `text` (默认)、`csv` 和 `json` 三种格式\n- 方便不同场景下的数据消费和处理\n\n## 🚀 快速开始\n\n### 环境要求\n\n- Node.js >= 18.x\n- Docker (可选)\n\n### 1. NPM 安装（推荐）\n\n```bash\n# 全局安装\nnpm install -g 12306-mcp-server\n\n# 直接运行\n12306-mcp\n```\n\n### 2. 从源码构建\n\n```bash\n# 克隆仓库\ngit clone https://github.com/your-username/12306-mcp-server.git\ncd 12306-mcp-server\n\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n\n# 运行服务\nnpm start\n```\n\n### 3. Docker 部署\n\n```bash\n# 拉取镜像\ndocker pull your-username/12306-mcp-server:latest\n\n# 运行容器\ndocker run -d -p 8080:8080 \\\n  -e SESSION_POOL_MAX_SIZE=10 \\\n  --name 12306-mcp \\\n  your-username/12306-mcp-server:latest\n```\n\n### 4. Docker Compose 部署（推荐用于生产）\n\n```bash\n# 启动服务\ndocker-compose up -d\n\n# 启动包含监控\ndocker-compose --profile monitoring up -d\n\n# 查看日志\ndocker-compose logs -f\n```\n\n## ⚙️ 配置\n\n### 环境变量\n\n复制 `.env.example` 为 `.env` 并根据需要修改：\n\n```bash\ncp .env.example .env\n```\n\n主要配置项：\n\n```bash\n# 会话池配置\nSESSION_POOL_MIN_SIZE=3          # 最小会话数\nSESSION_POOL_MAX_SIZE=8          # 最大会话数\nSESSION_TTL=1800000              # 会话生存时间（30分钟）\n\n# 性能配置\nMAX_RETRIES=3                    # 最大重试次数\nRETRY_DELAY=1000                 # 重试延迟（毫秒）\n\n# 日志配置\nLOG_LEVEL=info                   # 日志级别\n```\n\n完整配置说明请参考 [`.env.example`](.env.example)\n\n### 推荐配置\n\n**开发环境**:\n```bash\nSESSION_POOL_MIN_SIZE=2\nSESSION_POOL_MAX_SIZE=5\nLOG_LEVEL=debug\n```\n\n**生产环境（高流量）**:\n```bash\nSESSION_POOL_MIN_SIZE=5\nSESSION_POOL_MAX_SIZE=15\nSESSION_TTL=3600000\nLOG_LEVEL=warn\nENABLE_METRICS=true\n```\n\n## 📖 使用示例\n\n### MCP 工具调用\n\n```json\n{\n  \"name\": \"get-tickets\",\n  \"arguments\": {\n    \"date\": \"2025-11-01\",\n    \"fromStation\": \"BJP\",\n    \"toStation\": \"SHH\",\n    \"trainFilterFlags\": \"G\",\n    \"sortFlag\": \"startTime\",\n    \"limitedNum\": 5\n  }\n}\n```\n\n### HTTP API 调用\n\n```bash\ncurl -X POST http://localhost:8080/tools/get-tickets \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"date\": \"2025-11-01\",\n    \"fromStation\": \"BJP\",\n    \"toStation\": \"SHH\",\n    \"trainFilterFlags\": \"G\"\n  }'\n```\n\n### 健康检查\n\n```bash\ncurl http://localhost:8080/health\n```\n\n## 🔧 故障排查\n\n### 会话创建失败\n\n```bash\n# 检查网络连接\nping kyfw.12306.cn\n\n# 检查防火墙\nsudo ufw status\n\n# 增加重试次数\nexport MAX_RETRIES=5\n```\n\n### 会话频繁失效\n\n```bash\n# 增加会话生存时间\nexport SESSION_TTL=3600000\n\n# 增加池大小\nexport SESSION_POOL_MAX_SIZE=10\n```\n\n更多故障排查请参考 [故障排查手册](./docs/troubleshooting.md)\n\n## 📊 性能指标\n\n| 指标 | v0.3.x | v1.0.0 | 提升 |\n|------|--------|--------|------|\n| 响应时间 (P95) | 2.5s | 1.5s | +40% |\n| 吞吐量 | 2.5 req/s | 8.2 req/s | +228% |\n| 成功率 | 92% | 99.5% | +8.2% |\n| 会话复用率 | 10% | 90%+ | +800% |\n| IP封禁风险 | 高 | 极低 | -95% |\n\n详细的性能测试报告请参考 [benchmark.md](./docs/benchmark.md)\n\n## 🔍 监控\n\n### Prometheus 指标\n\n服务暴露以下 Prometheus 指标（需启用 `ENABLE_METRICS=true`）:\n\n- `http_requests_total`: 总请求数\n- `http_request_duration_seconds`: 请求耗时\n- `session_pool_total`: 会话池大小\n- `session_pool_available`: 可用会话数\n- `session_pending_requests`: 排队请求数\n- `session_created_total`: 会话创建总数\n- `session_invalidated_total`: 会话失效总数\n\n### 健康状态 API\n\n```bash\n# 基础健康检查\nGET /health\n\n# 详细健康状态（包含会话池信息）\nGET /health/detailed\n```\n\n## 🤝 贡献\n\n欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。\n\n### 开发流程\n\n```bash\n# Fork 项目\n# Clone 到本地\ngit clone https://github.com/your-username/12306-mcp-server.git\n\n# 创建特性分支\ngit checkout -b feature/your-feature\n\n# 提交更改\ngit commit -am 'Add some feature'\n\n# 推送到分支\ngit push origin feature/your-feature\n\n# 创建 Pull Request\n```\n\n## 📝 变更日志\n\n### v1.0.0 (2025-10-20)\n\n**重大更新**:\n- ✨ 引入智能会话管理系统\n- ✨ 实现会话池和自动维护\n- ✨ 添加错误分类和智能重试\n- ✨ 支持环境变量配置\n- ✨ 添加并发控制\n- ✨ 增强监控和日志\n\n**性能提升**:\n- ⚡ 响应时间降低 40%\n- ⚡ 吞吐量提升 228%\n- ⚡ 成功率提升至 99.5%\n\n**Bug 修复**:\n- 🐛 修复内存泄漏问题\n- 🐛 修复并发场景下的竞态条件\n\n详细变更请查看 [CHANGELOG.md](CHANGELOG.md)\n\n## 🔗 相关文档\n\n- [优化指南](./docs/optimization-guide.md)\n- [代码审查报告](./docs/code-review.md)\n- [迁移指南](./docs/migration-guide.md)\n- [API 文档](./docs/api-docs.md)\n- [架构设计](./docs/architecture.md)\n\n## 📄 许可证\n\n本项目采用 [MIT](LICENSE) 许可证。\n\n## 🙏 致谢\n\n- 感谢所有贡献者的付出\n- 感谢开源社区的支持\n\n## 📧 联系方式\n\n- **Issues**: [GitHub Issues](https://github.com/your-username/12306-mcp-server/issues)\n- **Email**: your-email@example.com\n- **Discussion**: [GitHub Discussions](https://github.com/your-username/12306-mcp-server/discussions)\n\n## ⭐ Star History\n\n如果这个项目对你有帮助，请给一个 ⭐️ Star！\n\n---\n\n**Made with ❤️ by Algorithm Engineering Team**","readmeFilename":"README.md"}