systa-mcp 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# SysTa MCP Server
+
+Bir [Model Context Protocol](https://modelcontextprotocol.io) (MCP) stdio sunucusu.
+Claude gibi AI ajanlarının, kullanıcının profilinden ürettiği **scoped API anahtarı**
+ile SysTa REST API'sini "araç" olarak kullanmasını sağlar.
+
+- **Sıfır npm bağımlılığı** — native Node (18+ global `fetch`) + JSON-RPC 2.0 (stdio).
+- **Güvenlik sunucu tarafında** — tüm scope/izin zorlaması backend'dedir. MCP yalnızca
+  `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
+
+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
+anahtarın içine gömülüdür, backend vendor'ı anahtardan çözer — nötr (subdomain'siz) bir
+API adresi yeterlidir.
+
+### Claude Code (önerilen — npx, dosya indirmeden)
+
+```bash
+claude mcp add systa \
+  -e SYSTA_API_KEY=sk_live_... \
+  -e SYSTA_API_BASE_URL=https://systa.example.com/api \
+  -- npx -y systa-mcp
+```
+
+İstemci skill'ini (trigger phrase'ler, varsayılanlar, progressive disclosure) tek
+komutla kur:
+
+```bash
+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)                           |
+
+### Yerel geliştirme / yerel klona karşı
+
+```bash
+claude mcp add systa \
+  -e SYSTA_API_KEY=sk_live_... \
+  -e SYSTA_API_BASE_URL=http://vizyoneks.localhost:3000/api \
+  -- node /path/to/Backend/mcp-server/server.js
+```
+
+### Komutlar
+
+| Komut                       | İşlev                                                  |
+| --------------------------- | ------------------------------------------------------ |
+| `systa-mcp`                 | MCP stdio sunucusunu çalıştırır (Claude Code kullanır) |
+| `systa-mcp --install-skill` | Gömülü skill'i `~/.claude/skills/systa/`'ya kopyalar   |
+| `systa-mcp --version`       | Sürümü yazar                                           |
+| `systa-mcp --help`          | Yardım                                                 |
+
+## Araçlar (tools)
+
+Toplam **44 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.
+
+| Araç                    | Açıklama                                                                                                                                                                                                                               |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_requests`         | Talepleri listele (limit/offset/search/statusId) — `request.read`                                                                                                                                                                      |
+| `get_request`           | Tek bir talebi id ile getir — `request.read`                                                                                                                                                                                           |
+| `list_projects`         | Projeleri listele — `project.read`                                                                                                                                                                                                     |
+| `create_request`        | Talep oluştur (title/description/companyId/statusId/assignedTo) — `request.create`                                                                                                                                                     |
+| `add_request_comment`   | Talebe yorum ekle (düz metin otomatik TipTap'e sarılır) — `request.comment.create` + `request.tabs.comments.view`                                                                                                                      |
+| `systa_api_call`        | Genel REST çağrısı (diğer endpoint'ler); kapsam sunucu tarafında zorlanır                                                                                                                                                              |
+| `download_request_file` | Dosya ekini (talep/görev kartı/proje) YEREL diske indirir, kaydedilen yolu döner — `file.download`                                                                                                                                     |
+| `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                                                                                                                                  |
+
+`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
+çağrılar `403` döner.
+
+### Dosya ekleri (download_request_file / upload_file_to)
+
+`systa_api_call` JSON-only olduğundan binary taşıyamaz — dosya ekleri için bu iki
+araç kullanılır. Tüm erişim/güvenlik kontrolleri (izin, şirket erişimi, uzantı/MIME
+allowlist, magic byte, rate limit) **sunucu tarafında** çalışır.
+
+- **`download_request_file`** — `{ fileId, savePath? }`: `GET /files/:id/download` çağırır,
+  binary'yi yerel diske yazar. `savePath` verilmezse OS temp dizinine
+  (`systa-mcp-downloads/`) kaydeder; mevcut bir dizin verilirse içine, dosya yolu
+  verilirse o yola yazar. Dönen değer: `savedPath`, `fileName`, `mimeType`, `sizeBytes`.
+  Gereken scope: `file.download`.
+- **`upload_file_to`** — `{ path, filePaths[], method? }`: multipart (`file` alanı) yükleme.
+  Yaygın hedefler: `/requests/:requestNumber/files` (talep eki),
+  `/projects/:projectId/files` (proje dosyası),
+  `/requests/:requestId/kanban/cards/:cardId/files` (görev kartı eki),
+  `/files/orphan-upload` (alt form ön-yükleme). Mevcut dosyayı değiştirmek için
+  `method: "PUT"` + `/requests/:n/files/:id` (tek dosya). Gereken scope: `file.upload`.
+  Executable/script uzantıları sunucu tarafından reddedilir.
+
+`file.download` ve `file.upload` yıkıcı sayılmadığından `*` / `file.*` wildcard
+scope'larına dahildir; `file.delete` ise yalnızca açık scope ile verilebilir.
+
+### Keşfedilebilirlik (discoverability)
+
+Sunucu, `initialize` yanıtında bir **server-seviye rehber** (`instructions`) döner:
+ajana scope semantiğini (`*`/`domain.*` wildcard, `.delete` istisnası), güvenlik
+sınıflarını ve "önce `list_capabilities`, sonra `describe_endpoint`" akışını öğretir.
+Böylece AI ajan, anahtarın **gerçekte neler yapabileceğini** (kategori + özet + alan
+tipleri + güvenlik sınıfı) kendi keşfeder — kapsam dışı yüzey sızmaz.
+
+Endpoint-bazlı detayın yanında, `list_capabilities` bir **kavramsal oryantasyon katmanı**
+da döner (DB: `ai_orientation_catalog`): SysTa platform özeti (`overview`), TR **glossary**
+(talep/görev/efor/pano/durum… → modül/kavram) ve her modülün **açıklaması** (`description` +
+`concepts`). Bu sayede kod tabanına hiç erişimi olmayan bir ajan, kullanıcının doğal dilini
+doğru modül ve endpoint'e eşleyebilir. `describe_module(module)` tek bir modülü topluca verir.
+
+### Scope-aware araç listesi (tools/list)
+
+`tools/list` yanıtı da anahtarın kapsamına göre filtrelenir: bir named tool yalnızca
+anahtar o aracın gerektirdiği izne sahipse listelenir. **Kapsam dışı araçlar ajana hiç
+görünmez** — örn. yalnızca `request.create` izni olan bir anahtar yalnızca `create_request`
+
+- `prepare_create_request` ve keşif araçlarını (`list_capabilities`, `describe_module`,
+  `describe_endpoint`, `systa_api_call`) görür; `update`/`delete`/kanban/plan araçları
+  listede yer almaz. Böylece ajan kapsam dışı bir aracı denemez (gereksiz `403` olmaz). İzin
+  seti, anahtarın scope-filtreli kataloğundan türetilir (tek kaynak backend; wildcard/`.delete`
+  mantığı orada). `SYSTA_MCP_STRICT_TOOLS=1` ile kapsam çözülemezse fail-closed davranır.
+
+## Manuel test (handshake)
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | SYSTA_API_BASE_URL=http://vizyoneks.localhost:3000/api SYSTA_API_KEY=sk_live_... node server.js
+```
+
+## Notlar
+
+- Anahtar süresi dolduğunda (varsayılan 90 gün) Ayarlar'dan yeni anahtar üretip env'i güncelleyin.
+- Anahtar iptal edildiğinde (Ayarlar → iptal) tüm çağrılar derhal `401` döner.
+- Yıkıcı işlemler (silme, toplu) için anahtara bu scope'ları **vermemeniz** önerilir.
+
+## 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.
+
+```bash
+cd Backend/mcp-server
+npm pack --dry-run     # tarball içeriğini doğrula (yalnız 4 dosya)
+npm login              # npm hesabı (publish için)
+npm publish            # publishConfig.access=public ile public yayınlanır
+```
+
+Sürüm `package.json` ve `server.js` (`SERVER_VERSION`) içinde **birlikte** yükseltilir.

