{"id":48392858,"url":"https://github.com/entur/opentripplanner-mcp","last_synced_at":"2026-04-06T00:31:45.629Z","repository":{"id":325260402,"uuid":"1076110910","full_name":"entur/opentripplanner-mcp","owner":"entur","description":"poc mcp using journey-planner and geocoder apis","archived":false,"fork":false,"pushed_at":"2026-01-22T09:17:57.000Z","size":142,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-22T23:55:43.192Z","etag":null,"topics":["ror"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/entur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-14T12:20:09.000Z","updated_at":"2026-01-22T09:16:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/entur/opentripplanner-mcp","commit_stats":null,"previous_names":["entur/opentripplanner-mcp"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/entur/opentripplanner-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entur%2Fopentripplanner-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entur%2Fopentripplanner-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entur%2Fopentripplanner-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entur%2Fopentripplanner-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/entur","download_url":"https://codeload.github.com/entur/opentripplanner-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entur%2Fopentripplanner-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31455375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"ssl_error","status_checked_at":"2026-04-05T21:22:51.943Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ror"],"created_at":"2026-04-06T00:31:44.854Z","updated_at":"2026-04-06T00:31:45.622Z","avatar_url":"https://github.com/entur.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenTripPlanner MCP Server\n\nThis is a Model Context Protocol (MCP) server for OpenTripPlanner's transmodel GraphQL API, implemented in Java using Spring Boot and [Spring AI's MCP framework](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html#_spring_ai_mcp_integration). It allows AI agents to use the OpenTripPlanner service as a tool for trip planning in Norwegian/Nordic public transport.\n\n## What is MCP?\n\nThe [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a standardized protocol designed to allow AI agents to interact with tools and services. It provides a consistent interface for LLMs to access external functionality, similar to how REST APIs work for web services but specifically optimized for AI agent interactions.\n\nThis server implements the MCP specification to provide a standardized interface for AI agents to access trip planning functionality from OpenTripPlanner.\n\n## Features\n\n- Trip planning between two points or coordinate pairs in Norwegian/Nordic public transport\n- Integration with Entur's geocoder for location search\n- Implements MCP specification for AI agent integration using Spring AI annotations\n- HTTP-based MCP server (port 8080)\n- Comprehensive test suite with unit and integration tests\n- Docker-ready with included Dockerfile\n\n## Tools Provided\n\nThis MCP server exposes two main tools:\n\n1. **trip** - Find trip options between two locations\n   - Parameters:\n     - `from`: Starting location (address, place name, or coordinates in \"lat,lng\" format)\n     - `to`: Destination location (address, place name, or coordinates in \"lat,lng\" format)\n     - `departureTime`: Optional departure time in ISO format (e.g., \"2023-05-26T12:00:00\")\n     - `arrivalTime`: Optional arrival time in ISO format (e.g., \"2023-05-26T14:00:00\")\n     - `maxResults`: Maximum number of trip options to return (default: 3)\n\n2. **geocode** - Search for locations by name or address\n   - Parameters:\n     - `text`: Location text to search for\n     - `maxResults`: Maximum number of results to return (default: 10)\n\n## API Endpoints\n\nThe server integrates with Entur's public APIs:\n\n- **Development** (default):\n  - Journey Planner: https://api.dev.entur.io/journey-planner/v3/graphql\n  - Geocoder: https://api.dev.entur.io/geocoder/v2/autocomplete\n\n- **Production**:\n  - Journey Planner: https://api.entur.io/journey-planner/v3/graphql\n  - Geocoder: https://api.entur.io/geocoder/v2/autocomplete\n\n## Getting Started\n\n### Prerequisites\n\n- Java 21 or higher\n- Maven 3.6 or higher\n- Docker (optional, for containerized deployment)\n\n### Building and Running\n\n**Build the project**:\n```bash\nmvn clean package\n```\n\n**Run the application**:\n```bash\nmvn spring-boot:run\n```\n\nThe server will start on port 8080 by default.\n\n**Run with production API endpoints**:\n```bash\nmvn spring-boot:run -Dspring-boot.run.arguments=--spring.profiles.active=prod\n```\n\n### Running Tests\n\n**Run all tests**:\n```bash\nmvn test\n```\n\n**Run only unit tests** (excludes integration tests):\n```bash\nmvn test -Dtest=*Test -Dtest=!*IntegrationTest\n```\n\n**Run only integration tests** (requires network access):\n```bash\nmvn test -Dtest=*IntegrationTest\n```\n\n**Run a specific test class**:\n```bash\nmvn test -Dtest=TripSearchToolTest\n```\n\n## Docker Deployment\n\n### Building the Docker Image\n\nFirst, build the application JAR:\n```bash\nmvn clean package\n```\n\nThen build the Docker image:\n```bash\ndocker build -t opentripplanner-mcp:latest .\n```\n\n### Running the Container\n\n```bash\ndocker run -p 8080:8080 opentripplanner-mcp:latest\n```\n\nThe MCP server will be available at `http://localhost:8080/mcp`.\n\n## Configuration\n\nThe application can be configured through `src/main/resources/application.properties` or via environment variables:\n\n- `SERVER_PORT`: HTTP port to listen on (default: 8080)\n- `ORG_ENTUR_OTP_URL`: OpenTripPlanner GraphQL endpoint URL\n- `ORG_ENTUR_GEOCODER_URL`: Entur Geocoder REST API URL\n- `ORG_ENTUR_MCP_CLIENT_NAME`: Client identifier for API requests (default: \"entur-mcp\")\n\nExample with environment variables:\n```bash\nexport SERVER_PORT=8080\nexport ORG_ENTUR_OTP_URL=https://api.entur.io/journey-planner/v3/graphql\nexport ORG_ENTUR_GEOCODER_URL=https://api.entur.io/geocoder/v2/autocomplete\nmvn spring-boot:run\n```\n\n## Using with AI Agents\n\n### Claude Desktop\n\nTo use this MCP server with Claude Desktop, you need to run it as an HTTP server and configure Claude Desktop to connect to it.\n\n1. **Start the MCP server**:\n   ```bash\n   mvn spring-boot:run\n   ```\n\n2. **Configure Claude Desktop** to connect to `http://localhost:8080/mcp` as an MCP server endpoint.\n\n3. **Use the tools** in your conversation:\n   - Ask Claude to plan a trip: \"Plan a trip from Oslo to Bergen\"\n   - Ask Claude to geocode a location: \"Find the coordinates for Oslo Central Station\"\n\n### Other MCP Clients\n\nAI agents that support the MCP protocol over HTTP can connect to this server at `http://localhost:8080/mcp`. The server provides:\n\n1. Tool discovery through the MCP `tools/list` method\n2. Tool execution through the MCP `tools/call` method\n\nThe server uses Spring AI's MCP annotations framework, which automatically handles the JSON-RPC protocol implementation.\n\n## Architecture\n\nThe application follows standard Spring Boot layered architecture:\n\n- **App.java**: Main Spring Boot application entry point\n- **tools/TripSearchTool.java**: MCP tool definitions using `@McpTool` annotations\n- **services/**: Business logic layer\n  - `OtpSearchService.java`: Trip planning via GraphQL\n  - `GeocoderService.java`: Location geocoding via REST\n- **model/**: Domain models (Location, ErrorResponse)\n- **validation/**: Input validation logic\n- **exception/**: Custom exception classes\n\nThe server uses:\n- **Spring Boot 3.5.7** for the application framework\n- **Spring AI 1.1.0** for MCP server implementation\n- **Jackson** for JSON processing\n- **Java HTTP Client** for external API calls\n- **JUnit 5 \u0026 AssertJ** for testing\n- **OkHttp MockWebServer** for HTTP mocking in tests\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── main/\n│   ├── java/org/entur/mcp/\n│   │   ├── App.java                    # Main application\n│   │   ├── tools/                      # MCP tool definitions\n│   │   ├── services/                   # Business logic\n│   │   ├── model/                      # Domain models\n│   │   ├── validation/                 # Input validation\n│   │   └── exception/                  # Custom exceptions\n│   └── resources/\n│       └── application.properties      # Configuration\n└── test/\n    └── java/org/entur/mcp/            # Test classes\n```\n\n### Adding New Tools\n\nTo add a new MCP tool:\n\n1. Create a method in `TripSearchTool.java` or a new `@Component` class\n2. Annotate it with `@McpTool` and specify name and description\n3. Add parameters with `@McpToolParam` annotations\n4. Return a JSON string response\n5. Handle errors appropriately and return structured error responses\n\nExample:\n```java\n@McpTool(\n    name = \"my_tool\",\n    description = \"Description of what this tool does\"\n)\npublic String myTool(\n    @McpToolParam(description = \"Parameter description\", required = true) String param\n) {\n    // Implementation\n    return objectMapper.writeValueAsString(result);\n}\n```\n\n## Contributing\n\nThis is a project by Entur for integrating OpenTripPlanner with AI agents through the Model Context Protocol.\n\n## License\n\nPlease check with Entur for licensing information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fentur%2Fopentripplanner-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fentur%2Fopentripplanner-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fentur%2Fopentripplanner-mcp/lists"}