@appaflytech/zeyrek-ai-mcp 0.0.3 → 0.0.5

package/.env.example

@@ -1,17 +1,28 @@
+# LOKAL PROFIL — platform/gateway kodu gelistirirken. Uzak ortam icin:
+#   cp zeyrek-mcp/.env.production.example .env
+# Ortam rolleri: docs/ortam.md
+#
+# npm paketiyle (npx @appaflytech/zeyrek-ai-mcp) kurulumda .env sart degil: ayni anahtarlar
+# .mcp.json'in env blogundan verilebilir ve o blok .env'i ezer. Arama sirasi:
+#   <calisma dizini>/.env -> <paket>/.env -> <paket>/../.env
+
 # Platform API adresleri (host makinesinden lokal compose icin)
-ORG_API_BASE_URL=http://localhost:7000
-TENANT_API_BASE_URL=http://localhost:5000
+ORG_API_BASE_URL=http://localhost:17000
+TENANT_API_BASE_URL=http://localhost:15000
 
 # Org cozumu: istekler Host: {ORGANIZATION}.{HOST_SUFFIX} header'i ile gider
-ORGANIZATION=zeyrek-local
+ORGANIZATION=zeyrek-test
 HOST_SUFFIX=localhost
 
-# Varsayilanlar; tool parametresi her zaman ezer
-DEFAULT_ENVIRONMENT=production
+# ZORUNLU. Gomulu varsayilan yok: bos birakilirsa sunucu acilmaz.
+# AI yazmalari her zaman development'a gider (AGENTS.md 1).
+DEFAULT_ENVIRONMENT=development
 DEFAULT_PROJECT=
 
 # local: kimlik asagidaki alanlardan, passthrough: istemcinin Authorization header'i aynen gecer
 # local modda ya TOKEN (hazir Bearer JWT) ya da USERNAME+PASSWORD verin
+# NOT: USERNAME isletim sisteminde de tanimli olabilir (Windows her zaman, macOS sik sik).
+# Sunucu, USER/LOGNAME ile AYNI olan USERNAME'i dusurur; asagidaki deger yine de gecerli olur.
 AUTH_MODE=local
 TOKEN=
 USERNAME=
@@ -33,14 +44,22 @@ LOG_MAX_BODY_CHARS=2000
 MAX_RESPONSE_BYTES=262144
 REQUEST_TIMEOUT_MS=100000
 
+# page_screenshot icin: Studio arayuzunun kok adresi (yerel gelistirmede http://localhost:3000).
+# Bos birakilirsa tool anlasilir hata doner; ilk kullanimda `npx playwright-core install chromium`
+# gerekir. SCREENSHOT_BROWSER_PATH ile playwright indirmesi yerine sistemdeki Chromium kullanilir.
+# Lokal Studio org'u Host'tan cozer; screenshot icin uzak host gerekebilir (docs/ortam.md).
+STUDIO_BASE_URL=http://localhost:3000
+SCREENSHOT_BROWSER_PATH=
+
 # generate-schemas icin swagger adresleri. Bos birakilirsa sirayla denenir:
 # 1) asagidaki override, 2) {API_BASE_URL}/swagger/v1/swagger.json, 3) localhost:3000 frontend proxy'si
 ORG_SWAGGER_URL=
 TENANT_SWAGGER_URL=
 
-# Bos = tum moduller (148 tool). Hazir kumeler: core (veri+mantik, 92), studio (sayfa
-# tasarimi, 45), admin (template/organizasyon/deployment, 15). Kume ve tekil modul adi
-# karisik yazilabilir. Ornek: core,studio  |  entity,row,microservice
+# Bos = tum moduller (162 tool / 26 modul). Hazir kumeler: core (veri+mantik, 93), studio
+# (sayfa tasarimi, 59), admin (template/organizasyon/deployment, 16). platform modulu (3 tool)
+# her kumede vardir. Kume ve tekil modul adi karisik yazilabilir.
+# Ornek: core,studio  |  entity,row,microservice
 MODULES=
 
 MCP_PORT=5100