package/SKILL.md

@@ -0,0 +1,187 @@
+---
+version: 0.1.0
+name: systa
+description: |
+  Drive SysTa (Talep Takip Sistemi / SysTa) — a
+  multi-tenant request, project, kanban, plan, SLA,
+  approval, release and reporting platform — from
+  Claude Code / claude.ai via its scoped API key + MCP
+  server. Talks user verbs ("open a request", "assign
+  it to me", "comment", "change status", "what's on my
+  plate", "start a project", "add a kanban card",
+  "submit plan for approval", "export a report") and
+  maps them to SysTa REST endpoints over the MCP
+  capability catalog. Use when (TR): "talep aç",
+  "bana/şuna ata", "yorum ekle", "durumu değiştir /
+  tamamla / kapat", "üzerimdeki işler", "proje aç",
+  "kanban kartı ekle", "onaya sun", "onayla/reddet",
+  "izin talebi", "rapor al / dışa aktar", "sürüm
+  oluştur". Use when (EN): "create a SysTa request",
+  "log a ticket", "assign / reassign", "add a comment",
+  "move/close the ticket", "show my open work", "create
+  project", "add task card", "request approval",
+  "approve/reject", "export report", "create release".
+  Multi-tenant (vendor schema) aware; resolves names →
+  ids; honors dynamic required fields. NOT for: editing
+  SysTa source code, running psql/DB migrations directly,
+  Higgsfield media generation, or any non-SysTa product.
+argument-hint: '[natural-language SysTa intent] [--vendor <schema>] [--dry-run]'
+allowed-tools: Bash, ToolSearch, mcp__systa__*
+---
+
+# SysTa
+
+Drive SysTa through its MCP server (or, where MCP is unavailable, its REST API with a scoped API key). SysTa = **Talep Takip Sistemi** (SysTa) — a multi-tenant work-management platform: requests, projects, kanban/task boards, plans/Gantt, SLAs, approvals, releases, forms, reports and admin. This skill maps **user verbs** to endpoints; it never edits SysTa's codebase and never touches the database directly.
+
+The golden rule: **talk intent, resolve ids behind the scenes, ask the user only for what is genuinely missing, and pre-resolve dynamic required fields before submitting.**
+
+## Step 0 — Bootstrap
+
+Before any SysTa action, confirm connectivity, auth and identity. Do this once per session (cache the result).
+
+1. **Find the connection.** Prefer the SysTa MCP server. If the deferred MCP tools aren't loaded yet, fetch their schemas:
+
+   ```
+   ToolSearch  query: "select:mcp__systa__list_capabilities,mcp__systa__describe_endpoint"
+   ```
+
+   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_KEY:?export a scoped sk_live_... key (do not paste in chat)}"
+   ```
+
+2. **Auth + identity check ("who am I").** Confirm the key/session is live and learn the caller's identity, vendor schema and permissions — this drives every default (assignee, companyId, scope):
+
+   ```bash
+   curl -fsS -H "Authorization: Bearer $SYSTA_API_KEY" \
+     "$SYSTA_BASE_URL/api/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.
+
+3. **Vendor scope.** SysTa is schema-per-vendor; every mutation runs inside the caller's vendor schema. The vendor is derived from the key/session — never inject another vendor's ids. If the user references a company/team/user, it is resolved **within** their vendor.
+
+4. **Decide MCP vs REST for the session.** If `list_capabilities` works, use the MCP tools for discovery (`list_capabilities` → `describe_endpoint`) and let the server enforce scope. Otherwise drive `curl` against the REST paths shown in each workflow.
+
+If bootstrap fails, deliver a one-line reason ("anahtar süresi dolmuş", "key expired", "endpoint için yetki yok") and stop — never fabricate a result.
+
+## SysTa nedir / temel kavramlar (glossary)
+
+Short shared vocabulary. Use these words with the user; never expose raw REST paths or internal jargon.
+
+| Kavram (TR)           | Concept (EN)        | Ne demek                                                                                                                                                        |
+| --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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`.                                                                                                               |
+| 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`.                                                                                                 |
+| Proje                 | Project             | Talepleri kapsayan üst yapı; milestone, paydaş, sağlık/risk/SLA dashboard, alt-proje hiyerarşisi.                                                               |
+| Kanban / Görev panosu | Kanban / task board | Bir talebin altında kolonlar + kartlar; kart yaşam döngüsü: oluştur → ata → taşı → tamamla. `boardId` daima bir `requestId`'ye bağlı.                           |
+| Plan / Baseline       | Plan / baseline     | Talepleri Gantt'ta planlama; baseline = onaylı plan snapshot'ı; tracking = gerçeğe karşı izleme (diff/burndown/timeline).                                       |
+| SLA                   | SLA                 | Süre taahhütleri (ilk yanıt, çözüm). Instance bir talebe bağlanır; pause/resume edilebilir.                                                                     |
+| Onay                  | Approval            | Toplu onaya gönderme + onayla/reddet; plan onayı ve talep onayı ayrı akışlar.                                                                                   |
+| 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.                                                                         |
+
+## 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.
+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.
+
+## Discovery
+
+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`.
+- **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`.
+
+## Ç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.
+
+### Talep aç (open a request) — `create_request` → `POST /api/requests`
+
+1. Need `title` (min 5 chars) — if missing or too short, ask once. Never invent it.
+2. Defaults: `channel='API'` (AI/MCP source), `companyId` ← who-am-i, `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.
+3. 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`
+
+- "taleplerim / on me" → `assignedTo=<my userId>`. "açık/open" → final olmayan durumlar. Default `limit=20-50`, sort `created_at desc`, `companyId` from scope. Summarize as a short list (numara + başlık + durum), not raw rows.
+
+### Talep detayı (show a request) — `get_request` → `GET /api/requests/:requestNumber`
+
+- Resolve the user's number/title to `requestNumber`. If ambiguous, `list_requests` first to find candidates, then fetch.
+
+### Bana / birine ata (assign) — `assign_request` → `PUT /api/requests/:requestNumber`
+
+- "bana/üzerime" → `assignedTo=<my userId>`. A name → resolve via user lookup (`GET /api/users?search=`) to `userId`. Partial update — only send `assignedTo`.
+
+### Yorum ekle (comment) — `add_request_comment` → `POST /api/requests/:requestNumber/comments`
+
+- Plain text → `commentText`. At least one of `commentText` / `commentTextJson` / `fileIds` required. No mentions unless asked.
+
+### Durum değiştir / tamamla / kapat (change status) — `change_request_status` → `PUT /api/requests/:requestNumber`
+
+- "tamamla/kapat" → pick the appropriate `is_final` status (resolve via `GET /api/statuses`). A named status → resolve to `statusId`. If the user wrote a closing note, add it as a comment; if not, don't.
+
+### Proje aç (start a project) — `create_project` → `POST /api/projects`
+
+- `projectCode` is auto-generated by the backend — **don't ask for it** (preview via `GET /api/projects/next-code` if needed). `companyId` ← who-am-i; dates optional. Report "Proje '<name>' oluşturuldu (kod: <code>)".
+
+### Projemi / projeleri gör + durum (list / health) — `list_projects` / `get_project_health`
+
+- 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`
+
+- `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).
+
+### Kartı taşı / tamamla (move / complete card) — `move_kanban_card` / `complete_kanban_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%.
+
+### Onaya sun / onayla / bekleyenler (approvals)
+
+- Submit (request approval): `request_approval` → `POST /api/approvals/batch`, `strategy='any_one'` default, approver names → ids. Plan onayı ayrı: `submit_plan_for_approval` → `POST /api/plan/approvals/submit` (`strategy='all_required'`).
+- 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`
+
+- `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`.
+
+### Rapor al / dışa aktar (report) — `preview_report` / `export_report`
+
+- Ö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.
+
+### Sürüm oluştur (release) — `create_release_list` → `POST /api/releases/lists`
+
+- `releaseType='standard'`, `requireAllStakeholderApprovals=false`, `companyId` from scope. Add items with `add_release_item`. Deployment workflow steps (`close-servers` → `start-db-migration` → `start-server-update` → `open-servers` → `complete`) are live ops — **never auto-advance blindly**; show which step you're on and confirm. Release notes: generate → review → publish (never auto-publish).
+
+## Zincirleme & hata kurtarma (chaining & error recovery)
+
+SysTa returns structured errors. Recover deterministically instead of giving up.
+
+1. **`400 VALIDATION_FAILED`** — the response carries `details[]` with `fieldKey`, message, and often `expected`/`enum`. For each entry:
+   - If it's a missing required field you can resolve (e.g. `statusId`, `companyId`, `categoryId`), resolve it (status list / who-am-i / category list) and **add the field, then retry once**.
+   - If it's a bad enum (`priority`, `decision`, `accessLevel`), map the user's word to an allowed value (`onayla→approved`, `reddet→rejected`, `acil→high`) and retry.
+   - 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.
+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.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "systa-mcp",
+  "version": "1.0.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",
+  "bin": {
+    "systa-mcp": "server.js"
+  },
+  "files": [
+    "server.js",
+    "SKILL.md",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node server.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "systa",
+    "claude",
+    "ai-agent",
+    "talep-takip"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://systa.vizyoneks.com.tr"
+}