MCP sunucusu: yapay zekâ asistanlarıyla Pushizo

{
  "mcpServers": {
    "pushizo": {
      "command": "npx",
      "args": ["-y", "@pushizo/mcp-server"],
      "env": {
        "PUSHIZO_API_KEY": "hs_live_…",
        "PUSHIZO_API_URL": "https://api.pushizo.com",
        "PUSHIZO_APP_ID": "app_…"
      }
    }
  }
}
```text

3. Claude Desktop'u yeniden başlatın; araç listesinde `pushizo` görünür.

| Ortam değişkeni | Zorunlu | Açıklama |
|---|---|---|
| `PUSHIZO_API_KEY` | evet | `hs_live_…` API anahtarı |
| `PUSHIZO_API_URL` | hayır | API kök adresi (varsayılan `https://api.pushizo.com`). `https` olmalı; yerel geliştirmede `http://localhost:<port>` veya `http://127.0.0.1:<port>` kabul edilir |
| `PUSHIZO_APP_ID` | hayır | Araçta `app_id` verilmezse kullanılacak app |

Sunucu stdout'u yalnızca MCP iletileri için kullanır; tanılama stderr'e yazılır (Claude Desktop MCP günlüğünde
görünür). Depodan çalıştırmak için: `npm run build --workspace @pushizo/mcp-server` ve
`node packages/mcp-server/dist/stdio.js`.

## Uzak sunucu: Streamable HTTP

- Adres: `POST {API_URL}/mcp` (ör. `https://api.pushizo.com/mcp`).
- Durumsuz sunucu, JSON yanıt (oturum kimliği ve sunucu kaynaklı SSE akışı yok); `GET` ve `DELETE` `405` döner.
- Hız sınırı: IP başına dakikada 600 istek.
- Kimlik: `Authorization: Bearer hs_live_…` (kapsamlı API anahtarı veya OAuth ile alınan erişim belirteci). Anahtarın
  IP izin listesi uygulanır (izin verilmeyen IP → `403`). Kimlik yoksa veya geçersizse `401` ile birlikte
  `WWW-Authenticate: Bearer resource_metadata="{API_URL}/.well-known/oauth-protected-resource/mcp"` döner; MCP
  istemcileri bu başlıktan OAuth akışını keşfeder.

```bash
curl -s -X POST "$API/mcp" \
  -H "Authorization: Bearer $HS_KEY" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```text

### Claude.ai / Claude Desktop özel bağlayıcı
**Settings → Connectors → Add custom connector** bölümünde URL olarak `{API_URL}/mcp` girin. Claude tarayıcıda
Pushizo yetkilendirme ekranını açar (aşağıdaki OAuth akışı); onay verdiğinizde bağlayıcı seçtiğiniz organizasyon,
app ve kapsamlarla çalışır.

## OAuth 2.1 yetkilendirme

Uzak MCP istemcileri API anahtarı kopyalamadan, tarayıcı tabanlı OAuth 2.1 (yetkilendirme kodu + PKCE) ile bağlanabilir.