package/.env.production.example

@@ -0,0 +1,44 @@
+# UZAK PROFIL — kosular, uygulama kurulumu, gercek-ekran dogrulama, demo.
+# Kurulum: cp zeyrek-mcp/.env.production.example .env  (sonra PASSWORD'u doldurun)
+# Ortam rolleri: docs/ortam.md
+# npm paketiyle kurulumda ayni anahtarlar .mcp.json'in env blogundan da verilebilir (README).
+#
+# "production" burada PLATFORM KURULUMUNUN adidir. AI'in yazma hedefi orada da
+# development environment'idir — asagidaki DEFAULT_ENVIRONMENT bu yuzden development.
+
+ORG_API_BASE_URL=https://new-zeyrek.glomil.com/api/org
+TENANT_API_BASE_URL=https://new-zeyrek.glomil.com/api
+
+ORGANIZATION=new-zeyrek
+HOST_SUFFIX=glomil.com
+
+# ZORUNLU. Gomulu varsayilan yok.
+DEFAULT_ENVIRONMENT=development
+DEFAULT_PROJECT=
+
+AUTH_MODE=local
+TOKEN=
+USERNAME=admin@zeyrek.com
+PASSWORD=
+
+POLICY=strict
+
+LOG_LEVEL=detail
+LOG_DIR=zeyrek-mcp/logs
+LOG_FILE=
+LOG_MAX_BODY_CHARS=2000
+
+MAX_RESPONSE_BYTES=262144
+REQUEST_TIMEOUT_MS=100000
+
+# page_screenshot icin gercek Studio host'u (localhost:3000 org'u cozemez — 27/S-22).
+STUDIO_BASE_URL=https://new-zeyrek.glomil.com
+SCREENSHOT_BROWSER_PATH=
+
+ORG_SWAGGER_URL=
+TENANT_SWAGGER_URL=
+
+# Bos = tum moduller (162 tool). Kumeler: core (93) | studio (59) | admin (16).
+MODULES=
+
+MCP_PORT=5100

package/README.md

@@ -1,167 +1,150 @@
-# zeyrek-ai-mcp
+# @appaflytech/zeyrek-ai-mcp
 
-NgApps platformunu MCP tool'ları olarak sunan bağımsız gateway — veri/mantık tarafı (project,
-application, datasource, entity, row, microservice, query, workflow, automation, dto, view) ve
-Studio tasarım tarafı (page, component, flow, layout, variable, folder, file) birlikte, **152
-tool / 24 modül**. Durum + yol haritası:
-[`docs/00-durum-ve-yol-haritasi.md`](docs/00-durum-ve-yol-haritasi.md);
-tasarım: [`docs/`](docs/01-vizyon-ve-kapsam.md). Platform koduna
-referans vermez; iki API'yi HTTP üzerinden sarar, istekler MVC binding'den geçtiği için
-FluentValidation aynen çalışır.
+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.
 
-## Kurulum
+- **162 tool · 26 modül** — veri/mantık tarafı (project, application, datasource, entity, row,
+  microservice, query, workflow, automation, dto, view, dependency), Studio tasarım tarafı
+  (page, component, external component, flow, layout, variable, folder, file, access,
+  translation) ve yönetim (template, organization, deployment).
+- 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.
 
-```bash
-cd zeyrek-mcp
-npm install
-cp .env.example ../.env
-```
+Gereken: **Node 20+** ve erişebildiğiniz bir platform kurulumu (API adresleri, org adı, kullanıcı).
 
-`.env` **repo kökünde**, `.mcp.json`'ın yanında durur (kök `.gitignore`'da `/.env` ile korunur).
-Sunucu şu sırayla arar, ilk bulunan anahtar kazanır: `<çalışma dizini>/.env` →
-`<paket>/.env` → `<paket>/../.env`.
+---
 
