AI导哈

荷兰铁路MCP服务器

一个基于模型上下文协议（MCP）的服务器，使AI助手能够与荷兰铁路（NS）API进行交互，用于路线规划、票价查询和实时出发信息。

  • by eze-godoy
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 eze-godoy/py-mcp-train-nl

使用说明

荷兰NS列车的MCP服务器

mcp名称：ns桥

A. 模型上下文协议（MCP） 服务器，使人工智能助手能够与荷兰铁路（NS）API交互，以进行路线规划、定价和实时发车信息。

与任何MCP客户端兼容，包括Claude Desktop、自定义实现和AI代理框架。

特性

MCP工具

  1. 搜索_状态 -按名称或国家查找火车站

    • 按车站名称搜索
    • 按国家代码筛选
    • 返回行程规划所需的车站代码

  2. 搜索条 -规划车站之间的路线

    • 通过连接获得多种旅行选择
    • 查看详细的逐段行程信息
    • 查看带有折扣选项的定价
    • 选择旅行舱位（1级或2级）
    • 按出发或到达时间搜索

  3. 获取_公寓 -查看实时出发板

    • 查看任何车站即将出发的航班
    • 跟踪延迟和取消
    • 监控平台变化

MCP资源

  • station://{code} -获取特定电台的详细信息

安装

先决条件

  • 来自的NS API密钥 NS API门户网站
  • 选择一种安装方法：
    • 码头工人 （最简单-无需安装Python）
    • 紫外线 （建议开发）
    • 点 （传统Python工作流程）

选项1:Docker（最简单）

先决条件：Docker桌面或Docker引擎

# Pull the pre-built image from Docker Hub
docker pull ezegodoy26/mcp-server-ns-bridge:latest

然后配置MCP客户端（请参阅 用法 以下部分为配置示例）。

有关Docker的详细使用、故障排除和高级选项，请参阅 医生.md.

选项2：使用紫外线设置（建议用于开发）

# Clone the repository
cd mcp-server-ns-bridge

# Install dependencies
uv sync --all-extras

# Set up pre-commit hooks (recommended for development)
uv run pre-commit install

# Copy environment template
cp .env.example .env

# Edit .env and add your NS API key
# NS_API_KEY=your_actual_api_key_here

选项3：使用pip进行设置

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Set up environment
cp .env.example .env
# Edit .env and add your NS API key

获取NS API密钥

  1. 首选 NS API门户网站
  2. 创建账户
  3. 订阅以下API：
    • 旅行信息API（Travel Information API）
    • NS-APP站点API
  4. 复制您的订阅密钥
  5. 将其添加到您的 .env 文件为 NS_API_KEY

用法

运行MCP服务器

开发模式（带检查员）

export PATH="$HOME/.local/bin:$PATH"
uv run mcp dev src/ns_bridge/server.py

这将打开MCP检查器进行交互式测试。

配置MCP客户端

此服务器可与任何兼容MCP的客户端配合使用。下面是常见客户端的配置示例。

克劳德桌面版

自动安装：

uv run mcp install src/ns_bridge/server.py

这将自动配置Claude Desktop以使用您的MCP服务器。

手动配置：

添加到您的Claude Desktop配置文件中（位置因操作系统而异）：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

对于Docker安装：

{
  "mcpServers": {
    "ns-bridge": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "NS_API_KEY",
        "ezegodoy26/mcp-server-ns-bridge:latest"
      ],
      "env": {
        "NS_API_KEY": "your_api_key_here"
      }
    }
  }
}

备注：The -e NS_API_KEY 在 args array命令Docker从主机传递环境变量（由 env 部分）放入容器中。如果没有这一点，API密钥将无法在Docker中使用。

对于紫外线安装：

{
  "mcpServers": {
    "ns-bridge": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-server-ns-bridge",
        "run",
        "src/ns_bridge/server.py"
      ],
      "env": {
        "NS_API_KEY": "your_api_key_here"
      }
    }
  }
}

