@appaflytech/zeyrek-ai-mcp 0.0.7 → 0.0.9

package/dist/tools/microservices.js

@@ -76,6 +76,8 @@ const executeInput = {
     query: z.record(z.unknown()).optional(),
     body: z.union([z.record(z.unknown()), z.array(z.record(z.unknown()))]).optional()
         .describe('İstek gövdesi: tek nesne ya da nesne dizisi (bulk uçlar için)'),
+    parameters: z.record(z.unknown()).optional()
+        .describe("Ucun çağrı parametreleri (ad → değer) — query kaynaklı ucun sorgu parametreleri ve tablo ucunun filtreleri. Platform değeri body → query-string → header sırasıyla arar; gateway GET/DELETE'te query-string'e, POST/PUT'ta gövdeye koyar ve nereye koyduğunu gatewayNormalized ile söyler. Aynı ad 'query'/'body'de FARKLI değerle de verilirse çağrı gönderilmez. Boş string platformda NULL'a çevrilir."),
     headers: z.record(z.string()).optional().describe("İsteğe eklenecek header'lar. 'Authorization' verirseniz gateway KENDİ token'ını KOYMAZ — istek tamamen sizin kimliğinizle gider (middleware'li uçları üye token'ıyla test etmenin yolu budur)"),
     anonymous: z.boolean().optional().describe("true: istek HİÇBİR Authorization header'ı olmadan gider — 'korumalı uç tokensız ne döner?' sorusunun cevabı budur (korumalı uçtan 401, anonim uçtan 200 beklenir). Gateway normalde her çağrıya kendi token'ını koyduğu için bu bayrak olmadan anonim erişim testi yapılamaz."),
     asUser: asUserParam,
@@ -133,6 +135,56 @@ async function middlewareChain(platform, project, environment, application, micr
         return { middlewareNote: `Middleware zinciri çözülemedi: ${error instanceof Error ? error.message : String(error)}. Uca bağlı middleware'leri microservice_get ile okuyabilirsiniz.` };
     }
 }
