systa-mcp 1.0.0 → 1.0.8

package/README.md

@@ -9,7 +9,47 @@ ile SysTa REST API'sini "araç" olarak kullanmasını sağlar.
   `Authorization: Bearer <key>` + `X-Vendor-Code` ile isteği proxy'ler; anahtarın kapsamı
   dışındaki çağrılar backend tarafından `403` ile reddedilir.
 
-## Kurulum
+## Hızlı Başlangıç (AI İstemci)
+
+Harici bir AI istemciyi (Claude Code, MCP uyumlu ajan vb.) SysTa'ya bağlamak için
+aşağıdaki adımları izleyin.
+
+### 1. API Anahtarı Oluşturun
+
+SysTa'da **Ayarlar > API Anahtarları** sayfasından scoped API key oluşturun.
+Anahtar yalnızca oluşturma anında gösterilir — güvenli bir yerde saklayın.
+
+### 2. Claude Code'a MCP Sunucusunu Ekleyin
+
+```bash
+claude mcp add systa \
+  -e SYSTA_API_KEY=sk_live_ANAHTARINIZ \
+  -e SYSTA_API_BASE_URL=https://systa.vizyoneks.com.tr/api \
+  -- npx -y systa-mcp
+```
+
+### 3. Skill'i Yükleyin
+
+```bash
+npx -y systa-mcp --install-skill
+```
+
+### 4. Doğrulama
+
+```bash
+# Kimlik kontrolü
+curl -H "Authorization: Bearer sk_live_..." https://systa.vizyoneks.com.tr/api/auth/me
+
+# Yetenek kataloğu
+curl -H "Authorization: Bearer sk_live_..." https://systa.vizyoneks.com.tr/api/api-keys/me/capabilities
+```
+
+Her iki endpoint de `200` dönüyorsa bağlantı hazırdır. `.env.example` dosyasını
+referans olarak kullanabilirsiniz (`cp .env.example .env` ile kopyalayıp doldurun).
+
+---
+
+## Kurulum (Detaylı)
 
 Anahtarı SysTa'da **Ayarlar → API Anahtarları → Yeni Anahtar** ile üretin (scope'ları
 seçin; anahtar yalnızca o anda gösterilir). Anahtar **self-routing**'tir: vendor bilgisi
@@ -34,12 +74,12 @@ npx -y systa-mcp --install-skill   # -> ~/.claude/skills/systa/SKILL.md
 
 ### Çevre değişkenleri
 
-| Değişken                 | Örnek                           | Açıklama                                                                                            |
-| ------------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `SYSTA_API_BASE_URL`     | `https://systa.example.com/api` | API kök adresi (`/api` dahil), nötr host                                                            |
-| `SYSTA_API_KEY`          | `sk_live_<vendor>_...`          | Profilden üretilen anahtar (bir kez gösterilir)                                                     |
-| `SYSTA_VENDOR_CODE`      | `vizyoneks`                     | OPSIYONEL — verilirse anahtarın vendor'ıyla aynı olmalı; boş bırakılırsa backend anahtardan türetir |
-| `SYSTA_MCP_STRICT_TOOLS` | `1`                             | OPSIYONEL — kapsam çözülemezse tüm aksiyon araçlarını gizle (fail-closed)                           |
+| Değişken                 | Örnek                           | Açıklama                                                                                                                                                 |
+| ------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SYSTA_API_BASE_URL`     | `https://systa.example.com/api` | API kök adresi (`/api` dahil), nötr host                                                                                                                 |
+| `SYSTA_API_KEY`          | `sk_live_<vendor>_...`          | Profilden üretilen anahtar (bir kez gösterilir)                                                                                                          |
+| `SYSTA_VENDOR_CODE`      | `vizyoneks`                     | OPSIYONEL — verilirse anahtarın vendor'ıyla aynı olmalı; boş bırakılırsa backend anahtardan türetir                                                      |
+| `SYSTA_MCP_STRICT_TOOLS` | `1`                             | OPSIYONEL — kapsam çözülemezse tüm aksiyon araçlarını gizle. Değer TAM olarak `1` olmalı; aksi halde fail-open (kapsam çözülemese de araçlar gösterilir) |
 
 ### Yerel geliştirme / yerel klona karşı
 

package/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 0.1.0
+version: 1.0.8
 name: systa
 description: |
   Drive SysTa (Talep Takip Sistemi / SysTa) — a
@@ -48,7 +48,7 @@ Before any SysTa action, confirm connectivity, auth and identity. Do this once p
    If there is no MCP server, fall back to the REST API with a scoped API key. The key is **never typed into chat** — read it from the environment / a local secret file:
 
    ```bash
-   : "${SYSTA_BASE_URL:?set SYSTA_BASE_URL, e.g. https://<vendor>.systa.example.com}"
+   : "${SYSTA_API_BASE_URL:?set SYSTA_API_BASE_URL, e.g. https://systa.example.com/api}"
    : "${SYSTA_API_KEY:?export a scoped sk_live_... key (do not paste in chat)}"
    ```
 
