> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.iklim.co/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Sunucusu

> Model Context Protocol (MCP) kullanarak Claude gibi yapay zeka asistanlarını iklim.co Hava Durumu API'siyle bağlayın.

<Note>
  Bu kılavuz **geliştiriciler ve teknik bilgiye sahip kullanıcılar** içindir. MCP sunucusunu kurabilmek için Node.js, terminal kullanımı ve yapılandırma dosyaları hakkında temel bilgi gerekmektedir.
</Note>

<CardGroup cols={3}>
  <Card title="57 Araç" icon="wrench">
    iklim.co API''sinin tüm yetenekleri MCP aracı olarak sunulur — yıldırım, fırtına, yağış, tahmin, alarmlar ve daha fazlası.
  </Card>

  <Card title="Otomatik Auth" icon="key">
    JWT token''lar otomatik olarak alınır ve yenilenir. Kimlik bilgilerinizi girin, gerisini sunucu halleder.
  </Card>

  <Card title="HMAC İmzalı" icon="shield-halved">
    Her istek HMAC-SHA256 ile imzalanır. Kimlik bilgileri düz metin olarak iletilmez; istek başına tekil nonce ile replay saldırıları engellenir.
  </Card>
</CardGroup>

## Genel Bakış

iklim.co MCP Sunucusu, [Model Context Protocol](https://modelcontextprotocol.io) standardını uygular ve iklim.co REST API'sinin tamamını 9 kategoride **57 araç** olarak sunar. MCP uyumlu herhangi bir yapay zeka istemcisi (Claude, OpenClaw vb.) doğal dil aracılığıyla canlı hava durumu verileri sorgulayabilir, alarmları yönetebilir ve kullanıcı hesaplarını kontrol edebilir.

| Kategori             | Araç Sayısı | Kapsam                                          |
| -------------------- | :---------: | ----------------------------------------------- |
| ⚡ Yıldırım           |      2      | Yıldırım çarpma verileri                        |
| 🌪️ Fırtına          |      3      | Fırtına hücresi takibi                          |
| 🌧️ Yağış            |      2      | Radar yağış verileri                            |
| 🌤️ Tahmin           |      3      | Saatlik / günlük / anlık hava durumu            |
| 👤 Auth & Kullanıcı  |      11     | Kimlik doğrulama ve kullanıcı yönetimi          |
| 🏢 Hesap             |      8      | Hesap ve abonelik yönetimi                      |
| 📍 Nokta Alarmları   |      6      | GPS tabanlı uyarı abonelikleri                  |
| 🗺️ Coğrafi Alarmlar |      12     | Sınır bazlı uyarılar + il/ilçe/mahalle kataloğu |
| 📅 Tahmin Alarmları  |      10     | Eşik bazlı tahmin uyarıları + il/ilçe kataloğu  |
| **Toplam**           |    **57**   |                                                 |

***

## Gereksinimler

* **Node.js** >= 18 (ES2022 desteği gerekli)
* **npm** >= 9
* iklim.co API erişim bilgileri: HMAC secret, kullanıcı adı ve şifre

***

## Kurulum

Kaynak kod [git.tarla.io/iklim.co/mcp-server](https://git.tarla.io/iklim.co/mcp-server) adresindeki public repository'den indirilebilir.

```bash theme={null}
git clone https://git.tarla.io/iklim.co/mcp-server.git
cd mcp-server
npm install
npm run build
```

***

## Ortam Değişkenleri

Sunucu başlamadan önce aşağıdaki değişkenlerin tanımlı olması gerekir. Geliştirme ortamında `mcp-server` dizininde bir `.env` dosyası oluşturabilirsiniz (`.gitignore` kapsamında):

```bash theme={null}
# .env
IKLIM_ENV=test                     # prod | test | local  (IKLIM_BASE_URL yoksa kullanılır)
IKLIM_BASE_URL=                    # Opsiyonel. Tanımlıysa IKLIM_ENV'i override eder
IKLIM_HMAC_SECRET=<secret>         # Zorunlu. İstek imzalama için HMAC-SHA256 anahtarı
IKLIM_USERNAME=<email>             # Zorunlu. API hesabı e-postası
IKLIM_PASSWORD=<password>          # Zorunlu. API hesabı şifresi
IKLIM_TOKEN_STORE_PATH=            # Opsiyonel. Access/refresh token'ları kalıcı saklamak için dosya yolu
IKLIM_HTTP_LOG_PATH=               # Opsiyonel. API istek log dosyası yolu
IKLIM_HTTP_LOG_MAX_BYTES=5242880   # Opsiyonel. Rotate eşiği (byte), varsayılan: 5 MB
IKLIM_HTTP_LOG_MAX_FILES=5         # Opsiyonel. Tutulacak rotated dosya sayısı
IKLIM_HTTP_LOG_REQUEST_BODY_MAX_BYTES=16384   # Opsiyonel. Request body log boyut sınırı
IKLIM_HTTP_LOG_RESPONSE_BODY_MAX_BYTES=16384  # Opsiyonel. Response body log boyut sınırı
```

**Ortama göre base URL:**

| `IKLIM_ENV` | URL                         |
| ----------- | --------------------------- |
| `prod`      | `https://api.iklim.co`      |
| `test`      | `https://api-test.iklim.co` |
| `local`     | `http://localhost:8080`     |

<Info>
  `IKLIM_HTTP_LOG_PATH` tanımlıysa her API çağrısı tek satır JSON olarak loglanır. Hassas alanlar (`Authorization`, `X-Signature`, `password`, `token` vb.) otomatik olarak maskelenir.
</Info>

***

## Build ve Çalıştırma

```bash theme={null}
# TypeScript'i derle (dist/ klasörünü oluşturur)
npm run build

# Derlenmiş sunucuyu başlat
npm start

# Geliştirme modunda çalıştır — derleme adımı gerekmez
npm run dev
```

Başarılı başlatmada çıktı:

```
iklim.co MCP server running
```

<Warning>
  Sunucu **stdio** transportu üzerinden iletişim kurar. Doğrudan terminalde çalıştırmak yerine bir MCP istemcisi tarafından yönetilmesi beklenir.
</Warning>

***

## MCP İstemci Konfigürasyonu

### Claude CLI (`.mcp.json`)

Proje kök dizinine bir `.mcp.json` dosyası ekleyin. Claude CLI bunu otomatik olarak yükler:

```json theme={null}
{
  "mcpServers": {
    "iklim": {
      "command": "node",
      "args": ["/tam/yol/mcp-server/dist/index.js"],
      "env": {
        "IKLIM_ENV": "test",
        "IKLIM_HMAC_SECRET": "<secret>",
        "IKLIM_USERNAME": "<email>",
        "IKLIM_PASSWORD": "<password>"
      }
    }
  }
}
```

Global olarak tanımlamak için aynı `mcpServers` bloğunu `~/.claude/settings.json` dosyasına ekleyin.

### OpenClaw

`openclaw mcp set` komutu `env` parametresini ayrı olarak desteklemez; tüm alanları tek bir JSON nesnesi olarak geçirin:

```bash theme={null}
openclaw mcp set iklim '{"type":"stdio","command":"node","args":["/tam/yol/mcp-server/dist/index.js"],"env":{"IKLIM_ENV":"test","IKLIM_HMAC_SECRET":"<secret>","IKLIM_USERNAME":"<email>","IKLIM_PASSWORD":"<password>"}}'
```

Ya da `~/.openclaw/openclaw.json` dosyasını doğrudan düzenleyin:

```json theme={null}
{
  "mcp": {
    "iklim": {
      "type": "stdio",
      "command": "node",
      "args": ["/tam/yol/mcp-server/dist/index.js"],
      "env": {
        "IKLIM_ENV": "test",
        "IKLIM_HMAC_SECRET": "<secret>",
        "IKLIM_USERNAME": "<email>",
        "IKLIM_PASSWORD": "<password>"
      }
    }
  }
}
```

### Diğer MCP İstemcileri

MCP stdio standardını destekleyen her istemci bağlanabilir. Gerekli parametreler:

| Parametre   | Değer                          |
| ----------- | ------------------------------ |
| `transport` | `stdio`                        |
| `command`   | `node`                         |
| `args`      | `["<dist/index.js tam yolu>"]` |
| `env`       | Yukarıdaki dört değişken       |

***

## Araç Kataloğu

### ⚡ Yıldırım

| Araç                    | Açıklama                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| `get_lightnings_within` | Merkez koordinatı ve yarıçap ile tanımlanan dairesel alan içindeki yıldırım çarpmalarını sorgular |
| `get_lightnings_page`   | Zaman aralığına göre yıldırım verilerini sayfalı olarak getirir                                   |

### 🌪️ Fırtına

| Araç                       | Açıklama                                                              |
| -------------------------- | --------------------------------------------------------------------- |
| `get_thunderstorms_within` | Dairesel alan içindeki fırtına hücrelerini sorgular                   |
| `get_thunderstorms_page`   | Zaman aralığına göre fırtına verilerini sayfalı getirir               |
| `get_thunderstorm_details` | `eventId` ile belirli bir fırtına olayının geçmiş detaylarını getirir |

### 🌧️ Yağış

| Araç                        | Açıklama                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `get_precipitations_within` | Dairesel alan içindeki radar yağış verilerini sorgular; `intensityThreshold` ile filtrelenebilir |
| `get_precipitations_page`   | Zaman aralığına göre yağış verilerini sayfalı getirir; `intensityThreshold` zorunludur           |

**Yoğunluk seviyeleri (en düşükten en yükseğe):** `DRIZZLE` \< `LIGHT` \< `MODERATE` \< `HEAVY` \< `VERY_HEAVY` \< `EXTREME`

### 🌤️ Hava Tahmini

| Araç                  | Açıklama                                                                             |
| --------------------- | ------------------------------------------------------------------------------------ |
| `get_hourly_forecast` | 1–14 günlük saatlik tahminler; 53 seçilebilir metrik desteklenir                     |
| `get_daily_forecast`  | Günlük agregat tahminler; saatlik ile aynı parametreler (solar panel alanları hariç) |
| `get_current_weather` | Koordinat için en güncel hava gözlemini getirir                                      |

<Accordion title="53 desteklenen tahmin metriği">
  `WEATHER_ICON`, `TEMPERATURE`, `APPARENT_TEMPERATURE`, `DEW_POINT_TEMPERATURE`, `HUMIDITY`, `CLOUD_COVER`, `CLOUD_COVER_LOW`, `CLOUD_COVER_MID`, `CLOUD_COVER_HIGH`, `WIND_SPEED`, `WIND_GUST`, `WIND_DIRECTION`, `WIND_SPEED_AT_100M`, `WIND_DIRECTION_AT_100M`, `PRECIPITATION`, `RAIN`, `SHOWERS`, `SNOWFALL`, `SNOW_DEPTH`, `PRECIPITATION_PROBABILITY`, `WEATHER_CODE`, `PRESSURE_MSL`, `SURFACE_PRESSURE`, `VISIBILITY`, `EVAPOTRANSPIRATION`, `ET0_FAO_EVAPOTRANSPIRATION`, `VAPOUR_PRESSURE_DEFICIT`, `CAPE`, `LIFTED_INDEX`, `CONVECTIVE_INHIBITION`, `SUNSHINE_DURATION`, `SHORTWAVE_RADIATION`, `DIRECT_RADIATION`, `DIFFUSE_RADIATION`, `DIRECT_NORMAL_IRRADIANCE`, `GLOBAL_TILTED_IRRADIANCE`, `TERRESTRIAL_RADIATION`, `SHORTWAVE_RADIATION_INSTANT`, `DIRECT_RADIATION_INSTANT`, `DIFFUSE_RADIATION_INSTANT`, `DIRECT_NORMAL_IRRADIANCE_INSTANT`, `GLOBAL_TILTED_IRRADIANCE_INSTANT`, `TERRESTRIAL_RADIATION_INSTANT`, `SOIL_TEMPERATURE_0CM`, `SOIL_TEMPERATURE_6CM`, `SOIL_TEMPERATURE_18CM`, `SOIL_TEMPERATURE_54CM`, `SOIL_MOISTURE_0_TO_1CM`, `SOIL_MOISTURE_1_TO_3CM`, `SOIL_MOISTURE_3_TO_9CM`, `SOIL_MOISTURE_9_TO_27CM`, `SOIL_MOISTURE_27_TO_81CM`, `IS_DAY`
</Accordion>

### 👤 Auth & Kullanıcı

| Araç                          | Açıklama                                                           |
| ----------------------------- | ------------------------------------------------------------------ |
| `auth_register`               | Yeni kullanıcı hesabı oluşturur                                    |
| `auth_logout`                 | Geçerli JWT token'ı geçersiz kılar                                 |
| `user_get_me`                 | Oturum açmış kullanıcının profilini getirir                        |
| `user_get`                    | `userId` ile kullanıcı detayını getirir                            |
| `user_create`                 | *(Admin)* `roles` ve `status` ile yeni kullanıcı oluşturur         |
| `user_update`                 | *(Admin)* `userId` ile kullanıcı alanlarını günceller              |
| `user_list`                   | Sayfalı kullanıcı listesi; `roles` ve `status` ile filtrelenebilir |
| `user_unblock`                | Bloke edilmiş kullanıcıyı açar                                     |
| `user_change_password`        | `oldPassword` ve `newPassword` ile şifre değiştirir                |
| `user_password_reset_request` | Şifre sıfırlama e-postası gönderir                                 |
| `user_password_reset`         | Sıfırlama token'ı ile şifreyi günceller                            |

### 🏢 Hesap

| Araç                               | Açıklama                                                |
| ---------------------------------- | ------------------------------------------------------- |
| `account_get`                      | `userId` ile hesap detaylarını getirir                  |
| `account_create`                   | Yeni hesap oluşturur (`INDIVIDUAL` veya `ORGANIZATION`) |
| `account_update`                   | `accountId` ile hesap alanlarını günceller              |
| `account_activation_request`       | Aktivasyon e-postası gönderir                           |
| `account_activate`                 | E-posta doğrulama token'ı ile hesabı aktive eder        |
| `account_phone_activation_request` | SMS doğrulama kodu gönderir                             |
| `account_activate_phone`           | SMS token'ı ile telefonu doğrular                       |
| `account_update_subscription`      | Abonelik planını değiştirir                             |

### 📍 Nokta Alarmları

GPS koordinatı ve yapılandırılabilir yarıçap etrafındaki olaylar için uyarı abonelikleri.

| Araç                           | Açıklama                                                  |
| ------------------------------ | --------------------------------------------------------- |
| `point_alarm_register`         | Yeni nokta alarmı oluşturur                               |
| `point_alarm_update`           | Mevcut alarmı günceller                                   |
| `point_alarm_delete`           | Alarm kaydını siler                                       |
| `point_alarm_get_by_id`        | Tekil alarm detayını getirir                              |
| `point_alarm_get_by_recipient` | Alıcıya ait tüm alarmları listeler                        |
| `point_alarm_list`             | Sayfalı alarm listesi; `recipientIds` ile filtrelenebilir |

### 🗺️ Coğrafi Alarmlar

İdari sınır, poligon veya H3 adresi bazlı uyarı abonelikleri.

Üç sınır tipi desteklenir:

```json theme={null}
// İdari sınır
{ "type": "ADMINISTRATIVE", "cityId": 6, "districtId": 60 }

// Poligon
{ "type": "POLYGON", "polygon": { "exterior": [{"lat": 39.9, "lng": 32.8}, ...] } }

// H3 hücre indeksi
{ "type": "H3INDEX", "h3Address": "8f2830828052d25" }
```

CRUD araçları (`geo_alarm_register`, `geo_alarm_update`, `geo_alarm_delete`, `geo_alarm_get_by_id`, `geo_alarm_get_by_recipient`, `geo_alarm_list`) Nokta Alarmları ile aynı imzayı paylaşır.

**Konum kataloğu:**

| Araç                           | Açıklama                                      |
| ------------------------------ | --------------------------------------------- |
| `geo_alarm_list_cities`        | Tüm illeri listeler                           |
| `geo_alarm_get_city`           | `cityId` ile il detayını getirir              |
| `geo_alarm_list_districts`     | `cityId` ile ilçeleri listeler                |
| `geo_alarm_get_district`       | `districtId` ile ilçe detayını getirir        |
| `geo_alarm_list_neighborhoods` | `districtId` ile mahalleleri listeler         |
| `geo_alarm_get_neighborhood`   | `neighborhoodId` ile mahalle detayını getirir |

### 📅 Tahmin Alarmları

Eşik aşıldığında sabah 04:00 UTC veya akşam 16:00 UTC'de gönderilen uyarılar.

**Eşik parametreleri:**

| Parametre                  | Değerler                                                  |
| -------------------------- | --------------------------------------------------------- |
| `precipitationThreshold`   | mm cinsinden sayısal değer                                |
| `snowFallThreshold`        | `LIGHT` \| `MODERATE` \| `HEAVY`                          |
| `windGustThreshold`        | `STRONG_WIND` \| `STORM` \| `SEVERE_STORM` \| `HURRICANE` |
| `hotTemperatureThreshold`  | `HOT_SNAP` \| `HEAVY_HOT_SNAP` \| `EXTREME_HOT_SNAP`      |
| `coldTemperatureThreshold` | `COLD_SNAP` \| `HEAVY_COLD_SNAP` \| `EXTREME_COLD_SNAP`   |

CRUD araçları Nokta Alarmları ile aynı imzayı takip eder. Ek konum kataloğu araçları: `forecast_alarm_list_cities`, `forecast_alarm_get_city`, `forecast_alarm_list_districts`, `forecast_alarm_get_district`.

***

## Mimari

```
src/
├── index.ts          # MCP sunucu başlatma, araç yönlendirme
├── config.ts         # Ortam değişkeni ayrıştırma
├── auth.ts           # JWT token yönetimi (otomatik yenileme)
├── client.ts         # HTTP API istemcisi (HMAC imzalama)
├── security.ts       # HMAC-SHA256, nonce, idempotency key
└── tools/
    ├── lightnings.ts
    ├── thunderstorms.ts
    ├── precipitations.ts
    ├── forecasts.ts
    ├── auth.ts
    ├── accounts.ts
    ├── point-alarms.ts
    ├── geo-alarms.ts
    └── forecast-alarms.ts
```

**İstek akışı:**

```
MCP İstemci
    │
    ▼
index.ts  (CallToolRequestSchema)
    │
    ▼
tools/<kategori>.ts  ← Zod validasyonu
    │
    ▼
client.ts  (apiGet / apiPost / apiPatch / apiDelete)
    │  ├── auth.ts → geçerli JWT al (gerekirse otomatik yenile)
    │  └── security.ts → HMAC-SHA256 imzası üret
    │
    ▼
iklim.co REST API
```

***

## Kimlik Doğrulama ve Güvenlik

Her API etkileşimi iki bağımsız güvenlik katmanı kullanır: **JWT tabanlı kimlik doğrulama** ve **HMAC-SHA256 istek imzalama**. Her ikisi de her isteğe uygulanır.

### Otomatik Auth Akışı

Sunucu, ilk araç çağrısında otomatik olarak giriş yapar. Manuel bir login adımı gerekmez.

```
İlk araç çağrısı
    │
    ▼
getValidAccessToken()          ← auth.ts
    │
    ├─ Token state yok → login()
    │       POST /v1/auth/login  { username, password }
    │       ← { accessToken, refreshToken }
    │       JWT payload decode → son kullanma süresini hesapla
    │       tokenState'e kaydet
    │
    ├─ accessToken süresi dolmak üzere (< 30 sn kaldı) → refresh()
    │       POST /v1/auth/refresh  { refreshToken }
    │       ← { accessToken, refreshToken }
    │       tokenState'i güncelle
    │
    └─ accessToken geçerli → doğrudan döndür
```

<Warning>
  `login` ve `refresh` endpoint'leri `Authorization: Bearer` header'ı **içermez** — bu istekler yalnızca HMAC imzasıyla doğrulanır.
</Warning>

### HTTP İstek Header'ları

| Header              | Değer                  | Notlar                                                       |
| ------------------- | ---------------------- | ------------------------------------------------------------ |
| `Content-Type`      | `application/json`     | Sabit                                                        |
| `Authorization`     | `Bearer <accessToken>` | Yalnızca normal API isteklerinde; login/refresh'te yer almaz |
| `X-Signature`       | hex string             | HMAC-SHA256 imzası                                           |
| `X-Timestamp`       | Unix epoch (ms)        | `Date.now()` string olarak                                   |
| `X-Nonce`           | UUID v4                | Her istekte tekil — replay saldırısını engeller              |
| `X-Idempotency-Key` | UUID v4                | `POST`, `PUT`, `PATCH` ve `DELETE` isteklerinde              |

### HMAC-SHA256 İmza Hesabı

`X-Signature` değeri dört bileşenin `|` ile birleştirilmesinin HMAC-SHA256'sıdır:

```
imzalanacak_veri = "METHOD|PATH_WITH_QUERY|TIMESTAMP|BODY"
X-Signature      = HMAC-SHA256(imzalanacak_veri, IKLIM_HMAC_SECRET) → hex
```

**Örnek — GET isteği:**

```
METHOD    = "GET"
PATH      = "/v1/users?pageNumber=0&pageSize=10"
TIMESTAMP = "1774349677000"
BODY      = ""   ← GET isteğinde body yok

imzalanacak = "GET|/v1/users?pageNumber=0&pageSize=10|1774349677000|"
X-Signature = HMAC-SHA256(imzalanacak, secret) → "a3f9c2..."
```

**Örnek — POST isteği:**

```
METHOD    = "POST"
PATH      = "/v1/lightnings/within"
TIMESTAMP = "1774349677000"
BODY      = '{"center":{"lat":39.87,"lng":32.74},"radius":50000,...}'

imzalanacak = "POST|/v1/lightnings/within|1774349677000|{\"center\":...}"
X-Signature = HMAC-SHA256(imzalanacak, secret) → "7be41d..."
```

### Güvenlik Önerileri

* `IKLIM_HMAC_SECRET` ve `IKLIM_PASSWORD` değerlerini kaynak koda veya git geçmişine eklemeyin
* Üretim ortamında `.env` dosyası yerine sistem ortam değişkenlerini veya bir secrets manager kullanın
* Her ortam için ayrı kimlik bilgileri kullanın (prod / test / local)
* HMAC secret'ı düzenli olarak rotate edin