荷兰NS列车的MCP服务器
mcp名称：ns桥
      ](https://hub.docker.com/r/ezegodoy26/mcp-server-ns-bridge)
A. 模型上下文协议（MCP） 服务器，使人工智能助手能够与荷兰铁路（NS）API交互，以进行路线规划、定价和实时发车信息。
与任何MCP客户端兼容，包括Claude Desktop、自定义实现和AI代理框架。
特性
MCP工具
- 搜索_状态 -按名称或国家查找火车站
- 按车站名称搜索 - 按国家代码筛选 - 返回行程规划所需的车站代码
- 搜索条 -规划车站之间的路线
- 通过连接获得多种旅行选择 - 查看详细的逐段行程信息 - 查看带有折扣选项的定价 - 选择旅行舱位（1级或2级） - 按出发或到达时间搜索
- 获取_公寓 -查看实时出发板
- 查看任何车站即将出发的航班 - 跟踪延迟和取消 - 监控平台变化
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密钥
- 首选 NS API门户网站
- 创建账户
- 订阅以下API：
- 旅行信息API（Travel Information API） - NS-APP站点API
- 复制您的订阅密钥
- 将其添加到您的
.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在argsarray命令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端点
- API站 (
/nsapp-stations/v2)
- 搜索并列出火车站 - 按国家筛选
- 行程API (
/reisinformatie-api/api/v3/trips)
- 带连接的路线规划 - 定价信息 - 对中转站的支持
- 离开API (
/reisinformatie-api/api/v2/departures)
- 实时出发信息 - 延迟和取消跟踪
车站代码
常用站代码：
ut乌得勒支 中央asd阿姆斯特丹 中央rtd鹿特丹 中央gvc海牙中央ehv埃因霍温 中央nm-奈梅亨gn-格罗宁根
使用 search_stations 查找更多电台代码的工具。
贡献
欢迎提出建议和改进！
开发工作流程
- 创建要素分支
- 进行更改
- 运行测试套件：
uv run pytest - 预提交钩子将在提交时自动运行（或手动运行：
uv run pre-commit run) - 提交拉取请求
备注：预提交挂钩自动处理格式化、linting、类型检查和安全扫描。
许可证
MIT许可证-有关详细信息，请参阅许可证文件
致谢
路线图
计划的未来增强功能：
- \[\]添加对中断的支持API
- \[\]包括车站设施信息
- \[\]添加行程详细信息（拥挤预测）
- \[\]支持国际航线
- \[\]缓存频繁访问的数据
- \[\]遵守API配额的速率限制