@@ -56,7 +56,7 @@ Before any SysTa action, confirm connectivity, auth and identity. Do this once p
 
    ```bash
    curl -fsS -H "Authorization: Bearer $SYSTA_API_KEY" \
-     "$SYSTA_BASE_URL/api/auth/me"
+     "$SYSTA_API_BASE_URL/auth/me"
    ```
 
    Capture: `userId`, `companyId` (default company), `vendorSchema`, and the permission/scope set. If this returns `401`/`403` or `API key not found`, stop and tell the user the key is missing/expired/over-scoped — do **not** guess credentials.
@@ -87,13 +87,55 @@ Short shared vocabulary. Use these words with the user; never expose raw REST pa
 | Sürüm                 | Release             | Yazılım sürüm yönetimi: liste → item → onay → Go/No-Go → deployment workflow.                                                                                   |
 | Vendor şema           | Vendor schema       | Multi-tenant izolasyon; her vendor ayrı schema (`vendor_xxx`). Public referans alınmaz.                                                                         |
 
+### Anahtar kelime → modül eşlemesi (keyword index)
+
+Kullanıcının doğal-dil kelimesini doğru modüle hızlı eşle. Bu, MCP `list_capabilities`
+yanıtındaki `glossary` alias'larının ayna kopyasıdır (MCP yokken de geçerli). Alias'lar
+ASCII'dir — eşleştirmede aksanı yok say. Modülü bulduktan sonra `describe_module(modül)`
+veya `describe_endpoint` ile gövdeyi netleştir.
+
+| Doğal dil (alias)                                         | Modül           | Birincil giriş                                  |
+| --------------------------------------------------------- | --------------- | ----------------------------------------------- |
+| talep, talepler, is, destek talebi                        | request         | list_requests / create_request                  |
+| gorev, task, kart, card                                   | kanban          | manage_request_card / move_request_card         |
+| pano, board, kanban / kolon, column, asama, liste         | kanban          | get_request_board                               |
+| efor, durum, oncelik, atanan, planla, denetim, gecmis     | request         | get_request / list_requests                     |
+| proje, klonla                                             | project         | list_projects / create_project                  |
+| onaya sunma, snapshot, sprint, sprinti kapat, optimize et | plan            | submit_plan_for_approval / create_plan_baseline |
+| onay, onayla, reddet                                      | approvals       | list_pending_approvals / respond_to_approval    |
+| sla, sure taahhudu                                        | sla             | (sla endpoints)                                 |
+| release, surum, go/no-go, deployment                      | release         | create_release_list / add_release_item          |
+| musaitlik, izin (leave), vekil                            | user/automation | systa_api_call /user-availability, /user-leaves |
+| vendor, sirket, musteri                                   | company         | systa_api_call GET /companies                   |
+| organizasyon birimi, departman, bolum, birim              | department      | GET /api/departments                            |
+| takim, ekip, team                                         | team            | GET /api/teams                                  |
+| yetki paketi, izin (permission)                           | security        | (bundle/permission endpoints)                   |
+| alt form, sub-form                                        | forms           | systa_api_call GET /forms/:id                   |
+| rapor, raporlama, disa aktar, export, excel, csv          | report          | systa_api_call /reports/preview,/reports/export |
+| ozel sorgu, sorgu, query builder, ad-hoc, veri cek        | query-builder   | querybuilder_describe_fields / \_execute_query  |
+| hesap tablosu, gridpad, tablo, excel, spreadsheet, hucre  | spreadsheet     | GET /api/spreadsheets                           |
+| dosya, ek, attachment, yukle, upload, indir, download     | file            | upload_file_to / download_request_file          |
+| bildirim, notification, uyari, okundu, push               | notification    | GET /api/notifications                          |
+| yetenek, beceri, skill, otomatik etiketleme               | skill           | GET /api/skills                                 |
+| duyuru, announcement, bildiri, ilan                       | announcement    | GET /api/announcements                          |
+| urun guncellemesi, surum notu, yenilikler, changelog      | product-update  | GET /api/product-updates                        |
+| not, kisisel not, hatirlatma                              | note            | GET /api/dashboard/notes                        |
+| yer imi, favori, bookmark, kisayol                        | bookmark        | GET /api/dashboard/bookmarks                    |
+| degerlendirme, puanlama, anket, memnuniyet, geri bildirim | ratings         | POST /api/ratings                               |
+| github, repo, pull request, commit, entegrasyon           | github          | GET /api/github/connection                      |
+| gosterge paneli, dashboard, widget, ozet, grafik, panel   | dashboard       | GET /api/dashboard/init                         |
+
+> Bu tablo, katalogdaki ~25 modülün kullanıcı-yüzeyli olanlarından bir alt küme kapsar. Listede olmayan
+> bir kelime için `list_capabilities` çağır — anahtarının erişebildiği güncel modül/alias
+> kümesini döndürür (kapsam-filtreli; yetkisiz modül görünmez).
+
 ## UX Rules
 
 1. **Be concise; summarize.** No raw IDs, no JSON dumps in chat. Report "Talep #1423 açıldı — 'Login hatası', sana atandı" / "Request #1423 created and assigned to you." Surface a stable handle the user recognizes (talep numarası, başlık), not internal uuids.
 2. **No jargon.** Don't narrate "calling describe_endpoint", "POST /api/requests", "resolving statusId". Speak in the product's user verbs.
 3. **Detect language and reply in it.** If the user writes Turkish, answer in Turkish; if English, English. Field keys and enum values passed to the API stay as the API expects (`statusKey`, `priority=high`) — only the conversation is localized.
 4. **Smart defaults + ask one thing at a time.** Apply opinionated defaults from the intent summary (`channel='API'`, `priority='normal'`, assignee=self for "bana", `strategy='any_one'`/`'all_required'` per module). Ask **one** genuinely-missing thing, never a batch ("ver bana başlık, şirket, durum, öncelik, kategori" YASAK). Never invent a `title`, a password, a webhook URL, or a secret — ask for those.
