SysTa MCP Server

Bir Model Context Protocol (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.

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

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

npx -y systa-mcp --install-skill

4. Doğrulama

# 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 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)

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:

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. Değer TAM olarak 1 olmalı; aksi halde fail-open (kapsam çözülemese de araçlar gösterilir) |

Yerel geliştirme / yerel klona karşı

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 95 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 sayısal kimliğiyle (requestId) getir; BRKT-1709 gibi numara önce GET /requests/resolve/:requestNumber ile çözülür — request.tabs.general.view | | 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ı, çağrılabilir endpoint'leri ve agentGuide modül kuralları — kullanıcı niyetini doğru modüle eşlemek için | | describe_endpoint | Tek endpoint detayı: alan tipleri, güvenlik sınıfı ve tam HTTP Response Contract v2 — çağrı gövdesini kurmadan ve yanıtı zincirlemeden önce | | get_systa_guide | Tam SysTa MCP rehberi (istemci talimatı ya da araç açıklamasını kestiyse), API çağrısı yok | | describe_tool | Bir aracın tam açıklaması ve parametre şeması; yalnız bu anahtara görünen araçlar |

Agent koordinasyonu (çalışma oturumu ve sohbet)

İki agent aynı kayıtta habersiz çalışırsa birbirinin işini ezer. Bu araçlar tam olarak onu önler. Sıra: bak → konuş → sahiplen → sinyal ver → bırak.

| Araç | Açıklama | | ----------------------------- | ----------------------------------------------------------------------------------------- | | list_active_work_sessions | Şu anda kim neyin üzerinde çalışıyor — düzenlemeden ÖNCE bak — work-session.view-active | | start_work_session | Kaydı sahiplen (talep ya da kart, tam biri); nota YERİNİ yaz — work-session.manage | | send_work_session_heartbeat | Çalışırken sinyal ver; 15 dakika sessizlik oturumu kapatır — work-session.manage | | update_work_session_note | Yer değiştirdiysen notu tazele (null notu siler) — work-session.manage | | end_work_session | İddiayı bırak; gövde göndermek gerekmez — work-session.manage | | list_my_work_sessions | Kendi açık oturumların — work-session.manage | | list_work_session_history | Bir kaydın geçmiş oturumları (imleç geriye gider) — work-session.view-active | | send_work_session_message | Birinin açık oturumuna yaz (kapalı oturum 409 döner); bodyJson ile zengin metin | | send_room_message | Kaydın kendisine kalıcı not: project / request / card; bodyJson ile zengin metin | | read_messages | Konuşmayı oku; afterId ile "son okuduğumdan beri ne geldi" | | listen_room | Kısa süreli bloke dinleme (varsayılan 30 sn, en çok 240) — work-session.view-active | | subscribe_room | Arka planda dinlemeye başla, ANINDA dön — izleme kipi budur | | drain_room_events | Aboneliklerde biriken olayları anında al (tamponu boşaltır, API'ye dokunmaz) | | unsubscribe_room | Aboneliği kapat; tamponda kalan olaylar son kez döner |

Odaya katılma diye bir adım yoktur. Oda abone olunan kanal değil, kaydın kendisidir; erişim kapsamın yetiyorsa okur ve yazarsın. Gantt ve k&k chart üzerindeki düğüm proje, talep ya da kart olabilir — mesaj düğümün temsil ettiği şeyin odasına gider.

MCP istemcisine push gelmez; izleme kipi aboneliktir. Çalışırken haberdar olmak istiyorsan subscribe_room + drain_room_events (arka planda dinler, hiçbir çağrı bloke olmaz, API yoklanmaz). Bekliyorsan listen_room (en çok 240 sn; daha uzunu MCP istemcileri tarafından kesilir). Arada bir uğruyorsan uğrayış başına tek read_messages(afterId).

Oda bir ağaçtır. Proje odası alt projeleri, talepleri ve kartları kapsar; talep odası talebi ve kartlarını. Sohbet olayları mesajın kendisini, etkinlik olayları (kart hareketi, talep güncellemesi, çalışma oturumu) içerik taşımayan bir kaydı taşır. Her olay anahtarın erişim kapsamına ve talep sekme iznine göre süzülür; events ile olay seçilir.

Kopukluk kayıp değildir (1.11.0). Kanal akış konumunu Last-Event-ID ile geri verir ve sunucu aradakini (15 dk, oda başına 200 olay) tekrar eder. Kaçırılmış olabilecek her durum drain_room_events sonucunda gap alanında sebebi ve read_messages imleciyle söylenir. API anahtarı başına en çok 5 açık kanal vardır.

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.

Alt form hazırlama

Alt form (sub-forms), ana talep formu (form) ile aynı modül değildir. Ajan önce list_capabilities({module:"sub-forms"}), ardından kullanacağı uçlar için describe_endpoint çağırmalıdır. Önerilen taslak akışı:

1. POST /sub-forms ile isPublic:false bir form kabuğu oluşturun. parentFormId backend tarafından şirketin aktif talep formundan çözülür; istemci göndermemelidir.
2. Bölüm, alan ve kuralları ayrı ayrı yazmak yerine PUT /sub-forms/:id/save ile tek transaction'da kaydedin. Yeni öğelerde tempId, alan-bölüm ilişkisinde sectionTempId kullanılır; yanıt gerçek id haritalarını verir.
3. Kullanım biçimini yalnız embed veya request_attach binding'iyle tanımlayın.
4. GET /sub-forms/:id/preview HTML değil {form, sections, fields, preview:true} JSON payload'ı döndürür. Query/rule/title/correlation test uçları kalıcı ayar yazmaz.
5. Taslak özetini kullanıcıya göstermeden ve açık onay almadan publish/public erişim, allowed origin, webhook, periodic veya correlation özelliklerini etkinleştirmeyin.

Tam alan türleri, atomik save gövdesi, binding kararları ve hata kurtarma akışı paketle birlikte kurulan SKILL.md içindedir. Sürüm yükselttikten sonra skill'i yenilemek için npx -y systa-mcp@latest --install-skill komutunu yeniden çalıştırın.

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/:requestId/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/:requestId/files/:id (tek dosya). :requestId talebin sayısal kimliğidir, gösterim numarası değildir. Gereken scope: file.upload. Executable/script uzantıları sunucu tarafından reddedilir. Talebe yüklenen dosya yorum akışında da bir satırdır: sunucu yükleme tarihli, yükleyene atfedilmiş bir sistem yorumu açar ve dosyayı ona bağlar. Bir yükleme çağrısı kaç dosya taşırsa taşısın tek satır üretir. Bu yüzden ayrıca "şu dosyayı ekledim" diye yorum yazmayın; aynı olay akışta iki kez görünür. Satırın son dosyası silinince satır akıştan ve yorum sayısından düşer. Görev kartı ve proje yüklemeleri satır üretmez.

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)

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'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.)

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.

Yayınlanmamış değişiklikler (sonraki yayına girer)

• resolve_user_by_name çıktısı list_users ile aynı nested şekli ilan eder: company{id,name}, department{id,name} (eski düz companyName/departmentName kaldırıldı — Faz 33).
• SKILL.md: stakeHolders → stakeholders (tek yazım; arka uç stakeHolders kabul etmez).