Mcp Server 12306

📑 目次

• ✨ 機能
• 🚀 クイックスタート
  • 環境要件
  • 方法1：Stdio モード（ローカルクライアント向け）
  • 方法2：Streamable HTTP モード（リモートデプロイ）
  • 方法3：Docker デプロイ
• 🛠️ ツール一覧
• ⚙️ 設定項目
• 🏗️ プロジェクト構成
• 🧑‍💻 開発ガイド
• 📚 詳細ドキュメント
• ⚠️ 免責事項
• 📄 ライセンス

✨ 機能

🚀 クイックスタート

環境要件

💡 uv の使用をおすすめします。環境を分離でき、インストールが速く、ロックファイルで依存関係のバージョンを管理できます。

方法1：Stdio モード（ローカルクライアント向け）

MCP サーバーは標準入出力を通じてクライアントと通信するため、ネットワークポートを使用しません。Claude Desktop、Cursor などのローカル MCP クライアントに適しています。

インストール：

# uvx（推荐，环境隔离）
uvx mcp-server-12306

# 或 pip / pipx
pip install mcp-server-12306

クライアントの設定（claude_desktop_config.json など）：

{
  "mcpServers": {
    "12306": {
      "command": "uvx",
      "args": ["mcp-server-12306"]
    }
  }
}

{
  "mcpServers": {
    "12306": {
      "command": "pipx",
      "args": ["run", "--no-cache", "mcp-server-12306"]
    }
  }
}

git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync

{
  "mcpServers": {
    "12306": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-12306", "run", "mcp-server-12306"]
    }
  }
}

方法2：Streamable HTTP モード（リモートデプロイ）

サーバーは Web サービスを起動し（デフォルトのポートは 8000）、MCP Streamable HTTP プロトコルで通信します。POST で JSON-RPC を送信し、GET でストリーミング応答を購読し、DELETE でセッションを終了します。

起動：

# 安装后直接启动
mcp-12306

# 或本地源码启动
uv run python scripts/start_server.py

クライアントの設定：

{
  "mcpServers": {
    "12306": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

組み込み HTTP エンドポイント：

方法3：Docker デプロイ

# 拉取镜像并运行（默认端口 8000）
docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest

# 自定义端口
docker run -d -p 8080:8000 \
  -e SERVER_HOST=0.0.0.0 \
  -e SERVER_PORT=8000 \
  --name mcp-server-12306 \
  drfccv/mcp-server-12306:latest

🛠️ 工具一览

📖 每个工具的参数说明、返回示例、调用示例详见 📚 详细文档。

⚙️ 配置项

通过环境变量或项目根目录 .env 文件配置：

# 示例：.env
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
LOG_LEVEL=INFO

🏗️ 项目结构

mcp-server-12306/
├── src/mcp_12306/            # 主包
│   ├── server.py             # 核心 Server（工具注册与分发，双传输共享）
│   ├── stdio_server.py       # Stdio 传输层 + CLI 入口
│   ├── http_server.py        # Streamable HTTP 传输层 + HTTP 端点
│   ├── services/             # 业务逻辑
│   │   ├── station_service.py    # 车站数据服务（加载/搜索/编码转换）
│   │   └── ticket_service.py     # 票务查询核心（7 个工具实现）
│   ├── utils/                # 配置与日期工具
│   │   ├── config.py             # pydantic-settings 配置
│   │   └── date_utils.py         # 日期校验工具
│   └── resources/            # 静态资源（车站数据 station_name.js）
├── scripts/                  # 运维脚本
│   ├── start_server.py       # HTTP 模式一键启动（环境自检）
│   └── update_stations.py    # 更新车站数据
├── docs/                     # 工具详细文档
├── pyproject.toml            # 项目元数据 / 依赖 / 构建配置
├── Dockerfile                # 多阶段构建（python:3.12-alpine）
├── server.json               # MCP 注册表元数据
└── uv.lock                   # 依赖锁文件

🧑‍💻 开发指南

# 1. 克隆并初始化
git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync

# 2. 类型检查（mypy，严格模式）
uv run mypy src scripts

# 3. 代码格式化
uv run black src scripts
uv run isort src scripts

# 4. 构建与发布
uv run python -m build
uv run twine upload dist/*

架构要点：

• server.py 是传输无关的核心模块——工具注册（TOOL_HANDLERS）与业务分发（call_tool）都在此，stdio 与 HTTP 复用同一实例，保证两种模式行为完全一致。
• 工具 Schema 单一来源于 ticket_service.MCP_TOOLS，HTTP 的 /schema/tools 端点与 MCP 工具列表同源。
• 网络请求统一走 _request_with_retry（自动重试 + init 会话保持），业务错误与网络错误分离处理。

📚 详细文档

每份文档均包含：功能说明、实现方法、请求参数、返回示例与典型调用方式。

⚠️ 免责声明

• 本项目仅供学习、研究与技术交流，严禁用于任何商业用途。
• 本项目不存储、不篡改、不传播任何 12306 官方数据，仅作为官方公开接口的智能聚合与转发。
• 使用本项目造成的任何后果（包括但不限于账号封禁、数据异常、法律风险等）均由使用者本人承担，项目作者不承担任何责任。
• 请遵守中国法律法规及 12306 官方相关规定，合理合规使用。

📄 License

MIT © Drfccv