-5. **Resolve dynamic required fields up front.** Before a create/mutation, resolve the entity's required fields _for this vendor_ (e.g. `statusId` via `GET /api/statuses`, `companyId` from `who-am-i`, approver name → `userId` via user lookup). Don't submit a half-filled body and let it 400 — pre-resolve, then submit. Forms with dynamic schemas: pull the schema first (`get_form_schema`) so required fields are known.
+5. **Resolve dynamic required fields up front.** Before a create/mutation, resolve the entity's required fields _for this vendor_ (e.g. `statusId` via `GET /api/statuses`, `companyId` from `who-am-i`, approver name → `userId` via user lookup). Don't submit a half-filled body and let it 400 — pre-resolve, then submit. Forms with dynamic schemas: pull the schema first (via `systa_api_call`, e.g. `GET /forms/:id`) so required fields are known.
 6. **Safety tiers gate confirmation.** `read_only` → just do it. `mutating`/`idempotent` → do it, then report. **`destructive`** (revoke access, delete, hard removal) and live side-effecting actions (publish, send invite, advance release workflow, test webhook) → show a one-line "şunu yapacağım" and get an explicit OK first. Publishing (announcement/release notes/product update) is **never** auto-published — show a summary, get approval.
 7. **Don't over-ask scope.** `companyId`/`userId`/`vendorSchema` come from `who-am-i`; don't ask the user for them when a single sane value exists.
 
@@ -143,13 +185,13 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 
 - List: `GET /api/projects` (default `page=1, limit=20`, recent first). "durum/sağlık" → combine `health-score` + `risk-score` + `sla-status` into one summary.
 
-### Kanban kart ekle (add a task card) — `create_kanban_card` → `POST /api/task-boards/:boardId/cards`
+### Kanban kart ekle (add a task card) — `manage_request_card` (create)
 
-- `boardId` is always tied to a `requestId` — first resolve the board via the request's kanban hierarchy (`GET /api/requests/:requestId/kanban/hierarchy`). Defaults: first/entry column if `columnId` omitted, `priority='normal'`, unassigned unless "bana ata", `cardTitle` min 3 chars (ask to clarify if shorter).
+- `boardId` is always tied to a `requestId` — first resolve the board (`get_request_board`, or `GET /api/requests/:requestId/kanban/hierarchy`). Defaults: first/entry column if `columnId` omitted, `priority='normal'`, unassigned unless "bana ata", `cardTitle` min 3 chars (ask to clarify if shorter). `manage_request_card` handles create / update / complete (the action is in the body) — call `describe_endpoint` if unsure of the fields.
 
-### Kartı taşı / tamamla (move / complete card) — `move_kanban_card` / `complete_kanban_card`
+### Kartı taşı / tamamla (move / complete card) — `move_request_card` / `manage_request_card`
 
-- Move: `PUT /api/task-boards/:boardId/cards/:cardId/move`; resolve the target column name → `columnId` from board detail; append to end if no position given. Complete: `PUT .../complete` — server sets `isCompleted=true`, 100%.
+- Move: `move_request_card` — resolve the target column name → `columnId` from the board detail; append to end if no position given. Complete: `manage_request_card` with the complete action — server sets `isCompleted=true`, 100%.
 
 ### Onaya sun / onayla / bekleyenler (approvals)
 
@@ -157,13 +199,13 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 - Respond: `respond_to_approval` → `POST /api/approvals/responses/:id/respond`; "onayla"→`approved`, "reddet"→`rejected` (rette kısa sebep iste, zorunlu değil).
 - Pending: `list_pending_approvals` → `GET /api/approvals/requests-awaiting` (mevcut kullanıcının onayını bekleyenler).
 
-### İzin talebi (leave) — `create_leave_request` → `POST /api/user-leaves`
+### İzin talebi (leave) — `systa_api_call` `POST /user-leaves` (no named tool)
 
-- `userId`=self (sormadan), `leaveType='annual'`, `isHalfDay=false`, dates normalized to `YYYY-MM-DD` ("yarın/cuma" → tarih), `returnToWorkDate` = next working day after end. "izinlerim" → `list_leaves` with `userId=self`.
+- No dedicated tool — drive via `systa_api_call`. `userId`=self (sormadan), `leaveType='annual'`, `isHalfDay=false`, dates normalized to `YYYY-MM-DD` ("yarın/cuma" → tarih), `returnToWorkDate` = next working day after end. "izinlerim" → `systa_api_call` `GET /user-leaves/me`. Needs the `user.leave.self` scope.
 
