@appaflytech/zeyrek-ai-mcp 0.0.1

package/dist/tools/workflows.js

@@ -0,0 +1,196 @@
+import { guid, projectParam, environmentParam, definitionParam, pagingParams, readOnly, writes, updates, destructive } from './common.js';
+import { normalizeWorkflowDefinition, withNormalization } from '../knowledge/normalize.js';
+import { evaluatePolicy, enforcePolicy, attachFindings } from '../knowledge/policy.js';
+import { workflowOutline, resolvePart, resolvePatchOperations } from '../knowledge/outlines.js';
+import { policyRules } from '../knowledge/rules.js';
+import { handle } from '../platform/responses.js';
+import fastJsonPatch from 'fast-json-patch';
+import { z } from 'zod';
+const policyOverrideParam = z.boolean().optional()
+    .describe('true: politika block bulgularını warn\'a indirir (bilinçli istisna; yanıtta işaretlenir)');
+const patchOperationsParam = z.array(z.record(z.unknown())).min(1)
+    .describe("RFC 6902 JSON Patch işlemleri. Step hedeflerken İNDEKS YERİNE SEÇİCİ kullanın: { op: 'replace', path: '/steps[id=<stepId>]/rule/expression', value: '…' } — saklanan steps sırası gönderdiğiniz sıra DEĞİLDİR, indeks yolu sessizce başka adımı yazar. Seçici gövde platforma gitmeden indekse çevrilir; çözülemezse istek hiç gönderilmez. '/steps[name=setUser]/rule/joins' ve düz '/steps/2/...' de kabul edilir; yanıt her op'un hangi adıma indiğini patchTargets ile döner.");
+/**
+ * Platform `set-user` step'i için `StepRule.Name`'i BOŞ döndürür (adı sabit: 'user') ve DTO
+ * bağlanmamışsa `Schema` de null olur — yanıt yalnız `{ stepId }` olarak gelir ve tool'un varlık
+ * sebebi olan "adı tahmin etme, buradan oku" tavsiyesi işlemez (crm koşumu B-6). Eksik adları
+ * middleware tanımlarından tamamlıyoruz: stepId ↔ step.id eşleşmesi
+ * (WorkflowRepository.FindMiddlewareVariablesAsync → MiddlewareVariableModel(.., StepRule.StepId)).
+ */
+async function enrichMiddlewareVariables(platform, project, environment, applicationId, entries) {
+    const stepsById = new Map();
+    try {
+        const list = await platform.tenant('GET', project, `/workflows/${applicationId}`, {
+            environment,
+            query: { type: 'middleware', pageLength: 100 }
+        });
+        for (const middleware of (list?.data ?? []).slice(0, 20)) {
+            const detail = await platform.tenant('GET', project, `/workflows/${applicationId}/${String(middleware.id)}`, { environment });
+            const definition = (detail?.data ?? detail);
+            for (const step of (Array.isArray(definition.steps) ? definition.steps : [])) {
+                if (!step || typeof step !== 'object')
+                    continue;
+                const record = step;
+                const rule = (record.rule ?? {});
+                const type = String(record.type ?? '');
+                if (type !== 'set-user' && type !== 'variable')
+                    continue;
+                stepsById.set(String(record.id ?? ''), {
+                    name: type === 'set-user' ? 'user' : String(rule.name ?? record.name ?? '?'),
+                    type,
+                    workflowId: String(definition.id ?? middleware.id ?? ''),
+                    workflowName: String(definition.name ?? middleware.name ?? '?')
+                });
+            }
+        }
+    }
+    catch {
+        return entries;
+    }
+    // Gateway yanıtta null alan taşımaz (responses.prune) — şemanın YOKLUĞU bu yüzden not olarak söylenir.
+    const missingSchemaNote = "Bu step'e DTO bağlı değil; platform şema (alan listesi) döndüremez — yalnız değişken ADI kesin. Alanları sözleşmeye bağlamak için step'in rule.dataTransferObjectId'sini doldurun.";
+    return entries.map(entry => {
+        const resolved = stepsById.get(String(entry.stepId ?? ''));
+        if (!resolved)
+            return entry.schema ? entry : { ...entry, note: missingSchemaNote };
+        return {
+            ...entry,
+            name: typeof entry.name === 'string' && entry.name !== '' ? entry.name : resolved.name,
+            stepType: resolved.type,
+            middlewareId: resolved.workflowId,
+            middlewareName: resolved.workflowName,
+            ...(entry.schema ? {} : { note: missingSchemaNote })
+        };
+    });
+}
+export function registerWorkflowTools(server, platform) {
+    const config = platform.config;
+    server.registerTool('workflow_list', {
+        title: 'Workflow listele',
+        description: 'Application altındaki workflow\'ları listeler.',
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            searchTerm: z.string().optional(),
+            type: z.string().optional().describe('workflow | middleware | automation'),
+            entityId: guid.optional(),
+            isDefault: z.boolean().optional(),
+            ...pagingParams
+        },
+        annotations: readOnly
+    }, handle(config, ({ project, environment, applicationId, ...query }) => platform.tenant('GET', project, `/workflows/${applicationId}`, { environment, query })));
+    server.registerTool('workflow_get', {
+        title: 'Workflow getir',
+        description: "Workflow'u getirir. Büyük workflow'da önce view:'outline' (step+branch grafı), sonra view:'part' ile tek parça çekin; full gövdeyi bağlama almak son çaredir.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            id: guid,
+            view: z.enum(['full', 'outline', 'part']).optional().describe('varsayılan full'),
+            part: z.string().optional().describe("view:'part' için yol, ör. steps[id=abc] veya steps[2].rule")
+        },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, applicationId, id, view, part }) => {
+        const payload = await platform.tenant('GET', project, `/workflows/${applicationId}/${id}`, { environment });
+        const definition = (payload?.data ?? payload);
+        if (view === 'outline')
+            return workflowOutline(definition);
+        if (view === 'part') {
+            if (!part)
+                throw new Error("view:'part' için 'part' parametresi zorunlu.");
+            return { part, value: resolvePart(definition, part) };
+        }
+        return payload;
+    }));
+    server.registerTool('workflow_create', {
+        title: 'Workflow oluştur',
+        description: "Yeni workflow tanımlar (definition = CreateWorkflowCommand). type: 'workflow' | 'automation' | 'middleware'. İlk kullanımdan önce platform_guide('workflow') okuyun: DTO-önce akışı, branch bağlama (branches[].nextStepId), tip×step matrisi. Middleware (istek öncesi koşan guard/setter, user değişkeni, alfabetik sıra) için platform_guide('middleware') + ngapps://examples/middleware-authenticate. Gövde politika kontrolünden geçer.",
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, definition: definitionParam, policyOverride: policyOverrideParam },
+        annotations: writes
+    }, handle(config, async ({ project, environment, applicationId, definition, policyOverride }) => {
+        const normalized = normalizeWorkflowDefinition(definition);
+        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'create', workflowKind: definition.type }, policyOverride));
+        const payload = await platform.tenant('POST', project, `/workflows/${applicationId}`, { environment, body: definition });
+        return attachFindings(withNormalization(payload, normalized), findings);
+    }));
+    server.registerTool('workflow_update', {
+        title: 'Workflow güncelle',
+        description: 'Workflow tanımını günceller (definition = UpdateWorkflowCommand, tam gövde). Hedefli değişiklik için workflow_patch tercih edin. Gövde politika kontrolünden geçer.',
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, id: guid, definition: definitionParam, policyOverride: policyOverrideParam },
+        annotations: updates
+    }, handle(config, async ({ project, environment, applicationId, id, definition, policyOverride }) => {
+        const normalized = normalizeWorkflowDefinition(definition);
+        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'update', workflowKind: definition.type }, policyOverride));
+        const payload = await platform.tenant('PUT', project, `/workflows/${applicationId}/${id}`, { environment, body: definition });
+        return attachFindings(withNormalization(payload, normalized), findings);
+    }));
+    server.registerTool('workflow_patch', {
+        title: 'Workflow\'a patch uygula',
+        description: 'Tam gövdeyi bağlama almadan hedefli değişiklik: gateway mevcut workflow\'u çeker, JSON Patch işlemlerini uygular, politika kontrolünden geçirir, tam gövdeyi geri yazar. Yanıt outline özetidir.',
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, id: guid, operations: patchOperationsParam, policyOverride: policyOverrideParam },
+        annotations: updates
+    }, handle(config, async ({ project, environment, applicationId, id, operations, policyOverride }) => {
+        const current = await platform.tenant('GET', project, `/workflows/${applicationId}/${id}`, { environment });
+        const definition = structuredClone((current?.data ?? current));
+        const resolved = resolvePatchOperations(definition, operations);
+        const patched = fastJsonPatch.applyPatch(definition, resolved.operations, true, false).newDocument;
+        const normalized = normalizeWorkflowDefinition(patched);
+        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'workflow', patched, { operation: 'update', workflowKind: patched.type }, policyOverride));
+        await platform.tenant('PUT', project, `/workflows/${applicationId}/${id}`, { environment, body: patched });
+        return attachFindings(withNormalization({
+            applied: operations.length,
+            patchTargets: resolved.targets,
+            outline: workflowOutline(patched)
+        }, [...normalized, ...resolved.notes.map(note => `patch yolu seçiciden indekse çözüldü: ${note}`)]), findings);
+    }));
+    server.registerTool('workflow_delete', {
+        title: 'Workflow sil',
+        description: 'Workflow\'u siler; önce workflow_dependencies ile bağımlılıklarını kontrol edin.',
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, id: guid },
+        annotations: destructive
+    }, handle(config, ({ project, environment, applicationId, id }) => platform.tenant('DELETE', project, `/workflows/${applicationId}/${id}`, { environment })));
+    server.registerTool('workflow_clone', {
+        title: 'Workflow klonla',
+        description: 'Workflow\'un kopyasını oluşturur.',
+        inputSchema: { project: projectParam, environment: environmentParam, id: guid },
+        annotations: writes
+    }, handle(config, ({ project, environment, id }) => platform.tenant('POST', project, `/workflows/clone/${id}`, { environment })));
+    server.registerTool('workflow_preview', {
+        title: 'Workflow önizle',
+        description: "Kaydedilmemiş workflow tanımını çalıştırır; kaydetmeden önce her akışı preview ile doğrulayın. definition = PreviewWorkflowCommand gövdesi. Test girdisi 'previewPayload' anahtarıyla verilir ('parameters'/'input' ÇALIŞMAZ), değişkenler 'previewVariables'. previewPayload STRING olmalıdır (JSON.stringify(...) ya da \"({ id: 1 })\") — nesne gönderilirse platform 'Unexpected end of input' ile 500 döner. Preview kuru çalıştırma değildir: table create/update step'leri kalıcı satır yazar.",
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, definition: definitionParam, policyOverride: policyOverrideParam },
+        annotations: writes
+    }, handle(config, async ({ project, environment, applicationId, definition, policyOverride }) => {
+        const normalized = normalizeWorkflowDefinition(definition);
+        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'preview', workflowKind: definition.type }, policyOverride));
+        const payload = await platform.tenant('POST', project, `/workflows/${applicationId}/preview`, { environment, body: definition });
+        return attachFindings(withNormalization(payload, normalized), findings);
+    }));
+    server.registerTool('workflow_step_schema', {
+        title: 'Step şeması üret',
+        description: 'Verilen step tanımı için çıktı şemasını üretir; step yazarken definition\'ı doğrulamanın en hızlı yolu.',
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, id: guid, step: definitionParam },
+        annotations: readOnly
+    }, handle(config, ({ project, environment, applicationId, id, step }) => platform.tenant('POST', project, `/workflows/${applicationId}/${id}/steps/schema`, { environment, body: step })));
+    server.registerTool('workflow_middleware_variables', {
+        title: 'Middleware değişkenleri',
+        description: "Application'ın middleware'lerinin kurduğu değişkenleri listeler (set-user → 'user', variable step'leri → rule.name adları) ve DTO bağlıysa şemasıyla birlikte döner. Expression'da (filtre value:'user.id', step ifadeleri) kullanılacak değişken adı/alanı TAHMİN EDİLMEZ — buradan okunur. DTO bağlanmamış step'lerde platform yalnız stepId döndürdüğü için gateway adı/tipi middleware tanımından tamamlar (schema: null olur). Ayrıntı: platform_guide('middleware').",
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, applicationId }) => {
+        const payload = await platform.tenant('GET', project, `/workflows/${applicationId}/variables`, { environment });
+        const entries = (Array.isArray(payload?.data) ? payload.data : [])
+            .filter((entry) => Boolean(entry) && typeof entry === 'object');
+        if (entries.length === 0 || entries.every(entry => typeof entry.name === 'string' && entry.name !== ''))
+            return payload;
+        return { ...payload, data: await enrichMiddlewareVariables(platform, project, environment, applicationId, entries) };
+    }));
+    server.registerTool('workflow_dependencies', {
+        title: 'Workflow bağımlılıkları',
+        description: 'Workflow\'a bağımlı kayıtların grafiğini döner.',
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, id: guid },
+        annotations: readOnly
+    }, handle(config, ({ project, environment, applicationId, id }) => platform.tenant('GET', project, `/workflows/${applicationId}/${id}/dependencies`, { environment })));
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@appaflytech/zeyrek-ai-mcp",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "MCP gateway exposing the NgApps platform APIs as tools",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "zeyrek-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    ".env.example",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "start:stdio": "tsx src/index.ts --stdio",
+    "build": "tsc -p tsconfig.build.json && tsx scripts/copy-assets.ts",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "generate-schemas": "tsx scripts/generate-schemas.ts",
+    "generate-reserved-tables": "tsx scripts/generate-reserved-tables.ts",
+    "harvest-examples": "tsx scripts/harvest-examples.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.0",
+    "fast-json-patch": "^3.1.1",
+    "pino": "^9.5.0",
+    "undici": "^7.3.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}