systa-mcp 1.1.0 → 1.2.0

package/README.md

@@ -101,7 +101,7 @@ claude mcp add systa \
 
 ## Araçlar (tools)
 
-Toplam **44 araç** vardır; `tools/list` yanıtı anahtarın kapsamına göre filtrelenir
+Toplam **64 araç** vardır; `tools/list` yanıtı anahtarın kapsamına göre filtrelenir
 (bkz. "Scope-aware araç listesi"). Aşağıdakiler en sık kullanılan çekirdek araçlardır —
 tam katalog `list_capabilities` ile keşfedilir.
 
@@ -190,8 +190,12 @@ printf '%s\n' \
 ## Yayınlama (maintainer)
 
 Paket sıfır bağımlılıklıdır; `files` whitelist'i yalnızca `server.js`, `SKILL.md`,
-`README.md` içerir. SKILL.md kaynağı `Analiz Dökümanları/12_AI_ve_Otomasyon/systa_client_skill_TASLAK.md`'dir
-— güncellenince pakete tekrar kopyalanmalıdır.
+`README.md` içerir.
+
+> **SKILL.md'nin tek kaynağı bu dizindeki `mcp-server/SKILL.md` dosyasıdır.** Doğrudan burada
+> düzenlenir. (Eskiden `Analiz Dökümanları/.../systa_client_skill_TASLAK.md` kaynak gösteriliyordu;
+> o dosya 2026-06-16'da donmuş bir taslaktır ve gerçek SKILL.md'nin yarısı kadardır. Oradan
+> kopyalamak içeriğin yarısını siler.)
 
 ```bash
 cd Backend/mcp-server

package/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 1.1.0
+version: 1.2.0
 name: systa
 description: |
   Drive SysTa (Talep Takip Sistemi / SysTa) — a
@@ -108,10 +108,16 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 | pano, board, kanban / kolon, column, asama, liste            | kanban          | get_request_board / create_request_board                          |
 | durum gecisi onizle, izinli gecisler, hangi duruma gecebilir | request         | list_allowed_transitions                                          |
 | plan modu, sprint kapsami, plan mode setup                   | plan            | create_plan_mode                                                  |
-| efor, durum, oncelik, atanan, planla, denetim, gecmis        | request         | get_request / list_requests                                       |
+| durum, oncelik, atanan, planla, denetim, gecmis              | request         | get_request / list_requests                                       |
+| tahmini efor, planlanan sure (estimatedEffort)               | request         | update_request (TAHMIN alani, defter DEGIL)                       |
+| efor gir, efor yaz, calistigim sure, efor defteri, mesai     | effort          | log_effort / list_effort_targets / list_effort_entries            |
+| eksik efor girisim var mi, efor uyumu                        | effort          | get_effort_compliance                                             |
 | 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                      |
+| onay tipleri, kime onaya gonderelim                          | approvals       | list_approval_types                                               |
+| red nedeni, neden reddedildi, gecerli red sebepleri          | approvals       | list_rejection_reasons                                            |
+| bu talep neden dondu, neden yazamiyorum, kilitli alan        | approvals       | get_request_freeze                                                |
 | 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                   |
@@ -130,7 +136,8 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 | 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                                                 |
+| degerlendirme, puanlama, memnuniyet, geri bildirim           | ratings         | POST /api/ratings                                                 |
+| anket, oylama, karar alalim, ekibe soralim, secenek sun      | decisions       | systa_api_call POST /requests/:n/decisions                        |
 | github, repo, pull request, commit, issue aktar              | github          | systa_api_call /github/me/{connection,repos,import,push}          |
 | gosterge paneli, dashboard, widget, ozet, grafik, panel      | dashboard       | GET /api/dashboard/init                                           |
 
@@ -164,7 +171,7 @@ Each maps a P0 user verb to a tool/endpoint, with the opinionated defaults from
 
 1. Need `title` (min 5 chars) — if missing or too short, ask once. Never invent it.
 2. Defaults: `channel='API'` (AI/MCP source), `statusId` ← default open/new status (resolve via `GET /api/statuses`, pick the non-final entry status), `priority='normal'` unless the user signals "acil/critical". `description` can be a plain string. **`companyId` — DIKKAT:** genelde `user.companyId` DEĞİL — B2B talepler MÜŞTERİ şirketi için açılır. Şirket adı netlesmediyse `systa_api_call GET /companies?search=<ad>` ile çöz veya kullanıcıya SOR. `prepare_create_request(companyId)` proaktif seçenekleri döner.
-3. **Efor** (`estimatedEffort`/`personDay`): KANONIK GÜN. Kullanıcı "N saat" derse ÖNCE `list_capabilities.effortPolicy.hoursPerDay` ile böl (varsayılan 8), sonra yaz. "8 saat" → `estimatedEffort=1` (8/8=1 gün), "4 saat" → `estimatedEffort=0.5`. Aynı kural `manage_request_card.estimatedEffort` ve `bulk_update_requests.updates.estimatedEffort` için de geçerli.
+3. **Efor** (`estimatedEffort`/`personDay`): bu alan **PLANLANAN TAHMİN**tir; gerçekleşen çalışma kaydı DEĞİLDİR (onun için `log_effort` / efor defteri kullanılır — ayrı modül, ayrı uç). KANONIK GÜN. Kullanıcı "N saat" derse ÖNCE `list_capabilities.effortPolicy.hoursPerDay` ile böl (varsayılan 8), sonra yaz. "8 saat" → `estimatedEffort=1` (8/8=1 gün), "4 saat" → `estimatedEffort=0.5`. Aynı kural `manage_request_card.estimatedEffort` ve `bulk_update_requests.updates.estimatedEffort` için de geçerli.
 4. Submit; report "Talep #<num> açıldı — '<title>'". If the user also said "bana ata", chain assignment below.
 
 ### Üzerimdeki işler / talepleri listele (what's on my plate) — `list_requests` → `GET /api/requests`
@@ -242,6 +249,27 @@ Kullanıcının kendi GitHub bağlantısı üzerinden talep açma/aktarma. Tüm
 - **Issue içe aktar (GitHub → SysTa talep):** `systa_api_call` `POST /github/me/import` — seçili repo'nun issue'larını kullanıcının KENDİ talepleri olarak içe aktarır (idempotent, createdBy=self). "şu repodan issue'ları SysTa'ya aktar / GitHub'dan talep aç" → bu. Mutating + canlı: hangi repo / kaç issue özetini göster, **onay al**.
 - **Talep push (SysTa → GitHub issue):** `systa_api_call` `POST /github/me/push` — kullanıcının talebini kendi repo'suna GitHub issue'su olarak gönderir/günceller (idempotent, node_id). Dış yan-etki (GitHub'a yazar) → **onay al**.
 
+### Efor gir (log worked time) — `log_effort`
+
+SysTa'da "efor" iki ayrı şeydir ve karıştırılması veri bozar:
+
+- **Tahmini efor** (`estimatedEffort` / `personDay`): talebin PLANLANAN süresi. `update_request` ile yazılır.
+- **Efor defteri** (`log_effort`): kullanıcının GERÇEKLEŞEN çalışma kaydı. Ayrı modül, ayrı uç, ayrı izin.
+
+Kullanıcı "bu haftaki eforumu yaz / 3 saat çalıştım / dün toplantıdaydım" derse **defter** kastedilir.
+
+1. **Önce `list_effort_targets`** çağır (`from`/`to` ver; aralık en fazla 366 gün). Dönen `enabledTargets` hangi hedef türünün açık olduğunu söyler: kapalı bir hedefi kullanıcıya ÖNERME. `candidates` son dokunulan talep/projeleri, `categories` efor türlerini, `activityTypes` serbest aktivite türlerini verir. Kimlikler uydurulamaz.
+2. **`log_effort`** ile yaz. `requestId` / `projectId` / `activityTypeId` üçlüsünden **TAM BİRİ** verilmelidir; sıfır da iki de reddedilir. `inputUnit` ZORUNLUDUR (`minute|hour|day`) — saat/gün çevrimini sen yapma, sunucu kanonik güne çevirir. `entryDate` boşsa bugün yazılır; **gelecek tarih reddedilir**.
+3. Hata karşılıkları: `403 EFFORT_TARGET_DISABLED` → o hedef türü vendor ayarında kapalı (adım 1'i oku). `403 EFFORT_SCOPE_DENIED` → kullanıcı efor modülü kapsamı dışında. `409 EFFORT_TARGET_IMMUTABLE` → bir kaydın hedefi **asla** değiştirilemez; sil ve yeniden gir.
+4. Okuma: `list_effort_entries(from, to)` kendi defterini döner; başkasınınki için `userId` ver (ek yetki ister). "Eksiğim var mı" sorusu tek çağrıyla `get_effort_compliance`.
+
+5. **BİRİM: iki farklı kural, karıştırma.** `log_effort`'ta çevrimi SEN YAPMA — kullanıcı ne dediyse o birimle gönder (`3 saat` → `inputValue:3, inputUnit:'hour'`; `yarım gün` → `inputValue:0.5, inputUnit:'day'`; `45 dakika` → `inputValue:45, inputUnit:'minute'`). Sunucu kanonik güne çevirir ve çevrimde HEDEFİN şirketinin `hoursPerDay` değerini kullanır; senin bölmen yanlış şirketin katsayısını uygulayabilir. Buna karşılık `estimatedEffort` (tahmin) alanına yazarken çevrimi SEN yaparsın (bkz. "Talep aç" adım 3). Sonucu kullanıcıya bildirirken vendor'un görünüm birimini kullan: `list_capabilities.effortPolicy.displayUnit` saat ise "3 saat işlendi" de, "0,375 gün" deme.
+
+6. **Kullanıcı efor girişine TABİ İSE proaktif ol.** Efor takibi vendor ayarıyla açılır ve kullanıcı kapsam içindeyse zorunlu hale gelir. Bunu `list_effort_targets` yanıtındaki `settings` (compliance alanları) ya da tek çağrıyla `get_effort_compliance` söyler; `satisfied:false` "bu kullanıcının eksik girişi var" demektir.
+   - Kullanıcı MCP üzerinden bir işi TAMAMLADIĞINDA (talep kapatma, statü ilerletme, kart tamamlama gibi), efor modülü açıksa **süreyi sor**: "Bu işe ne kadar zaman ayırdın? Efor defterine işleyeyim mi?" Süreyi UYDURMA ve kullanıcı vermeden yazma — defter kaydı kullanıcının beyanıdır.
+   - Kullanıcı "bugün ne yapmalıyım / eksiğim var mı" diye sorduğunda `get_effort_compliance` çağır ve eksik varsa hangi güne ne kadar gerektiğini söyle.
+   - Efor modülü bu vendor'da kapalıysa ya da kullanıcı kapsam dışındaysa (`403 EFFORT_SCOPE_DENIED`) hatırlatma YAPMA; olmayan bir yükümlülüğü dayatmak gürültüdür.
+
 ## Zincirleme & hata kurtarma (chaining & error recovery)
 
 SysTa returns structured errors. Recover deterministically instead of giving up.
@@ -258,6 +286,10 @@ SysTa returns structured errors. Recover deterministically instead of giving up.
 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.
+9. **`409 REQUEST_FROZEN_BY_APPROVAL`** — the request is FROZEN by a pending approval, so every write on it is refused (update, status change, assignment, comment, kanban card, file upload). This is **not** a permission problem and **not** a transition problem: retrying, calling `list_allowed_transitions` or re-authenticating will not help. Call `get_request_freeze(requestId)` to see which approval froze it and which fields are still writable (`writableFieldKeys` — non-empty only under a custom freeze scope). Then either write only those fields, or tell the user the request is waiting on an approval and offer to wait / cancel it. `list_requests` and `get_request` both carry `isFrozen` — check it BEFORE attempting a write.
+10. **`403 FEATURE_NOT_ENABLED`** — the vendor's API/MCP module is off, either because the licence lacks `api_access` or because a vendor admin disabled the `mcp` preference. This gate runs before any scope check, so **every** tool fails the same way. Do not tell the user to regenerate the key; tell them to have the vendor administrator enable API/MCP access.
+11. **`422 REJECTION_REASON_*` / `409 APPROVAL_SEQUENCE_NOT_ACTIVE`** — rejection reasons come from a per-approval-type catalog: call `list_rejection_reasons(approvalTypeId)` and send a `key` from it (`REJECTION_REASON_NOT_ALLOWED` means the code is not bound to that type; `REJECTION_REASON_NOTE_REQUIRED` means that reason needs a non-empty `rejectionReasonText`). `APPROVAL_SEQUENCE_NOT_ACTIVE` means a sequential chain has not reached your group yet — report that it is waiting on an earlier step instead of retrying.
+12. **Partial success is real.** `bulk_update_requests` can return HTTP 200 while skipping frozen requests; the tool adds a `partialSuccess` block when fewer rows changed than you asked for. Always compare the requested count with `updatedCount` and name the ids that did not change. Never report "all done" from a 200 alone.
 
 ## DX / Keşif Notları (talep 166 — prod'da doğrulanmış)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systa-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "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",
@@ -15,7 +15,9 @@
   "scripts": {
     "start": "node server.js",
     "check:version-sync": "node scripts/check-version-sync.js",
-    "prepublishOnly": "node scripts/check-version-sync.js"
+    "prepublishOnly": "node scripts/check-version-sync.js && node scripts/check-release-integrity.js --skip-npm",
+    "check:release-integrity": "node scripts/check-release-integrity.js",
+    "check:release-integrity:self-test": "node scripts/check-release-integrity.js --self-test"
   },
   "engines": {
     "node": ">=18"