-### Rapor al / dışa aktar (report) — `preview_report` / `export_report`
+### Rapor al / dışa aktar (report) — `systa_api_call` (no named tool)
 
-- Önce önizle (`POST /api/reports/preview`, read-only), sonra dışa aktar (`POST /api/reports/export`, `format='xlsx'` unless "csv"). `reportType` is the required pivot (request/sla/user/organization/project/lifecycle/subform) — infer from intent. Resolve columns via `GET /api/reports/columns` if the user only named a type. "bu ay/geçen ay" → dynamic date filter.
+- No dedicated tool — drive via `systa_api_call`. Önce önizle (`POST /reports/preview`, read-only), sonra dışa aktar (`POST /reports/export`, `format='xlsx'` unless "csv"). `reportType` is the required pivot (request/sla/user/organization/project/lifecycle/subform) — infer from intent. Resolve columns via `GET /reports/columns` if the user only named a type. "bu ay/geçen ay" → dynamic date filter. (For ad-hoc/free queries prefer the `querybuilder_*` tools.)
 
 ### Sürüm oluştur (release) — `create_release_list` → `POST /api/releases/lists`
 
@@ -179,9 +221,46 @@ SysTa returns structured errors. Recover deterministically instead of giving up.
    - If it's genuinely user-owned (a `title`, a date, an approver name, a secret), **ask the user for exactly that field** — quote the human-friendly meaning, not the raw key.
    - Retry once after a fix. If it fails again with the same field, surface it to the user rather than looping.
 2. **`UNEXPECTED_FILE_FIELD` / `UNKNOWN_PARAM`** — you sent a flag/field the endpoint doesn't accept. Re-check with `describe_endpoint` and drop it. (Web/UI-only fields aren't valid on the API surface.)
-3. **`404` on a `:requestNumber` / `:id`** — the handle didn't resolve. Run the matching list/search (`list_requests`, `list_projects`, `list_users?search=`, `search_tags`) to map name/number → id, then retry. Never hard-code an id.
-4. **ID resolution chain (general).** Most mutations need an id the user gave you as a name: company → `list_companies`, team → `list_teams` (name→`teamCode`), user → `list_users?search=` (name→`userId`, "ben/bana"→self), status → `GET /api/statuses` (name→`statusId`), tag → `search_tags`, board → request's kanban hierarchy (requestId→`boardId`→`columnId`). Resolve first, act second.
+3. **`404` on a `:requestNumber` / `:id`** — the handle didn't resolve. Run the matching list/search (`list_requests`, `list_projects`, or `systa_api_call` `GET /users?search=`, `GET /tags/search`) to map name/number → id, then retry. Never hard-code an id.
+4. **ID resolution chain (general).** Most mutations need an id the user gave you as a name. There are NO dedicated lookup tools — use `systa_api_call`: company → `GET /companies`, team → `GET /teams` (name→`teamCode`), user → `GET /users?search=` (name→`userId`, "ben/bana"→self via who-am-i), status → `GET /statuses` (name→`statusId`), tag → `GET /tags/search`, board → request's kanban hierarchy (`get_request_board`; requestId→`boardId`→`columnId`). Resolve first, act second.
 5. **`401/403`** — expired or out-of-scope key. Don't retry blindly; tell the user the auth/permission problem (in their language) and stop. For `403 permission`, name the capability the key lacks; don't attempt a privilege workaround.
 6. **`409 conflict`** (optimistic concurrency on cards/edits) — re-read the entity to get the latest `updatedAt`, then retry the mutation once with the fresh value; warn the user only if it conflicts again.
 7. **Dual-path "list vs create" endpoints** (e.g. `POST /api/sla/definitions`, `POST /api/sla/standby-configs`) — an empty/filter-only body lists; a full body creates. Choose the body shape that matches the intent; don't accidentally create when the user asked to list.
 8. **Multi-tenant safety.** Never carry an id across vendors. If a resolved id isn't found in the caller's vendor scope, treat it as not-found (step 3), not as a public-schema fallback.
