@appaflytech/zeyrek-ai-mcp

Zeyrek (NgApps) platformunu MCP tool'ları olarak sunan bağımsız gateway. Bir Claude / MCP oturumu Studio arayüzüne hiç girmeden proje kurabilir, veri modeli çıkarabilir, mikroservis ve workflow yazıp çalıştırabilir, sayfa tasarlayabilir.

• 212 tool · 34 modül — veri/mantık tarafı (project, application, datasource, entity, row, import, microservice, query, workflow, automation, function, dto, view, dependency), Studio tasarım tarafı (page, theme, component, external component, flow, layout, variable, function, folder, file, access, translation), yönetim (template, organization, deployment) ve proje dallanması (environment, merge).
• Platform koduna referans vermez: Organization.API ile Tenant.API'yi HTTP üzerinden sarar — istekler MVC binding'den geçtiği için FluentValidation aynen çalışır.
• Üstünde bir bilgi katmanı vardır (rehber + altın örnek + politika lint'i): platformun yazılı olmayan kuralları istek API'ye gitmeden uygulanır.

Gereken: Node 20+ ve erişebildiğiniz bir platform kurulumu (API adresleri, org adı, kullanıcı).

Hızlı başlangıç (npm)

Repoyu klonlamanıza gerek yok; paket npx ile çalışır. Projenizin kökündeki .mcp.json'a ekleyin:

{
  "mcpServers": {
    "zeyrek-ai": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@appaflytech/zeyrek-ai-mcp@latest", "--stdio"],
      "env": {
        "ORG_API_BASE_URL": "http://localhost:17000",
        "TENANT_API_BASE_URL": "http://localhost:15000",
        "ORGANIZATION": "zeyrek-test",
        "HOST_SUFFIX": "zeyrek.local",
        "DEFAULT_ENVIRONMENT": "development",
        "USERNAME": "[email protected]",
        "PASSWORD": "parolanız",
        "LOG_DIR": "logs"
      }
    }
  }
}

Claude Code'da komutla eklemek isterseniz:

claude mcp add zeyrek-ai \
  -e ORG_API_BASE_URL=http://localhost:17000 \
  -e TENANT_API_BASE_URL=http://localhost:15000 \
  -e ORGANIZATION=new-zeyrek \
  -e HOST_SUFFIX=zeyrek.local \
  -e DEFAULT_ENVIRONMENT=development \
  -e [email protected] \
  -e PASSWORD='parolanız' \
  -- npx -y @appaflytech/zeyrek-ai-mcp@latest --stdio

İlk doğrulama: oturumda platform_whoami tool'unu çağırtın — kimlik, org çözümü ve ağ erişimi tek seferde test edilir. Tool listesi boş geliyorsa Sorun giderme bölümüne bakın.

Sürüm seçimi

@latest önerilir: main'e giren her gateway değişikliği CI'da otomatik yayınlanır (bkz. Yayınlama), yeni sürüm MCP sunucusu yeniden başlatılınca gelir. npx kopyayı önbelleğe aldığı için eski sürümde kalan makinede ~/.npm/_npx silinip sunucu yeniden başlatılır. Herkesin aynı gateway'i çalıştırması gereken işlerde (koşu, kabul testi) @0.0.8 gibi sabit sürüm yazın.

Ayarlar

Ayar üç kaynaktan gelebilir, öncelik sırası:

1. .mcp.json'ın env bloğu (npm kurulumunda tek kaynak budur)
2. .env dosyası — sırayla aranır, ilk bulunan anahtar kazanır: <çalışma dizini>/.env → <paket>/.env → <paket>/../.env
3. Şemadaki varsayılan

Parolayı sürüm kontrolündeki bir dosyaya yazmak istemiyorsanız .mcp.json'da PASSWORD alanını hiç yazmayıp çalışma dizininize PASSWORD=... içeren bir .env koyun.

Zorunlu

| Değişken | Örnek | Not | |---|---|---| | ORG_API_BASE_URL | http://localhost:17000 | Organization.API kökü | | TENANT_API_BASE_URL | http://localhost:15000 | Tenant.API kökü | | ORGANIZATION | zeyrek-test | Org subdomain'i; istekler Host: {ORGANIZATION}.{HOST_SUFFIX} ile gider | | DEFAULT_ENVIRONMENT | development | Gömülü varsayılanı yoktur; boşsa sunucu açılmaz | | USERNAME + PASSWORD | | AUTH_MODE=local için; /connect/token ile takas edilir | | TOKEN | | USERNAME/PASSWORD yerine hazır Bearer JWT verilebilir |

