# @appaflytech/wappa-mcp

> MCP Server for WAPPA (Content Management System & Web Site Tools) Admin API — Claude Code integration for component, page, widget, and site management

Latest version **0.0.32** (published 2026-07-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @appaflytech/wappa-mcp
pnpm add @appaflytech/wappa-mcp
yarn add @appaflytech/wappa-mcp
bun add @appaflytech/wappa-mcp
```

Provides the commands `wappa-mcp`, `wappa-mcp-http`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.32 |
| Published | 2026-07-30 |
| First published | 2026-04-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 7 |
| Unpacked size | 2.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | appaflytech |
| Maintainers | emrahyurttutan, appa-tech |
| Keywords | mcp, model-context-protocol, claude, claude-code, wappa, cms, admin-api |

## Links

- npm: https://www.npmjs.com/package/@appaflytech/wappa-mcp
- Repository: https://github.com/appaflytech/wappa-mcp
- Homepage: https://github.com/appaflytech/wappa-mcp#readme
- Issues: https://github.com/appaflytech/wappa-mcp/issues
- npm.io page: https://npm.io/package/@appaflytech/wappa-mcp

## Dependencies (7)

- [zod](https://npm.io/package/zod.md) ^4.3.6
- [cors](https://npm.io/package/cors.md) ^2.8.5
- [dotenv](https://npm.io/package/dotenv.md) ^17.4.2
- [helmet](https://npm.io/package/helmet.md) ^8.0.0
- [express](https://npm.io/package/express.md) ^4.21.0
- [express-rate-limit](https://npm.io/package/express-rate-limit.md) ^7.5.0
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.12.1

## Recent versions

- 0.0.32 (latest) — 2026-07-30
- 0.0.31 — 2026-07-10
- 0.0.30 — 2026-07-10
- 0.0.29 — 2026-07-09
- 0.0.28 — 2026-07-07
- 0.0.27 — 2026-07-07
- 0.0.26 — 2026-07-06
- 0.0.25 — 2026-07-06
- 0.0.24 — 2026-07-06
- 0.0.23 — 2026-07-06
- 0.0.22 — 2026-07-06
- 0.0.21 — 2026-07-06
- 0.0.20 — 2026-07-06
- 0.0.19 — 2026-07-06
- 0.0.18 — 2026-07-03
- … 17 more at https://npm.io/package/@appaflytech/wappa-mcp/versions

## README

# @appaflytech/wappa-mcp

WAPPA (Content Management System & Web Site Tools) Admin API için [MCP (Model Context Protocol)](https://modelcontextprotocol.io) Server.

Claude Code / Claude Desktop gibi MCP istemcilerine WAPPA Admin API üzerinde doğrudan işlem yapma yeteneği kazandırır: **site, sayfa, layout, bileşen, entity (veritabanı tabloları), dinamik kayıtlar, query, workflow, menü, tema, dil, depolama, kullanıcı/rol, SaaS (organizasyon/plan/abonelik), push bildirim** ve daha fazlası — hepsi doğal dille.

> Doğal dille "bir blog tablosu oluştur, kategorilerle ilişkilendir, 3 örnek yazı ekle ve yayınla" gibi komutlar verebilirsiniz; MCP arka planda ilgili tool'ları sırayla çağırır.

---

## İçindekiler

- [Kurulum](#kurulum)
- [Yapılandırma](#yapılandırma)
- [Nasıl kullanılır — Prompt verme](#nasıl-kullanılır--prompt-verme)
- [Rehberli İş Akışları (Prompts)](#rehberli-i̇ş-akışları-prompts)
- [Yetenekler (Tüm Tool'lar)](#yetenekler-tüm-toollar)
- [Reçeteler ve Örnekler](#reçeteler-ve-örnekler)
  - [1. Basit tablo (entity) oluşturma](#1-basit-tablo-entity-oluşturma)
  - [2. İlişkili tablo nasıl yapılır (Reference)](#2-ilişkili-tablo-nasıl-yapılır-reference)
  - [3. Kayıt ekleme ve ilişki bağlama](#3-kayıt-ekleme-ve-ilişki-bağlama)
  - [4. Çok dilli (localization) içerik](#4-çok-dilli-localization-içerik)
  - [5. AI ile taslaktan tablo oluşturma](#5-ai-ile-taslaktan-tablo-oluşturma)
  - [6. Sayfa, menü, tema](#6-sayfa-menü-tema)
- [Kolon (Column) Tipleri](#kolon-column-tipleri)
- [Erişim Tipleri (accessType)](#erişim-tipleri-accesstype)
- [Kimlik Doğrulama](#kimlik-doğrulama)
- [Lisans](#lisans)

---

## Kurulum

### npx ile (Kurulum Gerektirmez)

Doğrudan MCP yapılandırmasında kullanabilirsiniz — ayrıca `npm install` yapmanıza gerek yok:

```json
{
  "mcpServers": {
    "wap": {
      "command": "npx",
      "args": ["-y", "@appaflytech/wappa-mcp@latest"],
      "env": {
        "WAP_ADMIN_API_URL": "https://your-wap-admin-api-url.com",
        "WAP_SITE_KEY": "your-site-slug",
        "WAP_EMAIL": "admin@example.com",
        "WAP_PASSWORD": "your-password",
        "WAP_LANGUAGE": "tr"
      }
    }
  }
}
```

### Global Kurulum

```bash
npm install -g @appaflytech/wappa-mcp
```

### Proje İçi Kurulum

```bash
npm install @appaflytech/wappa-mcp
```

---

## Yapılandırma

### Environment Variables

| Değişken            | Zorunlu | Açıklama                                                    | Örnek                                  |
| ------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- |
| `WAP_ADMIN_API_URL` | Evet    | Admin API base URL                                         | `https://wap-admin-api.example.com`    |
| `WAP_SITE_KEY`      | Evet\*  | Site slug/key (URL'de kullanılan kısa isim)                | `glomil`                               |
| `WAP_SITE_ID`       | Hayır   | `WAP_SITE_KEY` yoksa fallback site ID                      | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `WAP_EMAIL`         | Evet\*\*| Admin kullanıcı e-postası                                  | `admin@example.com`                    |
| `WAP_PASSWORD`      | Evet\*\*| Admin kullanıcı şifresi                                    | `your-password`                        |
| `WAP_API_KEY`       | Hayır   | Organizasyon API Key (verilirse email/şifre yerine kullanılır) | `org_xxx...`                      |
| `WAP_LANGUAGE`      | Hayır   | API dili (Accept-Language header)                          | `en-us` (varsayılan)                   |

\* `WAP_SITE_KEY` veya `WAP_SITE_ID`'den en az biri gerekir.
\*\* `WAP_API_KEY` verilmediyse `WAP_EMAIL` + `WAP_PASSWORD` zorunludur.

### Claude Code MCP Yapılandırması

Projenizin `.claude/mcp.json` (veya kullanıcı `~/.claude.json`) dosyasına ekleyin:

```json
{
  "mcpServers": {
    "wap": {
      "command": "npx",
      "args": ["-y", "@appaflytech/wappa-mcp@latest"],
      "env": {
        "WAP_ADMIN_API_URL": "https://wap-admin-api.example.com",
        "WAP_SITE_KEY": "your-site-slug",
        "WAP_EMAIL": "admin@example.com",
        "WAP_PASSWORD": "your-password"
      }
    }
  }
}
```

---

## Nasıl kullanılır — Prompt verme

MCP tool'larını **elle çağırmazsınız**; sadece ne istediğinizi doğal dille yazarsınız, ajan doğru tool'u seçer. Etkili prompt için ipuçları:

- **Net ve somut olun:** "Blog tablosu oluştur" yerine → _"`BlogPost` adında bir tablo oluştur; kolonları: Title (metin, zorunlu, öne çıkan), Content (zengin metin), CoverImage (görsel), PublishedAt (tarih)."_
- **İlişki isterken hedefi belirtin:** _"Her BlogPost bir Category'ye bağlı olsun (bire çok)"_ ya da _"BlogPost ile Tag arasında çoka çok ilişki kur."_
- **Sıra/durum belirtin:** _"3 örnek kayıt ekle ve hepsini yayınla (Published)."_
- **Bağlam eksikse ajan önce arar:** İlişki için hedef entity'nin GUID'i gerekir; ajan `list_entities` ile bulur. Siz sadece adıyla söyleyin.
- **Emin değilseniz keşfedin:** _"Bu sitede hangi tablolar var?"_ → `list_entities`. _"Bu MCP neler yapabilir?"_ → `list_capabilities`.

İlk komut olarak şunu deneyin:

> "Bu sitede neler yapabileceğini özetle ve mevcut tabloları (entity) listele."

---

## Rehberli İş Akışları (Prompts)

Bazı çok adımlı işler için MCP, **rehberli prompt**'lar sunar. Bunlar ajana adım adım, **önce kullanıcıya soran** bir iş akışı enjekte eder — böylece ajan statik/uydurma sonuçlara sapmadan gerçek modelleri (entity) kullanır.

**Nasıl çağrılır?**
- **Claude Code:** slash-command olarak — `/mcp__<server>__<prompt>`. Bu repo'daki örnek server adı `eticaret` ise:
  - `/mcp__eticaret__model-olustur`
  - `/mcp__eticaret__detay-sayfalari-ve-navigasyon`
  - `/mcp__eticaret__dokumandan-model-ve-demo`
  - Argümanlar (opsiyonel) sorulur; `/mcp` bağlı server'ların güncel prompt/tool listesini gösterir.
- **Claude Desktop:** mesaj kutusundaki **“+” (attachment)** menüsü → ilgili server → prompt'u seç → argümanları doldur.
- Prompt çağırmadan **düz doğal dille** de yazabilirsiniz; ilgili tool açıklamaları ajanı aynı kurallara yönlendirir (slash-command daha garantilidir).

### `model-olustur` — Model(ler) oluştur (sayfa ilişkisini sorarak)
Bir veya birden çok model (entity) oluşturur. **`hasPageRelation` (Sayfa ilişkisi) DEĞİŞTİRİLEMEZ (immutable)** olduğundan, oluşturmadan **önce** "bu modellerden hangileri sayfa gibi kullanılacak (her kaydın kendi detay sayfası olacak)?" diye sorar ve seçime göre kaydeder.
- Argümanlar: `models` (virgülle, örn. `"Ürünler, Kategoriler, Siparişler"`), `intent` (opsiyonel).
> _"Şu 10 modeli oluştur: … "_ → ajan hangilerinin sayfa ilişkili olacağını sorar.

### `detay-sayfalari-ve-navigasyon` — Detay sayfaları + liste→detay navigasyonu
Anasayfa/liste widget'larındaki öğelere tıklanınca ilgili kaydın **detay sayfasına** giden navigasyonu ekler ve model'e bağlı detay sayfaları kurar. Önce `wappa_plan_detail_pages` ile modelleri doğrular (var mı, `hasPageRelation` var mı), kullanıcıya sorar, sonra kurar. **Statik sayfa üretmez.**
- Detay sayfası = per-record **page-entity** (`wappa_create_page_entity`) — `create_page` değil.
- Liste→detay için list query modelin `Page.Path` alanını seçer; widget repeater şablonunda `touchable-link` + `refs.href={type:"repeater", ref:"pagePath"}` kullanılır.
- Argümanlar: `models`, `intent` (opsiyonel).
> _"Bir liste/kart widget'ındaki kayıtlara tıklanınca o kaydın detay sayfasına gidilsin."_

### `dokumandan-model-ve-demo` — Dokümandan model(ler) + demo içerik
Konuşmaya eklenen bir **dokümandaki** modelleri (tablolar/kolonlar/ilişkiler) çıkarır, `hasPageRelation`'ı sorar, entity'leri **bağımlılık sırasında** oluşturur ve her modele birkaç **demo kayıt** ekler (ilişki alanları için hedef kayıtlar önce oluşturulur). Dokümana sadık kalır; uydurma model/kolon eklemez.
- Argümanlar: `demoCount` (model başına demo kayıt, varsayılan 3), `intent` (opsiyonel).
> _"Bu dokümandaki modelleri oluştur ve her birine 3 demo kayıt ekle."_

**İlgili tool:** `wappa_plan_detail_pages` — model adlarını canlı `list_entities` ile çözer; her modelin durumunu (`ready` / `no-page-relation` / `not-found`), kolonlarını ve somut kurulum planını + kullanıcıya sorulacak soruları döndürür. Detay sayfası/navigasyon isteklerinde ilk adım budur (hiçbir şey oluşturmaz).

> **Not — `hasPageRelation` immutable:** Bir modelin kayıtlarının kendi detay sayfası olabilmesi, entity **oluşturulurken** `hasPageRelation:true` verilmiş olmasına bağlıdır; bu ayar sonradan eklenemez. Var olan bir modelde yoksa, tek çözüm modeli yeniden oluşturup veriyi taşımaktır.

---

## Yetenekler (Tüm Tool'lar)

Her başlık altında kısa bir **örnek prompt** verilmiştir.

### Sites (Siteler)
`list_sites` · `get_site` · `create_site` · `update_site` · `delete_site` · `get_sites_with_entities`
> _"Yeni bir site oluştur: adı 'Demo', slug 'demo'."_

### Pages (Sayfalar)
`list_pages` · `list_all_pages` · `get_page` · `get_page_by_path` · `create_page` · `update_page` · `clone_page` · `publish_page` · `unpublish_page` · `delete_page` · `preview_page` · `get_page_versions` · `list_page_drafts` · `delete_page_version` · `generate_page_path` · `create_page_localization` · `get_page_queries`
> _"'/hakkimizda' path'inde bir Hakkımızda sayfası oluştur ve yayınla."_

### Page Entities (Sayfaya bağlı kayıtlar)
`list_page_entities` · `list_page_entities_as_query` · `get_page_entity` · `create_page_entity` · `update_page_entity` · `change_page_entity_status` · `clone_page_entity` · `delete_page_entity` · `delete_page_entity_version` · `create_page_entity_localization` · `get_page_entity_versions` · `get_page_entity_drafts` · `get_page_entity_queries` · `get_page_entity_order_info` · `preview_page_entity` · `plan_detail_pages`
> _"Sayfa ile ilişkili (hasPageRelation) bir 'Portfolyo' kaydı ekle."_
> _"Listelenen kayıtlara tıklanınca ilgili kaydın detay sayfasına gidilsin."_ → önce `plan_detail_pages` (modelleri doğrular, planı ve soruları döndürür), sonra `detay-sayfalari-ve-navigasyon` prompt'u.

### Components (Bileşenler)
`list_components` · `get_component` · `create_component` · `update_component` · `delete_component` · `list_base_components`
> _"Yerleşik (base) bileşenleri listele; 'heading' bileşeninin şemasını göster."_

### Component Categories
`list_component_categories` · `get_component_category` · `create_component_category` · `update_component_category` · `delete_component_category`

### Layouts
`list_layouts` · `get_layout` · `create_layout` · `update_layout` · `delete_layout` · `clone_layout` · `clone_layout_to_site` · `create_layout_localization` · `get_layout_queries`
> _"Ana layout'u kopyala ve 'Landing' adıyla kaydet."_

### Entities (Veritabanı Tablo Şemaları)
`list_entities` · `list_global_entities` · `get_entity` · `create_entity` · `update_entity` · `delete_entity` · `get_entity_relations` · `get_entity_nested_relations` · `get_entity_nested_relations_root` · `get_entity_nested_relations_by_site` · `get_entity_queries` · `check_entity_deletable`
**AI destekli:** `create_entity_ai_drafts` · `create_entity_ai_drafts_from_image` · `get_entity_ai_drafts` · `commit_entity_ai_drafts`
> _"`Product` tablosu oluştur; Title, Price, Image kolonlarıyla."_ · _"Bu formun ekran görüntüsünden bir tablo taslağı çıkar."_

### Dynamic Entities (Kayıtlar / İçerikler)
`list_dynamic_entity_records` · `get_dynamic_entity_record` · `create_dynamic_entity_record` · `update_dynamic_entity_record` · `link_many_to_many_records` · `update_dynamic_entity_status` · `delete_dynamic_entity_record` · `clone_dynamic_entity_record` · `create_dynamic_entity_localization` · `bulk_create_dynamic_entity_localizations` · `get_dynamic_entity_versions` · `list_dynamic_entity_drafts` · `delete_dynamic_entity_version` · `get_dynamic_entity_as_query` · `get_dynamic_entity_order_info`
> _"Product tablosuna 5 örnek ürün ekle ve yayınla."_

### Queries (Sorgular)
`list_queries` · `get_query` · `run_query` · `run_query_with_body` · `run_query_form` · `create_query` · `update_query` · `delete_query` · `upsert_bulk_queries` · `preview_query` · `get_query_map` · `get_query_related_models`
**AI destekli:** `ai_raw_query_generator` · `ai_raw_query_chat`
> _"Son 10 yayınlanmış blog yazısını getiren bir query oluştur ve çalıştır."_

### Query Categories
`list_query_categories` · `get_query_category` · `create_query_category` · `update_query_category` · `delete_query_category` · `create_query_category_localization` · `list_query_category_nested_relations`

### Workflows (İş Akışları)
`list_workflows` · `get_workflow` · `create_workflow` · `update_workflow` · `delete_workflow` · `run_workflow` · `preview_workflow`
**AI destekli:** `ai_suggest_workflow` · `ai_build_workflow`
> _"Form gönderildiğinde e-posta atan basit bir workflow öner ve oluştur."_

### DB Routines (Veritabanı Rutinleri)
`list_db_routines` · `get_db_routine` · `create_db_routine` · `update_db_routine` · `delete_db_routine`

### Menus (Menüler)
`list_menus` · `get_menu` · `create_menu` · `update_menu` · `delete_menu` · `clone_menu` · `create_menu_localization`
> _"Anasayfa, Hakkımızda, İletişim linklerinden bir üst menü oluştur."_

### Widgets
`list_widgets` · `get_widget` · `create_widget` · `update_widget` · `delete_widget` · `create_widget_localization`

### Showcases (Vitrinler)
`list_showcases` · `get_showcase` · `create_showcase` · `update_showcase` · `delete_showcase` · `clone_showcase`

### Themes (Temalar)
`list_themes` · `get_theme` · `create_theme` · `update_theme` · `delete_theme`
> _"Ana rengi #0EA5E9 olan bir tema oluştur."_

### Languages (Diller)
`list_languages` · `get_language` · `create_language` · `update_language` · `delete_language`
> _"İngilizce (en-us) dilini ekle."_

### Regions & Countries
`list_regions` · `get_region` · `create_region` · `update_region` · `delete_region`
`list_countries` · `get_country` · `create_country` · `update_country` · `delete_country`

### Storage (Dosya / Klasör)
`create_directory` · `delete_directory` · `rename_directory` · `search_directories` · `get_directory_breadcrumb` · `delete_file` · `rename_file` · `move_file` · `copy_file` · `search_files`
> _"'banners' adında bir klasör oluştur."_

### App Users (Uygulama Kullanıcıları)
`list_app_users` · `get_app_user` · `get_app_user_stats` · `get_app_user_login_history` · `create_app_user` · `update_app_user` · `set_app_user_status` · `reset_app_user_password` · `delete_app_user`
**Mail config:** `get_mail_config` · `set_mail_config` · `test_mail_config` · `delete_mail_config`

### Users, Roles & Permissions (Admin panel kullanıcıları)
`list_users` · `get_user` · `create_user` · `update_user` · `update_user_password` · `get_user_authorized_permissions` · `update_user_left_menu`
`list_roles` · `get_role` · `create_role` · `update_role` · `delete_role` · `list_permissions` · `get_permission`

### AI Chat Sessions
`list_ai_chat_sessions` · `get_ai_chat_session` · `create_ai_chat_session` · `update_ai_chat_session` · `delete_ai_chat_session`

### SaaS — Organizations (Organizasyonlar)
`list_organizations` · `get_organization` · `create_organization` · `update_organization` · `delete_organization`

### SaaS — Plans (Planlar)
> Tüm plan işlemleri `organizationId` (GUID) gerektirir.

`list_plans` · `get_plan` · `create_plan` · `update_plan` · `create_plan_localization` · `delete_plan`

### SaaS — Subscriptions (Abonelikler)
> Tüm abonelik işlemleri `organizationId` (GUID) gerektirir.

`list_subscriptions` · `get_subscription` · `change_subscription_status` · `approve_subscription_refund` · `reject_subscription_refund`

### Push Notifications (Bildirimler)
> Bu uçlar global'dir; kiracı hedeflemek için `siteKey` kullanılır.

`get_push_token_stats` · `list_push_tokens` · `get_notification_history` · `send_notification`
**Firebase (Android/FCM):** `get_firebase_credential` · `set_firebase_credential` · `delete_firebase_credential`
**Apple (iOS/APNs):** `get_apns_credential` · `set_apns_credential` · `delete_apns_credential`
> _"Tüm cihazlara 'Kampanya başladı' başlıklı bildirim gönder."_

### Plugins (Eklentiler)
`list_plugins` · `get_plugin` · `create_plugin` · `update_plugin` · `delete_plugin` · `install_plugin` · `uninstall_plugin`

### System Tools & Variables
`list_root_entities` · `get_entity_dependencies` · `get_entity_dependencies_advanced` · `system_global_search`
`list_system_variables` · `get_system_variable` · `create_system_variable` · `update_system_variable` · `delete_system_variable`

### Settings (Ayarlar)
`get_app_settings` · `update_app_settings` · `get_app_settings_module` · `update_app_settings_module` · `create_app_settings_localization` · `delete_app_settings_localization` · `get_system_settings` · `update_system_settings` · `create_system_settings_localization`

### Operations (Bakım / İşlemler)
`cache_clear` · `operation_dependencies` · `operation_record_count` · `check_localization` · `operation_file_related_models` · `operation_compare` · `operation_site_installation_options`

### Error Logs
`list_error_logs` · `clear_error_logs` · `get_error_log_curl`

### General
`list_capabilities` — MCP'nin yeteneklerini özetler · `custom_request` — herhangi bir Admin API endpoint'ine özel istek gönder

---

## Reçeteler ve Örnekler

Aşağıdaki örneklerde **sol tarafta prompt** (ajana yazdığınız), açıklamalarda ise arkada hangi tool'un hangi veriyle çağrıldığı gösterilmiştir.

### 1. Basit tablo (entity) oluşturma

**Prompt:**
> "`BlogPost` adında bir tablo oluştur. Kolonlar: Title (metin, zorunlu, öne çıkan/isVisualized), Content (zengin metin/Editor), CoverImage (görsel), PublishedAt (tarih). Sıralama için Order kolonu da ekle. Siteye özel olsun."

Arkada `create_entity` şu payload ile çağrılır:

```jsonc
{
  "title": "BlogPost",
  "table": "BlogPost",             // PascalCase
  "accessType": 3,                  // 3 = siteye özel (OwnedSite)
  "columns": [
    { "name": "Title",       "title": "Başlık",   "type": 12, "required": true, "isVisualized": true, "localization": true },
    { "name": "Content",     "title": "İçerik",   "type": 3,  "localization": true },
    { "name": "CoverImage",  "title": "Kapak",    "type": 5 },
    { "name": "PublishedAt", "title": "Yayın T.", "type": 2 },
    { "name": "Order",       "title": "Sıra",     "type": 16, "isDefault": true, "initData": 0 }
  ]
}
```

Notlar:
- **En az bir kolon** `isVisualized: true` olmalı (liste başlık kolonu).
- `required: true` → otomatik `nullable: false` (zorunlu alan). Ayrı bir "required" alanı yoktur.
- `localization: true` → kolon çok dilli olur (dile özel `_Localization` tablosuna taşınır).
- `settings`, `customizations`, `schema` **verilmezse otomatik** üretilir (Admin UI ile aynı davranış).
- Kolon tipleri için [Kolon Tipleri](#kolon-column-tipleri) tablosuna bakın.

### 2. İlişkili tablo nasıl yapılır (Reference)

İlişki, **`type: 11` (Reference)** kolonuyla kurulur. İlişki kolonu şunları ister:

| Alan           | Açıklama                                                                 |
| -------------- | ----------------------------------------------------------------------- |
| `type`         | `11` (Reference)                                                        |
| `reference`    | **Hedef entity'nin GUID'i** (alan yolu değil; `list_entities` ile bulun)|
| `relationType` | `0` = bire bir · `1` = bire çok · `2` = çoka çok                        |

> **Akış:** Önce hedef tablo var olmalı. Ajan hedef entity'nin GUID'ini `list_entities`/`get_entity` ile bulur — siz sadece adıyla söylersiniz.

#### a) Bire çok (one-to-many) — örn. her BlogPost bir Category'ye bağlı

**Prompt:**
> "Önce `Category` tablosu oluştur (Title, Order). Sonra `BlogPost` tablosuna `Category` adında bir ilişki kolonu ekle: her yazı bir kategoriye bağlı olsun (bire çok)."

`update_entity` (veya `create_entity`) içindeki ilişki kolonu:

```jsonc
{
  "name": "Category",
  "title": "Kategori",
  "type": 11,
  "reference": "<CATEGORY_ENTITY_GUID>",   // list_entities ile bulunur
  "relationType": 1                          // bire çok
}
```

#### b) Çoka çok (many-to-many) — örn. BlogPost ↔ Tag

**Prompt:**
> "`Tag` tablosu oluştur (Title). `BlogPost` ile `Tag` arasında çoka çok ilişki kur; kolon adı `Tags` olsun."

```jsonc
{
  "name": "Tags",
  "title": "Etiketler",
  "type": 11,
  "reference": "<TAG_ENTITY_GUID>",
  "relationType": 2      // çoka çok
}
```

Çoka çokta otomatik uygulananlar:
- `multiple: true`, `settings.column: 12`, `customizations.detail.type: "auto-complete"`
- Sunucu **ara (junction) tablosunu kendisi oluşturur**; `relationMetadata` **göndermeyin**.

**Ara tabloya ek kolon** (örn. bağlantı ağırlığı) eklemek için reference kolonunun `columns` dizisine tam kolon objesi koyun:

```jsonc
{
  "name": "Tags", "type": 11, "reference": "<TAG_ENTITY_GUID>", "relationType": 2,
  "columns": [
    { "name": "Weight", "title": "Ağırlık", "type": 8, "nullable": true }
  ]
}
```

> **Önemli:** `update_entity` ile kolon eklerken **mevcut tüm kolonları + yeni kolonu birlikte** gönderin. Gönderilmeyen kolonlar (ve verileri) silinir.

### 3. Kayıt ekleme ve ilişki bağlama

Kayıtlar `create_dynamic_entity_record` ile eklenir. Üç kolon biçimi vardır:

```jsonc
{
  "entityId": "<BLOGPOST_ENTITY_GUID>",
  "status": "Published",                  // veya "Draft"
  "columns": [
    { "key": "Title",   "value": "Merhaba Dünya" },                 // 1) normal alan
    { "key": "Category", "refId": "<CATEGORY_RECORD_ID>" },         // 2) tekil ilişki (1-1 / 1-n)
    { "key": "Tags", "links": [                                      // 3) çoka çok
        "<TAG_RECORD_ID_1>",
        { "value": "<TAG_RECORD_ID_2>", "columns": [{ "key": "Weight", "value": 5 }] }
    ]},
    { "key": "Order", "value": 0 }
  ]
}
```

**Prompt:**
> "BlogPost'a 'Merhaba Dünya' başlıklı bir yazı ekle; 'Duyurular' kategorisine bağla, 'genel' ve 'haber' etiketlerini ekle, yayınla."

- `refId` → hedef **kayıt** ID'si (entity ID değil).
- Çoka çok `links` **tam liste** demektir: `update_dynamic_entity_record`'da gönderilmeyen eski bağlantılar kaldırılır.
- Sadece bağlantı yönetmek için `link_many_to_many_records` da kullanılabilir.

### 4. Çok dilli (localization) içerik

Tipik akış: **önce varsayılan dilde oluştur, sonra her hedef dil için `language` ile güncelle/çeviri ekle.**

**Prompt:**
> "Bu blog yazısının İngilizce (en-us) çevirisini ekle: başlık 'Hello World', içerik '...'."

- Kayıt çevirisi: `create_dynamic_entity_localization` (veya toplu: `bulk_create_dynamic_entity_localizations`).
- `language: "en-us"` verildiğinde hem localized main kolonlar hem de çoka çok ara-tablo localized ek kolonları o dile yazılır.
- Sayfa/menü/tema/plan gibi varlıkların da kendi `create_*_localization` tool'ları vardır.

### 5. AI ile taslaktan tablo oluşturma

**Prompt (metinden):**
> "Bir emlak ilanı modeli taslağı çıkar: başlık, fiyat, oda sayısı, konum, görseller."

1. `create_entity_ai_drafts` — prompt'tan taslak şemalar üretir (henüz uygulanmaz).
2. `get_entity_ai_drafts` — taslakları gözden geçir.
3. `commit_entity_ai_drafts` — taslakları gerçek tablolara dönüştürür (DB migrate).

**Prompt (görselden):**
> "Şu formun ekran görüntüsüne bak ve buna uygun bir tablo taslağı oluştur." → `create_entity_ai_drafts_from_image` (görsel base64 gönderilir).

### 6. Sayfa, menü, tema

```text
Prompt: "'/iletisim' path'inde bir İletişim sayfası oluştur ve yayınla."
   → generate_page_path (gerekirse) → create_page → publish_page

Prompt: "Üst menü oluştur: Anasayfa (/), Hakkımızda (/hakkimizda), İletişim (/iletisim)."
   → create_menu

Prompt: "Ana rengi #0EA5E9, ikincil rengi #64748B olan 'Ocean' temasını oluştur."
   → create_theme
```

---

## Kolon (Column) Tipleri

`create_entity` / `update_entity` içinde `type` alanı **sayısal** verilir:

| Değer | Tip           | Backend depolama   | Açıklama                        |
| ----- | ------------- | ------------------ | ------------------------------- |
| 0     | Boolean       | boolean            | Evet/Hayır                      |
| 1     | Color         | text               | Renk                            |
| 2     | Date          | time with zone     | Tarih/saat                      |
| 3     | Editor        | text               | Zengin metin (RichText)         |
| 4     | File          | uuid               | Dosya                           |
| 5     | Image         | uuid               | Görsel                          |
| 6     | Link          | uuid               | Bağlantı                        |
| 7     | LongText      | text               | Uzun metin                      |
| 8     | Number        | integer            | Tam sayı                        |
| 9     | Picture       | uuid               | Resim                           |
| 10    | Price         | decimal            | Fiyat                           |
| 11    | **Reference** | uuid               | **İlişki** (bkz. relationType)  |
| 12    | Text          | text               | Kısa metin                      |
| 13    | Video         | uuid               | Video                           |
| 14    | Guid          | uuid               | GUID                            |
| 15    | Uploader      | uuid               | Yükleyici (backend adı: Upload) |
| 16    | Order         | decimal            | Sıralama (backend'de Decimal)   |
| 17    | Dynamic       | jsonb              | Dinamik                         |
| 18    | RandomString  | text               | Rastgele string                 |
| 19    | Regions       | uuid               | Bölgeler                        |
| 22    | DateOnly      | time               | Sadece tarih                    |
| 23    | NumberEnum    | integer            | Sayısal enum                    |
| 24    | TextEnum      | text               | Metin enum                      |
| -1    | None          | —                  | Tip yok (özel durum)            |

**Kolon özellikleri (her tipte geçerli):**
- `name` / `title`: kolon adı (DB) ve görünen ad. `description`: açıklama.
- `nullable` (varsayılan `true`): `false` → zorunlu alan. Kolaylık: `required: true` → otomatik `nullable: false`.
- `localization` (varsayılan `false`): çok dilli (dile özel `_Localization` tablosuna taşınır).
- `unique` (varsayılan `false`): benzersizlik kısıtı.
- `multiple` (varsayılan `false`): çoklu değer (çoka çokta otomatik `true`).
- `isVisualized`: liste/öne çıkan başlık kolonu (en az birinde `true`).
- `isDefault`: sistem varsayılanı kolon (örn. Order); silinemez.
- `initData`: varsayılan değer (tipe göre doğrulanır).
- `settings`: `{ column: 3-12 }` grid genişliği + tipe özel bloklar (verilmezse otomatik).
- `validations`: `[{ message, regex }]` — tek validasyon tipi regex'tir.
- `reference` / `relationType`: ilişki kolonları için (bkz. [İlişkili tablo](#2-ilişkili-tablo-nasıl-yapılır-reference)).
- `relationMetadata`: çoka çok ara-tablo meta verisi — **normalde göndermeyin**, sunucu üretir (istisnai durumda açıkça verilebilir).
- `uploadMetadata`: `Upload` tipi için sunucunun oluşturduğu klasör bilgisi; güncellemede olduğu gibi geri gönderin.

---

## Erişim Tipleri (accessType)

| Değer | İsim            | Açıklama                                              |
| ----- | --------------- | ---------------------------------------------------- |
| 0     | Global          | Tüm siteler erişebilir                               |
| 1     | AllSites        | Tüm siteler erişebilir                               |
| 2     | SelectedSites   | Yalnızca `selectedSiteIds` listesindeki siteler      |
| 3     | OwnedSite       | Yalnızca route'tan gelen siteye özel (varsayılan)    |
| 4     | CustomSelected  | Özel seçim                                            |

> `accessType` 0/1 dışındaysa `selectedSiteIds` gönderilmesi gerekebilir.

---

## Kimlik Doğrulama

İki yöntem desteklenir:

**1. Email + şifre (varsayılan):**
1. `WAP_ADMIN_API_URL/Auth/sign-in` endpoint'ine POST `{ email, password }`
2. Dönen JWT token cache'lenir
3. Token'ın `exp` claim'inden süre hesaplanır, 5 dakika öncesinde yenilenir
4. Her istekte `Authorization: Bearer <token>` header'ı eklenir

**2. Organizasyon API Key:**
- `WAP_API_KEY` verilirse sign-in adımı atlanır; istekler `X-API-Key: <apiKey>` header'ı ile imzalanır.

---

## Lisans

MIT

---
_Source: https://npm.io/package/@appaflytech/wappa-mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._