+
+## DX / Keşif Notları (talep 166 — prod'da doğrulanmış)
+
+Gerçek AI kullanımında tespit edilen sürtünme noktaları; her biri canlı doğrulandı.
+
+### Cevap boyutu / kompaktlık
+
+- **Liste uçları ağırdır.** Geniş/wildcard anahtarda önce `list_capabilities({summary:true})` (oryantasyon, birkaç KB), sonra `list_capabilities({module:"<ad>"})` ile derinleş.
+- **Yalnızca SAYI gerekiyorsa** tüm veriyi çekme: `list_*` araçlarını `limit=1` ile çağır, `pagination.total` oku.
+
+### /api ön-eki
+
+- `systa_api_call` base'i zaten `/api` içerir. Katalog yolları `/api/...` gösterse de path `/requests` ya da `/api/requests` olabilir — baştaki tek `/api` otomatik strip edilir.
+
+### Analitik / rapor / agregasyon (ham veri çekip elle hesaplama)
+
+- `querybuilder_execute_query` server-side groupBy/aggregations yapar (queryConfig: `fields`/`groupBy`/`aggregations:[{field,function}]`/`having`).
+- HAZIR PIVOT: `reports/preview` (reportType=user/request/sla/organization/project/lifecycle) per-satır pivot/ortalama döner — örn. reportType=user → kullanıcı başına `avgResolutionHours`/`totalResolved`/`slaSuccessRate`.
+- Proje metrikleri: `get_project_analytics` + `get_project_health`; plan: `get_plan_critical_path`.
+
+### Talep açma — `description` = ilk yorum (commentNo 1)
+
+- Verdiğin `description` talebin **ilk yorumu** olarak materyalize edilir.
+- **Tablo/zengin içerik** için: `systa_api_call POST /requests` ile `descriptionJson` alanına TipTap doc (tablo dahil) gönder — bu da comment #1 olur. **Ayrıca ayrı yorum EKLEME** (çift yorum olur). İçeriği yalnız ayrı yorumda istiyorsan `description` boş bırak.
+
+### Kanban
+
+- Talep listesindeki `taskCount` ile kanban kart sayısı **farklı olabilir** (subtask/arşiv/parent kapsamı). Kesin liste/sayım için `get_request_board` (full board) otoritedir.
+- **Tamamlanma zamanı:** `completedAt`/`completedBy` yalnız full board'da gelir; lightweight `cards/list` bunları İÇERMEZ (yalnız `isCompleted`). Süre/performans analizinde full board kullan.
+
+### Plan modları
+
+- `POST/PUT /plan/modes` filtreleme **mod değil her BOARD içindeki** `filterCriteria` ile yapılır. Geçerli anahtarlar: `assignedTo`, `statusId`/`excludeStatusId`, `projectId` (id dizileri), `includeStakeholderRequests` (bool). describe opak gösterir; emin değilsen mevcut bir modu `GET /plan/modes` ile incele.
+
+### Proje alt-ağacı
+
+- Kök projenin tüm alt projelerini kapsamak için önce hiyerarşiyi al (`get_project`/`list_projects`), kök + tüm alt-proje id'lerini `projectId` DİZİSİ olarak geç.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systa-mcp",
-  "version": "1.0.0",
+  "version": "1.0.8",
   "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

@@ -29,7 +29,9 @@ const path = require('node:path');
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_NAME = 'systa-mcp';
-const SERVER_VERSION = '1.0.0';
+// Tek kaynak: surum package.json'dan okunur (drift onleme — server.js/SKILL.md/package.json
+// ayni surumu gosterir). npm yayinlanan pakete package.json'i daima dahil eder.
+const SERVER_VERSION = require('./package.json').version;
 
 // Server-seviye rehber — her oturumda AI ajanin context'ine girer (kisa tutulur).
 // Ajana SysTa'yi nasil kesfedip kullanacagini ogretir; detay lazy araclardadir.