Opsiyonel

| Değişken | Varsayılan | Not | |---|---|---| | HOST_SUFFIX | localhost | Org çözümündeki alan adı eki | | DEFAULT_PROJECT | — | Tool'daki project parametresi her zaman ezer | | AUTH_MODE | local | passthrough: kimlik istemcinin Authorization header'ından gelir (stdio kipinde kullanılamaz) | | MODULES | hepsi | Tool setini daraltır — aşağıdaki Modüller bölümü | | POLICY | strict | Politika lint'i: strict | warn | off | | LOG_LEVEL | detail | detail gövdeleri de yazar · summary gövdesiz · off dosya açmaz | | LOG_DIR | çalışma dizini altında logs/ | Günlük dosyaların klasörü | | LOG_FILE | — | Verilirse tek sabit dosyaya yazar (tarih döndürmesi kapanır) | | LOG_MAX_BODY_CHARS | 2000 | Tek gövde/parametre önizlemesinin karakter sınırı | | MAX_RESPONSE_BYTES | 262144 | Yanıt budama eşiği | | REQUEST_TIMEOUT_MS | 100000 | Platform isteklerinin zaman aşımı | | MCP_PORT | 5100 | Yalnız HTTP kipinde | | STUDIO_BASE_URL | — | Yalnız page_screenshot: Studio arayüzünün kök adresi | | SCREENSHOT_BROWSER_PATH | — | page_screenshot için sistemdeki Chromium ikilisi (verilmezse playwright-core'un indirdiği tarayıcı) |

Tam liste ve yorumlu şablon: pakete dahil edilen .env.example (lokal profil). Uzak kurulumlara dağıtım insanın ve CI'ın işidir; AI lokal dışına çıkmaz (../docs/ortam.md).

Bilinmesi gereken üç davranış

