systa-mcp 1.4.0 → 1.5.1

package/README.md

@@ -117,7 +117,7 @@ tam katalog `list_capabilities` ile keşfedilir.
 | `upload_file_to`        | Yerel dosyaları multipart olarak ek diye yükler (talep/proje/görev kartı/orphan) — `file.upload`                                                                                                                                       |
 | `list_capabilities`     | **Bu anahtar ne yapabilir?** — scope-filtreli modül/endpoint kataloğu (yetkisiz endpoint görünmez); her metot için safety class + gereken izin. Ayrıca SysTa platform özeti (overview), TR glossary ve her modülün açıklamasını içerir |
 | `describe_module`       | Bir modülün (örn. request/kanban/plan) amacı, kavramları ve çağrılabilir endpoint'leri — kullanıcı niyetini doğru modüle eşlemek için (oryantasyon)                                                                                    |
-| `describe_endpoint`     | Tek endpoint detayı: alan tipleri (fields), güvenlik sınıfı, açıklama — çağrı gövdesini kurmadan önce                                                                                                                                  |
+| `describe_endpoint`     | Tek endpoint detayı: alan tipleri, güvenlik sınıfı ve tam HTTP Response Contract v2 — çağrı gövdesini kurmadan ve yanıtı zincirlemeden önce                                                                                            |
 
 `systa_api_call` ile, özel bir aracı olmayan herhangi bir endpoint çağrılabilir
 (örn. `POST /requests`, `POST /requests/42/comments`). Anahtarın scope'u dışındaki

package/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 1.4.0
+version: 1.5.1
 name: systa
 description: |
   Drive SysTa (Talep Takip Sistemi / SysTa) — a
@@ -79,7 +79,7 @@ Short shared vocabulary. Use these words with the user; never expose raw REST pa
 | --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Talep                 | Request / ticket    | Core unit of work. Has `title` (min 5), `companyId`, `statusId`, priority, category, assignee, comments, files, relations. Çoğu iş bir talebin etrafında döner. |
 | Durum                 | Status              | Lifecycle state (Açık/Open, Devam Ediyor/In Progress, Tamamlandı/Done). `is_final` durumlar kapanışı temsil eder. Resolved via `GET /api/statuses`.             |
-| Öncelik               | Priority            | normal / high / critical. Belirtilmezse `normal`.                                                                                                               |
+| Öncelik               | Priority            | low / normal / high / urgent / critical. Belirtilmezse `normal`.                                                                                                |
 | Kategori              | Category            | Talep sınıflandırması (catalog/config).                                                                                                                         |
 | Yorum                 | Comment             | Talebe eklenen not/yorum (`commentText` plain string ok).                                                                                                       |
 | Atama                 | Assignment          | `assignedTo` = bir kullanıcı. "bana/üzerime" → mevcut `userId`.                                                                                                 |
@@ -169,9 +169,33 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 You don't memorize 600+ endpoints. Discover on demand.
 
 - **`list_capabilities`** — call when you need to find _which_ module/intent serves the user's verb, or when the user asks "ne yapabilirsin / what can you do". Returns scope-filtered modules (this key's reachable surface), each with a short summary, category, safety class and required permission. Use it to pick the right tool before acting; never claim a capability the catalog doesn't list for this key.
-- **`describe_endpoint`** — call when you've picked a tool and need its exact required fields, body shape, enums and defaults before submitting. Prefer this over guessing a body. It returns the field schema (`fieldKey`, type, required, enum, default) so you can pre-fill dynamic required fields and avoid `VALIDATION_FAILED`.
+- **`describe_endpoint`** — call with both `path` and `method` when you've picked a tool and need its exact required fields, body shape, enums and defaults before submitting. Prefer this over guessing a body. It returns the field schema plus the verified HTTP Response Contract v2 (status, transport, content type, envelope and data/body schema); use returned IDs, handles and pagination fields for the next step instead of guessing them.
+- **`describe_module`** — call after you've mapped the user's intent to a module. Returns the module's purpose, its key concepts, its endpoints, and **`entryPoints`**: the calls that need **no id up front**. A chain always starts at an entry point — calling an id-bearing endpoint first just returns 404/400.
 - **Rule of thumb:** ambiguous intent → `list_capabilities` first; chosen intent but unsure of body → `describe_endpoint`; clear intent + known body → act directly. For REST fallback, the equivalents are `GET /api/api-keys/me/capabilities` (preview of reachable endpoints) and the per-endpoint field schema returned by the MCP `describe_endpoint`.
 