@@ -41,9 +43,12 @@ const INSTRUCTIONS = [
   '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...)',
+  '     (scope-filtreli) gorursun. GENIS/WILDCARD anahtarda ONCE `list_capabilities({summary:true})`',
+  '     cagir (oryantasyon + modul indeksi, birkac KB; tam katalog yuzlerce KB olabilir), 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.',
@@ -70,7 +75,38 @@ const INSTRUCTIONS = [
   '  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.',
+  '  govdeyi describe_endpoint ciktisindan kur (path icin /api on-eki opsiyonel, otomatik normalize edilir).',
+  '',
+  'RAPOR / SAYIM / DAGILIM / TOPLAMA niyetinde: list_requests`i elle sayfalayip client-side TOPLAMA YAPMA.',
+  '  Sunucu-tarafli rapor araclari VARDIR: querybuilder_ai_generate_query (dogal dil -> sorgu),',
+  '  querybuilder_execute_query (server-side groupBy/sayim/filtre), querybuilder_describe_fields,',
+  '  querybuilder_saved_query, querybuilder_schedule_report. Proje metrikleri icin get_project_analytics',
+  '  (burndown/velocity/cumulative-flow...) ve get_project_health (saglik/risk/sla). Plan icin',
+  '  get_plan_critical_path. Bunlar katalogda da var — once list_capabilities ile dogrula.',
+  '  HAZIR PIVOT: reports/preview (reportType=user|request|sla|organization|project|lifecycle)',
+  '  sunucu-tarafli pivot/ortalama dondurur — orn. reportType=user kullanici basina',
+  '  avgResolutionHours/totalResolved/slaSuccessRate verir; "ortalama cozum suresi / kim kaç /',
+  '  dağılım" gibi sorularda ham veri cekip elle hesaplama, bu pivotu kullan.',
+  '  Yalnizca SAYI gerekiyorsa (kac kayit) tum veriyi cekme: list_* araclarini limit=1 ile',
+  '  cagir ve donen pagination.total degerini oku.',
+  '',
+  'KANBAN (gorev panosu): bir talebin taskCount`u (talep listesinde) ile kanban kart sayisi',
+  '  FARKLI olabilir — taskCount, subtask/arsiv/parent kartlari farkli kapsar. Kesin kart',
+  '  listesi/sayimi ve TAMAMLANMA bilgisi icin get_request_board (full /kanban) otoritedir:',
+  '  kartta completedAt + completedBy + isCompleted + completionPercentage gelir. Lightweight',
+  '  cards/list hafiftir ama completedAt/completedBy ICERMEZ (yalniz isCompleted) — tamamlanma',
+  '  suresi / performans analizi icin get_request_board kullan, her karti tek tek cekme.',
+  '',
+  'PLAN modlari (POST/PUT /plan/modes): filtreleme MOD seviyesinde degil, her BOARD icindeki',
+  '  filterCriteria ile yapilir (mode.boards[].filterCriteria). describe_endpoint bunu opak',
+  '  (unknown/additionalProperties) gosterir; gecerli anahtarlar request filtre semasidir:',
+  '  assignedTo (user id dizisi), statusId / excludeStatusId (durum id dizisi), projectId',
+  '  (proje id dizisi), includeStakeholderRequests (bool). Emin degilsen mevcut bir modu',
+  '  GET /plan/modes ile inceleyip formati ornek al — bastan tahmin etme.',
+  '',
+  'PROJE alt-agaci: bir kok projenin TUM alt projelerini kapsamak icin once hiyerarsiyi al',
+  '  (get_project / list_projects ile parent-child), sonra kok + tum alt-proje id`lerini',
+  '  projectId DIZISI olarak gec (tek kok id alt agaci otomatik kapsamaz).',
 ].join('\n');
 
 const BASE_URL = (process.env.SYSTA_API_BASE_URL || '').replace(/\/+$/, '');
@@ -79,6 +115,17 @@ const VENDOR_CODE = process.env.SYSTA_VENDOR_CODE || '';
 
 const ALLOWED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 
+// list_capabilities/describe_endpoint advertise route patterns WITH the "/api"
+// prefix (e.g. "/api/requests"), but BASE_URL already ends in /api — so a path
+// copied verbatim would double-prefix into /api/api -> ROUTE_NOT_FOUND. Strip a
+// single leading "/api" segment so both "/api/requests" and "/requests" work.
+const stripApiPrefix = (p) => {
+  if (typeof p !== 'string') {
+    return p;
+  }
+  return /^\/api(\/|$)/.test(p) ? p.slice(4) || '/' : p;
+};
+
 // Diagnostics MUST go to stderr — stdout is the JSON-RPC channel.
 const logErr = (message) => process.stderr.write(`[${SERVER_NAME}] ${message}\n`);
 
@@ -334,12 +381,51 @@ 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'.
+ */
+const shapeSummary = (caps) => ({
+  sessionType: caps.sessionType,
+  ...(caps.user ? { user: caps.user } : {}),
+  scopes: caps.scopes,
+  isSuperAdmin: caps.isSuperAdmin,
+  ...(caps.overview ? { overview: caps.overview } : {}),
+  ...(caps.glossary ? { glossary: caps.glossary } : {}),
+  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,
+  })),
+});
+
+const shapeOneModule = (caps, target) => {
+  const t = String(target).toLowerCase();
+  const full = shapeCompact(caps);
+  const mod = (full.modules || []).find((m) => String(m.module).toLowerCase() === t);
+  return {
+    ...full,
+    modules: mod ? [mod] : [],
+    ...(mod
+      ? {}
+      : {
+          note: `Module "${target}" not found or not in this key scope.`,
+          availableModules: (full.modules || []).map((m) => m.module),
+        }),
+  };
+};
+
 // ── 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.',
+      'List/search SysTa requests (talepler) with pagination and rich filters: status, assignee, company, category, department, priority, free-text. "uzerimdeki acik isler / my open work" => assignedTo=<me> (resolve via list_capabilities user.id) + openOnly:true (one call — excludes final/"Tamamlandi" statuses automatically). Multiple statuses: statusId can be an array [1,3,5]. Returns only requests the API key scope permits. For filters beyond these, use systa_api_call GET /requests (this endpoint rejects unknown params with a 400 naming the valid set).',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -352,7 +438,16 @@ const TOOLS = [
         },
         offset: { type: 'integer', minimum: 0, description: 'Pagination offset' },
         search: { type: 'string', description: 'Free-text search' },
-        statusId: { type: 'integer', description: 'Filter by status id' },
+        statusId: {
+          type: ['integer', 'array'],
+          items: { type: 'integer' },
+          description: 'Filter by a status id, or an array of status ids for multiple',
+        },
+        openOnly: {
+          type: 'boolean',
+          description:
+            'true => only open (non-final) requests — auto-resolves to the non-final status ids (excludes "Tamamlandi/kapatildi")',
+        },
         assignedTo: {
           type: 'integer',
           description: 'Filter by assignee user id (use own id for "my work")',
@@ -363,31 +458,55 @@ const TOOLS = [
         priority: { type: 'string', description: 'Filter by priority key/level' },
       },
     },