• ${…} genişletmesi istemciye bağlıdır. Claude Code ${PASSWORD} ve ${PASSWORD:-varsayılan} yazımını açar, VS Code'un kendi MCP istemcisi açmaz ve metni olduğu gibi geçirir. Sunucu, açılmamış yer tutucuyu boş değerle aynı sayıp düşürür — ayar .env'den ya da varsayılandan doldurulur, sunucu yer tutucu metinle patlamaz.
• Boş bırakılan ("") alan tanımsız sayılır; varsayılana düşer ya da .env'den doldurulur. Yani "MODULES": "" yazmak alanı hiç yazmamakla aynıdır.
• USERNAME adı işletim sistemine aittir (Windows'ta her zaman, macOS kabuklarında sık sık tanımlıdır). Bu yüzden .mcp.json'da ${USERNAME:-…} gibi genişletme kullanmayın, değeri düz yazın. Değer işletim sisteminin kullanıcı adıyla (USER/LOGNAME) aynıysa sunucu onu düşürür ve .env'deki değer geçerli olur; bu guard olmadan gateway kimliği makine kullanıcı adıyla almaya kalkıyor ve POST /connect/token "kayıt bulunamadı" diyerek 404 dönüyordu.

Modüller

MODULES ile tool seti daraltılabilir — tekil modül adı (entity,row,microservice), hazır küme ya da ikisi karışık (core,page). platform modülü (3 tool) her kümede vardır.

| Küme | Tool | Modüller | |---|---|---| | core | 136 | platform, project, application, datasource, entity, row, import, microservice, microfunction, query, workflow, automation, function, dto, view, dependency, environment, merge, activity, revision | | studio | 82 | platform, page, theme, component, externalComponent, flow, layout, variable, function, folder, file, import, access, translation, revision | | admin | 27 | platform, template, organization, deployment, environment, merge, activity | | (boş) | 212 | 34 modülün tamamı (ölçüm 2026-09-16, listTools()) |

Bilinmeyen bir modül/küme adı verilirse sunucu açılmaz, geçerli adları listeleyen bir hata yazar.

Kullanım kalıpları

• Keşif önce: project_list → project_get (environment id'leri burada) → datasource_list → entity_list.
• Derin gövdeler geçirgendir: entity_create / workflow_create / microservice_create definition parametresini API'ye birebir geçirir. En iyi şablon, mevcut bir kaydın *_get çıktısıdır; step şeması için workflow_step_schema kullanılır.
• Test kası: microservice_execute gerçek runtime yolunu çağırır; dönen httpStatus microservice'in kendi sonucudur. Beklenmedik sonuçta aynı parametrelerle microservice_debug çağırın — adım adım executionItems ağacı döner.
• Asenkron işler: automation_trigger fire-and-forget'tır (automation_histories ile izlenir); deployment_start bir saga başlatır (deployment_status ile izlenir).
• Sayfa tasarımı: layout_* → page_create → page_state → page_schema_patch (micro-op); olay akışları flow_* + set_event. Şema değişikliği page_update ile değil page_schema_patch ile yapılır; page_build diye bir tool yok — ayrıntı platform_guide('page').
• Yazma tool'ları replace gövdeleri merge eder: page_update, layout_update, component_update kaydı önce okur, yalnız verdiğiniz alanları değiştirir; şema/olay kaybı olmaz. flow_* yazmaları yalnız akışı gönderir; olay bağı page_schema_patch / layout_schema_patch / component_schema_patch ile ayrı yazılır.
• Gerçek ekran: UI değişikliği page_screenshot ile doğrulanır (STUDIO_BASE_URL gerekir; ilk kullanımda npx playwright-core install chromium).

Bilgi katmanı

Üç savunma hattı, hepsi pakete gömülü — ayrı kurulum gerekmez:

• Rehberler: platform_guide tool'u (workflow, microservice, entity, page, component, html, layout, middleware, view, expressions, getting-started, modify-existing) + ngapps://guides/* resource'ları. Bir modülde ilk yazma işleminden önce ilgili rehber okunmalıdır; tool açıklamaları bunu söyler. Komponent davranış bilgisi ayrıca component_get çıktısında knowledge alanı olarak döner.
• Altın örnekler: ngapps://examples/* — boş org'da şablon kaynağı.
• Politika lint'i: entity/microservice/workflow/automation create/update/preview gövdeleri API'ye gitmeden kurallardan geçer. Block kuralları (MS-001 join'li kaynakta boş selectFields, WF-001 kopuk step grafı, WF-002 workflow'da returnDtoId, WF-005 tip×step matrisi) isteği durdurup düzeltme önerisi döner; warn bulguları yanıta policyFindings olarak eklenir. POLICY=strict|warn|off, çağrı başına kaçış: policyOverride: true.

Büyük şema erişimi

Tam gövdeyi LLM bağlamına sokmadan çalışma modeli:

1. project_overview — projenin kompakt haritası (id/ad/tip envanteri)
2. workflow_get / microservice_get / entity_get + view: 'outline' — iskelet
3. view: 'part', part: 'steps[id=...]' — tek parçanın tam hâli
4. workflow_patch / microservice_patch / entity_patch — RFC 6902 işlemleri; gateway get→patch→lint→put zincirini kendi belleğinde yürütür, yanıt outline özetidir

Tool çağrısı günlüğü

Her MCP tool çağrısı, okunmak için biçimlenmiş tek bir blok olarak zeyrek-mcp/logs/gateway-YYYY-MM-DD.log dosyasına yazılır (.gitignore'da; LOG_LEVEL=detail|summary|off). Hızlı arama: SONUÇ : HATA tüm başarısız çağrılar, #<n> tek bir çağrı. Blok formatı, adım etiketleri, diğer LOG_* ayarları ve maskeleme: docs/30-tool-cagri-gunlugu.md.

Sorun giderme

| Belirti | Sebep / çözüm | |---|---| | İstemci bağlanıyor ama hiç tool görünmüyor | Konfigürasyon geçersiz. Sunucu stderr'e tek satır sebep yazıp exit 1 yapar; istemcinin MCP log'una bakın. En sık: DEFAULT_ENVIRONMENT boş, USERNAME/PASSWORD eksik. | | POST /connect/token 404 / "kayıt bulunamadı" | Kimlik makine kullanıcı adıyla gidiyor — USERNAME üstteki üçüncü davranış maddesi. | | Host çözülemedi / 404 | ORGANIZATION + HOST_SUFFIX birlikte {org}.{suffix} üretir; ikisi de doğru olmalı. | | page_screenshot hata veriyor | STUDIO_BASE_URL boş ya da tarayıcı yok: npx playwright-core install chromium veya SCREENSHOT_BROWSER_PATH. | | Eski sürüm çalışıyor | npx önbelleği: ~/.npm/_npx'i silip sunucuyu yeniden başlatın ya da .mcp.json'da sabit sürüm yazın. |

Her durumda ilk bakılacak yer günlük dosyasıdır (LOG_DIR).

HTTP kipi

Gateway'i ortak bir sunucu olarak çalıştırmak için (stateless streamable HTTP; /mcp, yalnız POST):

npx -y @appaflytech/zeyrek-ai-mcp@latest     # --stdio olmadan

Sağlık ucu: http://localhost:5100/healthz (port MCP_PORT). İstemci kaydı:

claude mcp add zeyrek-ai --transport http http://localhost:5100/mcp

AUTH_MODE=passthrough yalnız bu kipte anlamlıdır: kimlik istemcinin Authorization header'ından geçer. (PoC boyunca local modda test edildi.)

Geliştirme (repo)

Bu paket monorepo içindeki zeyrek-mcp/ klasöründen yayınlanır. Aşağıdaki bağlantılar ve komutlar repo içinde geçerlidir; npm paketinde docs/ ve src/ yoktur.

cd zeyrek-mcp
npm install
cp .env.example ../.env      # hedef her zaman lokal stack
npm run dev                  # HTTP · npm run start:stdio ile stdio

.env repo kökünde, .mcp.json'ın yanında durur. Repo kökündeki .mcp.json sunucuyu zeyrek-mcp/node_modules/.bin/tsx ile başlatır — bağımlılıklar kurulu değilken MCP istemcisi hata vermeden sıfır tool ile bağlanır; repoyu yeni klonladıysanız ilk adım npm install'dır.

Doğrulama:

npm run typecheck
npm test          # gerçek ağa çıkmaz (undici MockAgent); MCP katmanı InMemoryTransport ile
npm run docs:lint

Şema kaynakları (API'ler ayaktayken): npm run generate-schemas, Swagger'dan seçili komut şemalarını src/resources/schemas/ altına yazar; sunucu bunları ngapps://schemas/* resource'ları olarak yayınlar (ngapps://schemas/index dizindir). Swagger adresi sırayla denenir: ORG_SWAGGER_URL / TENANT_SWAGGER_URL override'ları → {API_BASE_URL}/swagger/v1/swagger.json → localhost:3000 frontend proxy'si.

Tasarım ve durum dokümanları: docs/INDEX.md, docs/00-durum-ve-yol-haritasi.md, kural envanteri docs/08-kural-envanteri.md.

Yayınlama (paket bakımcısı)

Yayın otomatiktir: main'e zeyrek-mcp/ değişikliği girince CI işi publish:mcp:npm (scripts/ci-publish-npm.sh) paketi üretip npm'deki son sürümle içerik olarak karşılaştırır; pakete giren dosyalar değiştiyse yeni patch sürümünü yayınlar. Yayından sonra CI yeni sürümü package.json + package-lock.json'a yazıp chore: zeyrek-mcp X.Y.Z [skip ci] bot commit'iyle main'e push eder (yeni pipeline başlatmaz); yayın olmazsa commit de olmaz. Push CI_JOB_TOKEN ile yapılır; gereken GitLab ayarları .gitlab-ci.yml'daki publish:mcp:npm notunda. Commit yazılamayıp iş kırmızı düşerse push yetkisi olan biri işi Retry eder: yayın tekrarlanmaz, yalnız sürüm main'e yazılır. Minor/major için package.json'daki sürümü elle yükseltip merge edin. Yayını o commit için atlamak: commit mesajına DoNotDeploy (iş elle tetiklenir hâle gelir).

Yerelde deneme (yayın yapmaz; npm ci çalıştırdığı için bir kopyada ya da Linux container'da):

DRY_RUN=1 sh scripts/ci-publish-npm.sh

dist/ içine src/resources/{schemas,guides,examples} altındaki JSON/MD varlıklarını scripts/copy-assets.ts kopyalar — tsc tek başına bunları taşımaz. Yayınlanan paket dist/, README.md ve iki .env şablonundan oluşur.

Bilinen sınırlar

• project_create/update LoaderImage yüklemez (multipart dosya kapsam dışı; urlencoded form kullanılır).
• row_list.selectedFields kırpması gateway tarafında yapılır: platform GetRowsQuery.SelectedFields alanını yalnızca many-to-many alt sorgularını daraltmak için okur, skaler kolonlar için her zaman tam satır döner. Gateway satırları verilen alanlara (+id) indirger; alan eşleşmesi büyük/küçük harf duyarsızdır.
• microservice_execute dosya (stream) çıktısını içerik olarak aktarmaz.
• Passthrough auth modu tanımlı ama uçtan uca tatbik edilmedi.
• Docker/compose servisi bilinçli olarak ertelendi.