# Uber MCP Server

AI asistanları için kapsamlı Uber entegrasyonu sağlayan Model Context Protocol (MCP) sunucusu. Bu server, AI asistanlarının Uber API'si ile etkileşime girmesini ve yolculuk yönetimi yapmasını sağlar.

## 🚗 Özellikler

### Temel İşlevler
- **Araç Çağırma**: uberX, uberXL, Comfort, Black ve diğer araç türlerini çağırma
- **Fiyat Tahmini**: Yolculuk öncesi fiyat tahmini alma
- **Süre Tahmini**: Sürücünün gelme süresini tahmin etme
- **Yolculuk Takibi**: Aktif yolculukların durumunu takip etme
- **İptal İşlemi**: Yolculukları iptal etme
- **Yolculuk Geçmişi**: Geçmiş yolculukları görüntüleme
- **Şoför Puanlama**: Tamamlanan yolculuklar için şoför değerlendirme

### Teknik Özellikler
- **TypeScript**: Tip güvenliği ve modern JavaScript desteği
- **Zod Validasyonu**: Güçlü veri doğrulama
- **Hata Yönetimi**: Kapsamlı hata yakalama ve raporlama
- **OAuth 2.0**: Güvenli kimlik doğrulama
- **Türkçe Dil Desteği**: Tam Türkçe arayüz ve mesajlar
- **Sandbox Desteği**: Geliştirme için test ortamı

## 📋 Gereksinimler

- Node.js 18.0.0 veya üzeri
- TypeScript 5.0+
- Uber Developer hesabı ve API anahtarları
- @modelcontextprotocol/sdk

## 🔧 Kurulum

### 1. Bağımlılıkları Yükleyin

```bash
cd /root/.openclaw/workspace/mcp-servers/uber-mcp/
npm install
```

### 2. Çevre Değişkenlerini Ayarlayın

`.env.example` dosyasını `.env` olarak kopyalayın ve gerekli bilgileri doldurun:

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

`.env` dosyasını düzenleyin:

```env
# Uber API Yapılandırması
UBER_CLIENT_ID=uber_client_id_buraya
UBER_CLIENT_SECRET=uber_client_secret_buraya
UBER_SERVER_TOKEN=uber_server_token_buraya
UBER_SANDBOX=true

# OAuth Yapılandırması
UBER_REDIRECT_URI=http://localhost:3000/auth/callback
UBER_SCOPE=profile request history

# API Yapılandırması
UBER_API_BASE_URL=https://api.uber.com
UBER_SANDBOX_API_BASE_URL=https://sandbox-api.uber.com

# MCP Server Yapılandırması
MCP_SERVER_NAME=uber-mcp-server
MCP_SERVER_VERSION=1.0.0

# Loglama
LOG_LEVEL=info

# Dil Desteği
DEFAULT_LANGUAGE=tr
SUPPORTED_LANGUAGES=en,tr
```

### 3. Uber Developer Hesabı Kurulumu