+### Çağrı sırası (prerequisites)
+
+A compact listing marks a method with `hasPrerequisites: true` when it needs an id you must obtain **first**. `describe_endpoint` returns the detail:
+
+```json
+"prerequisites": [
+  {
+    "parameter": "requestId",
+    "collection": "/api/requests",
+    "producedBy": [
+      { "path": "/api/requests", "method": "GET", "field": "id", "evidence": "response-field" }
+    ]
+  }
+]
+```
+
+- `source` is `"path"` when the id goes into the URL, `"body"` when it is a **required body field** (e.g. `POST /api/approvals` requires `requestId` in the body — it never appears in the path).
+- `producedBy` lists the endpoints that **produce** that id; the first candidate carries the strongest evidence.
+- `evidence: "response-field"` — the producer's response contract really contains `field`; chain it directly.
+- `evidence: "collection-path"` — the link comes from the REST path structure (the producer's response schema is dynamic); call the producer and read the id off the returned record.
+
+So the flow is: **user intent → `list_capabilities` (module) → `describe_module` (`entryPoints`) → `describe_endpoint` (fields + `prerequisites`) → walk the chain top-down → perform the action.** Never invent an id; always take it from a producer endpoint.
+
 ## Çekirdek iş akışları (core workflows)
 
 Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from the catalog. Resolve ids first, act, then summarize in the user's language.
@@ -185,7 +209,7 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 
 ### Üzerimdeki işler / talepleri listele (what's on my plate) — `list_requests` → `GET /api/requests`
 
-- "taleplerim / on me" → `assignedTo=<my userId>`. "açık/open" → `openOnly:true`. "geciken/overdue" → `overdue:true` (deadline geçmiş + non-final auto-composed) veya `slaBreached:true` (SLA ihlali). "SLA durumu" → `slaStatus:['breached','active']`. **"dosyalı talepler / eki olan" → `hasAttachments:true`** (top-level talep eki). Deadline'a göre → `deadlineFrom`/`deadlineTo` (YYYY-MM-DD) ya da `deadlineWithinDays:N` (önümüzdeki N gün). Search kapsamını genişlet: `searchIn:['assignee','creator','comments',...]`. **Response boyutu:** `fields` varsayılan `'summary'` (satır başına ~1KB); `'detail'` (description/effort/counts eklenir) veya `'full'` (customFields/stakeHolders dahil, çok büyük). Default `limit=20-50`, sort `created_at desc`. Yanıt zarfı: `{items, total, limit, offset}` — sayfa sayısı `= ceil(total/limit)`. Summarize as a short list (numara + başlık + durum), not raw rows.
+- "taleplerim / on me" → `assignedTo=<my userId>`. "açık/open" → `openOnly:true`. "geciken/overdue" → `overdue:true` (deadline geçmiş + non-final auto-composed) veya `slaBreached:true` (SLA ihlali). "SLA durumu" → `slaStatus:['breached','active']`. **"dosyalı talepler / eki olan" → `hasAttachments:true`** (top-level talep eki). Deadline'a göre → `deadlineFrom`/`deadlineTo` (YYYY-MM-DD) ya da `deadlineWithinDays:N` (önümüzdeki N gün). **`overdue` ile `deadlineWithinDays` birlikte kullanılmaz** — ikisi aynı arka uç parametresine yazar, birlikte verilirse `overdue` kazanır ve diğeri sessizce yok sayılır (zaten ters soruları sorarlar: geçmiş vs. yaklaşan). Search kapsamını genişlet: `searchIn:['assignee','creator','comments',...]`. **Response boyutu:** `fields` varsayılan `'summary'` (satır başına ~1KB); `'detail'` (description/effort/counts eklenir) veya `'full'` (customFields/stakeHolders dahil, çok büyük). Default `limit=20-50`, sort `created_at desc`. Yanıt zarfı: `data.requests[]` + `data.pagination{total, limit, offset, page, totalPages}` — dizinin anahtarı `requests`'tir (`items` DEĞİL) ve ikisi de `data` altındadır. Summarize as a short list (numara + başlık + durum), not raw rows.
 
 ### Talep detayı (show a request) — `get_request` → `GET /api/requests/:requestNumber`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systa-mcp",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "MCP stdio server for SysTa (Talep Takip Sistemi) — lets AI agents (Claude, Codex) use the SysTa REST API via a scoped API key. Zero npm dependencies (native Node).",
   "type": "commonjs",
   "main": "server.js",

package/server.js

@@ -44,16 +44,33 @@ const INSTRUCTIONS = [
   'cagri yine de sunucu tarafinda 403 doner. Bir isi yapmadan ONCE:',
   '  1) `list_capabilities` cagir — anahtarin erisebildigi modul/endpoint katalogunu',
   '     (scope-filtreli) gorursun. GENIS/WILDCARD anahtarda ONCE `list_capabilities({summary:true})`',
-  '     cagir (oryantasyon + modul indeksi, birkac KB; tam katalog yuzlerce KB olabilir), sonra',
+  '     cagir (oryantasyon + modul indeksi, ~57 KB; compact katalog ~483 KB, projeksiyonsuz cagri megabaytlara cikar), sonra',
   '     ilgili modul icin `list_capabilities({module:"<ad>"})` ile derinles. Yetkisiz endpoint listede GORUNMEZ. Yanit AYRICA SysTa',
   '     platform OZETI (overview), TR GLOSSARY, her modulun ACIKLAMASINI (description/concepts)',
   '     ve SENIN kullanicini (user) icerir — "ben / bana ata / uzerimdeki" niyetinde assignedTo',
   '     icin user.id BURADAN gelir. 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.',
+  '  2) `describe_module(module)` — modulun amacini, kavramlarini, cagirabilecegin endpointleri VE',
+  '     `entryPoints`i verir. `entryPoints` ONCEDEN BIR KIMLIK GEREKTIRMEYEN cagrilardir:',
+  '     zincir HER ZAMAN buradan baslar. Kimlik isteyen bir ucu once denemek 404/400 uretir.',
+  '  3) `describe_endpoint(path, method)` cagir — alan tiplerini (fields), guvenlik sinifini,',
+  '     tam HTTP Response Contract v2 bilgisini ve `prerequisites` alanini al.',
+  '',
+  'CAGRI SIRASI (prerequisites) — ONEMLI:',
+  '  Kompakt listede bir metodun `hasPrerequisites: true` olmasi, o ucun ONCE baska bir cagriyla',
+  '  elde edilmesi gereken bir kimlige ihtiyac duydugunu soyler. Ayrintiyi `describe_endpoint`',
+  '  verir:',
+  '    prerequisites: [{ parameter, collection, producedBy: [{ path, method, field?, evidence }] }]',
+  '  - `parameter`  : gereken kimlik (orn. requestId).',
+  "  - `source`     : `path` -> URL'de doldurulur. `body` -> ZORUNLU govde alanidir ve",
+  "                   path'te HIC gorunmez (orn. POST /api/approvals govdesinde requestId).",
+  '  - `producedBy` : o kimligi URETEN uclar. Ilk aday en guclu kanitlidir.',
+  '  - `evidence`   : `response-field` -> uretici ucun yanit semasinda `field` gercekten var,',
+  '                   dogrudan zincirle. `collection-path` -> baglanti REST yapisindan kurulmus;',
+  '                   uretici ucu cagir ve donen kayittan kimligi oku.',
+  '  Yani akis sudur: kullanicinin niyeti -> `list_capabilities` ile MODUL -> `describe_module`',
+  '  ile `entryPoints` -> gereken ucta `describe_endpoint` -> `prerequisites` zincirini yukaridan',
+  '  asagi cagir -> asil islemi yap. Kimlik UYDURMA; her zaman uretici uctan al.',
   '',
   'GUVENLIK SINIFI (safetyClass): read_only (guvenli okuma) | idempotent (tekrarlanabilir)',
   '  | mutating (durum degistirir) | destructive (geri-alinamaz — dikkatli ol, gerekirse onayla).',
@@ -407,6 +424,292 @@ const systaUploadMultipart = async (apiPath, method, filePaths) => {
 const unwrapCapabilities = (res) =>
   res && res.data && res.data.data ? res.data.data : res && res.data;
 
+const capabilityProjectionPath = (projection, filters = {}) => {
+  const query = new URLSearchParams({ projection });
+  for (const [key, value] of Object.entries(filters)) {
+    if (value !== undefined && value !== null && value !== '') {
+      query.set(key, String(value));
+    }
+  }
+  return `/api-keys/me/capabilities?${query.toString()}`;
+};
+
+const RESPONSE_TRANSPORTS = new Set([
+  'json',
+  'binary',
+  'text',
+  'sse',
+  'redirect',
+  'empty',
+  'webhook_ack',
+]);
+const RESPONSE_ENVELOPES = new Set([
+  'systa_success_v1',
+  'systa_error_v1',
+  'raw_json',
+  'legacy_error',
+  'none',
+]);
+const RESPONSE_SCHEMA_TYPES = new Set([
+  'null',
+  'boolean',
+  'object',
+  'array',
+  'number',
+  'integer',
+  'string',
+]);
+const RESPONSE_BINARY_DELIVERY_MODES = new Set(['buffer', 'stream']);
+const isPlainObject = (value) =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const validSchemaVariants = (schema) => {
+  const variants = schema.oneOf || schema.anyOf;
+  if (variants === undefined) {
+    return { valid: true, variants: null };
+  }
+  return {
+    valid:
+      Array.isArray(variants) &&
+      variants.length > 0 &&
+      (!schema.oneOf || typeof schema.branchReason === 'string') &&
+      variants.every(isValidResponseJsonSchema),
+    variants,
+  };
+};
+
+const validSchemaTypes = (schema) => {
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  return {
+    valid: types.length > 0 && types.every((type) => RESPONSE_SCHEMA_TYPES.has(type)),
+    types,
+  };
+};
+
+const validObjectResponseSchema = (schema) => {
+  const properties = schema.properties;
+  const hasProperties = isPlainObject(properties) && Object.keys(properties).length > 0;
+  const dynamic =
+    (schema.additionalProperties === true || isPlainObject(schema.additionalProperties)) &&
+    typeof schema.dynamicReason === 'string';
+  const requiredValid =
+    schema.required === undefined ||
+    (Array.isArray(schema.required) &&
+      schema.required.every((key) => typeof key === 'string' && key in properties));
+  const childrenValid =
+    !hasProperties || Object.values(properties).every(isValidResponseJsonSchema);
+  const additionalValid =
+    !isPlainObject(schema.additionalProperties) ||
+    isValidResponseJsonSchema(schema.additionalProperties);
+  return (hasProperties || dynamic) && requiredValid && childrenValid && additionalValid;
+};
+
+function isValidResponseJsonSchema(schema) {
+  if (!isPlainObject(schema)) {
+    return false;
+  }
+  const variantResult = validSchemaVariants(schema);
+  if (!variantResult.valid) {
+    return false;
+  }
+  if (schema.type === undefined) {
+    return Boolean(
+      variantResult.variants || schema.$ref !== undefined || schema.const !== undefined,
+    );
+  }
+  const typeResult = validSchemaTypes(schema);
+  if (!typeResult.valid) {
+    return false;
+  }
+  if (typeResult.types.includes('array') && !isValidResponseJsonSchema(schema.items)) {
+    return false;
+  }
+  return !typeResult.types.includes('object') || validObjectResponseSchema(schema);
+}
+
+const hasValidResponseBasics = (response) =>
+  isPlainObject(response) &&
+  Number.isInteger(response.status) &&
+  response.status >= 100 &&
+  response.status <= 599 &&
+  RESPONSE_TRANSPORTS.has(response.transport) &&
+  RESPONSE_ENVELOPES.has(response.envelope);
+
+const hasValidResponseContentType = (response) => {
+  const bodyless = response.transport === 'redirect' || response.transport === 'empty';
+  return bodyless
+    ? response.contentType === null && response.envelope === 'none'
+    : typeof response.contentType === 'string' && Boolean(response.contentType.trim());
+};
+
+const hasValidDynamicContentType = (response) => {
+  const hasDynamicMetadata =
+    response.dynamicContentType !== undefined ||
+    response.contentTypePattern !== undefined ||
+    response.contentTypeSource !== undefined;
+  if (response.contentType !== '*/*') {
+    return !hasDynamicMetadata;
+  }
+  if (
+    response.transport !== 'binary' ||
+    response.dynamicContentType !== true ||
+    typeof response.contentTypePattern !== 'string' ||
+    !response.contentTypePattern.trim() ||
+    typeof response.contentTypeSource !== 'string' ||
+    !response.contentTypeSource.trim()
+  ) {
+    return false;
+  }
+  try {
+    new RegExp(response.contentTypePattern);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const hasValidJsonResponseSchema = (response) => {
+  if (response.transport !== 'json' && response.transport !== 'webhook_ack') {
+    return true;
+  }
+  const schema =
+    response.envelope === 'systa_success_v1' ? response.dataSchema : response.bodySchema;
+  return isValidResponseJsonSchema(schema);
+};
+
+const hasValidBinaryMetadata = (response) => {
+  if (response.transport !== 'binary' || response.headers === undefined) {
+    return true;
+  }
+  return (
+    isPlainObject(response.headers) &&
+    (response.headers.contentDisposition === undefined ||
+      typeof response.headers.contentDisposition === 'string')
+  );
+};
+
+const hasValidBinaryDeliveryModes = (response) => {
+  if (response.deliveryModes === undefined) {
+    return true;
+  }
+  return (
+    response.transport === 'binary' &&
+    Array.isArray(response.deliveryModes) &&
+    response.deliveryModes.length > 0 &&
+    new Set(response.deliveryModes).size === response.deliveryModes.length &&
+    response.deliveryModes.every((mode) => RESPONSE_BINARY_DELIVERY_MODES.has(mode))
+  );
+};
+
+const hasValidRedirectMetadata = (response) =>
+  response.transport !== 'redirect' ||
+  (typeof response.locationSource === 'string' && Boolean(response.locationSource.trim()));
+
+const hasValidSseEvents = (response) =>
+  response.transport !== 'sse' ||
+  (Array.isArray(response.events) &&
+    response.events.length > 0 &&
+    response.events.every(
+      (event) =>
+        isPlainObject(event) &&
+        typeof event.name === 'string' &&
+        Boolean(event.name.trim()) &&
+        isValidResponseJsonSchema(event.dataSchema),
+    ));
+
+const isValidResponseVariant = (response) =>
+  hasValidResponseBasics(response) &&
+  hasValidResponseContentType(response) &&
+  hasValidDynamicContentType(response) &&
+  hasValidJsonResponseSchema(response) &&
+  hasValidBinaryMetadata(response) &&
+  hasValidBinaryDeliveryModes(response) &&
+  hasValidRedirectMetadata(response) &&
+  hasValidSseEvents(response);
+
+const isResponseContractV2 = (contract) => {
+  if (
+    !isPlainObject(contract) ||
+    contract.contractVersion !== 2 ||
+    !Array.isArray(contract.responses) ||
+    contract.responses.length === 0 ||
+    !contract.responses.every(isValidResponseVariant)
+  ) {
+    return false;
+  }
+  if (contract.errors === undefined) {
+    return true;
+  }
+  if (!isPlainObject(contract.errors) || !RESPONSE_ENVELOPES.has(contract.errors.envelope)) {
+    return false;
+  }
+  return (
+    contract.errors.statuses === undefined ||
+    (Array.isArray(contract.errors.statuses) &&
+      contract.errors.statuses.every(
+        (status) => Number.isInteger(status) && status >= 400 && status <= 599,
+      ))
+  );
+};
+
+const findCapabilityMethod = (caps, targetPath, targetMethod) => {
+  for (const module of caps.modules || []) {
+    const endpoint = (module.endpoints || []).find((item) => item.path === targetPath);
+    const method =
+      endpoint && (endpoint.methods || []).find((item) => item.method === targetMethod);
+    if (endpoint && method) {
+      return { module, endpoint, method };
+    }
+  }
+  return null;
+};
+
+const responseContractProblem = (responseSchema, targetMethod, targetPath) => {
+  if (responseSchema && responseSchema.contractVersion !== 2) {
+    return `Unsupported response contract version for ${targetMethod} ${targetPath}`;
+  }
+  if (!isResponseContractV2(responseSchema)) {
+    return `Missing or invalid Response Contract v2 for ${targetMethod} ${targetPath}`;
+  }
+  return null;
+};
+
+const describeCapabilityEndpoint = async (args) => {
+  const targetPath = String(args.path || '');
+  const targetMethod = String(args.method || '').toUpperCase();
+  const res = await systaFetch(
+    'GET',
+    capabilityProjectionPath('endpoint', { path: targetPath, method: targetMethod }),
+  );
+  if (!res.ok) {
+    return res;
+  }
+  const found = findCapabilityMethod(unwrapCapabilities(res), targetPath, targetMethod);
+  if (!found) {
+    return {
+      ok: false,
+      error: `Endpoint not found or not permitted for this key: ${targetMethod} ${targetPath}`,
+    };
+  }
+  const contractProblem = responseContractProblem(
+    found.method.responseSchema,
+    targetMethod,
+    targetPath,
+  );
+  if (contractProblem) {
+    return { ok: false, error: contractProblem };
+  }
+  const { responseSchema, ...methodDetail } = found.method;
+  return {
+    module: found.module.module,
+    path: found.endpoint.path,
+    summary: found.endpoint.summary,
+    ...methodDetail,
+    responseContract: responseSchema,
+    responseContractStatus: 'verified',
+  };
+};
+
 /**
  * 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).
@@ -444,7 +747,8 @@ const shapeCompact = (caps) => ({
         method: mm.method,
         safetyClass: mm.safetyClass,
         requiredPermission: mm.requiredPermission,
-        hasFields: Boolean(mm.fields),
+        hasFields: Boolean(mm.hasFields || mm.fields),
+        hasResponseContract: Boolean(mm.hasResponseContract || mm.responseSchema),
       })),
     })),
   })),
@@ -453,8 +757,9 @@ const shapeCompact = (caps) => ({
 /**
  * Index-only view: orientation (overview/glossary/user) + module names with
  * endpoint COUNTS, but NO per-endpoint detail. For a wildcard '*' key the full
- * compact catalog is ~250KB (26 modules / 698 endpoints) which overflows agent
- * buffers; this summary is a few KB. Drill into one module with module='x'.
+ * compact catalog is ~483KB (69 modules / 1663 endpoint-methods, olculdu 2026-08-30)
+ * which overflows agent buffers; this summary is ~57KB. Drill into one module with
+ * module='x' (~54KB) or straight to describe_endpoint (~22KB).
  */
 const shapeSummary = (caps) => ({
   sessionType: caps.sessionType,
@@ -468,11 +773,16 @@ const shapeSummary = (caps) => ({
   moduleCount: caps.moduleCount,
   endpointCount: caps.endpointCount,
   hint: 'Summary view — endpoints omitted. Call list_capabilities({module:"<name>"}) or describe_module to see a module\'s endpoints.',
-  modules: (caps.modules || []).map((m) => ({
-    module: m.module,
-    ...(m.description ? { description: m.description } : {}),
-    endpointCount: (m.endpoints || []).length,
-  })),
+  modules: (caps.modules || []).map((m) => {
+    const paths = m.endpoints || [];
+    const methodCount = paths.reduce((sum, endpoint) => sum + (endpoint.methods || []).length, 0);
+    return {
+      module: m.module,
+      ...(m.description ? { description: m.description } : {}),
+      pathCount: m.pathCount ?? paths.length,
+      endpointCount: m.endpointCount ?? (methodCount || paths.length),
+    };
+  }),
 });
 
 const shapeOneModule = (caps, target) => {
@@ -784,7 +1094,7 @@ const MODULE_GATE_NOTE =
 const TOOLS = [
   {
     name: 'list_requests',
-    description: `List/search SysTa requests (talepler) with pagination and rich filters: status, assignee, company, category, department, priority, free-text, OVERDUE / SLA / DEADLINE. Common intents: 'uzerimdeki acik isler / my open work' => assignedTo=<me> + openOnly:true (excludes final statuses). 'geciken isler / overdue' => overdue:true (deadline gecmis + non-final) OR slaBreached:true (SLA ihlali). 'bu ay kapatilan' => finalOnly:true + completedFrom/completedTo (NOT YET SUPPORTED — use systa_api_call). search covers title/requestNumber/description/externalRef by default (NOT assignee/creator); use searchIn to expand. Multiple statuses: statusId can be an array [1,3,5]. Returns only requests the API key scope permits. Response envelope: {items:[], total, limit, offset} — totalPages = ceil(total/limit). RESPONSE SIZE: fields controls how much each row carries -- default 'summary' returns lightweight rows (~1KB each: id, requestNumber, title, statusName, priority, assignedTo, deadline, isOverdue, slaStatus, commentCount, fileCount). Use fields:'detail' when you need description/effort/counts, or fields:'full' for everything incl. customFields/stakeHolders (LARGE — S-A2 kanit: 44 talep tam moduyla ~300KB).${MASKING_NOTE}${EMPTY_SCOPE_NOTE}`,
+    description: `List/search SysTa requests (talepler) with pagination and rich filters: status, assignee, company, category, department, priority, free-text, OVERDUE / SLA / DEADLINE. Common intents: 'uzerimdeki acik isler / my open work' => assignedTo=<me> + openOnly:true (excludes final statuses). 'geciken isler / overdue' => overdue:true (deadline gecmis + non-final) OR slaBreached:true (SLA ihlali). 'bu ay kapatilan' => finalOnly:true + completedFrom/completedTo (NOT YET SUPPORTED — use systa_api_call). search covers title/requestNumber/description/externalRef by default (NOT assignee/creator); use searchIn to expand. Multiple statuses: statusId can be an array [1,3,5]. Returns only requests the API key scope permits. Response envelope: data.requests[] + data.pagination{total,limit,offset,page,totalPages} — the array key is 'requests' (NOT 'items') and both live under 'data'. Verified against the endpoint Response Contract v2 (required: [requests, pagination]). RESPONSE SIZE: fields controls how much each row carries -- default 'summary' returns lightweight rows (~1KB each: id, requestNumber, title, statusName, priority, assignedTo, deadline, isOverdue, slaStatus, commentCount, fileCount). Use fields:'detail' when you need description/effort/counts, or fields:'full' for everything incl. customFields/stakeHolders (LARGE — S-A2 kanit: 44 talep tam moduyla ~300KB).${MASKING_NOTE}${EMPTY_SCOPE_NOTE}`,
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -852,7 +1162,8 @@ const TOOLS = [
         overdue: {
           type: 'boolean',
           description:
-            'true => geciken/overdue: deadline in the past AND not in a final status. Shorthand for deadlineDaysRemaining[operator]=lt&deadlineDaysRemaining[value]=0 combined with openOnly.',
+            'true => geciken/overdue: deadline in the past AND not in a final status. Shorthand for deadlineDaysRemaining[operator]=lt&deadlineDaysRemaining[value]=0 combined with openOnly. ' +
+            'MUTUALLY EXCLUSIVE with deadlineWithinDays (same backend parameter pair); when both are set, overdue WINS.',
         },
         slaStatus: {
           type: 'array',
@@ -879,7 +1190,10 @@ const TOOLS = [
         deadlineWithinDays: {
           type: 'integer',
           description:
-            'Deadline within N days from now (i.e. deadlineDaysRemaining[operator]=lte,value=N).',
+            'Deadline within N days from now (i.e. deadlineDaysRemaining[operator]=lte,value=N). ' +
+            'MUTUALLY EXCLUSIVE with overdue: both map to the same backend parameter pair, so ' +
+            'if overdue is also set this one is IGNORED. Pick one — they ask opposite questions ' +
+            '(already late vs. due soon).',
         },
         fields: {
           type: 'string',
@@ -3151,7 +3465,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       'shown), each with its HTTP methods, safety class (read_only/idempotent/mutating/' +
       'destructive) and required permission. Also returns SysTa overview, TR glossary and your ' +
       'user (who-am-i). Call this FIRST. For a broad key the full catalog can be large: pass ' +
-      'summary=true to get only orientation + module names with endpoint counts (a few KB), then ' +
+      'summary=true to get only orientation + module names with endpoint counts (~57KB vs ~483KB compact), then ' +
       `pass module="<name>" to drill into one module. No args = full compact catalog.${MODULE_GATE_NOTE}`,
     inputSchema: {
       type: 'object',
@@ -3169,7 +3483,13 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       },
     },
     handler: async (args) => {
-      const res = await systaFetch('GET', '/api-keys/me/capabilities');
+      let projectionPath = capabilityProjectionPath('compact');
+      if (args && args.module) {
+        projectionPath = capabilityProjectionPath('module', { module: args.module });
+      } else if (args && args.summary) {
+        projectionPath = capabilityProjectionPath('summary');
+      }
+      const res = await systaFetch('GET', projectionPath);
       if (!res.ok) {
         return res;
       }
@@ -3187,7 +3507,7 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
     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 ' +
+      'the endpoints THIS key can call within it (path + summary + method/safety), and entryPoints — the calls that need NO id up front, i.e. where a chain starts. 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: {
@@ -3199,7 +3519,10 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
       },
     },
     handler: async (args) => {
-      const res = await systaFetch('GET', '/api-keys/me/capabilities');
+      const res = await systaFetch(
+        'GET',
+        capabilityProjectionPath('module', { module: args.module }),
+      );
       if (!res.ok) {
         return res;
       }
@@ -3217,6 +3540,9 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
         module: mod.module,
         description: mod.description,
         concepts: mod.concepts,
+        // Zincirin BASI: kimlik gerektirmeyen uclar. Kullanicinin niyeti bu module
+        // dustuyse ilk cagri bunlardan biridir; donen kimlikler sonraki adimlari besler.
+        entryPoints: mod.entryPoints,
         endpoints: (mod.endpoints || []).map((e) => ({
           path: e.path,
           summary: e.summary,
@@ -3224,6 +3550,8 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
             method: mm.method,
             safetyClass: mm.safetyClass,
             requiredPermission: mm.requiredPermission,
+            // true ise once describe_endpoint ile onkosullari oku.
+            hasPrerequisites: mm.hasPrerequisites,
           })),
         })),
       };
@@ -3232,14 +3560,14 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
   {
     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 ' +
+      'Get full detail for one capability: input field types (fields), full HTTP Response ' +
+      'Contract v2 (status, transport, content type, envelope and data/body schema), safety class, ' +
+      'required permission, prerequisites (which id this call needs FIRST and which endpoint produces it), 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'],
+      required: ['path', 'method'],
       properties: {
         path: {
           type: 'string',
@@ -3248,41 +3576,11 @@ The number is the request number for "#", and the card's GLOBAL id for "##" (NOT
         method: {
           type: 'string',
           enum: ALLOWED_METHODS,
-          description: 'Optional HTTP method to disambiguate',
+          description: 'HTTP method; required so multi-method paths are never selected ambiguously',
         },
       },
     },
-    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}`,
-      };
-    },
+    handler: describeCapabilityEndpoint,
   },
 
   // ══════════════════════════════════════════════════════════════════════════
@@ -4191,7 +4489,7 @@ let allowedPermissionsPromise = null;
 // 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');
+    const res = await systaFetch('GET', capabilityProjectionPath('compact'));
     if (!res || !res.ok) {
       return null;
     }