-    handler: (args) =>
-      systaFetch('GET', '/requests', {
+    handler: async (args) => {
+      let statusId = args.statusId;
+      // openOnly: resolve the NON-final status ids and filter to them. GET /requests
+      // accepts statusId as an array (validator normalizes a comma list); it does NOT
+      // support excludeStatusIds, so we INCLUDE the open ones rather than exclude final.
+      if (args.openOnly) {
+        const st = await systaFetch('GET', '/statuses').catch(() => null);
+        const rows = st && st.ok ? (st.data && (st.data.data || st.data)) || [] : [];
+        const openIds = (Array.isArray(rows) ? rows : [])
+          .filter((s) => s && !s.isFinal)
+          .map((s) => s.id);
+        if (openIds.length > 0) {
+          statusId = openIds;
+        }
+      }
+      return systaFetch('GET', '/requests', {
         query: {
           limit: args.limit ?? 20,
           offset: args.offset,
           search: args.search,
-          statusId: args.statusId,
+          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.',
+    description:
+      'Get a single SysTa request (talep) by its request number, including its details. Param name is "requestNumber" to match the other request tools (add_request_comment/change_request_status/assign_request/update_request); "id" is accepted as an alias.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
-      required: ['id'],
-      properties: { id: { type: 'integer', description: 'Request id' } },
+      properties: {
+        requestNumber: { type: 'integer', description: 'Request number (the id shown in lists)' },
+        id: { type: 'integer', description: 'Alias for requestNumber (back-compat)' },
+      },
+    },
+    handler: async (args) => {
+      const rn = args.requestNumber ?? args.id;
+      if (rn === undefined || rn === null) {
+        throw new Error('requestNumber (or id) is required');
+      }
+      return systaFetch('GET', `/requests/${encodeURIComponent(rn)}`);
     },
-    handler: (args) => systaFetch('GET', `/requests/${encodeURIComponent(args.id)}`),
   },
   {
     name: 'list_projects',
@@ -411,11 +530,11 @@ const TOOLS = [
   {
     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.',
+      '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 (+ at least one assignment: assignedTo OR assignedTeams), 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. ONEMLI (talep 166 #60): verdigin `description` talebin ILK YORUMU (commentNo 1) olarak materyalize edilir; ZENGIN icerik istiyorsan (tablo/kod blogu/bicimli metin) `description` yerine systa_api_call POST /requests ile `descriptionJson` alanina TipTap doc gonder (tablo dahil) -- bu da comment #1 olur. Yani tabloyu talep ACARKEN descriptionJson icinde ver; AYRICA ayri bir yorum EKLEME (yoksa cift yorum olusur). Icerigi yalnizca ayri yorumda istiyorsan description bos birak.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
-      required: ['title', 'companyId', 'statusId', 'assignedTo'],
+      required: ['title', 'companyId', 'statusId'],
       properties: {
         title: { type: 'string', description: 'Request title' },
         description: { type: 'string', description: 'Request description (plain text)' },
@@ -423,7 +542,18 @@ const TOOLS = [
         statusId: { type: 'integer', description: 'Initial status id' },
         assignedTo: {
           type: 'integer',
-          description: 'Assignee user id (an assignment is required by SysTa)',
+          description:
+            'Assignee user id. SysTa requires at least ONE assignment: provide assignedTo (a user) OR assignedTeams (teams).',
+        },
+        assignedTeams: {
+          type: 'array',
+          items: { type: 'integer' },
+          description:
+            'Assignee team ids (alternative/addition to assignedTo; at least one of assignedTo/assignedTeams is required).',
+        },
+        channel: {
+          type: 'string',
+          description: "Source channel; defaults to 'API' for AI/MCP-created requests.",
         },
         categoryId: {
           type: 'integer',
@@ -443,7 +573,9 @@ const TOOLS = [
           description: args.description ?? '',
           companyId: args.companyId,
           statusId: args.statusId,
-          assignedTo: args.assignedTo,
+          channel: args.channel ?? 'API',
+          ...(args.assignedTo != null ? { assignedTo: args.assignedTo } : {}),
+          ...(args.assignedTeams != null ? { assignedTeams: args.assignedTeams } : {}),
           ...(args.categoryId != null ? { categoryId: args.categoryId } : {}),
           ...(args.organizationId != null ? { organizationId: args.organizationId } : {}),
         },
@@ -534,11 +666,17 @@ const TOOLS = [
       } catch {
         // non-fatal — baseline fallback below
       }
-      if (requiredFields.length === 0) {
-        requiredFields = ['title', 'companyId', 'statusId', 'assignedTo'].map((k) => ({
-          fieldKey: k,
-          isSystem: true,
-        }));
+      // create_request ALSO requires API-layer invariants that are NOT part of
+      // the active form schema (title/companyId/statusId/assignedTo). The form
+      // only describes custom/system form fields, so always merge these in —
+      // otherwise the helper omits e.g. assignedTo and the first create_request
+      // still 400s on a missing field (the exact roundtrip this tool prevents).
+      const BASELINE_REQUIRED = ['title', 'companyId', 'statusId', 'assignedTo'];
+      const have = new Set(requiredFields.map((f) => f.fieldKey));
+      for (const k of BASELINE_REQUIRED) {
+        if (!have.has(k)) {
+          requiredFields.push({ fieldKey: k, isSystem: true });
+        }
       }
       const need = new Set(requiredFields.map((f) => f.fieldKey));
 
@@ -579,7 +717,7 @@ const TOOLS = [
           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.',
+          note: 'Fill create_request with ALL these required fields; resolve each id from options[fieldKey]. assignedTo is the assignee user id — for "bana ata / assign to me" use your own user.id from list_capabilities (who-am-i). statusId.isFinal=true => a tamamla/kapat status. A missing option list = out of this key scope; ask the user or use systa_api_call.',
         },
       };
     },
@@ -1687,7 +1825,7 @@ const TOOLS = [
   {
     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").',
+      '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"). You may paste a path verbatim from list_capabilities/describe_endpoint even though those include the "/api" prefix — a leading "/api" is auto-stripped (the base URL already ends in /api), so "/api/requests" and "/requests" both work.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -1711,7 +1849,7 @@ const TOOLS = [
       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 });
+      return systaFetch(method, stripApiPrefix(args.path), { query: args.query, body: args.body });
     },
   },
   {
@@ -1798,7 +1936,7 @@ const TOOLS = [
       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);
+      return systaUploadMultipart(stripApiPrefix(args.path), method, filePaths);
     },
   },
   {
@@ -1807,15 +1945,38 @@ const TOOLS = [
       '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 () => {
+      '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 ' +
+      'pass module="<name>" to drill into one module. No args = full compact catalog.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        summary: {
+          type: 'boolean',
+          description: 'true => orientation + module index only (no per-endpoint detail)',
+        },
+        module: {
+          type: 'string',
+          description:
+            'return only this module\'s endpoints (e.g. "request", "project", "query-builder")',
+        },
+      },
+    },
+    handler: async (args) => {
       const res = await systaFetch('GET', '/api-keys/me/capabilities');
       if (!res.ok) {
         return res;
       }
-      return shapeCompact(unwrapCapabilities(res));
+      const caps = unwrapCapabilities(res);
+      if (args && args.module) {
+        return shapeOneModule(caps, args.module);
+      }
+      if (args && args.summary) {
+        return shapeSummary(caps);
+      }
+      return shapeCompact(caps);
     },
   },
   {
@@ -2037,14 +2198,63 @@ 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 } });
 
+/**
+ * Validate tool-call arguments against the tool's declared inputSchema BEFORE
+ * dispatch. The server advertises additionalProperties:false but did not enforce
+ * it, so a hallucinated arg (e.g. isCompleted on list_requests) was silently
+ * dropped and produced a confidently-wrong result. Reject unknown args + missing
+ * required fields with a clear, actionable message so the agent self-corrects.
+ * @returns {string|null} error message, or null if valid
+ */
+const validateArgs = (tool, args) => {
+  const schema = tool && tool.inputSchema;
+  if (!schema || schema.type !== 'object') {
+    return null;
+  }
+  const props = schema.properties || {};
+  const a = args && typeof args === 'object' ? args : {};
+  if (schema.additionalProperties === false) {
+    const unknown = Object.keys(a).filter((k) => !(k in props));
+    if (unknown.length > 0) {
+      const valid = Object.keys(props).join(', ') || '(none)';
+      return `Unknown argument(s): ${unknown.join(', ')}. This tool accepts only: ${valid}. For filters beyond these use systa_api_call (check describe_endpoint for the valid set).`;
+    }
+  }
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const missing = required.filter((k) => a[k] === undefined || a[k] === null);
+  if (missing.length > 0) {
+    return `Missing required argument(s): ${missing.join(', ')}.`;
+  }
+  return null;
+};
+
 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}`);
   }
+  const args = (params && params.arguments) || {};
+  // Enforce the declared inputSchema (additionalProperties:false + required) so
+  // unknown/missing args surface a clear error instead of being silently dropped.
+  const argError = validateArgs(tool, args);
+  if (argError) {
+    return reply(id, {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            { ok: false, error: 'INVALID_ARGUMENTS', message: argError },
+            null,
+            2,
+          ),
+        },
+      ],
+      isError: true,
+    });
+  }
   try {
-    const result = await tool.handler((params && params.arguments) || {});
+    const result = await tool.handler(args);
     const isError = result && result.ok === false;
     return reply(id, {
       content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -2211,6 +2421,7 @@ module.exports = {
   TOOL_MAP,
   TOOL_REQUIRED_PERMISSION,
   visibleTools,
+  validateArgs,
   installSkill,
   runCli,
   systaFetch,
@@ -2218,6 +2429,8 @@ module.exports = {
   systaUploadMultipart,
   handleMessage,
   shapeCompact,
+  shapeSummary,
+  stripApiPrefix,
   unwrapCapabilities,
   parseContentDispositionFilename,
   sanitizeFileName,