奥克兰交通MCP服务器
模型上下文协议（MCP）服务器，用于连接到奥克兰交通API。该服务器提供工具，使用通用交通馈送规范（GTFS）格式搜索公共交通站点并检索交通信息。
特性
- 停止搜索：按名称搜索奥克兰交通车站（不区分大小写的子字符串匹配）
- 停止行程信息：检索特定站点的预定行程和时间表
- GTFS集成：使用通用运输馈送规范进行标准化运输数据交换
- FastMCP框架：基于FastMCP构建，便于MCP服务器开发
- 类型安全：用于数据验证的完整类型提示和Pydantic模型
先决条件
- Python>=3.11
- 紫外线 包管理器（推荐）或pip
- 奥克兰交通API证书
安装
- 克隆存储库：
git clone
cd auckland_transport- 使用uv安装依赖项：
uv sync或者使用pip：
pip install -e .配置
创建一个 .env 根目录中的文件以及您的奥克兰交通API证书：
AT_BASE_URL=https://api.at.govt.nz/gtfs/v3
AT_API_KEY=your_api_key_here备注：确保添加 .env 你的 .gitignore 文件（已包含），以确保API密钥的安全。
用法
运行MCP服务器
启动MCP服务器：
python src/app.py测试
运行测试脚本以验证连接：
python src/test.py使用工具
服务器提供以下MCP工具：
search_stop(name: str) -> StopResponse
按名称搜索奥克兰交通车站（不区分大小写的子字符串匹配）。
参数：
name（str）：要搜索的站点名称
退货：
StopResponse：一个Pydantic模型，包含一系列匹配的停靠站，其属性包括：
- stop_id：站点的唯一标识符 - stop_code：面向公众的停车代码 - stop_name：站点名称 - stop_lat：纬度坐标 - stop_lon：经度坐标 - location_type：位置类型（0=车站，1=车站等） - wheelchair_boarding：轮椅无障碍信息（0=未知，1=无障碍，2=无障碍）
例子：
from at_service import ATService
at_service = ATService()
result = at_service.search_stop("University")
print(result.model_dump_json())get_stop_trips_by_stop_id(stop_id: str) -> StopTripResponse
检索当前日期和时间特定站点的计划行程。
参数：
stop_id（str）：站点的唯一标识符
退货：
StopTripResponse：一个Pydantic模型，包含一系列中途停留的行程，其属性包括：
- arrival_time：计划到达时间（HH:MM:SS格式） - departure_time：计划出发时间（HH:MM:SS格式） - route_id：路线标识符 - trip_headsign：本次行程车辆上显示的文本 - stop_headsign：车站标志上显示的文字 - stop_sequence：行程顺序中此站的顺序 - direction_id：行进方向（0或1） - service_date：送达日期（YYYY-MM-DD格式） - shape_id：路线形状/几何形状的标识符 - pickup_type：取件类型（0=常规，1=无，2=电话，3=司机） - drop_off_type：下车类型（0=常规，1=无，2=电话，3=司机）
例子：
from at_service import ATService
at_service = ATService()
# First, search for a stop to get its stop_id
stops = at_service.search_stop("University")
if stops.data:
stop_id = stops.data[0].attributes.stop_id
trips = at_service.get_stop_trips_by_stop_id(stop_id)
print(trips.model_dump_json())项目结构
auckland-transport/
├── src/
│ ├── app.py # FastMCP server application with MCP tools
│ ├── at_service.py # Auckland Transport API service class
│ ├── gtfs_types.py # Pydantic models for GTFS data structures
│ ├── test.py # Test script for API connectivity
│ └── utils.py # Utility functions
├── .env # Environment variables (not in repo, create locally)
├── pyproject.toml # Project dependencies and metadata
├── uv.lock # Dependency lock file
└── README.md # This file依赖项
fastmcp>=2.13.2：用于构建MCP服务器的FastMCP框架dotenv>=0.9.9：环境变量管理pydantic：GTFS结构的数据验证和建模requests：API调用的HTTP库
备注：该项目使用 uv 用于依赖性管理。所有依赖关系都在中指定 pyproject.toml.
发展
添加新工具
要添加新的MCP工具，请编辑 src/app.py 并添加新的工具功能，以装饰 @mcp.tool:
@mcp.tool
def your_new_tool(param: str) -> ReturnType:
# Your implementation
return resultapi参考
奥克兰交通API使用GTFS（通用运输进料规范）进行数据交换。有关API的更多信息，请访问 奥克兰交通API文件.
数据模型
该项目使用中定义的Pydantic模型 gtfs_types.py 以验证和构建API响应：
- 停止属性：包含站点位置和可访问性信息
- 停止：表示具有类型、ID和属性的单站资源
- 停止响应：多站搜索结果的容器
- StopTrip属性：包含行程时间、路线和服务信息
- 中途停留：表示单站行程资源
- StopTrip响应：多站行程结果容器
所有型号都遵循GTFS标准，并且是全类型的，以获得更好的IDE支持和错误检查。
故障排除
常见问题
- 找不到API密钥：确保您的
.env文件存在于根目录中，同时包含AT_BASE_URL和AT_API_KEY.
- 空结果：API返回当前日期和小时的数据。如果搜索行程，请确保当前时间有预定的服务。
- 连接错误：验证您的互联网连接，并且可以从您的网络访问奥克兰交通API。
参考文献
- GTFS静态概述-谷歌开发者 -GTFS的官方谷歌文档（通用交通馈送规范）
- GTFS文档-GTFS.org -MobilityData维护的官方GTFS规范文件
许可证
MIT许可证
版权所有（c）2025艾拉科技有限公司
特此免费向任何获得副本的人授予许可 本软件和相关文档文件（“软件”），以处理 在软件中不受限制，包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或销售 软件的副本，并允许软件的接收者 根据以下条件提供：
上述版权声明和本许可声明应包含在所有 软件的副本或实质性部分。
软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。