xurrent-mcp

Xurrent (ITSM) için MCP sunucusu ve chatbot — üç dilde, aynı sözleşmeyle. AI destekli geliştirme dersi için hazırlanmış örnek uygulama ve öğretim materyali.

Bir kişinin Xurrent'taki açık taleplerini listeler, kullanıcıyla süre üzerine müzakere eder, zaman girişlerini kaydeder ve günün takvimini okuyup her toplantıyı zaman girişine çevirir.

Aynı MCP sözleşmesi TypeScript, Python ve C# ile ayrı ayrı implemente edilmiştir. Dersin tezi budur: MCP bir protokoldür, dil seçimi bir detaydır.

---

60 saniyede başla

Hiçbir token, hesap veya internet bağlantısı gerekmez. Varsayılan mock moddur.

cp .env.example .env

Sonra herhangi bir dili seç:

cd servers/typescript && npm install && npm run build && npm run wizard

cd servers/python && uv sync && uv run xurrent-mcp --wizard

cd servers/csharp && dotnet run -- wizard

Üç komut da aynı dersi verir, aynı sayıları üretir.

---

Neyi çözüyor

#	İster	Karşılayan tool
1	İlgili kişinin açık görev/taleplerini id ve açıklama ile listele	xurrent_list_open_work
2	Her biri için kullanıcı süre belirtsin (başlangıç saati, tarih T veya T-1)	xurrent_create_time_entry (müzakere chatbot'ta)
3	Girişleri ilgili kişi ve görev için Xurrent'a kaydet	xurrent_create_time_entry, ..._bulk
4	Günün takvimini oku, her toplantıyı zaman girişi olarak ekle	calendar_list_today → plan_time_entries_from_calendar

⚠️ İster #2 ve #3 birlikte, Xurrent API'sinde tek adımda mümkün değil

Bu projenin en önemli bulgusu — ve dersin ana konusu:

	Yol A timeEntryCreate	Yol B requestUpdate / taskUpdate
Ticket'a bağlar mı?	❌ assignment = null	✅ tek yol
date (T-1) kontrolü	✅	❌ sunucu "bugün" atar
startedAt (başlangıç saati)	✅	❌
personId (başkası adına)	✅	❌ authenticated user

TimeEntryCreateInput içinde requestId/taskId/assignmentId yoktur.

Çözüm üç stratejiye ayrıldı ve üçü de kodlandı (XURRENT_BACKDATE_STRATEGY):

• two_step — Yol B ile yaz, ardından timeEntryUpdate ile date/startedAt/personId düzelt. Her şeyi korur; 2 istek, atomik değil. Neden çalışır: TimeEntryUpdateInput'ta assignment alanı yoktur, dolayısıyla 2. adım ticket bağını bozamaz.
• link_first — Sadece Yol B. Tek istek, atomik; tarih her zaman bugün.
• date_first — Sadece Yol A. Tarih/saat tam doğru; kayıt ticket'a bağlanmaz.

Ayrıntı: docs/02-zaman-girisi-modeli.md

---

Repo yapısı

contract/tools.json     ← dil-bağımsız tool sözleşmesi. Tek gerçek kaynak.
contract/protocol.md    ← çift protokol sözleşmesi (2025-11-25 + 2026-07-28)
fixtures/               ← ortak mock veri. Üç dil de aynı dosyaları okur.
docs/                   ← anlatım notları (Türkçe, 10 bölüm + demo senaryosu)
docs/wizard/steps.json  ← sihirbaz ders akışı. Üç dil de aynı dosyayı yürütür.
servers/typescript/     ├─ MCP sunucusu + chatbot + web (aynı sözleşme)
servers/python/         ├─
servers/csharp/         └─
clients/wizard/         ← MCP client sihirbaz — üç sunucuya da bağlanır
clients/web/            ← ortak statik web arayüzü, üç backend de servis eder

---

Üç çalıştırma modu

Her dil üçünü de destekler.

1 — MCP sunucusu olarak (LLM'i host sağlar, API key gerekmez)

claude

.mcp.json zaten hazır. Claude Code açılınca xurrent-ts sunucusunu onaylayın, ardından "bugünkü toplantılarımı Xurrent'a yaz" deyin.

2 — Terminal chatbot (GEMINI_API_KEY gerekir — ya da sahte Gemini, aşağıda)

cd servers/typescript && npm run chat

3 — Web arayüzü (GEMINI_API_KEY gerekir — ya da sahte Gemini, aşağıda)

cd servers/typescript && npm run web    # → http://localhost:8787

Bonus — Sihirbaz: yukarıdaki npm run wizard. API key gerekmez; tool'ları doğrudan çağırır, LLM kullanmaz.