systa-mcp 1.0.7 → 1.0.8

package/README.md

@@ -74,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
@@ -97,7 +97,7 @@ 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          | create_kanban_card / move_kanban_card           |
+| 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                  |
@@ -105,13 +105,13 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 | 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 | create_leave_request                            |
-| vendor, sirket, musteri                                   | company         | list_companies                                  |
+| 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           | get_form_schema                                 |
-| rapor, raporlama, disa aktar, export, excel, csv          | report          | preview_report / export_report                  |
+| 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          |
@@ -125,7 +125,7 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 | 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 ~44 modülden kullanıcı-yüzeyli olanları kapsar. Listede olmayan
+> 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).
 
@@ -135,7 +135,7 @@ veya `describe_endpoint` ile gövdeyi netleştir.
 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.
 
@@ -185,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)
 
@@ -199,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`
 
@@ -221,8 +221,8 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systa-mcp",
-  "version": "1.0.7",
+  "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.3';
+// 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.
@@ -528,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. 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.',
+      '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)' },
@@ -540,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',
@@ -560,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 } : {}),
         },