更新配置后，重新启动MCP客户端以加载服务器。

其他MCP客户端

对于其他兼容MCP的客户端（自定义实现、AI代理框架等），请参阅客户端的stdio服务器配置文档。服务器通过stdin/stdout接受标准MCP协议消息。

查询示例

配置后，您可以询问您的AI助手：

  • “下个小时有哪些火车从乌得勒支中央火车站出发？”
  • “明天早上9点给我找一趟从阿姆斯特丹到鹿特丹的火车”
  • “从海牙到格罗宁根最快的路线是什么？”
  • “从埃因霍温到马斯特里赫特的头等舱票价是多少？”
  • “给我看看德国边境附近的车站”

发展

项目结构

mcp-server-ns-bridge/
├── src/
│   └── ns_bridge/
│       ├── __init__.py          # Package initialization
│       ├── server.py            # MCP server implementation
│       ├── ns_api_client.py     # NS API wrapper
│       ├── models.py            # Data models (Pydantic)
│       └── config.py            # Configuration management
├── tests/                       # Test suite
├── pyproject.toml               # Project configuration & dependencies
├── .env.example                 # Environment template
└── README.md                    # This file

开发者工具

该项目使用现代Python开发工具来提高代码质量：

预提交钩子

预提交钩子在每次提交之前自动检查您的代码：

  • 一般检查：尾随空格、EOF修复、YAML/TOML验证
  • 拉夫：快速换行和代码格式化
  • MyPy 的：静态类型检查
  • 匪徒：安全漏洞扫描
# Install pre-commit hooks (one-time setup)
uv run pre-commit install

# Run manually on all files
uv run pre-commit run --all-files

# Hooks will automatically run on git commit

代码格式化和换行

您还可以手动运行工具：

# Format code with Ruff
uv run ruff format src/ tests/

# Lint and auto-fix
uv run ruff check --fix src/ tests/

# Type checking
uv run mypy src/

# Security scanning
uv run bandit -r src/

看 开发者_TOOLS.md 了解每个工具的详细文档以及我们使用它们的原因。

测试

  • pytest：测试框架
  • pytest异步：异步测试支持
  • 新冠肺炎：代码覆盖率
  • pytest httpx：API测试的HTTP模拟

运行测试：

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov

# Run specific test file
uv run pytest tests/test_models.py

# Run with verbose output
uv run pytest -v

虚拟环境说明

对， uv 与虚拟环境兼容！ uv 自动创建和管理 .venv 项目中的目录。如果需要，您可以手动激活它：

source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

然而， uv run 自动使用虚拟环境，因此对于大多数任务来说，激活是可选的。

API文档

使用的NS API端点

  1. API站 (/nsapp-stations/v2)

    • 搜索并列出火车站
    • 按国家筛选

  2. 行程API (/reisinformatie-api/api/v3/trips)

    • 带连接的路线规划
    • 定价信息
    • 对中转站的支持

  3. 离开API (/reisinformatie-api/api/v2/departures)

    • 实时出发信息
    • 延迟和取消跟踪

车站代码

常用站代码：

  • ut 乌得勒支 中央
  • asd 阿姆斯特丹 中央
  • rtd 鹿特丹 中央
  • gvc 海牙中央
  • ehv 埃因霍温 中央
  • nm -奈梅亨
  • gn -格罗宁根

使用 search_stations 查找更多电台代码的工具。

贡献

欢迎提出建议和改进！

开发工作流程

  1. 创建要素分支
  2. 进行更改
  3. 运行测试套件： uv run pytest
  4. 预提交钩子将在提交时自动运行（或手动运行： uv run pre-commit run)
  5. 提交拉取请求

备注：预提交挂钩自动处理格式化、linting、类型检查和安全扫描。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

路线图

计划的未来增强功能：

  • []添加对中断的支持API
  • []包括车站设施信息
  • []添加行程详细信息（拥挤预测）
  • []支持国际航线
  • []缓存频繁访问的数据
  • []遵守API配额的速率限制

相关 MCP