使用说明

项目简介

12306 MCP 服务器是一款基于 Model Context Protocol (MCP) 标准开发的后端服务，专注于提供中国铁路 12306 的火车票相关查询功能。它旨在通过标准化的 JSON-RPC 协议，将复杂的火车票查询接口封装为 LLM (大型语言模型) 客户端易于理解和调用的工具 (Tools) 和资源 (Resources)，从而赋能 AI 自动化和智能助手应用。

主要功能点

全面的查询支持: 提供官方 12306 的实时余票、车次时刻、座席详情、车站信息、经停站列表以及中转换乘方案等一站式查询能力。
MCP 标准化接口: 通过实现 Model Context Protocol，将上述查询功能封装为遵循 MCP 规范的工具和数据接口，便于各类兼容 MCP 的 AI 客户端集成。
高效与易用: 基于 FastAPI 框架构建，支持异步处理，具备高性能。项目提供简单易懂的本地部署和 Docker 部署方案，配置灵活，开箱即用。
流式通信: 支持 SSE (Server-Sent Events) 流式协议， enabling 实时数据传输和通知，提升 AI 交互的流畅性。
智能辅助: 具备车站名称模糊搜索及自动匹配功能，优化用户输入体验。

安装步骤

本项目支持本地 Python 环境和 Docker 容器部署。

方式一：本地 Python 环境部署

环境准备: 确保您的系统已安装 Python 3.10 或更高版本。推荐使用 'uv' 作为包管理器。

克隆代码: 打开终端，执行以下命令克隆仓库：

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

安装依赖: 使用 'uv' 安装项目所需的依赖：
```
uv sync
```

更新车站信息: 首次运行或需要更新车站数据时，执行此脚本（必须先执行一次）：

uv run python scripts/update_stations.py

启动服务器: 运行启动脚本：

uv run python scripts/start_server.py

服务器默认将在 'http://localhost:8000' 启动。

方式二：Docker 部署

安装 Docker: 确保您的系统已安装 Docker。

拉取镜像: 直接从 Docker Hub 拉取预构建的镜像：

docker pull drfccv/mcp-server-12306:latest

运行容器: 运行以下命令启动容器，并将服务器端口映射到本地的 8000 端口：

docker run -d -p 8000:8000 --name 12306-mcp-server drfccv/mcp-server-12306:latest

容器将在后台运行，服务器默认在容器的 8000 端口提供服务。

服务器配置（供 MCP 客户端参考）

MCP 客户端需要配置服务器的启动方式和连接信息。对于此 12306 MCP 服务器，您可以配置您的 MCP 客户端，使其能够启动并连接到该服务。

以下是 MCP 客户端配置中关于此服务器的关键信息（具体配置格式取决于您的 MCP 客户端）：

服务器名称 (server name)：您可以为这个服务指定一个客户端友好的名称，例如 '12306' 或 'huochepiao'。
启动命令 (command)：用于启动此 MCP 服务器进程的命令。
- 对于本地 Python 部署，命令通常是您的 Python 环境的执行器路径加上启动脚本路径，例如 'python' 或 'uv'。
- 对于 Docker 部署，命令通常是 'docker'。
命令参数 (args)：传递给启动命令的参数列表。
- 对于本地 Python 部署，参数通常是启动脚本路径及其所需的参数，例如 '['scripts/start_server.py']' (如果使用 'python' command) 或 '['run', 'python', 'scripts/start_server.py']' (如果使用 'uv' command)。
- 对于 Docker 部署，参数通常是运行 Docker 容器的命令和参数，例如 '['run', '-p', '8000:8000', '--rm', 'drfccv/mcp-server-12306:latest']'。
连接信息 (connection)：一旦服务器启动，客户端需要知道如何连接。对于此服务器，默认使用 HTTP/SSE 协议，端点路径是 '/sse'。客户端通常需要配置连接类型（如 'sse'）和服务器地址 ('host' 和 'port')。
- 如果服务器运行在本地，地址通常是 'http://localhost:8000/sse'。
- 客户端通常会根据配置的 'command' 和 'args' 启动服务器，并在服务器启动后连接到指定的地址。

示例 MCP 客户端配置（概念说明，请参考您的客户端文档）

{
  "mcpServers": [
    {
      "name": "12306火车票",
      "command": "uv", // 或 "python", 或 "docker"
      "args": ["run", "python", "scripts/start_server.py"], // 或 ["docker", "run", "-p", "8000:8000", "--rm", "drfccv/mcp-server-12306:latest"]
      "connection": {
        "type": "sse",
        "url": "http://localhost:8000/sse" // 服务器启动后监听的地址
      },
      "description": "官方12306火车票查询服务"
    }
    // ... 其他 MCP 服务器配置
  ]
}

请将上述示例中的 'command' 和 'args' 替换为您实际使用的启动方式对应的命令和参数，并确保 'connection.url' 与服务器实际监听的地址一致。

基本使用方法（LLM 客户端调用）

一旦 MCP 客户端成功连接到 12306 MCP 服务器，LLM 或自动化脚本即可通过 JSON-RPC 调用服务器提供的工具。

例如，调用 'query_tickets' 工具查询火车票：

客户端发送 (JSON-RPC over SSE POST):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "query_tickets",
    "arguments": {
      "from_station": "上海",
      "to_station": "北京",
      "train_date": "2024-12-31"
    }
  },
  "id": "req-123"
}

服务器响应 (JSON-RPC over SSE POST):

{
  "jsonrpc": "2.0",
  "id": "req-123",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "🚄 **上海 → 北京** (2024-12-31)\n\n📊 找到 **X** 趟列车:\n\n**1.** 🚆 **GXX** （上海[SHH] → 北京南[VNP]）\n      ⏰ 'XX:XX' → 'XX:XX' (历时 X:XX)\n      💺 商务座:X | 一等座:X | 二等座:X | ...\n\n**2.** 🚆 **DYY** （上海[SHH] → 北京南[VNP]）\n      ...\n"
      }
      // 可能还有其他 type 的 content
    ]
  }
}

LLM 客户端会解析服务器返回的 'content' 字段，通常会优先处理 'type: text' 的内容以文本形式呈现给用户，或处理 'type: json' 的内容进行进一步的自动化处理。

其他工具 ('search_stations', 'query_transfer' 等) 也以类似的方式通过 'tools/call' 方法调用，并根据其定义的 'inputSchema' 结构传递 'arguments'。详细的工具参数和返回值结构，客户端可以通过 'tools/list' 方法获取，或参考项目文档 (虽然文档内容未提供，但结构中指出了位置)。

关键词