Geliştiriciler

Claude ve MCP

Claude, VentionDesk'te bir ekip üyesi gibi çalışır: görev çeker, uygular ve geri bildirim verir — tam olarak ona verdiğin anahtarın haklarıyla. VentionDesk bunun için kendi modelini çalıştırmaz ve ücret almaz: Kendi Claude'unu getirirsin (Claude aboneliğinle veya Anthropic anahtarınla Claude Code).

Oraya iki yol çıkar: MCP sunucusu — Claude Code için önerilir — ve doğrudan API, örneğin kendi script'lerinden. Anahtarsız da olur: Her kişi Claude, ChatGPT, Cursor veya Codex'i kendi oturumuyla bağlar — bkz. Yapay zekâ uygulamalarını bağla.

1. Ajan anahtarı oluşturma

Ayarlar › API anahtarları › “Yeni anahtar”, tür “Ajan”:

İzinler: görevler üzerinde çalışmak için projects:read, tasks:read ve tasks:write; Claude not oluşturacaksa notes:write; çalıştırmalar kaydedilecekse agent:run. Talepleri, müşterilere yanıtları, fatura ve teklif taslaklarını, hataları, zamanları, temel göstergeleri, yol haritasını ve fikirleri yalnızca açıkça istersen açarsın (aşağıya bak).
Projeler: tümü veya yalnızca Claude'un üzerinde çalışacağı projeler.
Bitiş: öneri 365 gün.

Anahtar (vd_live_…) tam olarak bir kez görünür. Hemen altında anahtar dahil hazır komutla “Claude'u bağla” kartı bulunur.

Talepler, yanıtlar, finans ve raporlar — senin kararın

Varsayılan olarak bir ajan anahtarı hiçbir talebi, hatayı, zamanı ve temel göstergeyi görmez, hiçbir müşteriye yazmaz ve ne faturaya ne teklife, yol haritasına veya fikirlere dokunur. Bu izinlerin her birini anahtar başına kendin açarsın — oluştururken veya sonradan anahtar listesindeki “İzinler” altında. Her biri için form, anahtarın o zaman neler yapabileceğini söyler.

İzin	Anahtar o zaman neler yapabilir
`tickets:read`	Projelerinin taleplerini geçmiş, adlar, e-posta adresleri ve ekran görüntüleri dahil okur. Okuduğu her şey anahtarı girdiğin yapay zekâ hizmetine gider — bunun için sağlayıcısıyla bir veri işleme sözleşmesine ihtiyacın var (GDPR md. 28).
`tickets:write`	Talep oluşturur, dahili notlar ve yanıt taslakları yazar. Bunların hiçbiri müşteriye ulaşmaz.
`tickets:reply`	Müşterilere e-postayla yanıt verir — hemen, yanıtı bir kişi okumadan. “Yanıtı gönder” ile aynı şekilde: senin gönderenin, senin alt bilgin, e-posta dizisi. Her yanıt her zaman bunu bir yapay zekâ asistanının yazdığı notunu taşır. Saatte en fazla 20 yanıt ve talep başına günde 3 yanıt. `tickets:read` gerektirir.
`invoices:write`	Projelerinde fatura taslakları oluşturur — açık saatlerden de — ve kalemlerini değiştirir. Kesinleştirme, gönderme, iptal ve ödemeler sende kalır; bunu yalnızca arayüz değil, veritabanı zorunlu kılar.
`quotes:write`	Projelerinde teklif taslakları oluşturur ve değiştirir, kalemlerini yönetir ve yeniden siler. Gönderme (ve onunla numara), kabul, ret ve teklifi faturaya dönüştürme sende kalır. Müşteri dosyası olmayan bir aday için teklif oluşturmaz.
`errors:read`	Projelerinin hatalarını hata izleyicinden okur: başlık, seviye, durum, olay ve etkilenen kullanıcı sayısı, zamanlar, bağlantı. Stack trace yok, izleyicinin erişim bilgileri yok.
`errors:write`	Açık bir hatayı çözüldü olarak işaretler — önce izleyicide (hata kaynağının erişimiyle), yalnızca başarılı olursa VentionDesk'te. Erişim salt okunursa hata açık kalır ve Claude nedenini alır. Yeniden ortaya çıkarsa regresyon sayılır (zilde “Hata yeniden”, eşiğinden sonra yeni bir görev). Gizleme ve silme sende kalır. `errors:read` gerektirir.
`time:read`	Projelerinin zaman kayıtlarını okur: gün, süre, açıklama, görev, faturalanabilir ve faturalandı evet/hayır, kişinin adı. Saatlik ücret yok, tutar yok. Çalışanlarının adları böylece yapay zekâ hizmetine gider.
`stats:read`	Raporlar için projelerinin temel göstergeleri: ilerleme, duruma göre görevler, açık ve gecikmiş talepler, yol haritası, monitörler, dağıtımlar, açık pull request'ler. Gelir yok, bütçe yok, gider yok.
`roadmap:write`	Projelerinin yol haritası aşamalarını okur, oluşturur, yeniden adlandırır, kaydırır, sıralar ve tamamlandı olarak işaretler — sıradaki açık aşama paneldeki kilometre taşıdır. Silme sende kalır.
`ideas:write`	Projelerinden biriyle veya (“tüm projeler” ile) projesiz yeni fikirler oluşturur. Okuma, değiştirme ve silme sende kalır — kendi oluşturduğu fikirler dahil.

