> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Sistemi

> @leaderos/headless-mcp ile yapay zeka asistanlarınızın LeaderOS API'sini tanımasını ve çağırmasını sağlayın.

## MCP nedir?

**Model Context Protocol (MCP)**, yapay zeka asistanlarının (Claude Code, Cursor, Windsurf vb.) harici araçları ve verileri kullanmasını sağlayan açık bir standarttır. `@leaderos/headless-mcp` paketi, asistanınıza **sizin sitenizin** Headless API'sini tanıtan bir MCP sunucusudur.

MCP olmadan asistan API'yi tahmin eder ve hatalı endpoint/alan adı üretebilir. MCP ile ise:

* Endpoint'leri **arar** ve gerçek parametre/yanıt şemalarını okur,
* Sitenizin **gerçek yapılandırmasına** bakar (hangi modüller açık, hangi captcha sayfaları var),
* Canlı sitenizden **örnek yanıt** alıp ona göre arayüz yazar.

## Kurulum

Gereksinim: Node.js 18.18+. Paket `npx` ile çalıştırılır, ayrıca kurmanız gerekmez.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add leaderos \
>   -e LEADEROS_URL=https://siteniz.com \
>   -e LEADEROS_PUBLIC_KEY=pk_live_XXXXXXXX \
>   -- npx -y @leaderos/headless-mcp
> ```

> [tab] .mcp.json (Cursor vb.)
>
> Proje köküne `.mcp.json` oluşturun (`create-leaderos-theme` bunu zaten ekler):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "leaderos": {
>       "command": "npx",
>       "args": ["-y", "@leaderos/headless-mcp"],
>       "env": {
>         "LEADEROS_URL": "https://siteniz.com",
>         "LEADEROS_PUBLIC_KEY": "pk_live_XXXXXXXX"
>       }
>     }
>   }
> }
> ```

> [!NOTE]
>
> Şablondaki `.mcp.json` değerleri `${LEADEROS_URL}` ve `${LEADEROS_PUBLIC_KEY}` ortam değişkenlerinden okur. Değerler `.env.local` içinde de bulunur; gerekirse doğrudan değer yazabilirsiniz.

## Ortam değişkenleri

| Değişken | Zorunlu | Açıklama |
| - | - | - |
| `LEADEROS_URL` | Evet | Site adresi, ör. `https://siteniz.com` |
| `LEADEROS_PUBLIC_KEY` | `call_endpoint` için | `pk_live_...` |
| `LEADEROS_TOKEN` | Hayır | Giriş gerektiren endpoint'leri denemek için bir kullanıcı token'ı |
| `LEADEROS_ALLOW_WRITE` | Hayır | `1` ise POST/PUT/PATCH/DELETE çağrılarına izin verir (varsayılan: yalnızca GET) |
| `LEADEROS_OPENAPI` | Hayır | Yerel dosya yolu veya URL; varsayılan `<LEADEROS_URL>/headless/openapi.json` |

> [!WARNING]
>
> `LEADEROS_ALLOW_WRITE=1` ayarını yalnızca **test sitesinde** açın. Yapay zeka gerçek siparişler, kredi transferleri veya forum gönderileri oluşturabilir.

## Araçlar

| Araç | Ne yapar |
| - | - |
| `search_endpoints` | Anahtar kelimeyle endpoint arar (yol, özet, etiket, operationId). Metot, yol, kimlik doğrulama türü ve SDK `operationId` döner |
| `get_endpoint` | Tek endpoint'in parametreleri, istek gövdesi, yanıt şemaları, hata kodları, captcha sayfası ve kimlik doğrulaması |
| `get_schema` | Bir bileşen şemasını adıyla getirir (`Cart`, `StoreProduct`, `ForumThread`, `PaymentIntent`…) |
| `call_endpoint` | Yapılandırılan siteye gerçek istek atar. Varsayılan olarak yalnızca GET |
| `get_site_config` | `/site/config`: site adı, oyun, aktif modüller, captcha sayfaları, marka kuralı, para birimleri |
| `list_error_codes` | Tüm hata kodları ve hangi endpoint'lerin döndürdüğü |
| `scaffold_page` | Bir GET endpoint'i için Next.js sayfa iskeleti üretir |

Ayrıca bir **kaynak (resource)** sunar: `leaderos://llms-full.txt` (tüm API referansı).

## Örnek kullanım

Asistanınıza şunu yazabilirsiniz:

> "Mağazadaki ürünleri kategoriye göre listeleyen bir sayfa yap. Önce hangi modüllerin açık olduğuna bak."

Asistan şu sırayı izler:

1. `get_site_config` → `store` modülünün aktif olduğunu görür.
2. `search_endpoints("store products")` → `GET /store/...` endpoint'lerini bulur.
3. `get_endpoint` ve `get_schema("StoreProduct")` → alan adlarını öğrenir.
4. `call_endpoint` → gerçek ürün verisini görür.
5. `scaffold_page` ile iskeleti alır ve tasarımınıza uyarlar.

## Güvenlik

* Varsayılan mod **salt okunurdur**.
* MCP sunucusu yalnızca sizin makinenizde çalışır; site anahtarınız üçüncü taraflara gönderilmez.
* Public key hassas değildir ancak yine de depoya commit etmeyin; `.env.local` `.gitignore`'dadır.

## Sorun giderme

| Belirti | Çözüm |
| - | - |
| `Set LEADEROS_URL` hatası | Ortam değişkenini tanımlayın |
| `Could not load .../openapi.json (HTTP 404)` | Headless API panelden kapalı veya adres yanlış |
| `call_endpoint` 401 `INVALID_API_KEY` | Anahtar yenilenmiş olabilir; güncelleyin |
| Giriş gerektiren uç `UNAUTHENTICATED` | `LEADEROS_TOKEN` tanımlayın |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.