systa-mcp 1.0.0

package/server.js

@@ -0,0 +1,2226 @@
+#!/usr/bin/env node
+
+'use strict';
+
+/**
+ * SysTa MCP Server (SysTa CLI — Faz 4)
+ *
+ * Bir Model Context Protocol (MCP) stdio sunucusu. Claude gibi AI ajanlarinin
+ * SysTa REST API'sini scoped bir API anahtariyla "arac" olarak kullanmasini
+ * saglar. Native Node + JSON-RPC 2.0 (stdio, newline-delimited) — SUPPLY-CHAIN
+ * yuzeyini sifirda tutmak icin HICBIR npm bagimliligi yok (Node 18+ global fetch).
+ *
+ * Yetki modeli: Tum scope/izin zorlamasi SUNUCU TARAFINDADIR. MCP yalnizca
+ * Authorization: Bearer <key> + X-Vendor-Code basliklariyla istegi proxy'ler;
+ * anahtarin kapsami disindaki cagrilar backend tarafindan 403 ile reddedilir.
+ *
+ * Konfigurasyon (env):
+ *   SYSTA_API_BASE_URL   Orn: http://vizyoneks.localhost:3000/api
+ *   SYSTA_API_KEY        sk_live_... — anahtarin KENDISI vendor'i belirler (backend key'den cozer)
+ *   SYSTA_VENDOR_CODE    OPSIYONEL: X-Vendor-Code header'i. Verilirse anahtarin vendor'iyla AYNI
+ *                        olmali (farkliysa 403). Bos birak -> backend vendor'i key'den turetir.
+ *
+ * @module mcp-server/server
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_NAME = 'systa-mcp';
+const SERVER_VERSION = '1.0.0';
+
+// Server-seviye rehber — her oturumda AI ajanin context'ine girer (kisa tutulur).
+// Ajana SysTa'yi nasil kesfedip kullanacagini ogretir; detay lazy araclardadir.
+const INSTRUCTIONS = [
+  'SysTa (Talep Takip Sistemi) REST API — scoped bir API anahtariyla baglisin.',
+  '',
+  'KESIF (onemli): Bu anahtarin GERCEKTE neler yapabilecegi, sahip oldugu izinlerle',
+  'sinirlidir. Gordugun ARAÇ LISTESI de bu anahtarin kapsamina gore filtrelenmistir —',
+  'kapsam disi araclar listede yer almaz; listede gorundugu halde kapsam disi kalan bir',
+  'cagri yine de sunucu tarafinda 403 doner. Bir isi yapmadan ONCE:',
+  '  1) `list_capabilities` cagir — anahtarin erisebildigi modul/endpoint katalogunu',
+  '     (scope-filtreli) gorursun. Yetkisiz endpoint listede GORUNMEZ. Yanit AYRICA SysTa',
+  '     platform OZETI (overview), TR GLOSSARY ve her modulun ACIKLAMASINI (description/',
+  '     concepts) icerir — kullanicinin dogal dilini (talep/gorev/efor/pano/durum/atanan...)',
+  '     bunlarla dogru modul ve endpoint ile eslestir.',
+  '  2) `describe_module(module)` (opsiyonel) — bir modulun (orn. request/kanban/plan) amacini,',
+  '     kavramlarini ve cagirabilecegin endpointleri topluca gorursun.',
+  '  3) `describe_endpoint(path, method)` cagir — o endpoint için alan tiplerini (fields),',
+  '     guvenlik sinifini ve aciklamayi al; sonra cagri govdesini buna gore kur.',
+  '',
+  'GUVENLIK SINIFI (safetyClass): read_only (guvenli okuma) | idempotent (tekrarlanabilir)',
+  '  | mutating (durum degistirir) | destructive (geri-alinamaz — dikkatli ol, gerekirse onayla).',
+  '',
+  'SCOPE: anahtar izinleri permission_key namespace iledir (orn request.read). Wildcard',
+  "  '*' / 'domain.*' GUVENLI varsayilanla YIKICI suffix'leri (.delete/.purge/.wipe/.destroy/",
+  '  .truncate/.revoke/.deactivate/.remove) KAPSAMAZ — silme yalniz acik izinle verilir.',
+  '  Kapsam disi cagri sunucu tarafinda 403 doner. API anahtari KENDISI yeni anahtar',
+  '  uretemez/yonetemez (anahtar yonetimi insan oturumu gerektirir -> 403). Bir endpoint',
+  '  katalogda YOKSA: ya gercekten yok ya da bu anahtarin kapsami disinda — varlik',
+  '  varsayma, emin degilsen kullaniciya/anahtar sahibine sor.',
+  '',
+  'ARACLAR: list_requests (zengin filtre: status/assignee/company/category/department/priority) /',
+  '  get_request / list_projects / create_request / add_request_comment / change_request_status',
+  '  (durum degistir/tamamla/kapat + opsiyonel yorum) ozel araclardir.',
+  '  "talep ac" niyetinde ONCE prepare_create_request(companyId) cagir — aktif formun zorunlu',
+  '  alanlarini + gecerli id secenekleri (status/kategori/organizasyon) doner, 400 roundtrip onlenir;',
+  '  kanban (get_request_board/manage_request_card/move_request_card), onay (request_approval/',
+  '  respond_to_approval/list_pending_approvals), proje (create_project/get_project/update_project)',
+  '  ve dosya ekleri (download_request_file / upload_file_to) ozel araclardir — `systa_api_call` JSON-only oldugundan',
+  '  binary tasiyamaz; diger her endpoint icin `systa_api_call` (method+path) kullan — path ve',
+  '  govdeyi describe_endpoint ciktisindan kur.',
+].join('\n');
+
+const BASE_URL = (process.env.SYSTA_API_BASE_URL || '').replace(/\/+$/, '');
+const API_KEY = process.env.SYSTA_API_KEY || '';
+const VENDOR_CODE = process.env.SYSTA_VENDOR_CODE || '';
+
+const ALLOWED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+
+// Diagnostics MUST go to stderr — stdout is the JSON-RPC channel.
+const logErr = (message) => process.stderr.write(`[${SERVER_NAME}] ${message}\n`);
+
+// ── HTTP proxy to SysTa ──────────────────────────────────────────────────────
+/**
+ * Proxy a request to the SysTa REST API with the configured API key + vendor.
+ * @param {string} method
+ * @param {string} path - Path relative to SYSTA_API_BASE_URL, must start with '/'
+ * @param {{query?:Object, body?:*}} [opts]
+ * @returns {Promise<{status:number, ok:boolean, data:*}>}
+ */
+const systaFetch = async (method, path, opts = {}) => {
+  if (!BASE_URL) {
+    throw new Error('SYSTA_API_BASE_URL is not configured');
+  }
+  if (!API_KEY) {
+    throw new Error('SYSTA_API_KEY is not configured');
+  }
+  const url = new URL(BASE_URL + path);
+  if (opts.query) {
+    for (const [key, value] of Object.entries(opts.query)) {
+      if (value !== undefined && value !== null && value !== '') {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  const headers = {
+    Authorization: `Bearer ${API_KEY}`,
+    Accept: 'application/json',
+  };
+  if (VENDOR_CODE) {
+    headers['X-Vendor-Code'] = VENDOR_CODE;
+  }
+  const init = { method, headers };
+  if (opts.body !== undefined && opts.body !== null) {
+    headers['Content-Type'] = 'application/json';
+    init.body = JSON.stringify(opts.body);
+  }
+
+  const response = await fetch(url, init);
+  const text = await response.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+  return { status: response.status, ok: response.ok, data };
+};
+
+// ── Dosya araclari yardimcilari ──────────────────────────────────────────────
+// Backend fileSecurityMiddleware ALLOWED_FILE_TYPES allowlist'inin aynasi —
+// multipart part Content-Type'i uzantiyla eslesmezse sunucu yuklemeyi reddeder.
+const EXT_MIME = {
+  pdf: 'application/pdf',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  json: 'application/json',
+  xml: 'application/xml',
+  txt: 'text/plain',
+  csv: 'text/csv',
+  log: 'text/plain',
+  yaml: 'text/yaml',
+  yml: 'text/yaml',
+  zip: 'application/zip',
+};
+
+const mimeForFileName = (fileName) => {
+  const ext = path
+    .extname(String(fileName || ''))
+    .slice(1)
+    .toLowerCase();
+  return EXT_MIME[ext] || 'application/octet-stream';
+};
+
+/** Content-Disposition basligindan dosya adini cozer (RFC 5987 filename* oncelikli). */
+const parseContentDispositionFilename = (header) => {
+  if (!header) {
+    return null;
+  }
+  const star = /filename\*\s*=\s*utf-8''([^;]+)/i.exec(header);
+  if (star) {
+    try {
+      return decodeURIComponent(star[1].trim());
+    } catch {
+      // bozuk encoding — duz filename= varyantina dus
+    }
+  }
+  const plain = /filename\s*=\s*"([^"]+)"/.exec(header) || /filename\s*=\s*([^;]+)/.exec(header);
+  return plain ? plain[1].trim() : null;
+};
+
+/** Sunucudan gelen dosya adini path bilesenlerinden arindirir (path traversal koruma). */
+const sanitizeFileName = (name, fallback) => {
+  // Hem '/' hem '\' separator sayilir (POSIX path.basename backslash'i ayirmaz).
+  const segments = String(name || '')
+    .replace(/\0/g, '')
+    .split(/[\\/]/);
+  const base = segments[segments.length - 1].trim();
+  if (!base || base === '.' || base === '..') {
+    return fallback;
+  }
+  if (base.length > 255) {
+    const ext = path.extname(base);
+    return base.slice(0, 255 - ext.length) + ext;
+  }
+  return base;
+};
+
+/** Hedef yerel yolu cozer: yoksa temp dizin, mevcut dizinse icine, degilse tam yol. */
+const resolveSavePath = (fileName, savePath) => {
+  if (!savePath) {
+    const dir = path.join(os.tmpdir(), 'systa-mcp-downloads');
+    fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, fileName);
+  }
+  const resolved = path.resolve(String(savePath));
+  if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+    return path.join(resolved, fileName);
+  }
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  return resolved;
+};
+
+// RAM korumasi — tipik ek dosyalarinin cok ustunde bir tavan.
+const MAX_DOWNLOAD_BYTES = 500 * 1024 * 1024;
+
+/**
+ * Binary indirme: download endpoint'i ya dosyayi stream eder ya S3'e redirect eder
+ * (fetch redirect'i takip eder; undici cross-origin'de Authorization'i dusurur —
+ * presigned URL zaten auth istemez). Hata yanitlari (4xx/5xx) JSON envelope'tur.
+ */
+const systaFetchBinary = async (apiPath) => {
+  if (!BASE_URL) {
+    throw new Error('SYSTA_API_BASE_URL is not configured');
+  }
+  if (!API_KEY) {
+    throw new Error('SYSTA_API_KEY is not configured');
+  }
+  const headers = { Authorization: `Bearer ${API_KEY}` };
+  if (VENDOR_CODE) {
+    headers['X-Vendor-Code'] = VENDOR_CODE;
+  }
+  const response = await fetch(new URL(BASE_URL + apiPath), { method: 'GET', headers });
+  if (!response.ok) {
+    const text = await response.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = text;
+    }
+    return { status: response.status, ok: false, data };
+  }
+  const length = Number(response.headers.get('content-length') || 0);
+  if (length > MAX_DOWNLOAD_BYTES) {
+    return {
+      status: response.status,
+      ok: false,
+      data: { error: `File too large for MCP download (${length} bytes)` },
+    };
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  return {
+    status: response.status,
+    ok: true,
+    buffer,
+    mimeType: response.headers.get('content-type') || 'application/octet-stream',
+    fileName: parseContentDispositionFilename(response.headers.get('content-disposition')),
+  };
+};
+
+/** Multipart yukleme — native FormData/Blob (Node 18+), alan adi backend'le ayni: 'file'. */
+const systaUploadMultipart = async (apiPath, method, filePaths) => {
+  if (!BASE_URL) {
+    throw new Error('SYSTA_API_BASE_URL is not configured');
+  }
+  if (!API_KEY) {
+    throw new Error('SYSTA_API_KEY is not configured');
+  }
+  const form = new FormData();
+  for (const localPath of filePaths) {
+    const resolved = path.resolve(String(localPath));
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+      throw new Error(`Local file not found: ${resolved}`);
+    }
+    const fileName = path.basename(resolved);
+    const buffer = fs.readFileSync(resolved);
+    form.append('file', new Blob([buffer], { type: mimeForFileName(fileName) }), fileName);
+  }
+  const headers = { Authorization: `Bearer ${API_KEY}`, Accept: 'application/json' };
+  if (VENDOR_CODE) {
+    headers['X-Vendor-Code'] = VENDOR_CODE;
+  }
+  // Content-Type'i fetch kendisi kurar (multipart boundary dahil) — elle set etme.
+  const response = await fetch(new URL(BASE_URL + apiPath), { method, headers, body: form });
+  const text = await response.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+  return { status: response.status, ok: response.ok, data };
+};
+
+// ── Capability catalog helpers ───────────────────────────────────────────────
+/**
+ * Unwrap the SysTa API envelope ({success, data}) to the capabilities payload.
+ */
+const unwrapCapabilities = (res) =>
+  res && res.data && res.data.data ? res.data.data : res && res.data;
+
+/**
+ * Compact view of the capability catalog — drops field_schema/detail/scenario so
+ * the per-turn payload stays small (lazy: use describe_endpoint for full detail).
+ */
+const shapeCompact = (caps) => ({
+  sessionType: caps.sessionType,
+  // who-am-I: bu anahtarin sahibi olan kullanici. 'bana ata' / 'ben' -> user.id.
+  ...(caps.user ? { user: caps.user } : {}),
+  scopes: caps.scopes,
+  isSuperAdmin: caps.isSuperAdmin,
+  // Kavramsal oryantasyon (ai_orientation_catalog) — kod-kor ajan icin SysTa'yi
+  // anlama katmani: platform ozeti + TR glossary + modul aciklamalari.
+  ...(caps.overview ? { overview: caps.overview } : {}),
+  ...(caps.glossary ? { glossary: caps.glossary } : {}),
+  moduleCount: caps.moduleCount,
+  endpointCount: caps.endpointCount,
+  modules: (caps.modules || []).map((m) => ({
+    module: m.module,
+    ...(m.description ? { description: m.description } : {}),
+    ...(m.concepts ? { concepts: m.concepts } : {}),
+    endpoints: (m.endpoints || []).map((e) => ({
+      path: e.path,
+      summary: e.summary,
+      methods: (e.methods || []).map((mm) => ({
+        method: mm.method,
+        safetyClass: mm.safetyClass,
+        requiredPermission: mm.requiredPermission,
+        hasFields: Boolean(mm.fields),
+      })),
+    })),
+  })),
+});
+
+// ── Tool definitions ─────────────────────────────────────────────────────────
+const TOOLS = [
+  {
+    name: 'list_requests',
+    description:
+      'List/search SysTa requests (talepler) with pagination and rich filters: status, assignee, company, category, department, priority, free-text. "uzerimdeki isler / my open work" => assignedTo=<me> (resolve via list_capabilities user.id) + non-final statuses. Returns only requests the API key scope permits. For array/range filters beyond these, use systa_api_call GET /requests.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 100,
+          description: 'Page size (1-100, default 20)',
+        },
+        offset: { type: 'integer', minimum: 0, description: 'Pagination offset' },
+        search: { type: 'string', description: 'Free-text search' },
+        statusId: { type: 'integer', description: 'Filter by status id' },
+        assignedTo: {
+          type: 'integer',
+          description: 'Filter by assignee user id (use own id for "my work")',
+        },
+        companyId: { type: 'integer', description: 'Filter by company id' },
+        categoryId: { type: 'integer', description: 'Filter by category id' },
+        departmentId: { type: 'integer', description: 'Filter by department id' },
+        priority: { type: 'string', description: 'Filter by priority key/level' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', '/requests', {
+        query: {
+          limit: args.limit ?? 20,
+          offset: args.offset,
+          search: args.search,
+          statusId: args.statusId,
+          assignedTo: args.assignedTo,
+          companyId: args.companyId,
+          categoryId: args.categoryId,
+          departmentId: args.departmentId,
+          priority: args.priority,
+        },
+      }),
+  },
+  {
+    name: 'get_request',
+    description: 'Get a single SysTa request (talep) by its numeric id, including its details.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['id'],
+      properties: { id: { type: 'integer', description: 'Request id' } },
+    },
+    handler: (args) => systaFetch('GET', `/requests/${encodeURIComponent(args.id)}`),
+  },
+  {
+    name: 'list_projects',
+    description: 'List SysTa projects (projeler). Returns only projects the API key scope permits.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 100,
+          description: 'Page size (1-100, default 20)',
+        },
+        offset: { type: 'integer', minimum: 0, description: 'Pagination offset' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', '/projects', { query: { limit: args.limit ?? 20, offset: args.offset } }),
+  },
+  {
+    name: 'create_request',
+    description:
+      'Create a SysTa request (talep). Requires the "request.create" scope. Returns the created request under data.request. PROACTIVE (recommended): call prepare_create_request(companyId) FIRST -- it returns the active form\'s required fields AND valid ids (statuses/categories/organizations) so you fill them up front and avoid the 400 roundtrip. The required set is DYNAMIC: title/companyId/statusId are the baseline (+assignedTo for assignment), but this vendor\'s ACTIVE REQUEST FORM may require more system fields (e.g. categoryId, organizationId). If you skip prepare_, on a missing field the API returns 400 VALIDATION_FAILED naming it via details[].fieldKey -- add it and retry. For fields beyond this tool, use systa_api_call POST /requests.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['title', 'companyId', 'statusId', 'assignedTo'],
+      properties: {
+        title: { type: 'string', description: 'Request title' },
+        description: { type: 'string', description: 'Request description (plain text)' },
+        companyId: { type: 'integer', description: 'Target company id' },
+        statusId: { type: 'integer', description: 'Initial status id' },
+        assignedTo: {
+          type: 'integer',
+          description: 'Assignee user id (an assignment is required by SysTa)',
+        },
+        categoryId: {
+          type: 'integer',
+          description: 'Category id (optional, but the active request form may require it)',
+        },
+        organizationId: {
+          type: 'integer',
+          description:
+            'Organization-unit id (optional; may be required by the active form; must belong to companyId)',
+        },
+      },
+    },
+    handler: (args) =>
+      systaFetch('POST', '/requests', {
+        body: {
+          title: args.title,
+          description: args.description ?? '',
+          companyId: args.companyId,
+          statusId: args.statusId,
+          assignedTo: args.assignedTo,
+          ...(args.categoryId != null ? { categoryId: args.categoryId } : {}),
+          ...(args.organizationId != null ? { organizationId: args.organizationId } : {}),
+        },
+      }),
+  },
+  {
+    name: 'prepare_create_request',
+    description:
+      'Proactively fetch everything create_request needs for a company: the ACTIVE request form\'s required system fields PLUS valid id options (statuses, categories, organizations, departments). Call this FIRST whenever the user wants to "talep ac / open a request" so you fill categoryId/organizationId/statusId up front and avoid the 400 VALIDATION_FAILED roundtrip. Returns requiredFields[] and options{statusId,categoryId,organizationId,departmentId}. statusId options carry isFinal (true => a "tamamla/kapat" status). companyId is required (org/department options are scoped to it). A missing option list means that lookup is out of this key scope -- ask the user or use systa_api_call.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['companyId'],
+      properties: {
+        companyId: {
+          type: 'integer',
+          description: 'Target company id for the request (scopes organization/department options)',
+        },
+      },
+    },
+    handler: async (args) => {
+      const companyId = args.companyId;
+      const nameOf = (x) =>
+        x.name ??
+        x.statusName ??
+        x.categoryName ??
+        x.unitName ??
+        x.organizationName ??
+        x.departmentName ??
+        x.companyName ??
+        x.label ??
+        null;
+      const listOf = (res) => {
+        if (!res) {
+          return [];
+        }
+        const d = res.data && res.data.data !== undefined ? res.data.data : res.data;
+        if (Array.isArray(d)) {
+          return d;
+        }
+        if (d && Array.isArray(d.items)) {
+          return d.items;
+        }
+        for (const k of ['statuses', 'categories', 'organizations', 'departments']) {
+          if (d && Array.isArray(d[k])) {
+            return d[k];
+          }
+        }
+        return [];
+      };
+      const compact = (res, extra) =>
+        listOf(res)
+          .slice(0, 80)
+          .map((x) => {
+            const o = { id: x.id, name: nameOf(x) };
+            if (extra) {
+              extra(o, x);
+            }
+            return o;
+          });
+
+      // 1) Active request form -> required system fields
+      let requiredFields = [];
+      try {
+        const form = await systaFetch('GET', '/forms/request/active');
+        const fields = [];
+        (function walk(o) {
+          if (Array.isArray(o)) {
+            o.forEach(walk);
+            return;
+          }
+          if (o && typeof o === 'object') {
+            if (o.fieldKey) {
+              fields.push(o);
+            }
+            for (const v of Object.values(o)) {
+              walk(v);
+            }
+          }
+        })((form.data && form.data.data) || form.data);
+        requiredFields = fields
+          .filter((f) => f.isRequired)
+          .map((f) => ({
+            fieldKey: f.fieldKey,
+            type: f.fieldType || f.type || null,
+            isSystem: f.isSystem === true,
+          }));
+      } catch {
+        // non-fatal — baseline fallback below
+      }
+      if (requiredFields.length === 0) {
+        requiredFields = ['title', 'companyId', 'statusId', 'assignedTo'].map((k) => ({
+          fieldKey: k,
+          isSystem: true,
+        }));
+      }
+      const need = new Set(requiredFields.map((f) => f.fieldKey));
+
+      // 2) Id options for required lookup fields (best-effort, scope-aware)
+      const enc = encodeURIComponent(companyId);
+      const [statuses, categories, organizations, departments] = await Promise.all([
+        need.has('statusId') ? systaFetch('GET', '/statuses').catch(() => null) : null,
+        need.has('categoryId') ? systaFetch('GET', '/categories').catch(() => null) : null,
+        need.has('organizationId')
+          ? systaFetch('GET', `/organizations?companyId=${enc}`).catch(() => null)
+          : null,
+        need.has('departmentId')
+          ? systaFetch('GET', `/departments?companyId=${enc}`).catch(() => null)
+          : null,
+      ]);
+      const options = {};
+      if (statuses) {
+        options.statusId = compact(statuses, (o, x) => {
+          if (x.isFinal != null) {
+            o.isFinal = x.isFinal;
+          }
+        });
+      }
+      if (categories) {
+        options.categoryId = compact(categories);
+      }
+      if (organizations) {
+        options.organizationId = compact(organizations);
+      }
+      if (departments) {
+        options.departmentId = compact(departments);
+      }
+
+      return {
+        status: 200,
+        ok: true,
+        data: {
+          companyId,
+          requiredFields,
+          options,
+          note: 'Fill create_request with these required fields; resolve each id from options[fieldKey]. statusId.isFinal=true => a tamamla/kapat status. A missing option list = out of this key scope; ask the user or use systa_api_call.',
+        },
+      };
+    },
+  },
+  {
+    name: 'add_request_comment',
+    description:
+      'Add a PLAIN-TEXT comment to a SysTa request (talebe yorum ekle). Requires the API key to hold BOTH "request.comment.create" and "request.tabs.comments.view" scopes. The text is wrapped into the rich-text (TipTap) format automatically. For RICH content that renders for the end-user — tables, code blocks, @user mentions — or to attach files, do NOT use this tool: call describe_endpoint("/api/requests/:requestNumber/comments","POST") for the TipTap node contract, then systa_api_call POST /requests/{n}/comments with a full commentTextJson document (and fileIds:[...] for attachments; files appear in both the comment and the Files tab).',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestNumber', 'text'],
+      properties: {
+        requestNumber: { type: 'integer', description: 'Request id/number to comment on' },
+        text: { type: 'string', description: 'Comment text (plain)' },
+      },
+    },
+    handler: (args) => {
+      const content = String(args.text || '');
+      const doc = content
+        ? {
+            type: 'doc',
+            content: [{ type: 'paragraph', content: [{ type: 'text', text: content }] }],
+          }
+        : { type: 'doc', content: [{ type: 'paragraph' }] };
+      return systaFetch('POST', `/requests/${encodeURIComponent(args.requestNumber)}/comments`, {
+        body: { commentTextJson: doc },
+      });
+    },
+  },
+  {
+    name: 'change_request_status',
+    description:
+      'Move a SysTa request to a target status (durum degistir / tamamla / kapat / yeniden ac), optionally with a closing comment. Resolve the target statusId by NAME first (list_capabilities or systa_api_call GET /statuses) -- do NOT guess the id. "tamamla/kapat" => a final status; "yeniden ac" => a non-final one. A given comment is posted right after the transition (plain text, auto-wrapped to TipTap). A status change may trigger a workflow gate/approval -- if the API returns such an error, read it and act, do not retry blindly.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestNumber', 'statusId'],
+      properties: {
+        requestNumber: { type: 'integer', description: 'Request number to transition' },
+        statusId: { type: 'integer', description: 'Target status id (resolve by name first)' },
+        comment: {
+          type: 'string',
+          description: 'Optional closing/transition comment (plain text)',
+        },
+      },
+    },
+    handler: async (args) => {
+      const res = await systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, {
+        body: { statusId: args.statusId },
+      });
+      if (args.comment && String(args.comment).trim()) {
+        const doc = {
+          type: 'doc',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: String(args.comment) }] }],
+        };
+        await systaFetch('POST', `/requests/${encodeURIComponent(args.requestNumber)}/comments`, {
+          body: { commentTextJson: doc },
+        });
+      }
+      return res;
+    },
+  },
+  {
+    name: 'update_request',
+    description:
+      'Update fields of an existing SysTa request (talebi guncelle/duzenle) -- PARTIAL: only the fields you pass change. For STATUS use change_request_status, for ASSIGNEE use assign_request, for COMMENTS use add_request_comment (focused intents). Use this for title/description/category/department/priority/deadline/project edits. Resolve categoryId/departmentId/projectId by name first.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestNumber'],
+      properties: {
+        requestNumber: { type: 'integer', description: 'Request number to update' },
+        title: { type: 'string', description: 'New title (min 5 chars)' },
+        description: { type: 'string', description: 'New description (plain text)' },
+        categoryId: { type: 'integer', description: 'Category id (resolve by name)' },
+        departmentId: { type: 'integer', description: 'Department id' },
+        projectId: { type: 'integer', description: 'Link to project id' },
+        priority: { type: 'string', description: 'Priority key/level' },
+        deadline: { type: 'string', description: 'Deadline (ISO date)' },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      for (const [k, v] of Object.entries(args)) {
+        if (k !== 'requestNumber' && v !== undefined && v !== null) {
+          body[k] = v;
+        }
+      }
+      return systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, { body });
+    },
+  },
+  {
+    name: 'assign_request',
+    description:
+      'Assign a SysTa request (talebi ata) to a user or teams -- "bana ata / X kullanicisina ata / su ekibe ata". For "bana/me" use your own user id (list_capabilities -> user.id). Resolve a person\'s name to a user id first. Wraps PUT /requests/:n with assignedTo / assignedTeams.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestNumber'],
+      properties: {
+        requestNumber: { type: 'integer', description: 'Request number to assign' },
+        assignedTo: { type: 'integer', description: 'Assignee user id ("me" => your own id)' },
+        assignedTeams: {
+          type: 'array',
+          items: { type: 'integer' },
+          description: 'Team ids (optional, for team assignment)',
+        },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      if (args.assignedTo != null) {
+        body.assignedTo = args.assignedTo;
+      }
+      if (Array.isArray(args.assignedTeams)) {
+        body.assignedTeams = args.assignedTeams;
+      }
+      return systaFetch('PUT', `/requests/${encodeURIComponent(args.requestNumber)}`, { body });
+    },
+  },
+  {
+    name: 'get_request_board',
+    description:
+      "Read the kanban task board (gorev panosu) of a SysTa request: its columns and the cards in each. READ-only -- to add/edit a card use manage_request_card, to move/reorder use move_request_card; for the request's own fields/comments use get_request/add_request_comment. requestId is the request number.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestId'],
+      properties: {
+        requestId: { type: 'integer', description: 'Request number whose board to read' },
+        assignedToMe: { type: 'boolean', description: 'Only cards assigned to me' },
+        unassigned: {
+          type: 'boolean',
+          description: 'Only unassigned cards (not with assignedToMe)',
+        },
+        priority: { type: 'string', description: 'Filter by card priority' },
+        includeArchived: { type: 'boolean', description: 'Include archived cards (default false)' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', `/requests/${encodeURIComponent(args.requestId)}/kanban`, {
+        query: {
+          assignedToMe: args.assignedToMe,
+          unassigned: args.unassigned,
+          priority: args.priority,
+          includeArchived: args.includeArchived,
+        },
+      }),
+  },
+  {
+    name: 'manage_request_card',
+    description:
+      'Create a card in a board column (requestId + columnId + cardTitle) OR update an existing card (requestId + cardId, partial fields). Does NOT move/reorder cards -- use move_request_card; read ids first with get_request_board. Resolve columnId and assignee ids before calling.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestId'],
+      properties: {
+        requestId: { type: 'integer', description: 'Request number (board owner)' },
+        cardId: {
+          type: 'integer',
+          description: 'Existing card id -> UPDATE mode (omit to CREATE)',
+        },
+        columnId: { type: 'integer', description: 'Target column id (REQUIRED for create)' },
+        cardTitle: { type: 'string', description: 'Card title 3-1000 chars (REQUIRED for create)' },
+        cardDescription: { type: 'string' },
+        assignedUsers: {
+          type: 'array',
+          items: { type: 'integer' },
+          description: 'Assignee user ids',
+        },
+        assignedTeams: { type: 'array', items: { type: 'integer' } },
+        priority: { type: 'string', description: 'low|normal|high|urgent|critical' },
+        tags: { type: 'array', items: { type: 'string' } },
+        deadline: { type: 'string', description: 'ISO-8601 datetime' },
+        cardColor: { type: 'string', description: '#RRGGBB hex' },
+        isCompleted: { type: 'boolean' },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      for (const [k, v] of Object.entries(args)) {
+        if (k !== 'requestId' && k !== 'cardId' && v !== undefined && v !== null) {
+          body[k] = v;
+        }
+      }
+      if (args.cardId != null) {
+        return systaFetch(
+          'PUT',
+          `/requests/${encodeURIComponent(args.requestId)}/kanban/cards/${encodeURIComponent(args.cardId)}`,
+          { body },
+        );
+      }
+      return systaFetch('POST', `/requests/${encodeURIComponent(args.requestId)}/kanban/cards`, {
+        body,
+      });
+    },
+  },
+  {
+    name: 'move_request_card',
+    description:
+      'Move a card to a target column and/or reorder it (drag-drop). Use ONLY for column/position changes -- edit fields with manage_request_card, read ids with get_request_board. To reorder within the same column, set targetColumnId to the current column and pass beforeCardId/afterCardId.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestId', 'cardId', 'targetColumnId'],
+      properties: {
+        requestId: { type: 'integer' },
+        cardId: { type: 'integer', description: 'Card to move (from get_request_board)' },
+        targetColumnId: { type: 'integer', description: 'Destination column id' },
+        beforeCardId: { type: 'integer', description: 'Place before this sibling (optional)' },
+        afterCardId: { type: 'integer', description: 'Place after this sibling (optional)' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('POST', `/requests/${encodeURIComponent(args.requestId)}/kanban/cards/move`, {
+        body: {
+          cardId: args.cardId,
+          targetColumnId: args.targetColumnId,
+          ...(args.beforeCardId != null ? { beforeCardId: args.beforeCardId } : {}),
+          ...(args.afterCardId != null ? { afterCardId: args.afterCardId } : {}),
+        },
+      }),
+  },
+  {
+    name: 'request_approval',
+    description:
+      'Start an approval flow on a request (onaya sun): send an approval request to one or more approvers. Resolve approvalTypeId by name first (systa_api_call GET /approvals/types) and approver user ids by name. strategy: any_one (default) | all_required | quorum (with quorumCount). To RESPOND to an approval use respond_to_approval.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestId', 'approvalTypeId', 'approverUserIds'],
+      properties: {
+        requestId: { type: 'integer', description: 'requests_table.id of the request' },
+        approvalTypeId: { type: 'integer', description: 'Approval type id (resolve by name)' },
+        approverUserIds: {
+          type: 'array',
+          items: { type: 'integer' },
+          minItems: 1,
+          description: 'Approver user ids',
+        },
+        strategy: { type: 'string', enum: ['any_one', 'all_required', 'quorum'] },
+        quorumCount: { type: 'integer', description: 'Required when strategy=quorum' },
+        requestNote: { type: 'string' },
+      },
+    },
+    handler: (args) => {
+      const body = {
+        requestId: args.requestId,
+        approvalTypeId: args.approvalTypeId,
+        approverUserIds: args.approverUserIds,
+      };
+      if (args.strategy) {
+        body.strategy = args.strategy;
+      }
+      if (args.quorumCount != null) {
+        body.quorumCount = args.quorumCount;
+      }
+      if (args.requestNote) {
+        body.requestNote = args.requestNote;
+      }
+      return systaFetch('POST', '/approvals/batch', { body });
+    },
+  },
+  {
+    name: 'respond_to_approval',
+    description:
+      'Respond to an approval assigned to you (onayla / reddet). id is the approval RESPONSE id (the approvalId/responseId from list_pending_approvals). decision must be "approved" or "rejected"; for a rejection add rejectionReasonText. To START an approval use request_approval.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['id', 'decision'],
+      properties: {
+        id: { type: 'integer', description: 'Approval response id (from list_pending_approvals)' },
+        decision: { type: 'string', enum: ['approved', 'rejected'] },
+        responseNote: { type: 'string' },
+        rejectionReasonText: { type: 'string', description: 'Reason when rejecting' },
+        rejectionReasonCode: { type: 'string' },
+      },
+    },
+    handler: (args) => {
+      const body = { decision: args.decision };
+      for (const k of ['responseNote', 'rejectionReasonText', 'rejectionReasonCode']) {
+        if (args[k] != null) {
+          body[k] = args[k];
+        }
+      }
+      return systaFetch('POST', `/approvals/responses/${encodeURIComponent(args.id)}/respond`, {
+        body,
+      });
+    },
+  },
+  {
+    name: 'list_pending_approvals',
+    description:
+      'List approvals waiting on you (uzerimde bekleyen onaylar) -- "bana atanan, yanitlamadigim onaylar". Each row carries the approvalId/responseId you pass to respond_to_approval.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        includeSnoozed: { type: 'boolean' },
+        limit: { type: 'integer' },
+        offset: { type: 'integer' },
+      },
+    },
+    handler: (args) =>
+      systaFetch('GET', '/approvals/all-my-pending', {
+        query: {
+          includeSnoozed: args.includeSnoozed ? 'true' : undefined,
+          limit: args.limit,
+          offset: args.offset,
+        },
+      }),
+  },
+  {
+    name: 'create_project',
+    description:
+      'Create a SysTa project (proje), or a sub-project under parentProjectId. Only projectName is strictly required; companyId/department/organization/dates are optional but recommended. Resolve company/department ids by name first. For request task cards use manage_request_card, not this.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['projectName'],
+      properties: {
+        projectName: { type: 'string', description: 'Project name' },
+        projectCode: { type: 'string' },
+        companyId: { type: 'integer' },
+        departmentId: { type: 'integer' },
+        organizationId: { type: 'integer' },
+        parentProjectId: { type: 'integer', description: 'Parent project id for a sub-project' },
+        description: { type: 'string' },
+        startDate: { type: 'string', description: 'ISO date' },
+        endDate: { type: 'string', description: 'ISO date' },
+        deadline: { type: 'string', description: 'ISO date' },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      for (const [k, v] of Object.entries(args)) {
+        if (v !== undefined && v !== null) {
+          body[k] = v;
+        }
+      }
+      return systaFetch('POST', '/projects', { body });
+    },
+  },
+  {
+    name: 'get_project',
+    description: 'Get one SysTa project (proje) by its numeric id, including sub-projects.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['id'],
+      properties: { id: { type: 'integer', description: 'Project id' } },
+    },
+    handler: (args) => systaFetch('GET', `/projects/${encodeURIComponent(args.id)}`),
+  },
+  {
+    name: 'update_project',
+    description:
+      'Update fields of an existing SysTa project (partial -- only the fields you send change). Resolve referenced ids by name first.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['id'],
+      properties: {
+        id: { type: 'integer', description: 'Project id to update' },
+        projectName: { type: 'string' },
+        projectCode: { type: 'string' },
+        companyId: { type: 'integer' },
+        departmentId: { type: 'integer' },
+        organizationId: { type: 'integer' },
+        parentProjectId: { type: 'integer' },
+        description: { type: 'string' },
+        startDate: { type: 'string' },
+        endDate: { type: 'string' },
+        deadline: { type: 'string' },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      for (const [k, v] of Object.entries(args)) {
+        if (k !== 'id' && v !== undefined && v !== null) {
+          body[k] = v;
+        }
+      }
+      return systaFetch('PUT', `/projects/${encodeURIComponent(args.id)}`, { body });
+    },
+  },
+  {
+    name: 'get_project_health',
+    description:
+      "Read a project's health, risk or SLA status (aspect) -- 'bu proje ne durumda, riskli mi, SLA tutuyor mu'. Read-only diagnostic for ONE project; for time-series charts use get_project_analytics, for many projects loop via list_projects.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['projectId', 'aspect'],
+      properties: {
+        projectId: { type: 'integer' },
+        aspect: { type: 'string', enum: ['health', 'risk', 'sla'] },
+        period: { type: 'integer', description: 'Days 1-90 (health only, default 30)' },
+        includeHierarchy: { type: 'boolean', description: 'Include sub-projects' },
+      },
+    },
+    handler: (args) => {
+      const suffix = { health: '/health-score', risk: '/risk-score', sla: '/sla-status' }[
+        args.aspect
+      ];
+      return systaFetch(
+        'GET',
+        `/projects/${encodeURIComponent(args.projectId)}/dashboard${suffix}`,
+        {
+          query: {
+            period: args.period,
+            includeHierarchy: args.includeHierarchy ? 'true' : undefined,
+          },
+        },
+      );
+    },
+  },
+  {
+    name: 'get_project_analytics',
+    description:
+      "Read a project's time-series chart data (burndown/velocity/cumulative_flow/activity_heatmap/cycle_time) via chartType. Read-only chart feed; for a scalar health/risk score use get_project_health.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['projectId', 'chartType'],
+      properties: {
+        projectId: { type: 'integer' },
+        chartType: {
+          type: 'string',
+          enum: ['burndown', 'velocity', 'cumulative_flow', 'activity_heatmap', 'cycle_time'],
+        },
+        startDate: { type: 'string', description: 'YYYY-MM-DD' },
+        endDate: { type: 'string', description: 'YYYY-MM-DD' },
+        period: { type: 'string', description: "velocity: 'weekly'|'monthly'" },
+        granularity: { type: 'string', description: "cumulative_flow: 'daily'|'weekly'" },
+        months: { type: 'integer', description: 'activity_heatmap' },
+        metric: { type: 'string', description: 'burndown metric' },
+        count: { type: 'integer', description: 'velocity count' },
+        includeHierarchy: { type: 'boolean' },
+      },
+    },
+    handler: (args) => {
+      const suffix = {
+        burndown: '/burndown',
+        velocity: '/velocity',
+        cumulative_flow: '/cumulative-flow',
+        activity_heatmap: '/activity-heatmap',
+        cycle_time: '/cycle-time',
+      }[args.chartType];
+      return systaFetch(
+        'GET',
+        `/projects/${encodeURIComponent(args.projectId)}/dashboard${suffix}`,
+        {
+          query: {
+            startDate: args.startDate,
+            endDate: args.endDate,
+            period: args.period,
+            granularity: args.granularity,
+            months: args.months,
+            metric: args.metric,
+            count: args.count,
+            includeHierarchy: args.includeHierarchy ? 'true' : undefined,
+          },
+        },
+      );
+    },
+  },
+  {
+    name: 'list_milestones',
+    description:
+      "List a project's milestones, or scope='summary' for a status-count summary. Read-only; create with create_milestone, complete with achieve_milestone.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['projectId'],
+      properties: {
+        projectId: { type: 'integer' },
+        scope: { type: 'string', enum: ['list', 'summary'] },
+      },
+    },
+    handler: (args) =>
+      systaFetch(
+        'GET',
+        `/projects/${encodeURIComponent(args.projectId)}/milestones${args.scope === 'summary' ? '/summary' : ''}`,
+      ),
+  },
+  {
+    name: 'create_milestone',
+    description:
+      "Create a milestone on a project (kilometre tasi). NOT idempotent -- duplicate names create duplicates, so check list_milestones first. triggerConfig is required for non-'manual' milestoneType (call describe_endpoint for the per-type shape).",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['projectId', 'milestoneName', 'milestoneType'],
+      properties: {
+        projectId: { type: 'integer' },
+        milestoneName: { type: 'string' },
+        milestoneType: {
+          type: 'string',
+          enum: [
+            'manual',
+            'date_threshold',
+            'percentage',
+            'task_completion',
+            'phase_gate',
+            'kpi_metric',
+            'composite',
+          ],
+        },
+        description: { type: 'string' },
+        status: { type: 'string' },
+        priority: { type: 'string' },
+        targetDate: { type: 'string', description: 'ISO datetime with offset' },
+        triggerConfig: {
+          type: 'object',
+          additionalProperties: true,
+          description: 'Required for non-manual types; shape depends on milestoneType',
+        },
+        displayOrder: { type: 'integer' },
+        color: { type: 'string' },
+        icon: { type: 'string' },
+        showOnGantt: { type: 'boolean' },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      for (const [k, v] of Object.entries(args)) {
+        if (k !== 'projectId' && v !== undefined && v !== null) {
+          body[k] = v;
+        }
+      }
+      return systaFetch('POST', `/projects/${encodeURIComponent(args.projectId)}/milestones`, {
+        body,
+      });
+    },
+  },
+  {
+    name: 'achieve_milestone',
+    description:
+      'Mark a milestone as achieved (kilometre tasini tamamla). No body. The backend checks dependencies + a valid transition; resolve the milestone id via list_milestones first.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['projectId', 'id'],
+      properties: {
+        projectId: { type: 'integer' },
+        id: { type: 'integer', description: 'Milestone id' },
+      },
+    },
+    handler: (args) =>
+      systaFetch(
+        'PATCH',
+        `/projects/${encodeURIComponent(args.projectId)}/milestones/${encodeURIComponent(args.id)}/achieve`,
+      ),
+  },
+  {
+    name: 'manage_project_stakeholders',
+    description:
+      "Manage project stakeholders (paydas): action 'list' | 'add' | 'add_bulk' | 'remove'. Resolve userId/userIds by name first (ids, not names).",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['action', 'projectId'],
+      properties: {
+        action: { type: 'string', enum: ['list', 'add', 'add_bulk', 'remove'] },
+        projectId: { type: 'integer' },
+        userId: { type: 'integer', description: 'add/remove' },
+        userIds: { type: 'array', items: { type: 'integer' }, description: 'add_bulk' },
+        role: { type: 'string' },
+        notes: { type: 'string' },
+        includeHierarchy: { type: 'boolean', description: 'list' },
+      },
+    },
+    handler: (args) => {
+      const pid = encodeURIComponent(args.projectId);
+      if (args.action === 'list') {
+        return systaFetch('GET', `/stakeholders/projects/${pid}`, {
+          query: { includeHierarchy: args.includeHierarchy ? 'true' : undefined },
+        });
+      }
+      if (args.action === 'add') {
+        return systaFetch('POST', '/stakeholders', {
+          body: {
+            projectId: args.projectId,
+            userId: args.userId,
+            ...(args.role ? { role: args.role } : {}),
+            ...(args.notes ? { notes: args.notes } : {}),
+          },
+        });
+      }
+      if (args.action === 'add_bulk') {
+        return systaFetch('POST', '/stakeholders/bulk', {
+          body: {
+            projectId: args.projectId,
+            userIds: args.userIds,
+            ...(args.role ? { role: args.role } : {}),
+            ...(args.notes ? { notes: args.notes } : {}),
+          },
+        });
+      }
+      return systaFetch(
+        'DELETE',
+        `/stakeholders/projects/${pid}/users/${encodeURIComponent(args.userId)}`,
+      );
+    },
+  },
+  {
+    name: 'manage_project_notes',
+    description:
+      "Manage project notes and tags: action 'list'|'create'|'delete' (notes) and 'list_tags'|'add_tag'|'remove_tag' (tags). projectId is always in the path.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['action', 'projectId'],
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'create', 'delete', 'list_tags', 'add_tag', 'remove_tag'],
+        },
+        projectId: { type: 'integer' },
+        noteContent: { type: 'string', description: 'create (1-10000)' },
+        noteId: { type: 'integer', description: 'delete' },
+        tagId: { type: 'integer', description: 'add_tag/remove_tag' },
+        tagName: { type: 'string', description: 'add_tag (tagId OR tagName)' },
+      },
+    },
+    handler: (args) => {
+      const pid = encodeURIComponent(args.projectId);
+      switch (args.action) {
+        case 'list':
+          return systaFetch('GET', `/projects/${pid}/notes`);
+        case 'create':
+          return systaFetch('POST', `/projects/${pid}/notes`, {
+            body: { noteContent: args.noteContent },
+          });
+        case 'delete':
+          return systaFetch('DELETE', `/projects/${pid}/notes/${encodeURIComponent(args.noteId)}`);
+        case 'list_tags':
+          return systaFetch('GET', `/projects/${pid}/tags`);
+        case 'add_tag':
+          return systaFetch('POST', `/projects/${pid}/tags`, {
+            body: {
+              ...(args.tagId != null ? { tagId: args.tagId } : {}),
+              ...(args.tagName ? { tagName: args.tagName } : {}),
+            },
+          });
+        default:
+          return systaFetch('DELETE', `/projects/${pid}/tags/${encodeURIComponent(args.tagId)}`);
+      }
+    },
+  },
+  {
+    name: 'create_plan_baseline',
+    description:
+      'Create a plan baseline/snapshot for a plan mode (POST /plan/modes/:modeId/baselines). Omit boards -- the server snapshots the mode live state (built for AI clients with no board state). Returns baselineId for submit_plan_for_approval.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['modeId', 'baselineName'],
+      properties: {
+        modeId: { type: 'integer' },
+        baselineName: { type: 'string' },
+        boards: {
+          type: 'array',
+          items: { type: 'object', additionalProperties: true },
+          description: 'Optional explicit board snapshot; usually omit',
+        },
+      },
+    },
+    handler: (args) => {
+      const body = { baselineName: args.baselineName };
+      if (Array.isArray(args.boards) && args.boards.length) {
+        body.boards = args.boards;
+      }
+      return systaFetch('POST', `/plan/modes/${encodeURIComponent(args.modeId)}/baselines`, {
+        body,
+      });
+    },
+  },
+  {
+    name: 'submit_plan_for_approval',
+    description:
+      'Submit a plan baseline for approval (POST /plan/approvals/submit). strategy: any_one (default)|all_required|quorum (+quorumCount). deadline is ISO-8601 WITH offset. baselineId from create_plan_baseline; resolve approverUserIds by name.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['baselineId', 'approverUserIds'],
+      properties: {
+        baselineId: { type: 'integer' },
+        approverUserIds: { type: 'array', items: { type: 'integer' }, minItems: 1 },
+        strategy: { type: 'string', enum: ['any_one', 'all_required', 'quorum'] },
+        quorumCount: { type: 'integer' },
+        requestNote: { type: 'string' },
+        deadline: { type: 'string', description: 'ISO-8601 with offset' },
+        lockedFields: { type: 'array', items: { type: 'string' } },
+        periodStart: { type: 'string', description: 'YYYY-MM-DD' },
+        periodEnd: { type: 'string', description: 'YYYY-MM-DD' },
+      },
+    },
+    handler: (args) => {
+      const body = { baselineId: args.baselineId, approverUserIds: args.approverUserIds };
+      for (const k of [
+        'strategy',
+        'quorumCount',
+        'requestNote',
+        'deadline',
+        'lockedFields',
+        'periodStart',
+        'periodEnd',
+      ]) {
+        if (args[k] != null) {
+          body[k] = args[k];
+        }
+      }
+      return systaFetch('POST', '/plan/approvals/submit', { body });
+    },
+  },
+  {
+    name: 'respond_to_plan_approval',
+    description:
+      "Respond to a plan approval: action 'respond' (decision approved/rejected on a RESPONSE id), 'revision' (request changes with a note on a RESPONSE id), or 'cancel' (requester cancels an APPROVAL REQUEST id). id meaning depends on action.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['action', 'id'],
+      properties: {
+        action: { type: 'string', enum: ['respond', 'revision', 'cancel'] },
+        id: {
+          type: 'integer',
+          description: 'response id (respond/revision) or approvalRequest id (cancel)',
+        },
+        decision: { type: 'string', enum: ['approved', 'rejected'], description: 'respond' },
+        responseNote: { type: 'string' },
+        rejectionReason: { type: 'string' },
+      },
+    },
+    handler: (args) => {
+      const id = encodeURIComponent(args.id);
+      if (args.action === 'respond') {
+        const body = { decision: args.decision };
+        if (args.responseNote != null) {
+          body.responseNote = args.responseNote;
+        }
+        if (args.rejectionReason != null) {
+          body.rejectionReason = args.rejectionReason;
+        }
+        return systaFetch('POST', `/plan/approvals/responses/${id}/respond`, { body });
+      }
+      if (args.action === 'revision') {
+        return systaFetch('POST', `/plan/approvals/responses/${id}/revision`, {
+          body: { responseNote: args.responseNote },
+        });
+      }
+      return systaFetch('POST', `/plan/approvals/${id}/cancel`);
+    },
+  },
+  {
+    name: 'get_plan_critical_path',
+    description:
+      'Get the critical path (nodes, durations, slack) for a set of requests. requestIds come from list_requests or plan board cards.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['requestIds'],
+      properties: {
+        requestIds: { type: 'array', items: { type: 'integer' }, description: 'Request ids' },
+      },
+    },
+    handler: (args) => {
+      const ids = Array.isArray(args.requestIds)
+        ? args.requestIds.join(',')
+        : String(args.requestIds);
+      return systaFetch('GET', '/plan/critical-path', { query: { requestIds: ids } });
+    },
+  },
+  {
+    name: 'distribute_plan_schedule',
+    description:
+      'Compute a proposed schedule distribution across plan boards (POST /plan/distribute). READ-ONLY despite POST -- returns proposed per-board assignments, persists NOTHING. Usually call with no args (server uses the mode boards).',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        boards: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        options: { type: 'object', additionalProperties: true },
+        modeId: { type: 'integer' },
+        fields: { type: 'string', description: 'Query projection' },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      for (const k of ['boards', 'options', 'modeId']) {
+        if (args[k] != null) {
+          body[k] = args[k];
+        }
+      }
+      return systaFetch('POST', '/plan/distribute', {
+        body,
+        query: args.fields ? { fields: args.fields } : undefined,
+      });
+    },
+  },
+  {
+    name: 'create_release_list',
+    description:
+      "Create a release list (surum listesi) for a company on a deployment date. releaseType 'standard' (default) | 'emergency' (+emergencyJustification). companyId must be a resolved numeric id.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['companyId', 'deploymentDate'],
+      properties: {
+        companyId: { type: 'integer' },
+        deploymentDate: { type: 'string', description: 'ISO date/datetime' },
+        plannedStartTime: { type: 'string', description: 'HH:mm' },
+        requireAllStakeholderApprovals: { type: 'boolean' },
+        releaseType: { type: 'string', enum: ['standard', 'emergency'] },
+        emergencyJustification: { type: 'string' },
+      },
+    },
+    handler: (args) => {
+      const body = {};
+      for (const [k, v] of Object.entries(args)) {
+        if (v !== undefined && v !== null) {
+          body[k] = v;
+        }
+      }
+      return systaFetch('POST', '/releases/lists', { body });
+    },
+  },
+  {
+    name: 'add_release_item',
+    description:
+      "Add a request to a release list as a release item (POST /releases/items). Pass 'items' (array) for a batch, or a single listId+requestId. Resolve developer/analyst/stakeholder ids by name.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['listId', 'requestId'],
+      properties: {
+        listId: { type: 'integer' },
+        requestId: { type: 'integer' },
+        plannedProdDate: { type: 'string', description: 'ISO date' },
+        developerIds: { type: 'array', items: { type: 'integer' } },
+        analystIds: { type: 'array', items: { type: 'integer' } },
+        stakeholderIds: { type: 'array', items: { type: 'integer' } },
+        stakeholderRoles: { type: 'object', additionalProperties: true },
+        items: {
+          type: 'array',
+          items: { type: 'object', additionalProperties: true },
+          description: 'Batch: array of full item objects (overrides the single fields)',
+        },
+      },
+    },
+    handler: (args) => {
+      if (Array.isArray(args.items) && args.items.length) {
+        return systaFetch('POST', '/releases/items', { body: args.items });
+      }
+      const body = {};
+      for (const [k, v] of Object.entries(args)) {
+        if (k !== 'items' && v !== undefined && v !== null) {
+          body[k] = v;
+        }
+      }
+      return systaFetch('POST', '/releases/items', { body });
+    },
+  },
+  {
+    name: 'advance_release_workflow',
+    description:
+      "Advance a release list deployment workflow one ordered step (close_servers -> start_db_migration -> start_server_update -> open_servers -> complete; or fail/reset). Idempotent: re-issuing the current step is safe. Only 'fail' takes errorMessage. Admin manual-override is intentionally excluded.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['listId', 'step'],
+      properties: {
+        listId: { type: 'integer' },
+        step: {
+          type: 'string',
+          enum: [
+            'close_servers',
+            'start_db_migration',
+            'start_server_update',
+            'open_servers',
+            'complete',
+            'fail',
+            'reset',
+          ],
+        },
+        errorMessage: { type: 'string', description: "only for step='fail'" },
+      },
+    },
+    handler: (args) => {
+      const map = {
+        close_servers: 'close-servers',
+        start_db_migration: 'start-db-migration',
+        start_server_update: 'start-server-update',
+        open_servers: 'open-servers',
+        complete: 'complete',
+        fail: 'fail',
+        reset: 'reset',
+      };
+      const action = map[args.step];
+      return systaFetch(
+        'PUT',
+        `/releases/lists/${encodeURIComponent(args.listId)}/workflow/${action}`,
+        args.step === 'fail' ? { body: { errorMessage: args.errorMessage } } : {},
+      );
+    },
+  },
+  {
+    name: 'querybuilder_ai_generate_query',
+    description:
+      'Generate a report query config from natural language (POST /query-builder/ai/generate). Returns a queryConfig you feed to querybuilder_execute_query (mode=preview). It only DRAFTS a query -- no result rows.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['text', 'reportType'],
+      properties: {
+        text: { type: 'string', description: '3-500 chars natural-language request' },
+        reportType: {
+          type: 'string',
+          enum: ['request', 'sla', 'user', 'organization', 'project', 'lifecycle', 'subform'],
+        },
+        language: { type: 'string' },
+        model: { type: 'string' },
+      },
+    },
+    handler: (args) => {
+      const body = {
+        text: args.text,
+        reportType: args.reportType,
+        language: args.language ?? 'tr',
+      };
+      if (args.model) {
+        body.model = args.model;
+      }
+      return systaFetch('POST', '/query-builder/ai/generate', { body });
+    },
+  },
+  {
+    name: 'querybuilder_execute_query',
+    description:
+      "Run a report query: mode 'preview' (25 rows, validate first), 'execute' (full rows, limit/offset), or 'export' (xlsx/csv). queryConfig.fields is required. Always preview before execute. Rate-limited.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['mode', 'reportType', 'queryConfig'],
+      properties: {
+        mode: { type: 'string', enum: ['preview', 'execute', 'export'] },
+        reportType: {
+          type: 'string',
+          enum: ['request', 'sla', 'user', 'organization', 'project', 'lifecycle', 'subform'],
+        },
+        queryConfig: {
+          type: 'object',
+          additionalProperties: true,
+          description: '{fields:[],rules?,orderBy?,groupBy?,aggregations?,having?}',
+        },
+        limit: { type: 'integer' },
+        offset: { type: 'integer' },
+        parameterValues: { type: 'object', additionalProperties: true },
+        format: { type: 'string', enum: ['xlsx', 'csv'], description: 'required for export' },
+        conditionalFormats: {
+          type: 'array',
+          items: { type: 'object', additionalProperties: true },
+        },
+      },
+    },
+    handler: (args) => {
+      const base = { reportType: args.reportType, queryConfig: args.queryConfig };
+      if (args.mode === 'preview') {
+        return systaFetch('POST', '/query-builder/preview', { body: base });
+      }
+      if (args.mode === 'execute') {
+        const body = { ...base };
+        for (const k of ['limit', 'offset', 'parameterValues']) {
+          if (args[k] != null) {
+            body[k] = args[k];
+          }
+        }
+        return systaFetch('POST', '/query-builder/execute', { body });
+      }
+      const body = { ...base, format: args.format };
+      for (const k of ['limit', 'conditionalFormats']) {
+        if (args[k] != null) {
+          body[k] = args[k];
+        }
+      }
+      return systaFetch('POST', '/query-builder/export', { body });
+    },
+  },
+  {
+    name: 'querybuilder_describe_fields',
+    description:
+      "Discover queryable fields for a reportType: mode 'fields' (metadata/fieldKeys), 'options' (filter value options), or 'suggest' (q search). Never invent field names -- read mode='fields' first.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['mode', 'reportType'],
+      properties: {
+        mode: { type: 'string', enum: ['fields', 'options', 'suggest'] },
+        reportType: {
+          type: 'string',
+          enum: ['request', 'sla', 'user', 'organization', 'project', 'lifecycle', 'subform'],
+        },
+        q: { type: 'string', description: "required for mode='suggest'" },
+      },
+    },
+    handler: (args) => {
+      const path = {
+        fields: '/query-builder/metadata',
+        options: '/query-builder/field-options',
+        suggest: '/query-builder/suggest-fields',
+      }[args.mode];
+      return systaFetch('GET', path, {
+        query: { reportType: args.reportType, ...(args.mode === 'suggest' ? { q: args.q } : {}) },
+      });
+    },
+  },
+  {
+    name: 'querybuilder_saved_query',
+    description:
+      "Saved report queries: mode 'list' (mine+shared), 'save' (name+reportType+queryConfig), or 'run' (id +parameterValues). update/delete/clone/share are intentionally excluded (use systa_api_call). Validate config with querybuilder_execute_query mode=preview before saving.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['mode'],
+      properties: {
+        mode: { type: 'string', enum: ['list', 'save', 'run'] },
+        id: { type: 'integer', description: 'run' },
+        name: { type: 'string' },
+        description: { type: 'string' },
+        reportType: {
+          type: 'string',
+          enum: ['request', 'sla', 'user', 'organization', 'project', 'lifecycle', 'subform'],
+        },
+        queryConfig: { type: 'object', additionalProperties: true },
+        isShared: { type: 'boolean' },
+        parameters: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        categoryId: { type: 'integer' },
+        parameterValues: { type: 'object', additionalProperties: true, description: 'run' },
+      },
+    },
+    handler: (args) => {
+      if (args.mode === 'list') {
+        return systaFetch('GET', '/query-builder/saved');
+      }
+      if (args.mode === 'save') {
+        const body = {
+          name: args.name,
+          reportType: args.reportType,
+          queryConfig: args.queryConfig,
+        };
+        for (const k of ['description', 'isShared', 'parameters', 'categoryId']) {
+          if (args[k] != null) {
+            body[k] = args[k];
+          }
+        }
+        return systaFetch('POST', '/query-builder/saved', { body });
+      }
+      return systaFetch(
+        'POST',
+        `/query-builder/saved/${encodeURIComponent(args.id)}/execute`,
+        args.parameterValues != null ? { body: { parameterValues: args.parameterValues } } : {},
+      );
+    },
+  },
+  {
+    name: 'querybuilder_schedule_report',
+    description:
+      'Schedule a saved query to run on a cadence (POST /query-builder/schedules). queryId is a saved query id (resolve via querybuilder_saved_query). frequency daily/weekly/monthly + timeOfDay HH:MM. Does NOT run it now -- use querybuilder_execute_query for that.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['queryId', 'scheduleName', 'frequency', 'timeOfDay'],
+      properties: {
+        queryId: { type: 'integer' },
+        scheduleName: { type: 'string' },
+        frequency: { type: 'string', enum: ['daily', 'weekly', 'monthly'] },
+        timeOfDay: { type: 'string', description: 'HH:MM' },
+        dayOfWeek: { type: 'integer', description: '0-6 (weekly)' },
+        dayOfMonth: { type: 'integer', description: '1-31 (monthly)' },
+        timezone: { type: 'string' },
+        exportFormat: { type: 'string', enum: ['xlsx', 'csv'] },
+        recipients: { type: 'array', items: { type: 'object', additionalProperties: true } },
+      },
+    },
+    handler: (args) => {
+      const body = {
+        queryId: args.queryId,
+        scheduleName: args.scheduleName,
+        frequency: args.frequency,
+        timeOfDay: args.timeOfDay,
+      };
+      for (const k of ['dayOfWeek', 'dayOfMonth', 'timezone', 'exportFormat', 'recipients']) {
+        if (args[k] != null) {
+          body[k] = args[k];
+        }
+      }
+      return systaFetch('POST', '/query-builder/schedules', { body });
+    },
+  },
+  {
+    name: 'systa_api_call',
+    description:
+      'Generic SysTa REST API call. Use for any endpoint not covered by a specific tool (create/update/comment, etc.). The API key scope is enforced server-side: out-of-scope calls return 403. path is relative to the API base (e.g. "/requests/42/comments").',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['method', 'path'],
+      properties: {
+        method: { type: 'string', enum: ALLOWED_METHODS, description: 'HTTP method' },
+        path: { type: 'string', description: 'Path relative to the API base, must start with "/"' },
+        query: {
+          type: 'object',
+          description: 'Query string parameters',
+          additionalProperties: true,
+        },
+        body: { type: 'object', description: 'JSON request body', additionalProperties: true },
+      },
+    },
+    handler: (args) => {
+      const method = String(args.method || '').toUpperCase();
+      if (!ALLOWED_METHODS.includes(method)) {
+        throw new Error(`Method not allowed: ${args.method}`);
+      }
+      if (typeof args.path !== 'string' || !args.path.startsWith('/')) {
+        throw new Error('path must start with "/"');
+      }
+      return systaFetch(method, args.path, { query: args.query, body: args.body });
+    },
+  },
+  {
+    name: 'download_request_file',
+    description:
+      'Download a SysTa attachment (request/task-card/project file) to the LOCAL disk and ' +
+      'return the saved path. Requires the "file.download" scope; all access checks run ' +
+      'server-side. fileId comes from file list endpoints (e.g. GET /requests/:n/files). ' +
+      'Saves into a temp directory unless savePath is given.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['fileId'],
+      properties: {
+        fileId: { type: 'integer', description: 'File id (from a file list endpoint)' },
+        savePath: {
+          type: 'string',
+          description:
+            'Optional local target: an existing directory OR a full file path. Default: OS temp dir.',
+        },
+      },
+    },
+    handler: async (args) => {
+      const res = await systaFetchBinary(`/files/${encodeURIComponent(args.fileId)}/download`);
+      if (!res.ok) {
+        return { status: res.status, ok: false, data: res.data };
+      }
+      const fileName = sanitizeFileName(res.fileName, `file-${args.fileId}`);
+      const savedPath = resolveSavePath(fileName, args.savePath);
+      fs.writeFileSync(savedPath, res.buffer);
+      return {
+        status: res.status,
+        ok: true,
+        savedPath,
+        fileName,
+        mimeType: res.mimeType,
+        sizeBytes: res.buffer.length,
+      };
+    },
+  },
+  {
+    name: 'upload_file_to',
+    description:
+      'Upload local file(s) as SysTa attachments (multipart) to a request/task-card/project. Requires the "file.upload" scope; ' +
+      'security checks (extension/MIME allowlist, magic bytes, rate limit) run server-side — ' +
+      'executable/script extensions are rejected. Common paths: "/requests/:requestNumber/files" ' +
+      '(request attachment), "/projects/:projectId/files" (project file), ' +
+      '"/requests/:requestId/kanban/cards/:cardId/files" (task card file), ' +
+      '"/files/orphan-upload" (pre-upload for sub-forms). Use method PUT with exactly one file ' +
+      'for "/requests/:n/files/:id" (replace an existing file). The multipart field name is set ' +
+      "automatically to 'file' — you only pass filePaths; you never set the field name yourself.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path', 'filePaths'],
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Upload endpoint path relative to the API base, must start with "/"',
+        },
+        filePaths: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 50,
+          items: { type: 'string' },
+          description: 'Absolute local file paths to upload',
+        },
+        method: {
+          type: 'string',
+          enum: ['POST', 'PUT'],
+          description: 'HTTP method (default POST)',
+        },
+      },
+    },
+    handler: (args) => {
+      if (typeof args.path !== 'string' || !args.path.startsWith('/')) {
+        throw new Error('path must start with "/"');
+      }
+      const method = args.method ? String(args.method).toUpperCase() : 'POST';
+      if (!['POST', 'PUT'].includes(method)) {
+        throw new Error(`Method not allowed for upload: ${args.method}`);
+      }
+      const filePaths = Array.isArray(args.filePaths) ? args.filePaths : [];
+      if (filePaths.length < 1 || filePaths.length > 50) {
+        throw new Error('filePaths must contain between 1 and 50 local file paths');
+      }
+      return systaUploadMultipart(args.path, method, filePaths);
+    },
+  },
+  {
+    name: 'list_capabilities',
+    description:
+      'Discover what THIS API key can actually do. Returns a scope-filtered catalog of ' +
+      'modules and endpoints the key is permitted to call (out-of-scope endpoints are not ' +
+      'shown), each with its HTTP methods, safety class (read_only/idempotent/mutating/' +
+      'destructive) and required permission. Call this FIRST to learn available capabilities, ' +
+      'then describe_endpoint for parameter details. Compact view — no field schemas.',
+    inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+    handler: async () => {
+      const res = await systaFetch('GET', '/api-keys/me/capabilities');
+      if (!res.ok) {
+        return res;
+      }
+      return shapeCompact(unwrapCapabilities(res));
+    },
+  },
+  {
+    name: 'describe_module',
+    description:
+      'Orient on ONE SysTa module: returns its purpose (description, TR/EN), key concepts, ' +
+      'and the endpoints THIS key can call within it (path + summary + method/safety). Use the ' +
+      'module name from list_capabilities (e.g. "request", "kanban", "plan", "sla"). Helps map a ' +
+      "user's natural-language intent to the right module before describe_endpoint.",
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['module'],
+      properties: {
+        module: { type: 'string', description: 'Module name, e.g. request / kanban / plan / sla' },
+      },
+    },
+    handler: async (args) => {
+      const res = await systaFetch('GET', '/api-keys/me/capabilities');
+      if (!res.ok) {
+        return res;
+      }
+      const caps = unwrapCapabilities(res);
+      const target = String(args.module || '').toLowerCase();
+      const mod = (caps.modules || []).find((m) => String(m.module).toLowerCase() === target);
+      if (!mod) {
+        return {
+          ok: false,
+          error: `Module not found or not permitted for this key: ${args.module}`,
+          availableModules: (caps.modules || []).map((m) => m.module),
+        };
+      }
+      return {
+        module: mod.module,
+        description: mod.description,
+        concepts: mod.concepts,
+        endpoints: (mod.endpoints || []).map((e) => ({
+          path: e.path,
+          summary: e.summary,
+          methods: (e.methods || []).map((mm) => ({
+            method: mm.method,
+            safetyClass: mm.safetyClass,
+            requiredPermission: mm.requiredPermission,
+          })),
+        })),
+      };
+    },
+  },
+  {
+    name: 'describe_endpoint',
+    description:
+      'Get full detail for one capability: input field types (fields), response shape ' +
+      '(responseSchema — the data body inside the {success, data} envelope), safety class, ' +
+      'required permission, and summary/scenario when available. Use the path + method from ' +
+      'list_capabilities. Returns only if the key is permitted to call it.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Route pattern, e.g. "/api/requests" or "/api/requests/:requestNumber"',
+        },
+        method: {
+          type: 'string',
+          enum: ALLOWED_METHODS,
+          description: 'Optional HTTP method to disambiguate',
+        },
+      },
+    },
+    handler: async (args) => {
+      const targetPath = String(args.path || '');
+      const targetMethod = args.method ? String(args.method).toUpperCase() : '';
+      const res = await systaFetch('GET', '/api-keys/me/capabilities');
+      if (!res.ok) {
+        return res;
+      }
+      const caps = unwrapCapabilities(res);
+      for (const module of caps.modules || []) {
+        for (const endpoint of module.endpoints || []) {
+          if (endpoint.path !== targetPath) {
+            continue;
+          }
+          const match = (endpoint.methods || []).find(
+            (mm) => !targetMethod || mm.method === targetMethod,
+          );
+          if (match) {
+            return {
+              module: module.module,
+              path: endpoint.path,
+              summary: endpoint.summary,
+              ...match,
+            };
+          }
+        }
+      }
+      return {
+        ok: false,
+        error: `Endpoint not found or not permitted for this key: ${targetMethod || 'ANY'} ${targetPath}`,
+      };
+    },
+  },
+];
+
+const TOOL_MAP = new Map(TOOLS.map((tool) => [tool.name, tool]));
+
+// ── Scope-aware tool visibility ──────────────────────────────────────────────
+// Her named tool'un PRIMARY endpoint'inin gerektirdigi izin (permission_key).
+// `tools/list` bunu, anahtarin scope-filtreli katalogunda GERCEKTEN gorunen izin
+// setiyle karsilastirir: bir arac yalnizca anahtar o izne sahipse listelenir.
+// Boylece kapsam disi araclar AJANA HIC GORUNMEZ -> ajan onlari denemez, gereksiz
+// 403 olmaz. Yikici/wildcard mantigi (`*`/`domain.*` + `.delete` istisnasi) zaten
+// backend'de uygulanip katalogu filtreledigi icin burada yeniden yazilmaz — tek
+// kaynak backend. Bu haritada OLMAYAN araclar (list_capabilities, describe_module,
+// describe_endpoint, systa_api_call) izin gerektirmez, her zaman gorunur: bunlar
+// kesif/jenerik katmanidir (systa_api_call belirli bir endpoint'i REKLAM ETMEZ;
+// scope sunucuda 403 ile zorlanir). Permission degerleri canli katalogdan dogrulandi.
+const TOOL_REQUIRED_PERMISSION = {
+  list_requests: 'request.read',
+  get_request: 'request.tabs.general.view',
+  list_projects: 'project.read',
+  create_request: 'request.create',
+  prepare_create_request: 'request.create',
+  add_request_comment: 'request.comment.create',
+  change_request_status: 'request.update',
+  update_request: 'request.update',
+  assign_request: 'request.update',
+  get_request_board: 'request.read',
+  manage_request_card: 'request.update',
+  move_request_card: 'request.update',
+  request_approval: 'request.approval.create',
+  respond_to_approval: 'request.approval.respond',
+  list_pending_approvals: 'request.approval.view',
+  create_project: 'project.create',
+  get_project: 'project.read',
+  update_project: 'project.update',
+  get_project_health: 'project.read',
+  get_project_analytics: 'project.read',
+  list_milestones: 'project.read',
+  create_milestone: 'project.update',
+  achieve_milestone: 'project.update',
+  manage_project_stakeholders: 'project.update',
+  manage_project_notes: 'project.update',
+  create_plan_baseline: 'request.update',
+  submit_plan_for_approval: 'plan.approval.submit',
+  respond_to_plan_approval: 'plan.approval.review',
+  get_plan_critical_path: 'request.read',
+  distribute_plan_schedule: 'request.read',
+  create_release_list: 'release.list.create',
+  add_release_item: 'release.item.create',
+  advance_release_workflow: 'release.workflow.manage',
+  querybuilder_ai_generate_query: 'report.query-builder',
+  querybuilder_execute_query: 'report.query-builder',
+  querybuilder_describe_fields: 'report.query-builder',
+  querybuilder_saved_query: 'report.query-builder',
+  querybuilder_schedule_report: 'report.query-builder',
+  download_request_file: 'file.download',
+  upload_file_to: 'file.upload',
+};
+
+// Hata aninda davranis: fail-open (varsayilan) tum araclari gosterir — gerçek
+// guvenlik siniri backend 403'tur, gecici bir aglama hatasi tum araç setini
+// kilitlememeli. SYSTA_MCP_STRICT_TOOLS=1 -> fail-closed: kapsam bilinemezse yalniz
+// izin gerektirmeyen kesif araclari gorunur.
+const STRICT_TOOLS = process.env.SYSTA_MCP_STRICT_TOOLS === '1';
+
+let allowedPermissionsPromise = null;
+// Anahtarin EFEKTIF izin seti = scope-filtreli katalogda gorunen tum
+// requiredPermission degerleri. Anahtar+base sabit oldugu icin process omru boyunca
+// bir kez cekilir (memoized). Basarisizlik -> null (cagiran fail-open/closed'a karar verir).
+const fetchAllowedPermissions = async () => {
+  try {
+    const res = await systaFetch('GET', '/api-keys/me/capabilities');
+    if (!res || !res.ok) {
+      return null;
+    }
+    const caps = unwrapCapabilities(res) || {};
+    const methods = (caps.modules || [])
+      .flatMap((m) => m.endpoints || [])
+      .flatMap((e) => e.methods || []);
+    const set = new Set();
+    for (const mm of methods) {
+      if (mm.requiredPermission) {
+        set.add(mm.requiredPermission);
+      }
+    }
+    return set;
+  } catch {
+    return null;
+  }
+};
+const getAllowedPermissions = () => {
+  if (!allowedPermissionsPromise) {
+    allowedPermissionsPromise = fetchAllowedPermissions();
+  }
+  return allowedPermissionsPromise;
+};
+
+/**
+ * Filter the tool list down to what THIS key can actually use.
+ * @param {Set<string>|null} allowed - effective permission set, or null if unknown
+ * @returns {Array} visible tool definitions
+ */
+const visibleTools = (allowed) =>
+  TOOLS.filter((tool) => {
+    const need = TOOL_REQUIRED_PERMISSION[tool.name];
+    if (!need) {
+      return true; // kesif/jenerik araclar — her zaman
+    }
+    if (allowed === null) {
+      return !STRICT_TOOLS; // kapsam bilinemiyor: fail-open varsayilan
+    }
+    return allowed.has(need);
+  });
+
+// ── JSON-RPC plumbing ────────────────────────────────────────────────────────
+const send = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
+const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
+const errorReply = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+const handleToolCall = async (id, params) => {
+  const name = params && params.name;
+  const tool = TOOL_MAP.get(name);
+  if (!tool) {
+    return errorReply(id, -32602, `Unknown tool: ${name}`);
+  }
+  try {
+    const result = await tool.handler((params && params.arguments) || {});
+    const isError = result && result.ok === false;
+    return reply(id, {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      isError: Boolean(isError),
+    });
+  } catch (toolError) {
+    return reply(id, {
+      content: [{ type: 'text', text: `Tool error: ${toolError.message}` }],
+      isError: true,
+    });
+  }
+};
+
+const handleMessage = async (line) => {
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    return;
+  }
+  const { id, method, params } = message;
+
+  if (method === 'initialize') {
+    return send(
+      reply(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+        instructions: INSTRUCTIONS,
+      }),
+    );
+  }
+  if (method === 'tools/list') {
+    // Scope-aware: anahtarin yetkili oldugu araclari goster (kapsam disi araclar
+    // ajana HIC gorunmez). Kapsam, anahtarin scope-filtreli katalogundan turetilir.
+    const allowed = BASE_URL && API_KEY ? await getAllowedPermissions() : null;
+    return send(
+      reply(id, {
+        tools: visibleTools(allowed).map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+      }),
+    );
+  }
+  if (method === 'tools/call') {
+    return send(await handleToolCall(id, params));
+  }
+  if (method === 'ping') {
+    return send(reply(id, {}));
+  }
+  // Notifications (no id) — acknowledge silently.
+  if (typeof method === 'string' && method.startsWith('notifications/')) {
+    return undefined;
+  }
+  if (id !== undefined && id !== null) {
+    return send(errorReply(id, -32601, `Method not found: ${method}`));
+  }
+  return undefined;
+};
+
+// ── stdio loop ───────────────────────────────────────────────────────────────
+const main = () => {
+  if (!BASE_URL || !API_KEY) {
+    logErr('WARNING: SYSTA_API_BASE_URL and/or SYSTA_API_KEY not set — tool calls will fail.');
+  }
+  logErr(`ready (${TOOLS.length} tools, protocol ${PROTOCOL_VERSION})`);
+
+  let buffer = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let newlineIndex = buffer.indexOf('\n');
+    while (newlineIndex >= 0) {
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = buffer.slice(newlineIndex + 1);
+      if (line) {
+        // Fire-and-forget: each JSON-RPC reply carries its own id.
+        handleMessage(line).catch((err) => logErr(`handler error: ${err.message}`));
+      }
+      newlineIndex = buffer.indexOf('\n');
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+};
+
+// ── CLI (npx systa-mcp [--install-skill|--version|--help]) ───────────────────
+/**
+ * Pakete gomulu istemci SKILL.md'sini ~/.claude/skills/systa/'ya kopyalar.
+ * @param {string} [homeDir] - test/override icin ana dizin; varsayilan os.homedir().
+ * @returns {string} yazilan hedef yol
+ */
+const installSkill = (homeDir) => {
+  const src = path.join(__dirname, 'SKILL.md');
+  if (!fs.existsSync(src)) {
+    throw new Error('Bundled SKILL.md not found in this package');
+  }
+  const dir = path.join(homeDir || os.homedir(), '.claude', 'skills', 'systa');
+  fs.mkdirSync(dir, { recursive: true });
+  const dest = path.join(dir, 'SKILL.md');
+  fs.copyFileSync(src, dest);
+  return dest;
+};
+
+const HELP_TEXT = `systa-mcp ${SERVER_VERSION} — MCP stdio server for SysTa
+
+Usage:
+  systa-mcp                  Run the MCP stdio server (default; used by Claude Code)
+  systa-mcp --install-skill  Copy the bundled SysTa skill to ~/.claude/skills/systa/
+  systa-mcp --version        Print version and exit
+  systa-mcp --help           Show this help
+
+Environment:
+  SYSTA_API_BASE_URL   SysTa API base incl. /api (e.g. https://systa.example.com/api)
+  SYSTA_API_KEY        Scoped API key from your SysTa profile (sk_live_...)
+  SYSTA_VENDOR_CODE    Optional X-Vendor-Code; normally derived from the key
+  SYSTA_MCP_STRICT_TOOLS=1   Hide all action tools if scope can't be resolved (fail-closed)
+
+Register with Claude Code:
+  claude mcp add systa -e SYSTA_API_KEY=sk_live_... \\
+    -e SYSTA_API_BASE_URL=https://systa.example.com/api -- npx -y systa-mcp
+`;
+
+/**
+ * Handle a one-shot CLI command. Returns true if a command was handled (the
+ * stdio server should then NOT start).
+ * @param {string[]} argv - process.argv.slice(2)
+ * @returns {boolean}
+ */
+const runCli = (argv) => {
+  if (argv.includes('--install-skill')) {
+    try {
+      const dest = installSkill();
+      process.stdout.write(`SysTa skill installed -> ${dest}\n`);
+      process.stdout.write('Restart Claude Code (or reload skills) to activate it.\n');
+    } catch (err) {
+      process.stderr.write(`install-skill failed: ${err.message}\n`);
+      process.exitCode = 1;
+    }
+    return true;
+  }
+  if (argv.includes('--version') || argv.includes('-v')) {
+    process.stdout.write(`${SERVER_VERSION}\n`);
+    return true;
+  }
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(HELP_TEXT);
+    return true;
+  }
+  return false;
+};
+
+// stdio dongusu yalnizca dogrudan calistirildiginda baslar; require eden testler
+// internals'a erisir. CLI komutu islendiyse stdio sunucusu baslamaz.
+if (require.main === module) {
+  if (!runCli(process.argv.slice(2))) {
+    main();
+  }
+}
+
+module.exports = {
+  TOOLS,
+  TOOL_MAP,
+  TOOL_REQUIRED_PERMISSION,
+  visibleTools,
+  installSkill,
+  runCli,
+  systaFetch,
+  systaFetchBinary,
+  systaUploadMultipart,
+  handleMessage,
+  shapeCompact,
+  unwrapCapabilities,
+  parseContentDispositionFilename,
+  sanitizeFileName,
+  mimeForFileName,
+  resolveSavePath,
+};