+/**
+ * G-13 — üst düzey `parameters` isteğin platformun okuduğu yerine bağlanır.
+ *
+ * Platform çağrı parametresini `MicroserviceExecuteParameter.FindValue` ile body → query-string →
+ * header sırasıyla arar. GET/DELETE isteğinde gövde taşınmadığı için değer query-string'e, yazan
+ * yöntemde gövdeye (tek nesne) konur; gövdede tipi (sayı, bool) korunur. Aynı ad çağrıda iki
+ * farklı değerle geldiğinde hangisinin kazanacağını tahmin ettirmek yerine istek gönderilmez.
+ */
+function bindCallParameters(method, parameters, query, body, notes) {
+    const names = Object.keys(parameters ?? {});
+    if (parameters === undefined || names.length === 0)
+        return { query, body };
+    const intoQuery = method === 'GET' || method === 'DELETE';
+    if (!intoQuery && Array.isArray(body)) {
+        throw new PlatformApiError(`parameters (${names.join(', ')}) ${method} isteğinde gövdeye bağlanır, ama body bir DİZİ (bulk). Platform parametreyi yalnız gövdenin İLK öğesinden okur — değerleri body[0]'a yazın ya da parameters'ı kaldırın.`, 400);
+    }
+    const target = (intoQuery ? query : body) ?? {};
+    const conflicts = names.filter(name => name in target && JSON.stringify(target[name]) !== JSON.stringify(parameters[name]));
+    if (conflicts.length > 0) {
+        throw new PlatformApiError(`parameters ile ${intoQuery ? 'query' : 'body'} aynı adı farklı değerle taşıyor: ${conflicts.map(name => `'${name}'`).join(', ')}. Değeri tek yerde verin.`, 400);
+    }
+    const merged = { ...target, ...parameters };
+    notes.push(`parameters ${intoQuery ? "query-string'e" : 'gövdeye'} bağlandı (${method}): ${names.join(', ')}`);
+    return intoQuery ? { query: merged, body } : { query, body: merged };
+}
+/**
+ * Debug ağacında query düğümünün parametre satırı değer NULL bağlandığında `value` taşır ama
+ * gateway yanıtı `prune` ile null alanlardan temizlediği için satır ANAHTARSIZ görünür — G-13'te
+ * kökü veren tek iz bu yokluktu. Yokluğu okumak zorunda kalmamak için satırlar adıyla listelenir.
+ */
+function unboundQueryParameters(value, into = []) {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            unboundQueryParameters(entry, into);
+        return into;
+    }
+    if (!value || typeof value !== 'object')
+        return into;
+    const node = value;
+    if (node.type === 'query' && Array.isArray(node.input)) {
+        for (const row of node.input) {
+            if (row?.source === 'query' && row.member === 'parameter' && (row.value === null || row.value === undefined || row.value === '')) {
+                into.push({ step: String(node.name ?? '(adsız query)'), parameter: String(row.expression ?? '') });
+            }
+        }
+    }
+    for (const entry of Object.values(node))
+        unboundQueryParameters(entry, into);
+    return into;
+}
 function executePath(prefix, application, microservice, routeParams) {
     const routeSuffix = routeParams && routeParams.length > 0
         ? `/${routeParams.map(encodeURIComponent).join('/')}`
@@ -325,25 +377,37 @@ export function registerMicroserviceTools(server, platform) {
         description: "Kayıtlı microservice'i gerçek runtime yolundan çalıştırır (POST /{project}/m/{application}/{microservice SLUG'ı}). Dönen httpStatus microservice'in kendi sonucudur (hata da geçerli çıktıdır); beklenmedik sonuçta microservice_debug ile adım adım inceleyin. Anonim erişim testi için anonymous: true. Yanıt 'headers' alanında platformun döndüğü header'ları taşır (küçük harf; ör. headers['total-count'] — sayfalı tablo akışlarının okuduğu sözleşme; set-cookie/authorization elenir).",
         inputSchema: executeInput,
         annotations: writes
-    }, handle(config, async ({ project, environment, application, microservice, method, routeParams, query, body, headers, anonymous, asUser, cookies, language }) => {
+    }, handle(config, async ({ project, environment, application, microservice, method, routeParams, query, body, parameters, headers, anonymous, asUser, cookies, language }) => {
         const notes = [];
         const requestHeaders = { ...runIdentity(anonymous, asUser, cookies, headers), ...languageHeader(language, notes) };
-        return withNormalization(await platform.tenantRaw(method, project, executePath('m', application, microservice, routeParams), { environment, query, body, headers: requestHeaders, anonymous, mirrorAuthorizationCookie: true }), notes);
+        const bound = bindCallParameters(method, parameters, query, body, notes);
+        return withNormalization(await platform.tenantRaw(method, project, executePath('m', application, microservice, routeParams), { environment, query: bound.query, body: bound.body, headers: requestHeaders, anonymous, mirrorAuthorizationCookie: true }), notes);
     }));
     server.registerTool('microservice_debug', {
         title: 'Microservice debug',
-        description: "Microservice'i debug modunda çalıştırır; yanıtta adım adım executionItems ağacı döner (her adımın girdi/çıktısı). executionItems YALNIZ ucun kendi adımlarını kapsar — ucun ÖNÜNDE koşan middleware'ler ayrıca 'middlewares' alanında adım özetiyle listelenir (09-04 Y-04).",
+        description: "Microservice'i debug modunda çalıştırır; yanıtta adım adım executionItems ağacı döner (her adımın girdi/çıktısı). executionItems YALNIZ ucun kendi adımlarını kapsar — ucun ÖNÜNDE koşan middleware'ler ayrıca 'middlewares' alanında adım özetiyle listelenir (09-04 Y-04). Değeri NULL bağlanan query parametreleri 'unboundParameters' alanında adıyla listelenir (ağaçta bu satırların value anahtarı görünmez). Preview semantiğiyle koşar: tek transaction + sonunda rollback, kalıcı satır yazmaz. httpStatus akışın kendi sonucudur (4xx/5xx'te runtimeErrors eklenir); ağaç düğümlerinde hata bayrağı YOKTUR — patlayan adımın output'u boştur, hata gövdesi hata dalındaki response adımının çıktısındadır. Zamanlanmış (schedule-job) uçlar da slug yoluyla debug edilir (method: 'POST', parametresiz): job geçmişi hatayı yalnız mesaj olarak yazar, adım adım girdi/çıktı burada görülür (platform_guide('microservice') §Zamanlanmış işin gerçek sonucunu görmek).",
         inputSchema: executeInput,
         annotations: writes
-    }, handle(config, async ({ project, environment, application, microservice, method, routeParams, query, body, headers, anonymous, asUser, cookies, language }) => {
+    }, handle(config, async ({ project, environment, application, microservice, method, routeParams, query, body, parameters, headers, anonymous, asUser, cookies, language }) => {
         const notes = [];
         const requestHeaders = { ...runIdentity(anonymous, asUser, cookies, headers), ...languageHeader(language, notes) };
-        const payload = await platform.tenantRaw(method, project, executePath('debug', application, microservice, routeParams), { environment, query, body, headers: requestHeaders, anonymous, mirrorAuthorizationCookie: true });
-        return withNormalization({ ...payload, ...await middlewareChain(platform, project, environment, application, microservice, payload?.httpStatus) }, notes);
+        const bound = bindCallParameters(method, parameters, query, body, notes);
+        const payload = await platform.tenantRaw(method, project, executePath('debug', application, microservice, routeParams), { environment, query: bound.query, body: bound.body, headers: requestHeaders, anonymous, mirrorAuthorizationCookie: true });
+        const unbound = unboundQueryParameters(payload.body);
+        return withNormalization({
+            ...payload,
+            ...(unbound.length > 0
+                ? {
+                    unboundParameters: unbound,
+                    unboundParametersNote: "Bu query parametreleri NULL bağlandı: çağrıda yoklar ya da değerleri boş string'di (platform boş string'i NULL'a çevirir). Parametreyi 'parameters' (ya da GET'te 'query', POST/PUT'ta 'body') ile verin; ad sorgunun parametre adıyla birebir aynı olmalı."
+                }
+                : {}),
+            ...await middlewareChain(platform, project, environment, application, microservice, payload.httpStatus)
+        }, notes);
     }));
     server.registerTool('microservice_preview', {
         title: 'Microservice önizle',
-        description: "Microservice tanımını çalıştırır: kaydedilmemiş gövde için definition, KAYITLI bir uç için yalnız id verin (gateway tanımı kendisi çeker — tam gövdeyi bağlama almanız gerekmez). previewParameters ayrı alandır ve ikisiyle de çalışır. Preview tek transaction'da koşar ve sonunda ROLLBACK edilir — kalıcı satır yazmaz; code step'teki dış HTTP çağrıları istisnadır. Davranış kuralları: platform_guide('microservice').",
+        description: "Microservice tanımını çalıştırır: kaydedilmemiş gövde için definition, KAYITLI bir uç için yalnız id verin (gateway tanımı kendisi çeker — tam gövdeyi bağlama almanız gerekmez). previewParameters ayrı alandır ve ikisiyle de çalışır. Preview tek transaction'da koşar ve sonunda ROLLBACK edilir — kalıcı satır yazmaz; code step'teki dış HTTP çağrıları istisnadır. Yanıt httpStatus (akışın KENDİ sonucu; 4xx/5xx'te gateway runtimeErrors ekler) + gövdeden ibarettir, adım ağacı DÖNMEZ — adım adım girdi/çıktı için microservice_debug, adım başına hata alanı için workflow_preview. Zamanlanmış (schedule-job) ucu id ile parametresiz önizleyin: zamanlanmış koşu da girdisiz koşar. Davranış kuralları: platform_guide('microservice').",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
@@ -383,7 +447,7 @@ export function registerMicroserviceTools(server, platform) {
     }));
     server.registerTool('microservice_job_history', {
         title: 'Job geçmişi',
-        description: 'Zamanlanmış (job tipli) microservice\'in çalışma geçmişini listeler. status ile yalnız running | completed | failed koşular süzülür; order TriggeredAt | CompletedAt | ExecutionStatus | DurationMs.',
+        description: "Zamanlanmış (schedule-job) microservice'in çalışma geçmişini listeler: satır başına { status: running | completed | failed, triggeredAt, completedAt, durationMs, errorMessage }. failed satırın errorMessage'ı patlayan adımı ve sebebini taşır: bağlanmamış fail dalında \"Step 'x' failed: <sebep>\", bağlı global-error dalıyla 2xx dışı sonuçta \"The job's workflow returned 500 (<code>): <mesaj>\"; iki durumda da yazmalar geri alınmıştır (2026-09-16 öncesi imajlar bu ikisini completed yazardı). completed = akış 2xx ile bitti ve yazmalar commit edildi. Adım adım girdi/çıktı burada YOK: aynı akışı workflow_preview (adım başına hata alanı) ya da microservice_debug (executionItems) ile koşturun — platform_guide('microservice') §Zamanlanmış işin gerçek sonucunu görmek. status ile yalnız running | completed | failed koşular süzülür; order TriggeredAt | CompletedAt | ExecutionStatus | DurationMs.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
@@ -395,7 +459,7 @@ export function registerMicroserviceTools(server, platform) {
     }, handle(config, ({ project, environment, id, ...query }) => platform.tenant('GET', project, `/microservices/${id}/job-history`, { environment, query })));
     server.registerTool('microservice_schedule_get', {
         title: 'Zamanlama durumu',
-        description: 'Zamanlanmış (schedule-job) microservice\'in canlı zamanlama durumunu döner: state (scheduled | paused | notScheduled | error | ended), isRunning, nextFireTimeUtc, previousFireTimeUtc, sıradaki 5 koşu (upcomingFireTimesUtc), cron + timeZoneId, serverTimeUtc ve son koşunun özeti (lastExecution). "Bir sonraki sefer ne zaman koşacak?" sorusunu cron\'u yorumlamadan buradan cevaplayın. paused iken nextFireTimeUtc null ve upcoming boştur. notScheduled: kayıt var ama zamanlayıcıda trigger yok — en geç 5 dk içinde uzlaştırma kurar ya da servisi kaydedin (microservice_update). ended: tanımın sonraki koşusu yok (once geçti, end on/after doldu). schedule alanı tanımın kendisidir. Schedule tipli olmayan servis 400 döner.',
+        description: 'Zamanlanmış (schedule-job) microservice\'in canlı zamanlama durumunu döner: state (scheduled | paused | notScheduled | error | ended), isRunning, nextFireTimeUtc, previousFireTimeUtc, sıradaki 5 koşu (upcomingFireTimesUtc), cron + timeZoneId, serverTimeUtc ve son koşunun özeti (lastExecution — geçmiş satırının aynısı: failed ise errorMessage patlayan adımı ve sebebini taşır; bkz. microservice_job_history). "Bir sonraki sefer ne zaman koşacak?" sorusunu cron\'u yorumlamadan buradan cevaplayın. paused iken nextFireTimeUtc null ve upcoming boştur. notScheduled: kayıt var ama zamanlayıcıda trigger yok — en geç 5 dk içinde uzlaştırma kurar ya da servisi kaydedin (microservice_update). ended: tanımın sonraki koşusu yok (once geçti, end on/after doldu). schedule alanı tanımın kendisidir. Schedule tipli olmayan servis 400 döner.',
         inputSchema: { project: projectParam, environment: environmentParam, id: guid },
         annotations: readOnly
     }, handle(config, ({ project, environment, id }) => platform.tenant('GET', project, `/microservices/${id}/schedule`, { environment })));
@@ -411,7 +475,7 @@ export function registerMicroserviceTools(server, platform) {
     }, handle(config, ({ project, environment, schedule }) => platform.tenant('POST', project, '/microservices/schedule/preview', { environment, body: { schedule } })));
     server.registerTool('microservice_schedule_control', {
         title: 'Zamanlamayı yönet',
-        description: 'Zamanlanmış microservice\'i duraklatır (pause), sürdürür (resume) ya da cron\'u beklemeden bir kez koşturur (trigger). pause/resume yalnız zamanlayıcıdaki durumu değiştirir, tanımı değil; duraklatma cron güncellemesi ve deployment senkronundan sonra da korunur. resume: duraklatılmışken bir koşu kaçırıldıysa iş bir kez hemen koşar. trigger KUYRUĞA ALIR, sonucu beklemez: deployment ya da template kurulumu sürüyorsa koşu veto edilir ve geçmişe hiç düşmez — sonucu microservice_job_history ile doğrulayın. Zamanlayıcıda kaydı olmayan iş 400 (ScheduleJobNotRegisteredException) döner. Production ortamında üç eylem de 400 CantWriteInProductionException ile reddedilir; trigger ayrıca deployment/template kurulumu sürerken reddedilir.',
+        description: 'Zamanlanmış microservice\'i duraklatır (pause), sürdürür (resume) ya da cron\'u beklemeden bir kez koşturur (trigger). pause/resume yalnız zamanlayıcıdaki durumu değiştirir, tanımı değil; duraklatma cron güncellemesi ve deployment senkronundan sonra da korunur. resume: duraklatılmışken bir koşu kaçırıldıysa iş bir kez hemen koşar. trigger KUYRUĞA ALIR, sonucu beklemez: deployment ya da template kurulumu sürüyorsa koşu veto edilir ve geçmişe hiç düşmez — sonucu microservice_job_history ile doğrulayın. Geçmiş failed satırında patlayan adımı ve sebebini yazar ama adım izi vermez; tetiklemeden ÖNCE akışı workflow_preview / microservice_debug ile koşturun. Zamanlayıcıda kaydı olmayan iş 400 (ScheduleJobNotRegisteredException) döner. Production ortamında üç eylem de 400 CantWriteInProductionException ile reddedilir; trigger ayrıca deployment/template kurulumu sürerken reddedilir.',
         inputSchema: {
             project: projectParam,
             environment: environmentParam,