# YHT Bilet MCP Server

A Model Context Protocol (MCP) server for searching Turkish train (YHT/High-Speed Train) tickets via TCDD API.

> Built with [MCP TypeScript SDK](https://modelcontextprotocol.io/docs/develop/build-server#typescript)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io/)

## ✨ Features

- 🚄 **Real-time ticket availability** from TCDD API
- 🗺️ **Station name to ID mapping** - automatic station resolution
- 📅 **Smart date formatting** - automatically formats dates for API (1 day prior at 21:00)
- 👥 **Passenger count support** - search for multiple passengers
- ♿ **Wheelchair accessibility filter** - option to include/exclude wheelchair-accessible seats
- ✅ **Schema validation** with Zod
- 🎯 **Future train filtering** - only shows trains that haven't departed yet
- 📦 **Object-oriented architecture** - clean, maintainable, and testable code

## 📋 Table of Contents

- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage](#usage)
- [License](#license)

## 🚀 Quick Start

```bash
# 1. Clone the repository
git clone https://github.com/yourusername/yht-bilet-mcp.git
cd yht-bilet-mcp

# 2. Install dependencies
npm install

# 3. Create environment file
cp .env.example .env

# 4. Add your TCDD authorization token to .env
# (See "Getting Authorization Token" section below)

# 5. Build the project
npm run build

# 6. Add to Claude Desktop config (see Configuration section)
```

## 📦 Installation

### Prerequisites

- Node.js 18+ 
- npm or yarn
- Claude Desktop or any MCP-compatible client

### Steps

#### 1. Install Dependencies

```bash
npm install
```

#### 2. Set Up Environment Variables

Copy the example environment file:

```bash
cp .env.example .env
```

#### 3. Get Your Authorization Token

1. Visit [TCDD E-Ticket Website](https://ebilet.tcddtasimacilik.gov.tr)
2. Open your browser's Developer Tools (F12)
3. Go to the Network tab
4. Perform a ticket search
5. Find the `train-availability` request
6. Copy the `Authorization` header value from Request Headers
7. Paste it into your `.env` file:

```env
AUTH_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...
```

**Note:** Authorization tokens expire after some time. If you get authentication errors, get a fresh token.

#### 4. Build the Project

```bash
npm run build
```

## 🎮 Usage

### Adding to Claude Desktop

Add the server to your MCP client configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "yht-bilet": {
      "command": "node",
      "args": [
        "/absolute/path/to/yht-bilet-mcp/build/index.js"
      ]
    }
  }
}
```

**Important:** Use absolute paths, not relative paths!

### Available Tools

The server provides one tool: `search_train_ticket`

#### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `from` | string | Yes | - | Departure station name (e.g., "Ankara") |
| `to` | string | Yes | - | Arrival station name (e.g., "Eskişehir") |
| `date` | string | Yes | - | Travel date in YYYY-MM-DD format (e.g., "2025-12-25") |
| `passengerCount` | number | No | 1 | Number of passengers |
| `includeWheelchairSeats` | boolean | No | true | Include wheelchair-accessible seats in results |

#### Example Usage

**In Claude Desktop, you can ask:**

```
Are there any train tickets from Ankara to Eskişehir on December 25, 2025 for 2 passengers?
```

**MCP client will translate this to:**

```json
{
  "from": "Ankara",
  "to": "Eskişehir",
  "date": "2025-12-25",
  "passengerCount": 2,
  "includeWheelchairSeats": true
}
```

**To exclude wheelchair seats:**

```
Find train tickets from Ankara to Eskişehir on December 25, 2025, but don't show wheelchair seats.
```

#### Response Format

The server returns a formatted text response with:
- ✅/✗ Success/failure indicator
- 🚂 Train commercial name
- ⏰ Departure and arrival times
- 💰 Minimum price
- 📍 Available cabin classes with seat counts

**Example Response:**

```
✓ Ankara - Eskişehir arası 27.12.2025 tarihi için 3 adet tren sefer bulundu.

🚂 YHT ESKİŞEHİR - ANKARA (11:30 - 12:54):
   Minimum Fiyat: 390 TL
   
   📍 Müsait Kabinler:
      • BUSİNESS: 39 koltuk
      • EKONOMİ: 86 koltuk
      • TEKERLEKLİ SANDALYE: 2 koltuk
...
```

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details

---

**Made with ❤️ for the Turkish rail community**

Need help? [Open an issue](https://github.com/yourusername/yht-bilet-mcp/issues)