使用说明

• 项目简介

  • 该仓库实现了一个可运行的 MCP 服务器框架，用于向大语言模型（LLM）客户端提供铁路数据的上下文信息与功能入口。核心功能包括站点数据的统一服务、价格查询工具以及基于 GTFS 的排班查询能力，并通过安全机制（API 密钥、速率限制、日志记录）进行访问控制。

• 主要功能点

  • MCP 服务器入口：基于 FastMCP，定义可由 LLM 调用的工具（Tools），并通过 JSON-RPC 与客户端通信。
  • 工具集成：包含 train 搜索、站点查询、票价查询等工具，并结合身份认证与速率限制进行保护。
  • 安全策略：包含 API Key 验证、速率限制、日志记录与敏感数据保护的实现。
  • 数据源与查询能力：
    • GTFS 数据：通过 ScheduleSearcher 加载 expires-renfe_schedule 下的 GTFS 数据，支持基于日期的排班查询。
    • Renfe 数据：通过统一的 StationService 将 GTFS 数据与 Renfe 的站点编码整合，支持价格查询所需的 Renfe 编码。
  • 数据更新与安全提取：update_data 模块实现 GTFS 数据的更新、以及对下载数据的安全 ZIP 提取（防止 Zip Slip 等攻击）。

• 安装步骤

  • 将代码克隆至本地。
  • 安装依赖（Python 环境，建议使用虚拟环境）：
    • pip install -r 依赖文件（若仓库未给出固定依赖，请自行安装如 fastmcp、httpx、pandas、pydantic、dateutil、python-dotenv 等）
  • 运行 MCP 服务器：
    • 进入仓库目录，执行 python -m renfe_mcp.server（或直接运行 src/renfe_mcp/server.py，视打包方式而定）
  • 运行后服务器会监听并通过 MCP 客户端进行 JSON-RPC 调用。

• 服务器配置（MCP 客户端需要的配置，JSON 格式，包含 server name、command、args 等）

  • server name: Renfe Train MCP Server
  • command: python
  • args: ["-m", "renfe_mcp.server"]
  • 注释说明：
    • server name：用于标识 MCP 服务器的名称，便于客户端在多服务器环境中区分。
    • command/args：用于启动服务器的命令行参数。这里提供的是最直接的启动方式，使用 Python 解释器执行模块 Renfe MCP 服务器入口。

• 基本使用方法

  • 启动后，MCP 客户端（LLM 系统）即可通过标准 MCP 机制向服务器发出请求，例如：
    • 调用搜索列车工具以获取 Madrid 到 Barcelona 的列车信息。
    • 请求获取指定城市的站点列表及其 Renfe 编码，用于后续的价格查询。
    • 使用价格查询工具获得指定日期的实时票价与可用性信息。
  • 认证与安全：若环境开启了认证，LLM 客户端需提供 api_key 参数（或者在配置中设置 RENFE_API_KEY），才能通过鉴权并执行请求。
  • 服务器日志与调试：在配置允许的情况下，日志会记录访问、错误与安全事件，便于排错与审计。