Opentripplanner MCP

OpenTripPlanner MCP服务器

这是一个用于OpenTripPlanner的transmodel GraphQL API的模型上下文协议（MCP）服务器，使用Spring Boot和 Spring AI的MCP框架。它允许人工智能代理使用OpenTripPlanner服务作为挪威/北欧公共交通旅行规划的工具，并为出发板、旅行地图和附近的停车地图嵌入交互式UI。

什么是MCP？

这 模型上下文协议（MCP） 是一种标准化协议，旨在允许AI代理与工具和服务进行交互。它为LLM提供了一个一致的接口来访问外部功能，类似于REST API在web服务中的工作方式，但专门针对AI代理交互进行了优化。

此服务器实现了MCP规范，为AI代理提供了一个标准化的接口，以便从OpenTripPlanner访问行程计划功能。

特性

• 挪威/北欧公共交通中两点或坐标对之间的行程规划
• 带有交互式UI的实时出发板
• 使用地图UI查找附近站点
• 服务警报和中断信息
• 与Entur的地理编码器集成，用于位置搜索
• 用于出发、旅行和附近站点的交互式MCP应用程序UI
• 使用Spring AI注释实现AI代理集成的MCP规范
• 基于HTTP的无状态MCP服务器（端口8080）
• 包含单元和集成测试的综合测试套件
• Docker就绪，附带Dockerfile

提供的工具

此MCP服务器公开了五个模型可见工具和两个仅限应用程序的工具：

模型可见工具

1. 旅行 --查找两个地点之间的旅行选项

- 参数： - from：起始位置（地址、地名或“lat，lng”格式的坐标） - to：目的地位置（地址、地名或“lat，lng”格式的坐标） - departureTime：ISO格式的可选出发时间 - arrivalTime：ISO格式的可选到达时间 - maxResults：返回的行程选项的最大数量（默认值：3） - language：UI语言-- en, nb，或 nn - 使用交互式地图UI返回行程选项

1. 出发 --从车站或车站实时出发

- 参数： - stop：站点名称（例如“Oslo S”）或NSR ID（例如“NSR:StopPlace:337”） - numberOfDepartures：要返回的出发次数（默认值：10，最大值：50） - startTime：ISO格式的可选开始时间（默认值：现在） - timeRangeMinutes：时间窗口（分钟）（默认值：60，最大值：1440） - transportModes：按模式可选过滤器（公共汽车、铁路、有轨电车、地铁、水、空气） - language：UI语言-- en, nb，或 nn - 使用交互式出发板UI返回出发

1. 附近的车站 --查找某个地点附近的公共交通站点

- 参数： - location：地址、地名或 lat,lng 坐标 - radius：搜索半径（单位：米）（默认值：500，最大值：2000） - maximumResults：返回的最大停止次数（默认值：10，最大值：50） - transportModes：按模式选择过滤器 - language：UI语言-- en, nb，或 nn - 返回按距离排序的站点，包括下一个出发点和地图UI

1. 警报 --主动服务中断和取消

- 参数： - severities：可选过滤器（无影响、非常轻微、轻微、正常、严重、非常严重） - 返回挪威语和英语的中断描述

1. 地理编码 --按名称或地址搜索位置

- 参数： - text：要搜索的位置文本 - maxResults：要返回的最大结果数（默认值：10）

仅限应用程序的工具（由嵌入式UI调用）

• 投票偏离 --刷新出发板UI的出发数据
• 投票之旅 --使用行程地图UI的更新参数重新规划行程

API终点

该服务器与Entur的公共API集成：

• 发展 （默认）：

- 行程计划：https://api.dev.entur.io/journey-planner/v3/graphql - 地理编码器：https://api.dev.entur.io/geocoder/v2/autocomplete

• 生产:

- 行程计划：https://api.entur.io/journey-planner/v3/graphql - 地理编码器：https://api.entur.io/geocoder/v2/autocomplete

入门指南

先决条件

• Java 21或更高版本
• Maven 3.6或更高版本
• Docker（可选，用于容器化部署）

建立和运行

构建项目:

mvn clean package

运行应用程序:

mvn spring-boot:run

默认情况下，服务器将在端口8080上启动。

使用生产API端点运行:

mvn spring-boot:run -Dspring-boot.run.arguments=--spring.profiles.active=prod

运行测试

运行所有测试:

mvn test

仅运行单元测试 （不包括集成测试）：

mvn test -Dtest=*Test -Dtest=!*IntegrationTest

仅运行集成测试 （需要网络访问）：

mvn test -Dtest=*IntegrationTest

运行特定的测试类:

mvn test -Dtest=TripSearchToolTest

Docker部署

构建Docker镜像

首先，构建应用程序JAR：

mvn clean package

然后构建Docker镜像：