### Keşif
| Uç | Standart | İçerik |
|---|---|---|
| `GET /.well-known/oauth-protected-resource` ve `…/oauth-protected-resource/mcp` | RFC 9728 | `resource` (`{API_URL}/mcp`), `authorization_servers: [API_URL]`, `scopes_supported`, `bearer_methods_supported: ["header"]`, `resource_documentation` |
| `GET /.well-known/oauth-authorization-server` | RFC 8414 | `issuer` (= `API_URL`), `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, `revocation_endpoint`, desteklenen yöntemler |

### Dinamik istemci kaydı: `POST /oauth/register` (RFC 7591)
- Varsayılan istemci türü public'tir (`token_endpoint_auth_method: none`); gizli istemciler için `client_secret_post`
  veya `client_secret_basic` de desteklenir. Gizli anahtar yalnızca kayıt yanıtında **bir kez** döner.
- `redirect_uris` kuralları: `https` adresi; `http` yalnızca loopback (`localhost`, `127.0.0.1`, `[::1]`); veya nokta
  içeren özel şema (ör. `com.example.app:/cb`).

```bash
curl -s -X POST "$API/oauth/register" -H 'content-type: application/json' -d '{
  "client_name": "Benim MCP istemcim",
  "redirect_uris": ["http://127.0.0.1:33418/callback"]
}'
```text

### Yetkilendirme: `GET /oauth/authorize`
Parametreler: `response_type=code`, `client_id`, `redirect_uri`, `code_challenge` + `code_challenge_method=S256`
(PKCE **zorunlu**, yalnızca S256), `state`, isteğe bağlı `scope` (boşlukla ayrılmış) ve isteğe bağlı `resource`
(verilirse `{API_URL}/mcp` veya `{API_URL}` olmalıdır). `admin` kapsamı OAuth ile verilemez; tam yetki gereken
otomasyonlarda kapsamlı API anahtarı kullanın. Geçersiz istemci veya kayıtsız `redirect_uri` için yönlendirme yapılmaz
(`400`); diğer parametre hataları `redirect_uri`'ye `error` ile döner. Loopback adreslerinde port istemci tarafından
seçilebilir (RFC 8252).

Tarayıcı dashboard'daki onay ekranına (`/oauth/consent`) yönlendirilir; oturum yoksa önce giriş istenir. Kullanıcı
ekranda:
- organizasyonu,
- isteğe bağlı olarak tek bir app'i (seçilmezse organizasyon geneli),
- kapsamları (yalnızca rolünün verebildiği kapsamlar seçilebilir; varsayılan `segments:read analytics:read`)

seçer ve onaylar. Ardından istemcinin `redirect_uri` adresine `code`, `state` ve `iss` (RFC 9207) ile dönülür. Onay ucu
organizasyonun SSO/MFA/IP politikalarına tabidir ve `apikeys.manage` izni gerektirir.

### Belirteç: `POST /oauth/token`
Gövde `application/x-www-form-urlencoded` veya JSON olabilir.
- `grant_type=authorization_code` + `code`, `redirect_uri`, `client_id`, `code_verifier`.
- `grant_type=refresh_token` + `refresh_token`, `client_id`.

```bash
curl -s -X POST "$API/oauth/token" \
  -d grant_type=authorization_code -d code="$CODE" -d client_id="$CLIENT_ID" \
  -d redirect_uri=http://127.0.0.1:33418/callback -d code_verifier="$VERIFIER"
```text

| Belirteç | Ömür | Not |
|---|---|---|
| Erişim belirteci | 1 saat | Kapsamlı API anahtarıdır (`hs_live_…`); `Authorization: Bearer` ile kullanılır |
| Yenileme belirteci | 30 gün | Her kullanımda yenisiyle değiştirilir (rotation). Eski bir yenileme belirtecinin tekrar kullanılması tüm yetkiyi (grant) iptal eder |

### İptal: `POST /oauth/revoke` (RFC 7009)
Erişim veya yenileme belirtecini iptal eder.

### Yönetim ve güvenlik
- OAuth ile verilen erişim, dashboard'da **Geliştirici → API anahtarları** listesinde `OAuth · <istemci adı>` olarak
  görünür; buradan iptal etmek yetkiyi (grant) sonlandırır.
- Kullanıcı organizasyondan ayrılır veya ilgili izinlerini kaybederse yenileme başarısız olur; istemcinin yeniden
  yetkilendirme alması gerekir.
- Belirteçler, yetkilendirme kodları ve istemci gizli anahtarları yalnızca SHA-256 özetleri olarak saklanır.

## Kapsamlar

| Kapsam | MCP'de açtığı araçlar |
|---|---|
| `segments:read` | `list_segments`, `get_segment` |
| `analytics:read` | `list_campaigns`, `get_campaign`, `list_campaign_messages`, `get_analytics_summary`, `list_templates`, `list_messages`, `get_message` |
| `notifications:write` | `list_messages`, `get_message` (geriye dönük uyumluluk) |
| `mcp:write` | `create_campaign_draft`, `create_segment_draft` |
| `admin` | Tümü |

`users:read`, `users:write` ve `events:write` kapsamları korunan kaynak meta verisinde listelenir ancak MCP araçları
tarafından kullanılmaz. En az yetki ilkesine uyun: asistanın yalnızca okuması gerekiyorsa `mcp:write` vermeyin.

## Hata durumları
- Kapsam eksikse araç `isError` sonucu döner (`… (HTTP 403) — API anahtarının kapsamlarını kontrol edin.`).
- `app_id gerekli` hatası: organizasyon geneli anahtarda araca `app_id` verin veya `PUSHIZO_APP_ID` tanımlayın.
- `401` (HTTP): anahtar/belirteç geçersiz, süresi dolmuş veya iptal edilmiş; OAuth istemcisi yenileme belirteciyle yeni
  erişim belirteci almalıdır.