AI导哈

公共交通信息查询服务

Auckland Transport MCP Server 是一个基于MCP协议的服务器，提供奥克兰公共交通站点搜索和时间表查询功能，支持GTFS格式数据交换。

  • by airatech
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 airatech/mcp-auckland-transport

使用说明

奥克兰交通MCP服务器

模型上下文协议（MCP）服务器，用于连接到奥克兰交通API。该服务器提供工具，使用通用交通馈送规范（GTFS）格式搜索公共交通站点并检索交通信息。

特性

  • 停止搜索：按名称搜索奥克兰交通车站（不区分大小写的子字符串匹配）
  • 停止行程信息：检索特定站点的预定行程和时间表
  • GTFS集成：使用通用运输馈送规范进行标准化运输数据交换
  • FastMCP框架：基于FastMCP构建，便于MCP服务器开发
  • 类型安全：用于数据验证的完整类型提示和Pydantic模型

先决条件

  • Python>=3.11
  • 紫外线 包管理器（推荐）或pip
  • 奥克兰交通API证书

安装

  1. 克隆存储库：
git clone <repository-url>
cd auckland_transport
  1. 使用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 result

api参考

奥克兰交通API使用GTFS（通用运输进料规范）进行数据交换。有关API的更多信息，请访问 奥克兰交通API文件.

数据模型

该项目使用中定义的Pydantic模型 gtfs_types.py 以验证和构建API响应：

  • 停止属性：包含站点位置和可访问性信息
  • 停止：表示具有类型、ID和属性的单站资源
  • 停止响应：多站搜索结果的容器
  • StopTrip属性：包含行程时间、路线和服务信息
  • 中途停留：表示单站行程资源
  • StopTrip响应：多站行程结果容器

所有型号都遵循GTFS标准，并且是全类型的，以获得更好的IDE支持和错误检查。

故障排除

常见问题

  1. 找不到API密钥：确保您的 .env 文件存在于根目录中，同时包含 AT_BASE_URL 和 AT_API_KEY.

  2. 空结果：API返回当前日期和小时的数据。如果搜索行程，请确保当前时间有预定的服务。

  3. 连接错误：验证您的互联网连接，并且可以从您的网络访问奥克兰交通API。

参考文献

许可证

MIT许可证

版权所有（c）2025艾拉科技有限公司

特此免费向任何获得副本的人授予许可 本软件和相关文档文件（“软件”），以处理 在软件中不受限制，包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或销售 软件的副本，并允许软件的接收者 根据以下条件提供：

上述版权声明和本许可声明应包含在所有 软件的副本或实质性部分。

软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。

相关 MCP