docker build -t opentripplanner-mcp:latest .

运行容器

docker run -p 8080:8080 opentripplanner-mcp:latest

MCP服务器将在 http://localhost:8080/mcp.

配置

应用程序可以通过以下方式配置 src/main/resources/application.properties 或通过环境变量：

• SERVER_PORT：要侦听的HTTP端口（默认值：8080）
• ORG_ENTUR_OTP_URL：OpenTripPlanner GraphQL端点URL
• ORG_ENTUR_GEOCODER_URL：Entur Geocoder REST API URL
• ORG_ENTUR_MCP_CLIENT_NAME：API请求的客户端标识符（默认值：“entur-mcp”）

环境变量示例：

export SERVER_PORT=8080
export ORG_ENTUR_OTP_URL=https://api.entur.io/journey-planner/v3/graphql
export ORG_ENTUR_GEOCODER_URL=https://api.entur.io/geocoder/v2/autocomplete
mvn spring-boot:run

与AI代理一起使用

克劳德桌面

要将此MCP服务器与Claude Desktop一起使用，您需要将其作为HTTP服务器运行，并配置Claude Desktop以连接到它。

1. 启动MCP服务器:

   mvn spring-boot:run

1. 配置Claude桌面 要连接到 http://localhost:8080/mcp 作为MCP服务器端点。

1. 使用工具 在您的对话中：

- “计划从奥斯陆到卑尔根的旅行” - “下一班从奥斯陆S站来的火车是什么时候？” - “Grünerløkka附近有哪些车站？” - “今天有严重的服务警报吗？”

其他MCP客户端

支持HTTP MCP协议的AI代理可以在以下位置连接到此服务器 http://localhost:8080/mcp服务器提供：

1. 通过MCP发现工具 tools/list 方法
2. 通过MCP执行工具 tools/call 方法

服务器使用Spring AI的MCP注释框架，该框架自动处理JSON-RPC协议实现。

建筑

该应用程序遵循标准的Spring Boot分层架构：

• App.java：主Spring Boot应用程序入口点
• 工具/TripSearchTool.java：MCP工具定义使用 @McpTool 注释
• tools/LanguageUtil.java：语言规范化助手
• 服务/：业务逻辑层

- OtpSearchService.java：通过GraphQL进行行程规划、出发、附近站点和警报 - GeocoderService.java：通过REST进行位置地理编码

• 模型/：域模型（位置、错误响应）
• 验证/：输入验证逻辑
• 例外情况/：自定义异常类

UI应用程序是作为MCP资源的纯HTML文件(@McpResource)从 src/main/resources/app/.他们使用 @modelcontextprotocol/ext-apps 通过仅限应用程序的工具回调到服务器，以进行自动刷新和重新规划。

服务器使用：

• 弹簧靴4.0.0 对于应用程序框架
• 春季AI 2.0.0-M4 用于MCP服务器实现
• 杰克逊 用于JSON处理
• Java HTTP客户端 用于外部API调用
• JUnit5和AssertJ 用于测试
• OkHttp模拟Web服务器 用于测试中的HTTP模拟

发展

项目结构

src/
├── main/
│   ├── java/org/entur/mcp/
│   │   ├── App.java                    # Main application
│   │   ├── tools/                      # MCP tool definitions
│   │   │   ├── TripSearchTool.java     # All tools + MetaProvider classes
│   │   │   └── LanguageUtil.java       # Language normalization
│   │   ├── services/                   # Business logic
│   │   │   ├── OtpSearchService.java   # OTP GraphQL API
│   │   │   └── GeocoderService.java    # Geocoder REST API
│   │   ├── model/                      # Domain models
│   │   ├── validation/                 # Input validation
│   │   └── exception/                  # Custom exceptions
│   └── resources/
│       ├── application.properties      # Configuration
│       └── app/                        # Embedded UI apps
│           ├── departures-board.html   # Departure board UI
│           ├── trip-map.html           # Trip options map UI
│           └── nearby-stops-map.html   # Nearby stops map UI
└── test/
    └── java/org/entur/mcp/            # Test classes

添加新工具

要添加新的MCP工具：

1. 在中创建一个方法 TripSearchTool.java 或者一个新的 @Component 类
2. 用注释 @McpTool 并指定名称和描述
3. 添加参数 @McpToolParam 注释
4. 返回JSON字符串响应
5. 适当处理错误并返回结构化错误响应

例子：

@McpTool(
    name = "my_tool",
    description = "Description of what this tool does"
)
public String myTool(
    @McpToolParam(description = "Parameter description", required = true) String param
) {
    // Implementation
    return objectMapper.writeValueAsString(result);
}

贡献

这是Entur通过模型上下文协议将OpenTripPlanner与AI代理集成的项目。

许可证

请向Entur咨询许可信息。