@appaflytech/zeyrek-ai-mcp 0.0.3 → 0.0.4

package/.env.example

@@ -1,17 +1,24 @@
+# LOKAL PROFIL — platform/gateway kodu gelistirirken. Uzak ortam icin:
+#   cp zeyrek-mcp/.env.production.example .env
+# Ortam rolleri: docs/ortam.md
+
 # 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,13 +40,20 @@ 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
+# Bos = tum moduller (149 tool). Hazir kumeler: core (veri+mantik, 92), studio (sayfa
+# tasarimi, 46), admin (template/organizasyon/deployment, 15). Kume ve tekil modul adi
 # karisik yazilabilir. Ornek: core,studio  |  entity,row,microservice
 MODULES=
 

package/.env.production.example

@@ -0,0 +1,42 @@
+# 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
+#
+# "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=
+
+MODULES=
+
+MCP_PORT=5100

package/README.md

@@ -2,7 +2,7 @@
 
 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
+Studio tasarım tarafı (page, component, flow, layout, variable, folder, file) birlikte, **162
 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
@@ -36,6 +36,8 @@ kurulum](#npm-paketi-olarak-kurulum). Asgari şunlar gerekir:
 | `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 |
+| `STUDIO_BASE_URL` | `http://localhost:3000` | Opsiyonel; yalnız `page_screenshot` kullanır — Studio arayüzünün kök adresi ([`docs/26`](docs/26-sayfa-ekran-goruntusu.md)) |
+| `SCREENSHOT_BROWSER_PATH` | `/usr/bin/chromium-browser` | Opsiyonel; `page_screenshot` için sistemdeki Chromium ikilisinin yolu (verilmezse playwright-core'un indirdiği tarayıcı) |
 
 ## Çalıştırma
 
@@ -69,7 +71,8 @@ okuyabilmek.
 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,
+`kırpma ✂` (yanıt `MAX_RESPONSE_BYTES` sınırını aştı), `tarayıcı →/←` (`page_screenshot`'ın
+headless Chromium turu: açılan URL, viewport, PNG boyutu), `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.
@@ -145,9 +148,13 @@ pakette `.env` yoktur, tüm ayarlar env bloğundan gelir.
 - 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.
+  ortamındaki aynı adlı değişkenlerle çakışabilir — `USERNAME` Windows'ta yerleşiktir, macOS
+  kabukları da sık sık tanımlar. Bu yüzden `.mcp.json`'da `${USERNAME:-…}` gibi genişletme
+  kullanmayın; değeri düz yazın.
+  `USERNAME` işletim sisteminin kullanıcı adıyla (`USER`/`LOGNAME`) AYNIYSA sunucu onu düşürür ve
+  `.env`'deki değer geçerli olur — bu guard olmadan terminalden `npm run dev` çalıştırmak kimliği
+  makine kullanıcısı adıyla almaya kalkıyor ve `POST /connect/token` 404 dönüyordu. Hata metni
+  "kayıt bulunamadı" olduğu için kimlik ayarına değil veriye işaret ediyor, teşhisi zorlaştırıyordu.
 - `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.
@@ -183,7 +190,7 @@ npm publish          # prepack: tsc -p tsconfig.build.json + varlık kopyalama
   `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ı),
+  ya da hazır küme — `core` (92 tool: veri + mantık), `studio` (50 tool: sayfa tasarımı),
   `admin` (15 tool: template, organizasyon, deployment). Küme ve modül adları karışık
   yazılabilir: `MODULES=core,page`.
 
@@ -193,7 +200,7 @@ 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/*`
+  html, layout, 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`).

package/dist/config.js

@@ -1,35 +1,62 @@
-import { z } from 'zod';
+import { z } from "zod";
 export const moduleNames = [
-    'platform',
-    'project',
-    'application',
-    'datasource',
-    'entity',
-    'row',
-    'microservice',
-    'query',
-    'workflow',
-    'automation',
-    'dto',
-    'view',
-    'page',
-    'component',
-    'flow',
-    'layout',
-    'variable',
-    'folder',
-    'file',
-    'access',
-    'translation',
-    'template',
-    'organization',
-    'dependency',
-    'deployment'
+    "platform",
+    "project",
+    "application",
+    "datasource",
+    "entity",
+    "row",
+    "microservice",
+    "query",
+    "workflow",
+    "automation",
+    "dto",
+    "view",
+    "page",
+    "component",
+    "externalComponent",
+    "flow",
+    "layout",
+    "variable",
+    "folder",
+    "file",
+    "access",
+    "translation",
+    "template",
+    "organization",
+    "dependency",
+    "deployment",
 ];
 export const modulePresets = {
-    core: ['platform', 'project', 'application', 'datasource', 'entity', 'row', 'microservice', 'query', 'workflow', 'automation', 'dto', 'view', 'dependency'],
-    studio: ['platform', 'page', 'component', 'flow', 'layout', 'variable', 'folder', 'file', 'access', 'translation'],
-    admin: ['platform', 'template', 'organization', 'deployment']
+    core: [
+        "platform",
+        "project",
+        "application",
+        "datasource",
+        "entity",
+        "row",
+        "microservice",
+        "query",
+        "workflow",
+        "automation",
+        "dto",
+        "view",
+        "dependency",
+    ],
+    studio: [
+        "platform",
+        "page",
+        "component",
+        "externalComponent",
+        "flow",
+        "layout",
+        "variable",
+        "folder",
+        "file",
+        "access",
+        "translation",
+    ],
+    admin: ["platform", "template", "organization", "deployment"],
 };
 function expandModuleNames(entries) {
     const modules = [];
@@ -52,22 +79,24 @@ const environmentSchema = z.object({
     ORG_API_BASE_URL: z.string().url(),
     TENANT_API_BASE_URL: z.string().url(),
     ORGANIZATION: z.string().min(1),
-    HOST_SUFFIX: z.string().min(1).default('localhost'),
-    DEFAULT_ENVIRONMENT: z.string().min(1).default('production'),
+    HOST_SUFFIX: z.string().min(1).default("localhost"),
+    DEFAULT_ENVIRONMENT: z.string().min(1),
     DEFAULT_PROJECT: z.string().optional(),
-    AUTH_MODE: z.enum(['local', 'passthrough']).default('local'),
+    AUTH_MODE: z.enum(["local", "passthrough"]).default("local"),
     TOKEN: z.string().optional(),
     USERNAME: z.string().optional(),
     PASSWORD: z.string().optional(),
-    POLICY: z.enum(['strict', 'warn', 'off']).default('strict'),
+    POLICY: z.enum(["strict", "warn", "off"]).default("strict"),
     MAX_RESPONSE_BYTES: z.coerce.number().int().positive().default(262144),
     REQUEST_TIMEOUT_MS: z.coerce.number().int().positive().default(100000),
     MODULES: z.string().optional(),
-    LOG_LEVEL: z.enum(['off', 'summary', 'detail']).default('detail'),
+    LOG_LEVEL: z.enum(["off", "summary", "detail"]).default("detail"),
     LOG_DIR: z.string().min(1).optional(),
     LOG_FILE: z.string().min(1).optional(),
     LOG_MAX_BODY_CHARS: z.coerce.number().int().positive().default(2000),
-    MCP_PORT: z.coerce.number().int().positive().default(5100)
+    MCP_PORT: z.coerce.number().int().positive().default(5100),
+    STUDIO_BASE_URL: z.string().url().optional(),
+    SCREENSHOT_BROWSER_PATH: z.string().min(1).optional(),
 });
 export const environmentKeys = Object.keys(environmentSchema.shape);
 /**
@@ -76,38 +105,73 @@ export const environmentKeys = Object.keys(environmentSchema.shape);
  * kullanılamazdır: boş string (README §Ayar öncelik sırası: boş = tanımsız) ve genişletilmemiş
  * `${VAR:-…}` yer tutucusu — Claude Code bu sözdizimini açar, VS Code'un kendi MCP istemcisi
  * açmadan olduğu gibi geçirir ve düşürülmezse konfigürasyon doğrulaması yer tutucu metinle patlar.
+ *
+ * Üçüncü hâl `USERNAME`'e özeldir: bu ad işletim sistemine ait. Windows onu HER ZAMAN, macOS
+ * kabukları da sık sık oturum açan kullanıcının adıyla tanımlar. dotenv mevcut anahtarı ezmediği
+ * için `.env`'deki `USERNAME=admin@…` sessizce yok sayılır ve gateway, kimliği makine kullanıcısı
+ * adıyla almaya çalışıp `POST /connect/token` üzerinden 404 alır — hata mesajı da "kayıt
+ * bulunamadı" dediği için kimlik ayarına değil, veriye işaret eder. `USERNAME` yalnız işletim
+ * sisteminin kullanıcı adıyla AYNIYSA düşürülür: gerçekten o adla giren bir kurulum zaten
+ * `.env`/`.mcp.json`'da aynı değeri yazar ve dosyadan geri okunur.
  */
 export function dropUnusableEnvironment(env) {
     for (const key of environmentKeys) {
         const value = env[key];
-        if (value === '' || (value !== undefined && /^\$\{[^}]*\}$/.test(value))) {
+        if (value === "" || (value !== undefined && /^\$\{[^}]*\}$/.test(value))) {
             delete env[key];
         }
     }
+    const osUser = env.USER ?? env.LOGNAME;
+    if (env.USERNAME !== undefined && env.USERNAME === osUser) {
+        delete env.USERNAME;
+    }
+}
+/**
+ * "Boş = tanımsız" kuralını `.env`'den gelen değerlere de uygular. `dropUnusableEnvironment`
+ * yalnız süreç ortamına, yani dotenv ÖNCESİNE bakar; `.env`'deki `LOG_FILE=` gibi boş bir satırı
+ * dotenv sonradan boş string olarak yazar ve `.min(1)` şemaları patlar. `.env.example` bu
+ * anahtarları boş gönderdiği için kopyalayan her kurulum açılmayan bir gateway alıyordu.
+ * USERNAME kuralı bilerek burada tekrarlanmaz: o, dotenv'den ÖNCE bir kez uygulanmalıdır ki
+ * `.env`'deki kimlik işletim sistemininkiyle aynı olduğunda düşürülmesin.
+ */
+function withoutEmptyValues(env) {
+    const copy = { ...env };
+    for (const key of environmentKeys) {
+        if (copy[key] === "")
+            delete copy[key];
+    }
+    return copy;
 }
 export function loadConfig(env) {
-    const parsed = environmentSchema.safeParse(env);
+    const parsed = environmentSchema.safeParse(withoutEmptyValues(env));
     if (!parsed.success) {
-        const missing = parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+        const missing = parsed.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; ");
         throw new Error(`Gateway konfigürasyonu geçersiz — ${missing}. Gerekli değişkenler için zeyrek-mcp/.env.example dosyasına bakın.`);
     }
     const values = parsed.data;
-    if (values.AUTH_MODE === 'local' && !values.TOKEN && (!values.USERNAME || !values.PASSWORD)) {
-        throw new Error('AUTH_MODE=local için TOKEN ya da USERNAME + PASSWORD zorunludur.');
+    if (values.AUTH_MODE === "local" &&
+        !values.TOKEN &&
+        (!values.USERNAME || !values.PASSWORD)) {
+        throw new Error("AUTH_MODE=local için TOKEN ya da USERNAME + PASSWORD zorunludur.");
     }
-    if (values.AUTH_MODE === 'passthrough' && (values.TOKEN || values.USERNAME || values.PASSWORD)) {
-        throw new Error('AUTH_MODE=passthrough iken TOKEN/USERNAME/PASSWORD tanımlanamaz — kimlik istemciden gelir.');
+    if (values.AUTH_MODE === "passthrough" &&
+        (values.TOKEN || values.USERNAME || values.PASSWORD)) {
+        throw new Error("AUTH_MODE=passthrough iken TOKEN/USERNAME/PASSWORD tanımlanamaz — kimlik istemciden gelir.");
     }
     const requested = values.MODULES
-        ? values.MODULES.split(',').map(name => name.trim()).filter(name => name.length > 0)
+        ? values.MODULES.split(",")
+            .map((name) => name.trim())
+            .filter((name) => name.length > 0)
         : [...moduleNames];
     const { modules, unknown: unknownModules } = expandModuleNames(requested);
     if (unknownModules.length > 0) {
-        throw new Error(`MODULES bilinmeyen modül/küme içeriyor: ${unknownModules.join(', ')}. Kümeler: ${Object.keys(modulePresets).join(', ')}. Modüller: ${moduleNames.join(', ')}.`);
+        throw new Error(`MODULES bilinmeyen modül/küme içeriyor: ${unknownModules.join(", ")}. Kümeler: ${Object.keys(modulePresets).join(", ")}. Modüller: ${moduleNames.join(", ")}.`);
     }
     return {
-        orgApiBaseUrl: values.ORG_API_BASE_URL.replace(/\/+$/, ''),
-        tenantApiBaseUrl: values.TENANT_API_BASE_URL.replace(/\/+$/, ''),
+        orgApiBaseUrl: values.ORG_API_BASE_URL.replace(/\/+$/, ""),
+        tenantApiBaseUrl: values.TENANT_API_BASE_URL.replace(/\/+$/, ""),
         organization: values.ORGANIZATION,
         hostSuffix: values.HOST_SUFFIX,
         defaultEnvironment: values.DEFAULT_ENVIRONMENT,
@@ -124,6 +188,8 @@ export function loadConfig(env) {
         logDirectory: values.LOG_DIR,
         logFile: values.LOG_FILE,
         logMaxBodyChars: values.LOG_MAX_BODY_CHARS,
-        port: values.MCP_PORT
+        port: values.MCP_PORT,
+        studioBaseUrl: values.STUDIO_BASE_URL?.replace(/\/+$/, ""),
+        screenshotBrowserPath: values.SCREENSHOT_BROWSER_PATH,
     };
 }