Bir talebin geçmişinde ajanın her yanıtı, anahtarın adıyla “yapay zekâ gönderdi” olarak işaretlenir.

2. Claude Code'u bağlama

Claude Code'u kur ve oturum aç, ardından terminalde projenin klasöründe:

claude mcp add --transport http ventiondesk https://api.ventiondesk.com/mcp --header "Authorization: Bearer vd_live_…"

vd_live_… yerine anahtarını koy — ya da komutu doğrudan “Claude'u bağla” kartından kopyala. Claude Code ardından HTTP üzerinden VentionDesk'in MCP sunucusuyla konuşur (POST https://api.ventiondesk.com/mcp, durumsuz). Sunucu ajan anahtarlarını ve bağlı bir yapay zekâ uygulamasının oturumunu kabul eder; tarayıcıda oturum açmış bir kişinin token'ını reddeder.

Sonrasında Claude'a basitçe sorarsın: “VentionDesk'te hangi görevler açık?” veya “shop projesindeki sıradaki görevi al.”

3. Araçlar

MCP sunucusu 38 araç sunar. Her biri API'yi senin anahtarınla çağırır — yani bir aracın neler yapabileceğini anahtar belirler. Gerekli izin eksikse araç bunu belirterek yanıt verir.

Araç	Ne yapar
`ventiondesk_list_projects`	Anahtarın görebildiği projeleri, isteğe bağlı olarak duruma göre listeler.
`ventiondesk_get_project`	Slug'ına göre bir proje — depo, dal, teknoloji yığını ve görev sayılarıyla.
`ventiondesk_list_tasks`	Görevleri projeye, duruma ve şu anda çekilebilir olup olmadıklarına göre filtreleyerek listeler.
`ventiondesk_get_task`	Açıklama, önceki geri bildirimler, proje bağlamı ve istenirse görselleriyle bir görev.
`ventiondesk_claim_next_task`	Çalıştırıcı kuralına göre sıradaki açık görevi üstlenir ve tamamını gösterir.
`ventiondesk_claim_task`	Bir görevi üstlenir — atomik olarak, iki çalıştırma asla aynı görevi almaz.
`ventiondesk_report_task_result`	Bir görevin durumunu bildirir ve böylece durumunu belirler.
`ventiondesk_create_task`	Çalışırken fark edilen bir şey için yeni bir görev oluşturur (25 karakter veya daha uzun başlık).
`ventiondesk_start_run`	Üstlenmelerin ve geri bildirimlerin kaydedildiği bir çalıştırma açar.
`ventiondesk_finish_run`	Çalıştırmayı bir durum ve tek satırlık bir özetle kapatır.
`ventiondesk_list_tickets`	Bir projenin taleplerini listeler.
`ventiondesk_get_ticket`	Geçmişi dahil bir talep.
`ventiondesk_add_ticket_note`	Bir talebin geçmişine dahili bir not yazar.
`ventiondesk_draft_ticket_reply`	Bir müşteri yanıtının taslağını oluşturur — gönderilmez.
`ventiondesk_send_ticket_reply`	Müşteriye e-postayla bir yanıt gönderir — yalnızca `tickets:reply` ile.
`ventiondesk_list_invoice_drafts`	Anahtarın projelerindeki fatura taslaklarını listeler.
`ventiondesk_get_invoice_draft`	Kalemleri dahil bir fatura taslağı.
`ventiondesk_create_invoice_draft`	Bir projede fatura taslağı oluşturur.
`ventiondesk_invoice_from_unbilled`	Bir projenin açık saatlerini kayıt başına bir kalemle taslağa dönüştürür.
`ventiondesk_add_invoice_position`	Bir taslağa kalem ekler.
`ventiondesk_update_invoice_position`	Bir taslağın kalemini değiştirir.
`ventiondesk_delete_invoice_position`	Bir taslaktan kalem kaldırır.
`ventiondesk_list_quote_drafts`	Anahtarın projelerindeki teklif taslaklarını listeler — yalnızca `quotes:write` ile.
`ventiondesk_get_quote_draft`	Kalemleri dahil bir teklif taslağı.
`ventiondesk_create_quote_draft`	Bir projede teklif taslağı oluşturur; alıcı projenin müşterisidir.
`ventiondesk_update_quote_draft`	Bir teklif taslağının başlığını veya geçerliliğini değiştirir.
`ventiondesk_delete_quote_draft`	Bir teklif taslağını siler — henüz numarası yoktur.
`ventiondesk_add_quote_position`	Bir teklif taslağına kalem ekler.
`ventiondesk_update_quote_position`	Bir teklif taslağının kalemini değiştirir.
`ventiondesk_delete_quote_position`	Bir teklif taslağından kalem kaldırır.
`ventiondesk_list_project_errors`	Bir projenin açık hataları — yalnızca `errors:read` ile.
`ventiondesk_resolve_error`	Açık bir hatayı izleyicide ve burada çözüldü olarak işaretler — yalnızca `errors:write` ile.
`ventiondesk_list_time_entries`	Bir projenin ücret ve tutar içermeyen zaman kayıtları — yalnızca `time:read` ile.
`ventiondesk_get_project_report`	Bir rapor için para içermeyen proje durumu — yalnızca `stats:read` ile.
`ventiondesk_list_roadmap`	Bir projenin yol haritası aşamaları — yalnızca `roadmap:write` ile.
`ventiondesk_create_roadmap_phase`	Bir yol haritası aşaması oluşturur.
`ventiondesk_update_roadmap_phase`	Bir aşamayı değiştirir, sıralar veya tamamlandı olarak işaretler.
`ventiondesk_create_idea`	Yeni bir fikir oluşturur — yalnızca `ideas:write` ile.

tickets:reply olmadan Claude yanıtları taslak olarak hazırlar ve bir kişi onları gönderir. Bir faturayı kesinleştirmek, göndermek veya ödemek için bir araç yoktur; bir teklifi göndermek, kabul etmek veya reddetmek, bir hatayı gizlemek veya silmek, bir aşamayı silmek ya da fikirleri okumak, değiştirmek ve silmek için de yoktur.

4. Geri bildirimler

Claude her görev için altı geri bildirimden biriyle yanıt verir:

Sonuç	Gösterim	Etkisi
`arbeitet`	Hâlâ çalışıyor	Ara durum. Görev “Devam ediyor” durumunda kalır.
`kontrolle`	Kontrol gerekiyor	Uygulandı ve teslim edildi. Durum “Kontrol edilecek” (Kontrol sütunu); kanıt gerektirir.
`frage`	Sana bir soru	Soru. Durum “Soru”; biri yanıtlayana kadar görev yeniden alınmaz.
`master`	İşletme sahibinin yapması gerekiyor	İşletme sahibinde, durum değişikliği olmadan — örneğin Claude'un erişimi olmayan bir adım.
`blockiert`	Engellendi	Devam edilemiyor. Görev “Devam ediyor” durumunda kalır ve bir kişidedir.
`erledigt`	Tamamlandı	Tamamlandı. Durum “Tamamlandı”; kanıt gerektirir.

“Soru”, “Kontrol gerekiyor”, “İşletme sahibinin yapması gerekiyor” ve “Engellendi”ye görev ayrıntı görünümünde onay veya ret ile yanıt verirsin — bkz. Görevler ve pano. Görev ardından Claude'a geri döner.

/aufgaben gibi bir tur, dosya sistemi olmadan da (tarayıcıda veya uygulamada Claude): “Work on the next open VentionDesk task” demen yeterli. Claude sıradaki görevi alır — çalıştırıcıyla aynı seçimle —, açıklamayı, retler dahil geçmişi ve projeyi (depo, canlı adres, pano bağlantısı) okur, ekran görüntülerini yalnızca gerektiğinde getirir (withAttachments, en fazla üç görsel, her biri 1 MB, diğer dosyalar bir saat geçerli bağlantı olarak), sonucu kanıtla bildirir ve turu kapatır (görevi alma, bildirme ve çalışmayı kapatma yukarıdaki tabloda). Claude, görevi alırken aldığı runId değerini bildirime ve kapanışa aktarır; 30 dakika boyunca yaşam belirtisi göstermeyen bir çalışma zaman aşımına uğramış sayılır.

Claude yalnızca kimseye veya Claude'a atanmış ve ne beklemede, ne kontrolde ne de tamamlanmış görevleri çeker. Claude'un izin verilen sayıda başarısız olduğu bir görev (varsayılan: üç deneme, maxAttempts ile ayarlanabilir) VentionDesk tarafından artık sunulmaz; bir kişinin her yanıtı sayacı sıfırlar.

5. Commit'leri görevlere bağlama

Bir commit mesajı şu satırı içeriyorsa

VentionDesk-Task: <task ID>

VentionDesk commit'i göreve bağlar — GitHub bağlıysa ve depo projede girilmişse. Kimlik, API'nin ve araçların döndürdüğü şekliyle görevin UUID'sidir.

6. MCP olmadan: görev çalıştırıcısı ve API

Claude'u veya başka bir aracı MCP olmadan çalıştırırsan aynı endpoint'leri doğrudan kullanır:

Çalıştırma başlat (isteğe bağlı, izin agent:run): POST /v1/agent/runs; çalışma sırasında POST /v1/agent/runs/:id/heartbeat, sonunda POST /v1/agent/runs/:id/finish. Hayat belirtisi olmayan bir çalıştırma bir süre sonra iptal edilmiş olarak işaretlenir.
Çek: GET /v1/tasks?projectSlug=<slug>&claimable=true, ardından POST /v1/tasks/:id/claim.
Geri bildir: state (arbeitet, kontrolle, frage, master, blockiert, erledigt), summaryMd, detailsMd ve kontrolle ile erledigt için evidence içinde kanıtla POST /v1/tasks/:id/result.
Yeni oluştur: POST /v1/tasks.

VentionDesk bunun için kendisi, bağımlılıksız Node script'lerinden oluşan küçük bir görev çalıştırıcısı kullanır (pull.mjs çeker, push.mjs --state ile geri bildirir, create.mjs oluşturur, finish.mjs çalıştırmayı kapatır); VENTIONDESK_API_KEY ve VENTIONDESK_API_URL ortam değişkenleriyle yönetilir. Paket olarak yayımlanmamıştır; Claude Code için yukarıdaki MCP yolu daha basittir.

Parametreleriyle tüm endpoint'ler: API referansı.