# Yapay zekâ ajanları (MCP)

> Claude, Cursor, VS Code ve diğer yapay zekâ ajanları zefily CLI'nin MCP sunucusu ve sizin kontrol ettiğiniz bir API token'ıyla sunucularınızı ve sitelerinizi listelesin, deploy etsin ya da geri alsın.

[Model Context Protocol](https://modelcontextprotocol.io) (MCP), Claude, Cursor ve VS Code gibi yapay zekâ uygulamalarının dış araçları kullanma yoludur. [zefily CLI](/tr/docs/cli) bir MCP sunucusu içerir: `zefily mcp`. Onu yapay zekâ uygulamanıza ekledikten sonra *"Hangi sitelerimin son deploy'u başarısız oldu, neden?"* ya da *"shop.example.com'u deploy et ve yayına girince haber ver."* gibi şeyler sorabilirsiniz.

Ajan, her şey gibi aynı [REST API](/tr/docs/api-ve-cli) üzerinden çalışır. Yalnızca API token'ının izin verdiğini yapabilir; onay modundaki bir token'la her değişiklik passkey'inizi bekler.

## Ajan neler yapabilir

| Araç | Ne yapar | Token kapsamı |
| --- | --- | --- |
| `list_servers` | Sunucularınız, durumları, işletim sistemleri ve ajan sürümleri | `servers:read` |
| `list_sites` | Siteler, türleri, HTTPS ve deploy dalı; bir sunucunun ya da tümünün | `sites:read` |
| `list_jobs` | Bir sunucunun son işleri (kurulumlar, deploy'lar, güncellemeler) | `jobs:read` |
| `get_job` | Bir işin durumu, hata nedeni ve günlüğü | `jobs:read` |
| `deploy_site` | Bir siteyi deposundan deploy eder | `sites:deploy` |
| `rollback_site` | Bir siteyi önceki sürümüne ya da verilen sürüme geri alır | `sites:deploy` |

Terminal açamaz, dosya okuyamaz, ayar değiştiremez ve hiçbir şey silemez.

## 1. CLI'yi kurun

[Zefily CLI](/tr/docs/cli) sayfasını izleyin: sisteminize uygun dosyayı indirip PATH'e ekleyin. Sonra yeni bir terminalde `zefily version`'ın yanıt verdiğini kontrol edin.

Bazı yapay zekâ uygulamaları, özellikle Claude Desktop, terminalinizin kullandığı PATH'i okumaz. Uygulama `zefily`'yi başlatamadığını söylerse aşağıdaki örneklerde `command` olarak programın tam yolunu yazın:

| Sistem | CLI rehberindeki gibi kurduysanız tam yol |
| --- | --- |
| Linux | `/home/<siz>/.local/bin/zefily` |
| macOS | `/Users/<siz>/.local/bin/zefily` |
| Windows | `C:\Users\<siz>\AppData\Local\Programs\zefily\zefily.exe` (JSON'da her `\` iki kez yazılır: `C:\\Users\\…`) |

`which zefily` (Linux, macOS) ya da `where.exe zefily` (Windows) bu yolu yazar.

## 2. Ajan için bir token oluşturun

**Ayarlar → API token'ları** altında yalnızca ajan için bir token oluşturun:

- **Kapsamlar**: `servers:read`, `sites:read` ve `jobs:read` bakmasına izin verir; deploy edip geri alabilmesi için `sites:deploy` ekleyin.
- **Her değişiklik için passkey onayımı iste**: işaretleyin. Ajanın başlattığı bir deploy ya da geri alma, siz [onay passkey'inizle](/tr/docs/onaylar) onaylayana kadar ana sayfanızda bekler; okuma etkilenmez. Ajana değişikliğin sizi beklediği söylenir.
- **Geçerlilik süresi**: bir süre seçin; unutulan bir token kendiliğinden çalışmaz hale gelir.

Token bir kez gösterilir. Sonraki adım için kopyalayın; aynı listeden istediğiniz zaman iptal edebilirsiniz.

## 3. Zefily'yi yapay zekâ uygulamanıza ekleyin

### Claude Code

```bash
claude mcp add zefily --scope user --env ZEFILY_TOKEN=zf_… -- zefily mcp
```

`--scope user` onu her projede kullanılabilir yapar; yalnızca açık projeye eklemek için bu kısmı çıkarın. `claude mcp list` bağlanıp bağlanmadığını gösterir.

### Claude Desktop

Claude Desktop'ta **Settings → Developer → Edit Config**'i açın. `claude_desktop_config.json` dosyası açılır (macOS'ta `~/Library/Application Support/Claude/`, Windows'ta `%APPDATA%\Claude\` içinde). Oradaki sunucuları koruyarak `mcpServers` altına `zefily`'yi ekleyin:

```json
{
  "mcpServers": {
    "zefily": {
      "command": "zefily",
      "args": ["mcp"],
      "env": { "ZEFILY_TOKEN": "zf_…" }
    }
  }
}
```

Dosyayı kaydedin, Claude Desktop'tan tamamen çıkın (yalnızca penceresini kapatmak yetmez) ve yeniden başlatın. Zefily'nin araçları sohbet kutusunun araçlar düğmesinde görünür.

### Cursor

**Cursor Settings → MCP → Add new global MCP server** `~/.cursor/mcp.json` dosyasını açar. Claude Desktop'taki `mcpServers` girdisinin aynısını ekleyip kaydedin.

### VS Code

Komut Paleti'nden **MCP: Open User Configuration**'ı çalıştırın (ya da bir projede `.vscode/mcp.json` oluşturun) ve şunu ekleyin:

```json
{
  "inputs": [
    { "type": "promptString", "id": "zefily-token", "description": "Zefily API token", "password": true }
  ],
  "servers": {
    "zefily": {
      "type": "stdio",
      "command": "zefily",
      "args": ["mcp"],
      "env": { "ZEFILY_TOKEN": "${input:zefily-token}" }
    }
  }
}
```

VS Code sunucuyu ilk başlattığında token'ı sorar ve dosya yerine kendi gizli deposunda saklar. Araçları Copilot Chat'in ajan modunda kullanın.

### Diğer MCP istemcileri

Yerel (stdio) sunucu başlatabilen her istemci çalışır: komut `zefily`, argüman `mcp`, token'ı da `ZEFILY_TOKEN` ortam değişkeni taşır.

## Güvenlik

- Yukarıdaki yapılandırma dosyaları token'ı düz metin olarak tutar (VS Code'un sorduğu dışında). Bunları bir depoya commit etmeyin ve paylaşmayın.
- Her ajana ya da bilgisayara ayrı bir token verin; birini diğerlerine dokunmadan iptal edebilirsiniz. **Ayarlar → API token'ları** her token'ın en son ne zaman kullanıldığını gösterir.
- `sites:deploy` kapsamlı token'larda onay modunu açık tutun. Beklemediğiniz bir deploy onayı token'ı iptal etmeniz için bir nedendir.

## Sorun giderme

| Mesaj | Çözüm |
| --- | --- |
| Uygulama `zefily`'yi başlatamıyor | `command` olarak tam yolu kullanın (1. adım) ve uygulamayı yeniden başlatın |
| *set ZEFILY_TOKEN to an API token* | Token'ınızla `env` girdisini ekleyin |
| *the token is missing, wrong, revoked or expired* | Yeni bir token oluşturup yapılandırmaya yazın |
| *not allowed (token scope or member role)* | Token'da aracın gerektirdiği kapsam yok ya da rolünüz buna izin vermiyor: o kapsamla bir token oluşturun |
| *rate limit reached* | Planınız için bir dakikada çok fazla istek: biraz bekleyin |
| Bir deploy bekliyor | Bu onay modu: ana sayfanızdan onaylayın |

---
Kaynak: https://zefily.com/tr/docs/mcp