@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.

• 260 tool · 35 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

Opsiyonel

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.

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

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.