# cd-mcp
MCP (Model Context Protocol) server for Czech Railways (České dráhy) API.
This server provides AI assistants with tools to search for train connections, stations, and prices on the Czech railway network.
## Features
- **Search Locations**: Find train stations and cities in the Czech Railways network
- **Search Connections**: Search for train connections between two stations
- **Get Connection Details**: Get detailed information about a specific connection
- **Get Passenger Types**: List available passenger types and discount categories
- **Get Price Offers**: Get pricing information for connections
## Installation
```bash
npm install
npm run build
```
## Usage
### With Claude Desktop
Add to your Claude Desktop configuration (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"cd-mcp": {
"command": "node",
"args": ["/path/to/cd-mcp/dist/index.js"]
}
}
}
```
### With MCP Inspector
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
### Development
```bash
npm run dev
```
## Available Tools
### search_locations
Search for train stations and cities by name.
**Parameters:**
- `query` (string, required): Search query (e.g., "Praha", "Brno")
- `type` (string, optional): Location type filter (e.g., "station", "city")
### search_connections
Search for train connections between two stations.
**Parameters:**
- `from` (string, required): Departure station
- `to` (string, required): Arrival station
- `departure` (string, required): Departure date/time in ISO 8601 format
- `passengers` (number, optional): Number of passengers (1-9, default: 1)
### get_connection_details
Get detailed information about a specific connection.
**Parameters:**
- `handle` (string, required): Connection search handle from previous search
- `connectionId` (string, required): Connection identifier
### get_passenger_types
Get available passenger types and discount categories.
**Parameters:** None
### get_price_offer
Get a price offer for a connection (read-only, does not book tickets).
**Parameters:**
- `connectionId` (string, required): Connection identifier
- `passengers` (array, required): Array of passenger types and counts
## Design Decisions
As a Principal Architect, the following design decisions were made:
1. **Read-only operations only**: The server only exposes read operations (search, get details, pricing). Booking, payment, and refund operations are intentionally excluded for security reasons - these should require explicit user action through official channels.
2. **Stdio transport**: Uses stdio transport for simple integration with MCP clients like Claude Desktop. HTTP transport can be added if needed.
3. **Error handling**: All tools include proper error handling and return user-friendly error messages.
4. **Type safety**: Full TypeScript implementation with proper type definitions for API responses.
5. **Formatting**: Results are formatted for readability with emojis and structured text output.
## API Reference
This server interfaces with the Czech Railways Ticket API:
- Documentation: https://ticket-api.cd.cz/swaggerUI/cdapi-1.0.0.yml
- Base URL: https://ticket-api.cd.cz/api/v1
## License
MIT