-> `npm install` yalnız `npm run dev` için değil: 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 budur.
+## Hızlı başlangıç (npm)
 
-Ayarlar `.env` yerine (ya da onunla birlikte) repo kökündeki `.mcp.json`'ın `env` bloğundan da
-verilebilir; env bloğu her zaman `.env`'i ezer — ayrıntı [npm paketi olarak
-kurulum](#npm-paketi-olarak-kurulum). Asgari şunlar gerekir:
+Repoyu klonlamanıza gerek yok; paket npx ile çalışır. Projenizin kökündeki `.mcp.json`'a
+ekleyin:
 
-| Değişken | Örnek | Not |
-|----------|-------|-----|
-| `ORG_API_BASE_URL` | `http://localhost:7000` | Organization.API |
-| `TENANT_API_BASE_URL` | `http://localhost:5000` | Tenant.API |
-| `ORGANIZATION` | `zeyrek-local` | Org subdomain'i; istekler `Host: {org}.{suffix}` ile gider |
-| `USERNAME` / `PASSWORD` | | `/connect/token` ile takas edilir (AuthMode=local) |
-| `DEFAULT_PROJECT` | `crm` | Opsiyonel; tool'daki `project` parametresi her zaman ezer |
+```json
+{
+  "mcpServers": {
+    "zeyrek-ai": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@appaflytech/zeyrek-ai-mcp@0.0.5", "--stdio"],
+      "env": {
+        "ORG_API_BASE_URL": "https://new-zeyrek.glomil.com/api/org",
+        "TENANT_API_BASE_URL": "https://new-zeyrek.glomil.com/api",
+        "ORGANIZATION": "new-zeyrek",
+        "HOST_SUFFIX": "glomil.com",
+        "DEFAULT_ENVIRONMENT": "development",
+        "USERNAME": "admin@zeyrek.com",
+        "PASSWORD": "parolanız",
+        "LOG_DIR": "logs"
+      }
+    }
+  }
+}
+```
 
-## Çalıştırma
+Claude Code'da komutla eklemek isterseniz:
 
 ```bash
-npm run dev
+claude mcp add zeyrek-ai \
+  -e ORG_API_BASE_URL=https://new-zeyrek.glomil.com/api/org \
+  -e TENANT_API_BASE_URL=https://new-zeyrek.glomil.com/api \
+  -e ORGANIZATION=new-zeyrek \
+  -e HOST_SUFFIX=glomil.com \
+  -e DEFAULT_ENVIRONMENT=development \
+  -e USERNAME=admin@zeyrek.com \
+  -e PASSWORD='parolanız' \
+  -- npx -y @appaflytech/zeyrek-ai-mcp@0.0.5 --stdio
 ```
 
-Sağlık: `http://localhost:5100/healthz`. Sunucu stateless streamable HTTP konuşur (`/mcp`,
-yalnız POST); `npm run start:stdio` ile stdio kipi de var.
+**İ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.
 
-## Tool çağrısı günlüğü
+### Sürüm seçimi
 
-Her MCP tool çağrısı, okunmak için biçimlenmiş tek bir blok olarak dosyaya yazılır — varsayılan
-`zeyrek-mcp/logs/gateway-YYYY-MM-DD.log` (günlük dosya, `.gitignore`'da). Amaç: bir çağrının ne
-yapmaya çalıştığını, içeriden hangi duraklardan geçtiğini ve nerede patladığını **koda inmeden**
-okuyabilmek.
+`@0.0.5` gibi sabit sürüm önerilir: npx kopyayı önbelleğe alır, sabit sürümde herkes aynı
+gateway'i çalıştırır. `@latest` yazarsanız ekipteki makineler farklı sürümlerde kalabilir;
+güncellemek için `.mcp.json`'daki sürümü yükseltip MCP sunucusunu yeniden başlatın.
 
-```
-┌─ #1 · 11:27:27.082 · platform_whoami — Oturum bilgisi
-│  amaç   : Gateway'in platformda kimin adına çalıştığını döner; auth kurulumunu doğrulamak için ilk çağrılacak tool.
-│  girdi  : (parametresiz)
-│  adımlar:
-│    +2ms      kimlik →    önbellekte geçerli token yok — POST http://localhost:7000/connect/token · kullanıcı admin@zeyrek.com
-│    +229ms    kimlik ←    HTTP 200 · token alındı, önbellekte 63158340 sn geçerli
-│    +229ms    istek →     GET http://localhost:7000/connect/userinfo · org api · env=development
-│    +237ms    yanıt ←     HTTP 200 · 8 ms · 174 B
-│                          gövde: {"sub":"01917edf-…","email":"admin@zeyrek.com","role":["super-admin"]}
-└─ SONUÇ  : başarılı · 238 ms · 4 adım · 137 B yanıt
-```
+---
 
-Adım etiketleri: `politika` (lint kuralları; `politika ✕` isteği hiç göndermez), `düzeltme`
-(gateway'in gövdeye uyguladığı otomatik düzeltmeler — yanıttaki `gatewayNormalized`), `kimlik →/←`
-(`/connect/token` turu), `istek →/yanıt ←` (platform API turu, tam URL + süre + boyut),
-`kırpma ✂` (yanıt `MAX_RESPONSE_BYTES` sınırını aştı), `hata ✕` (yakalanan hata: sınıf,
-HTTP kodu, mesaj, ilk 3 stack satırı). Tool gövdesine hiç girmeyen çağrılar — yanlış tool adı ya da
-parametre şemasına takılan gövde — `MCP KATMANI REDDETTİ` bloğu olarak düşer; bunlar aksi hâlde
-hiçbir yerde görünmezdi.
+## Ayarlar
 
-Arama: `SONUÇ  : HATA` tüm başarısız çağrılar, `hata ✕` hata satırları, `#<n>` tek bir çağrı.
+Ayar üç kaynaktan gelebilir, **öncelik sırası**:
 
-| Değişken | Varsayılan | Not |
-|----------|-----------|-----|
-| `LOG_LEVEL` | `detail` | `detail` istek/yanıt gövdelerini de yazar · `summary` yalnız durak + boyut + hata gövdeleri · `off` hiç dosya açmaz |
-| `LOG_DIR` | `zeyrek-mcp/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 bir gövde/parametre önizlemesinin karakter sınırı |
+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
 
-Adı `pass|secret|token|authorization|api key|credential|connectionString` desenine uyan alanlar
-`***` ile maskelenir (`girdi` satırında ve gövde önizlemelerinde). Günlükleme yazma hatası tool
-çağrısını **düşürmez**: ilk hatada stderr'e tek satır yazılıp günlükleme kapatılır.
+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.
 
-## Claude Code kaydı
+### Zorunlu
 
-```bash
-claude mcp add ngapps --transport http http://localhost:5100/mcp
-```
+| Değişken | Örnek | Not |
+|---|---|---|
+| `ORG_API_BASE_URL` | `https://new-zeyrek.glomil.com/api/org` | Organization.API kökü |
+| `TENANT_API_BASE_URL` | `https://new-zeyrek.glomil.com/api` | Tenant.API kökü |
+| `ORGANIZATION` | `new-zeyrek` | 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 |
 
-stdio alternatifi (port gerekmez, sunucuyu istemci başlatır):
+### Opsiyonel
 
-```bash
-claude mcp add zeyrek-ai -- npx tsx <repo>/zeyrek-mcp/src/index.ts --stdio
-```
+| 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ı) |
 
-İlk doğrulama: oturumda `platform_whoami` tool'unu çağırtın — kimlik ve org çözümü tek seferde
-test edilir.
+Tam liste ve yorumlu şablon: pakete dahil edilen `.env.example` (lokal profil) ve
+`.env.production.example` (uzak profil).
 
-## npm paketi olarak kurulum
+### Bilinmesi gereken üç davranış
 
-Repoyu klonlamadan, yayınlanmış paketle. Tüm ayarlar `.mcp.json`'ın `env` bloğundan gelir;
-`.env` dosyasına gerek yoktur:
+- **`${…}` 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.
 
-```json
-{
-  "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_PROJECT": "emrah",
-        "DEFAULT_ENVIRONMENT": "development",
-        "USERNAME": "admin@zeyrek.com",
-        "PASSWORD": "${PASSWORD}",
-        "MODULES": "core",
-        "LOG_DIR": "logs"
-      }
-    }
-  }
-}
-```
+---
 
-Ayar öncelik sırası: **`.mcp.json` env bloğu → `.env` (varsa; repo içinden çalışırken kökte
-durur) → şemadaki varsayılan.** `.env.example` tüm değişkenlerin tam listesidir. npx ile kurulan
-pakette `.env` yoktur, tüm ayarlar env bloğundan gelir.
-
-- `.mcp.json` sürüm kontrolündeyse parolayı düz yazmayın: Claude Code `${PASSWORD}` ve
-  `${PASSWORD:-varsayılan}` genişletmesi yapar, değer kabuk ortamından gelir.
-- Genişletme **istemciye bağlıdır**: Claude Code açar, VS Code'un kendi MCP istemcisi açmaz ve
-  metni olduğu gibi geçirir. Bu yüzden sunucu, açılmamış `${…}` yer tutucusunu boş değerle aynı
-  sayıp **düşürür** — ayar `.env`'den ya da şema varsayılanından doldurulur, sunucu yer tutucu
-  metinle patlamaz (`dropUnusableEnvironment`). Ortama göre gerçekten değişen ayarı `.env`'e
-  koymak her istemcide çalışan yoldur.
-- Boş bırakılan (`""`) alanlar **tanımsız** sayılır; varsayılana düşer ya da `.env`'den
-  doldurulur. Yani `"${MODULES:-}"` yazmak alanı hiç yazmamakla aynıdır.
-- Değişken adları ön eksizdir (`USERNAME`, `PASSWORD`, `TOKEN`, `LOG_LEVEL` …), yani kabuk
-  ortamındaki aynı adlı değişkenlerle çakışabilir — `USERNAME` Windows'ta yerleşiktir. Bu yüzden
-  `.mcp.json`'da `${USERNAME:-…}` gibi genişletme kullanmayın; değeri düz yazın ya da `.env`'e
-  koyun.
-- `LOG_DIR` verilmezse günlükler **çalışma dizininin** altındaki `logs/` klasörüne yazılır.
-- Konfigürasyon geçersizse sunucu stderr'e tek satır sebep yazıp `exit 1` yapar — istemci artık
-  sessizce sıfır tool ile bağlanmaz.
-
-Yayınlama (paket bakımcısı için):
+## Modüller
 
-```bash
-cd zeyrek-mcp
-npm run typecheck && npm test
-npm publish          # prepack: tsc -p tsconfig.build.json + varlık kopyalama
-```
+`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` | 93 | platform, project, application, datasource, entity, row, microservice, query, workflow, automation, dto, view, dependency |
+| `studio` | 59 | platform, page, component, externalComponent, flow, layout, variable, folder, file, access, translation |
+| `admin` | 16 | platform, template, organization, deployment |
+| (boş) | **162** | 26 modülün tamamı |
 
-`dist/` içine `src/resources/{schemas,guides,examples}` altındaki 41 JSON/MD varlığı
-`scripts/copy-assets.ts` kopyalar — `tsc` tek başına bunları taşımaz.
+Bilinmeyen bir modül/küme adı verilirse sunucu açılmaz, geçerli adları listeleyen bir hata yazar.
+
+---
 
 ## Kullanım kalıpları
 
@@ -171,47 +154,39 @@ npm publish          # prepack: tsc -p tsconfig.build.json + varlık kopyalama
   `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.
+  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** (platform ucu üründe
-  olmayan ayrı bir servise delege ediyor) — ayrıntı `platform_guide('page')`.
+  `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_*` uçlarının istediği barındırıcı gövdesini de gateway kurar.
-- Tool seti `MODULES` ile daraltılabilir: tekil modül adı (`entity,row,microservice`)
-  ya da hazır küme — `core` (92 tool: veri + mantık), `studio` (49 tool: sayfa tasarımı),
-  `admin` (15 tool: template, organizasyon, deployment). Küme ve modül adları karışık
-  yazılabilir: `MODULES=core,page`.
-
-## Bilgi katmanı (Faz 1.5)
-
-Tasarım: [`docs/07-bilgi-katmani.md`](docs/07-bilgi-katmani.md).
-Üç savunma hattı:
-
-- **Rehberler:** `platform_guide` tool'u (workflow, microservice, entity, page, component,
-  html, middleware, view, expressions, getting-started, modify-existing) + `ngapps://guides/*`
-  resource'ları. Bir modülde ilk yazma işleminden önce ilgili rehber okunmalı; tool
-  açıklamaları bunu söyler. Komponent davranış bilgisi ayrıca `component_get` çıktısında
-  `knowledge` alanı olarak döner (`src/knowledge/componentCatalog.ts`).
-- **Altın örnekler:** `ngapps://examples/*` — boş org'da şablon kaynağı. Şu an sentetik seed;
-  platform ayaktayken `npm run harvest-examples -- --project qm` ham hasadı
-  `src/resources/examples/harvested/` altına yazar, küratörlükten geçen dosyalar `examples/`
-  köküne taşını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 `src/knowledge/rules.ts` kurallarından 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`. Kural envanteri: `docs/08-kural-envanteri.md`.
+  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
-([tasarım](docs/09-buyuk-sema-stratejisi.md)):
+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
@@ -219,42 +194,135 @@ Tam gövdeyi LLM bağlamına sokmadan çalışma modeli
 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
 
-## Şema kaynakları
+---
+
+## Tool çağrısı günlüğü
+
+Her MCP tool çağrısı, okunmak için biçimlenmiş tek bir blok olarak dosyaya yazılır — varsayılan
+`{LOG_DIR}/gateway-YYYY-AA-GG.log`. Amaç: bir çağrının ne yapmaya çalıştığını, hangi duraklardan
+geçtiğini ve nerede patladığını **koda inmeden** okuyabilmek.
+
+```
+┌─ #1 · 11:27:27.082 · platform_whoami — Oturum bilgisi
+│  amaç   : Gateway'in platformda kimin adına çalıştığını döner; auth kurulumunu doğrulamak için ilk çağrılacak tool.
+│  girdi  : (parametresiz)
+│  adımlar:
+│    +2ms      kimlik →    önbellekte geçerli token yok — POST http://localhost:7000/connect/token · kullanıcı admin@zeyrek.com
+│    +229ms    kimlik ←    HTTP 200 · token alındı, önbellekte 63158340 sn geçerli
+│    +229ms    istek →     GET http://localhost:7000/connect/userinfo · org api · env=development
+│    +237ms    yanıt ←     HTTP 200 · 8 ms · 174 B
+│                          gövde: {"sub":"01917edf-…","email":"admin@zeyrek.com","role":["super-admin"]}
+└─ SONUÇ  : başarılı · 238 ms · 4 adım · 137 B yanıt
+```
+
+Adım etiketleri: `politika` (lint kuralları; `politika ✕` isteği hiç göndermez), `düzeltme`
+(gateway'in gövdeye uyguladığı otomatik düzeltmeler — yanıttaki `gatewayNormalized`),
+`kimlik →/←` (`/connect/token` turu), `istek →/yanıt ←` (platform API turu, tam URL + süre +
+boyut), `kırpma ✂` (yanıt `MAX_RESPONSE_BYTES` sınırını aştı), `tarayıcı →/←`
+(`page_screenshot`'ın headless Chromium turu), `hata ✕` (yakalanan hata: sınıf, HTTP kodu, mesaj,
+ilk 3 stack satırı). Tool gövdesine hiç girmeyen çağrılar — yanlış tool adı ya da parametre
+şemasına takılan gövde — `MCP KATMANI REDDETTİ` bloğu olarak düşer.
+
+Arama: `SONUÇ  : HATA` tüm başarısız çağrılar, `hata ✕` hata satırları, `#<n>` tek bir çağrı.
+
+Adı `pass|secret|token|authorization|api key|credential|connectionString` desenine uyan alanlar
+`***` ile maskelenir. Günlükleme yazma hatası tool çağrısını **düşürmez**: ilk hatada stderr'e
+tek satır yazılıp günlükleme kapatılır.
+
+## 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: `.mcp.json`'da sabit sürüm yazın ve sunucuyu yeniden başlatın. |
+
+Her durumda ilk bakılacak yer günlük dosyasıdır (`LOG_DIR`).
+
+---
+
+## HTTP kipi
 
-API'ler ayaktayken:
+Gateway'i ortak bir sunucu olarak çalıştırmak için (stateless streamable HTTP; `/mcp`, yalnız
+POST):
 
 ```bash
-npm run generate-schemas
+npx -y @appaflytech/zeyrek-ai-mcp@0.0.5     # --stdio olmadan
 ```
 
-Swagger'dan seçili komut şemalarını `src/resources/schemas/` altına yazar; sunucu bunları
-`ngapps://schemas/*` MCP resource'ları olarak yayınlar (`ngapps://schemas/index` dizindir).
-Üretilen JSON'lar klasörde durur ve gateway'le birlikte taşınır — script yalnızca yeniden
-üretmek için gerekir.
+Sağlık ucu: `http://localhost:5100/healthz` (port `MCP_PORT`). İstemci kaydı:
+
+```bash
+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](https://gitlab.com/new-zeyrek/zeyrek-app) 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.
 
-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
-(`/api/org` ve `/api`). Hangi adresin kullanıldığı çıktıda yazar.
+```bash
+cd zeyrek-mcp
+npm install
+cp .env.example ../.env      # uzak profil için: cp .env.production.example ../.env
+npm run dev                  # HTTP · npm run start:stdio ile stdio
+```
 
-## Test
+`.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:
 
 ```bash
 npm run typecheck
-npm test
+npm test          # gerçek ağa çıkmaz (undici MockAgent); MCP katmanı InMemoryTransport ile
+npm run docs:lint
 ```
 
-Testler gerçek ağa çıkmaz (undici `MockAgent`); MCP katmanı `InMemoryTransport` üzerinden
-gerçek el sıkışmasıyla doğrulanır.
+Ş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/INDEX.md),
+[`docs/00-durum-ve-yol-haritasi.md`](docs/00-durum-ve-yol-haritasi.md),
+kural envanteri [`docs/08-kural-envanteri.md`](docs/08-kural-envanteri.md).
+
+### Yayınlama (paket bakımcısı)
+
+```bash
+cd zeyrek-mcp
+npm run typecheck && npm test
+npm version patch            # package.json sürümü
+npm publish                  # prepack: tsc -p tsconfig.build.json + varlık kopyalama
+```
+
+`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.
+
+Sürüm yükseldikten sonra ekipteki `.mcp.json` örneklerindeki sabit sürümü de güncelleyin.
+
+---
 
-## Bilinen sınırlar (PoC)
+## 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.
+- `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; PoC `local` modda test edilir.
-- Docker/compose servisi bilinçli olarak ertelendi (Faz 3 backlog'u —
-  `docs/00-durum-ve-yol-haritasi.md` §5.4).
+- Passthrough auth modu tanımlı ama uçtan uca tatbik edilmedi.
+- Docker/compose servisi bilinçli olarak ertelendi.