1. [Uber Developer Portal](https://developer.uber.com/)'a gidin
2. Yeni bir uygulama oluşturun
3. Client ID, Client Secret ve Server Token'ı alın
4. Redirect URI'yi ayarlayın: `http://localhost:3000/auth/callback`
5. Gerekli scope'ları etkinleştirin: `profile`, `request`, `history`

### 4. Projeyi Derleyin

```bash
npm run build
```

### 5. Sunucuyu Başlatın

```bash
npm start
```

Veya geliştirme modunda:

```bash
npm run dev
```

## 🛠️ Kullanım

### MCP Client Entegrasyonu

Bu server, MCP protokolünü destekleyen herhangi bir AI asistanı ile kullanılabilir. Server başlatıldıktan sonra, AI asistanınız aşağıdaki araçları kullanabilir:

### Mevcut Araçlar

#### 1. `uber_arac_turlerini_getir`
Belirli bir konumda mevcut olan Uber araç türlerini getirir.

**Parametreler:**
- `latitude` (number): Enlem koordinatı
- `longitude` (number): Boylam koordinatı

**Örnek:**
```json
{
  "name": "uber_arac_turlerini_getir",
  "arguments": {
    "latitude": 41.0082,
    "longitude": 28.9784
  }
}
```

#### 2. `uber_fiyat_tahmini_al`
Başlangıç ve bitiş noktaları arasında fiyat tahmini alır.

**Parametreler:**
- `start_latitude` (number): Başlangıç enlem koordinatı
- `start_longitude` (number): Başlangıç boylam koordinatı
- `end_latitude` (number): Bitiş enlem koordinatı
- `end_longitude` (number): Bitiş boylam koordinatı

#### 3. `uber_sure_tahmini_al`
Sürücünün gelme süresini tahmin eder.

**Parametreler:**
- `start_latitude` (number): Başlangıç enlem koordinatı
- `start_longitude` (number): Başlangıç boylam koordinatı
- `product_id` (string, isteğe bağlı): Belirli araç türü ID'si

#### 4. `uber_arac_cagir`
Yeni bir Uber yolculuğu talep eder.

**Parametreler:**
- `product_id` (string): Araç türü ID'si
- `start_latitude` (number): Başlangıç enlem koordinatı
- `start_longitude` (number): Başlangıç boylam koordinatı
- `end_latitude` (number, isteğe bağlı): Bitiş enlem koordinatı
- `end_longitude` (number, isteğe bağlı): Bitiş boylam koordinatı
- `seat_count` (number, isteğe bağlı): Yolcu sayısı (1-6 arası)

#### 5. `uber_aktif_yolculuk`
Şu anda aktif olan yolculuğu getirir.

**Parametreler:** Yok

#### 6. `uber_yolculuk_detaylari`
Belirli bir yolculuğun detaylarını getirir.

**Parametreler:**
- `request_id` (string): Yolculuk talep ID'si

#### 7. `uber_yolculuk_iptal`
Aktif yolculuğu iptal eder.

**Parametreler:**
- `request_id` (string): İptal edilecek yolculuk ID'si

#### 8. `uber_yolculuk_gecmisi`
Geçmiş yolculukların listesini getirir.

**Parametreler:**
- `offset` (number, isteğe bağlı): Başlangıç offset (varsayılan: 0)
- `limit` (number, isteğe bağlı): Maksimum sonuç sayısı (varsayılan: 10)

#### 9. `uber_sofor_puanla`
Tamamlanan yolculuk için şoförü puanlar.

**Parametreler:**
- `request_id` (string): Yolculuk talep ID'si
- `rating` (number): Puan (1-5 arası)
- `feedback` (string, isteğe bağlı): Geri bildirim

#### 10. `uber_profil_getir`
Kullanıcı profil bilgilerini getirir.

**Parametreler:** Yok

## 🔐 Kimlik Doğrulama

Server, Uber OAuth 2.0 akışını destekler. İki kimlik doğrulama yöntemi vardır:

### 1. Server Token (Sunucu Jetonu)
Basit API erişimi için server token kullanın:

```env
UBER_SERVER_TOKEN=your_server_token_here
```

### 2. OAuth 2.0 Flow
Kullanıcı adına işlem yapmak için OAuth flow kullanın:

1. Authorization URL'ini alın:
```javascript
const authUrl = uberAPI.getAuthorizationUrl('http://localhost:3000/auth/callback', 'state123');
```

2. Kullanıcıyı yetkilendirme sayfasına yönlendirin
3. Callback'ten authorization code'u alın
4. Access token için kod ile değiştirin:
```javascript
const tokens = await uberAPI.exchangeCodeForToken(code, 'http://localhost:3000/auth/callback');
uberAPI.updateAccessToken(tokens.access_token);
```

## 🧪 Test ve Geliştirme

### Sandbox Modu

Geliştirme ve test için Uber sandbox ortamını kullanın:

```env
UBER_SANDBOX=true
UBER_SANDBOX_API_BASE_URL=https://sandbox-api.uber.com
```

Sandbox modunda:
- Gerçek para tahsil edilmez
- Simüle edilmiş sürücü ve yolculuk verileri kullanılır
- Tüm API çağrıları güvenli test ortamında gerçekleşir

### Test Komutları

```bash
# Projeyi test et
npm test

# Kod kalitesini kontrol et
npm run lint

# Kodu biçimlendir
npm run format
```

## 📁 Proje Yapısı

```
uber-mcp/
├── src/
│   ├── index.ts          # Ana MCP server implementasyonu
│   ├── uber-api.ts       # Uber API client ve tip tanımları
├── dist/                 # Derlenmiş JavaScript dosyaları
├── package.json          # Proje bağımlılıkları ve scriptler
├── tsconfig.json         # TypeScript yapılandırması
├── .env.example          # Örnek çevre değişkenleri
└── README.md             # Bu dokümantasyon dosyası
```

## 🔧 Yapılandırma

### Çevre Değişkenleri

| Değişken | Açıklama | Gerekli |
|----------|----------|---------|
| `UBER_CLIENT_ID` | Uber uygulama Client ID | ✓ |
| `UBER_CLIENT_SECRET` | Uber uygulama Client Secret | ✓ |
| `UBER_SERVER_TOKEN` | Uber Server Token | - |
| `UBER_SANDBOX` | Sandbox modu (true/false) | - |
| `UBER_API_BASE_URL` | Production API URL | - |
| `UBER_SANDBOX_API_BASE_URL` | Sandbox API URL | - |
| `UBER_REDIRECT_URI` | OAuth redirect URI | ✓ |
| `UBER_SCOPE` | OAuth scope'ları | ✓ |
| `MCP_SERVER_NAME` | MCP server adı | - |
| `MCP_SERVER_VERSION` | MCP server versiyonu | - |
| `LOG_LEVEL` | Log seviyesi | - |
| `DEFAULT_LANGUAGE` | Varsayılan dil | - |

### Hata Yönetimi

Server kapsamlı hata yönetimi sağlar:

- **API Hataları**: Uber API'sinden gelen hataları yakalar ve Türkçe mesajlarla döner
- **Validasyon Hataları**: Zod şemaları ile giriş validasyonu
- **Ağ Hataları**: Bağlantı sorunlarını yakalar
- **Kimlik Doğrulama Hataları**: OAuth ve token hatalarını yönetir

### Türkçe Dil Desteği

Tüm kullanıcı arayüzü ve hata mesajları Türkçe olarak sunulur:

- Araç isimleri ve açıklamaları
- Durum mesajları
- Hata bildirimleri
- Yolculuk detayları

## 🤝 Katkıda Bulunma

1. Repo'yu fork edin
2. Feature branch oluşturun (`git checkout -b feature/amazing-feature`)
3. Değişikliklerinizi commit edin (`git commit -m 'Add some amazing feature'`)
4. Branch'inizi push edin (`git push origin feature/amazing-feature`)
5. Pull Request oluşturun

## 📄 Lisans

Bu proje MIT lisansı altında lisanslanmıştır. Detaylar için [LICENSE](LICENSE) dosyasına bakın.

## 🐛 Hata Raporlama

Hata bulursanız veya öneriniz varsa:

1. [Issues](https://github.com/your-repo/uber-mcp/issues) sayfasından yeni bir issue oluşturun
2. Hatayı detaylı şekilde açıklayın
3. Mümkünse hata loglarını ekleyin
4. Çalışma ortamı bilgilerinizi paylaşın

## ❓ SSS

### S: Server token vs Access token farkı nedir?
**C:** Server token, uygulamanız adına genel API çağrıları yapmak için kullanılır. Access token ise belirli bir kullanıcı adına işlem yapmak için gereklidir. Yolculuk çağırmak için access token gereklidir.

### S: Sandbox modunda gerçek yolculuk çağırabilir miyim?
**C:** Hayır, sandbox modu sadece test amaçlıdır. Gerçek yolculuk çağırmak için production API'sini kullanmanız gerekir.

### S: Hangi şehirlerde Uber kullanabilir miyim?
**C:** Uber'in aktif olduğu tüm şehirlerde bu MCP server'ı kullanabilirsiniz. Güncel şehir listesi için Uber'in resmi web sitesini kontrol edin.

### S: Rate limiting var mı?
**C:** Evet, Uber API'si rate limiting uygulamaktadır. Server otomatik olarak bu durumu yönetir ve gerekli hata mesajlarını döner.

## 📞 Destek

Teknik destek için:
- GitHub Issues kullanın
- Dokümantasyonu kontrol edin
- Uber Developer Portal'a başvurun

---

**Not**: Bu MCP server, Uber Technologies Inc. tarafından resmi olarak desteklenmemektedir. Bağımsız bir açık kaynak projesidir.