डेवलपर
Claude और MCP
Claude VentionDesk में टीम के एक सदस्य की तरह काम करता है: वह टास्क लेता है, उन्हें पूरा करता है और रिपोर्ट करता है — ठीक उन्हीं अधिकारों के साथ जो आप उसे दी गई कुंजी में देते हैं। VentionDesk इसके लिए अपना कोई मॉडल नहीं चलाता और कोई शुल्क नहीं लेता: आप अपना Claude लाते हैं (आपके Claude सब्सक्रिप्शन या Anthropic कुंजी के साथ Claude Code)।
वहाँ तक दो रास्ते जाते हैं: MCP सर्वर — Claude Code के लिए सुझाया गया — और सीधे API, जैसे आपकी अपनी स्क्रिप्ट से। यह कुंजी के बिना भी काम करता है: हर व्यक्ति Claude, ChatGPT, Cursor या Codex को अपने साइन इन से जोड़ता है — देखें AI ऐप जोड़ें।
1. एजेंट कुंजी बनाएँ (Create an agent key)
सेटिंग्स › API कुंजियाँ › “नई कुंजी”, प्रकार “एजेंट”:
- अनुमतियाँ: टास्क पर काम करने के लिए
projects:read,tasks:readऔरtasks:write;notes:writeअगर Claude को नोट बनाने हैं;agent:runअगर रन लॉग होने चाहिए। टिकट, ग्राहकों को जवाब, इनवॉइस और कोटेशन ड्राफ़्ट, त्रुटियाँ, समय, मुख्य आँकड़े, रोडमैप और आइडिया आप केवल तभी चालू करें जब आप सच में ऐसा चाहते हों (नीचे देखें)। - प्रोजेक्ट: सभी, या केवल वे जिन पर Claude को काम करना है।
- समाप्ति: सुझाव 365 दिन।
कुंजी (vd_live_…) ठीक एक बार दिखती है। ठीक उसके नीचे “Claude जोड़ें” कार्ड होता है, जिसमें कुंजी के साथ तैयार कमांड होती है।
टिकट, जवाब, फ़ाइनेंस और रिपोर्ट — आपका फ़ैसला (Tickets, replies, finances and reports — your decision)
डिफ़ॉल्ट रूप से एजेंट कुंजी न टिकट देखती है, न त्रुटियाँ, न समय और न मुख्य आँकड़े; वह किसी ग्राहक को नहीं लिखती और न इनवॉइस, न कोटेशन, न रोडमैप और न आइडिया को छूती है। इनमें से हर स्कोप आप हर कुंजी के लिए ख़ुद चालू करते हैं — बनाते समय या बाद में कुंजी सूची में “अनुमतियाँ” के नीचे। हर एक के लिए फ़ॉर्म बताता है कि कुंजी तब क्या कर सकती है।
| स्कोप | कुंजी तब क्या कर सकती है |
|---|---|
tickets:read | अपने प्रोजेक्ट के टिकट पढ़ना, इतिहास, नाम, ईमेल पते और स्क्रीनशॉट समेत। वह जो पढ़ती है, वह उस AI सेवा के पास जाता है जिसमें आप कुंजी डालते हैं — इसके लिए आपको उसके प्रोवाइडर के साथ डेटा प्रोसेसिंग अनुबंध चाहिए (Art. 28 GDPR)। |
tickets:write | टिकट बनाना, आंतरिक नोट और जवाब के ड्राफ़्ट लिखना। इनमें से कुछ भी ग्राहक तक नहीं पहुँचता। |
tickets:reply | ग्राहकों को ईमेल से जवाब देना — तुरंत, बिना किसी व्यक्ति के जवाब पढ़े। “जवाब भेजें” वाला ही तरीका: आपका प्रेषक, आपका फ़ुटर, ईमेल थ्रेड। हर जवाब में हमेशा यह सूचना होती है कि उसे एक AI असिस्टेंट ने लिखा है। प्रति घंटा अधिकतम 20 जवाब और प्रति टिकट प्रति दिन 3। tickets:read ज़रूरी है। |
invoices:write | अपने प्रोजेक्ट में इनवॉइस ड्राफ़्ट बनाना — खुले घंटों से भी — और उनके लाइन आइटम बदलना। फ़ाइनल करना, भेजना, रद्द करना और भुगतान आपके पास रहते हैं; यह डेटाबेस लागू करता है, केवल इंटरफ़ेस नहीं। |
quotes:write | अपने प्रोजेक्ट में कोटेशन ड्राफ़्ट बनाना और बदलना, उनके लाइन आइटम संभालना और उन्हें फिर से हटाना। भेजना (और उसके साथ नंबर), स्वीकार करना, अस्वीकार करना और कोटेशन को इनवॉइस में बदलना आपके पास रहते हैं। यह ग्राहक रिकॉर्ड के बिना किसी संभावित ग्राहक के लिए कोटेशन नहीं बनाती। |
errors:read | आपके एरर ट्रैकर से अपने प्रोजेक्ट की त्रुटियाँ पढ़ना: शीर्षक, स्तर, स्थिति, इवेंट और प्रभावित यूज़र्स की संख्या, समय, लिंक। कोई स्टैक ट्रेस नहीं, ट्रैकर का कोई एक्सेस डेटा नहीं। |
errors:write | किसी खुली त्रुटि को हल के रूप में चिह्नित करना — पहले ट्रैकर पर (आपके त्रुटि स्रोत के एक्सेस से), सफल होने पर ही VentionDesk में। अगर एक्सेस केवल पढ़ने का है, तो त्रुटि खुली रहती है और Claude को कारण मिलता है। अगर वह फिर आती है, तो उसे रिग्रेशन माना जाता है (घंटी में “फिर से त्रुटि”, आपकी सीमा के बाद एक नया टास्क)। छिपाना और हटाना आपके पास रहते हैं। errors:read ज़रूरी है। |
time:read | अपने प्रोजेक्ट की टाइम एंट्री पढ़ना: दिन, अवधि, विवरण, टास्क, बिल योग्य और बिल हुआ हाँ/नहीं, व्यक्ति का नाम। कोई घंटे की दर नहीं, कोई राशि नहीं। इससे आपके स्टाफ़ सदस्यों के नाम AI सेवा के पास जाते हैं। |
stats:read | रिपोर्ट के लिए अपने प्रोजेक्ट के मुख्य आँकड़े: प्रगति, स्थिति के अनुसार टास्क, खुले और अतिदेय टिकट, रोडमैप, मॉनिटर, डिप्लॉयमेंट, खुले पुल रिक्वेस्ट। कोई राजस्व नहीं, कोई बजट नहीं, कोई लागत नहीं। |
roadmap:write | अपने प्रोजेक्ट के रोडमैप चरण पढ़ना, बनाना, नाम बदलना, खिसकाना, क्रम में लगाना और पूरा चिह्नित करना — अगला खुला चरण कॉकपिट में माइलस्टोन होता है। हटाना आपके पास रहता है। |
ideas:write | नए आइडिया बनाना, अपने किसी प्रोजेक्ट के साथ या (“सभी प्रोजेक्ट” के साथ) बिना प्रोजेक्ट के। पढ़ना, बदलना और हटाना आपके पास रहते हैं — उसके ख़ुद बनाए आइडिया समेत। |
किसी टिकट के इतिहास में एजेंट का हर जवाब कुंजी के नाम के साथ “AI द्वारा भेजा गया” के रूप में चिह्नित होता है।
2. टर्मिनल में जोड़ें (Connect Claude Code)
Claude Code इंस्टॉल करें और साइन इन करें, फिर अपने प्रोजेक्ट के फ़ोल्डर में टर्मिनल में:
claude mcp add --transport http ventiondesk https://api.ventiondesk.com/mcp --header "Authorization: Bearer vd_live_…"vd_live_… की जगह अपनी कुंजी डालें — या कमांड सीधे “Claude जोड़ें” कार्ड से कॉपी करें। तब Claude Code HTTP पर VentionDesk के MCP सर्वर से बात करता है (POST https://api.ventiondesk.com/mcp, स्टेटलेस)। सर्वर एजेंट कुंजियाँ और किसी जुड़े हुए AI ऐप का साइन इन स्वीकार करता है; ब्राउज़र में साइन इन किए हुए व्यक्ति का टोकन वह अस्वीकार करता है।
इसके बाद आप Claude से बस पूछें: “VentionDesk में कौन-से टास्क खुले हैं?” या “प्रोजेक्ट shop में अगला टास्क लो।”
3. टूल (The tools)
MCP सर्वर 38 टूल देता है। हर एक आपकी कुंजी से API को कॉल करता है — इसलिए कोई टूल क्या कर सकता है, यह कुंजी तय करती है। अगर स्कोप नहीं है, तो टूल अनुमति न होने का जवाब देता है।
| टूल | यह क्या करता है |
|---|---|
ventiondesk_list_projects | वे प्रोजेक्ट दिखाता है जिन्हें कुंजी देख सकती है, चाहें तो स्थिति के अनुसार। |
ventiondesk_get_project | स्लग से एक प्रोजेक्ट — रिपॉज़िटरी, ब्रांच, स्टैक और टास्क की गिनती के साथ। |
ventiondesk_list_tasks | टास्क दिखाता है, प्रोजेक्ट, स्थिति और इस आधार पर फ़िल्टर करके कि वे अभी लिए जा सकते हैं या नहीं। |
ventiondesk_get_task | विवरण, पिछले नतीजों, प्रोजेक्ट संदर्भ और माँगने पर इमेज के साथ एक टास्क। |
ventiondesk_claim_next_task | रनर के नियम के अनुसार अगला खुला टास्क लेता है और उसे पूरा दिखाता है। |
ventiondesk_claim_task | एक टास्क लेता है — एटॉमिक रूप से, दो रन को कभी एक ही टास्क नहीं मिलता। |
ventiondesk_report_task_result | किसी टास्क का नतीजा बताता है और इससे उसकी स्थिति सेट करता है। |
ventiondesk_create_task | काम के दौरान दिखी किसी बात के लिए नया टास्क बनाता है (शीर्षक 25 या ज़्यादा अक्षरों का)। |
ventiondesk_start_run | एक रन खोलता है, जिसके तहत टास्क लेना और नतीजे लॉग होते हैं। |
ventiondesk_finish_run | रन को एक स्थिति और एक पंक्ति के सारांश के साथ बंद करता है। |
ventiondesk_list_tickets | किसी प्रोजेक्ट के टिकट दिखाता है। |
ventiondesk_get_ticket | इतिहास समेत एक टिकट। |
ventiondesk_add_ticket_note | किसी टिकट के इतिहास में आंतरिक नोट लिखता है। |
ventiondesk_draft_ticket_reply | ग्राहक को जवाब का एक ड्राफ़्ट बनाता है — यह भेजा नहीं जाता। |
ventiondesk_send_ticket_reply | ग्राहक को ईमेल से जवाब भेजता है — केवल tickets:reply के साथ। |
ventiondesk_list_invoice_drafts | कुंजी के प्रोजेक्ट के इनवॉइस ड्राफ़्ट दिखाता है। |
ventiondesk_get_invoice_draft | लाइन आइटम समेत एक इनवॉइस ड्राफ़्ट। |
ventiondesk_create_invoice_draft | किसी प्रोजेक्ट में इनवॉइस ड्राफ़्ट बनाता है। |
ventiondesk_invoice_from_unbilled | किसी प्रोजेक्ट के खुले घंटों को ड्राफ़्ट में बदलता है, हर प्रविष्टि के लिए एक लाइन आइटम। |
ventiondesk_add_invoice_position | किसी ड्राफ़्ट में लाइन आइटम जोड़ता है। |
ventiondesk_update_invoice_position | किसी ड्राफ़्ट का लाइन आइटम बदलता है। |
ventiondesk_delete_invoice_position | किसी ड्राफ़्ट से लाइन आइटम हटाता है। |
ventiondesk_list_quote_drafts | कुंजी के प्रोजेक्ट के कोटेशन ड्राफ़्ट दिखाता है — केवल quotes:write के साथ। |
ventiondesk_get_quote_draft | लाइन आइटम समेत एक कोटेशन ड्राफ़्ट। |
ventiondesk_create_quote_draft | किसी प्रोजेक्ट में कोटेशन ड्राफ़्ट बनाता है; प्राप्तकर्ता प्रोजेक्ट का ग्राहक होता है। |
ventiondesk_update_quote_draft | कोटेशन ड्राफ़्ट का शीर्षक या वैधता बदलता है। |
ventiondesk_delete_quote_draft | कोटेशन ड्राफ़्ट हटाता है — उसका अभी कोई नंबर नहीं होता। |
ventiondesk_add_quote_position | कोटेशन ड्राफ़्ट में लाइन आइटम जोड़ता है। |
ventiondesk_update_quote_position | कोटेशन ड्राफ़्ट का लाइन आइटम बदलता है। |
ventiondesk_delete_quote_position | कोटेशन ड्राफ़्ट से लाइन आइटम हटाता है। |
ventiondesk_list_project_errors | किसी प्रोजेक्ट की खुली त्रुटियाँ — केवल errors:read के साथ। |
ventiondesk_resolve_error | किसी खुली त्रुटि को ट्रैकर पर और यहाँ हल के रूप में चिह्नित करता है — केवल errors:write के साथ। |
ventiondesk_list_time_entries | किसी प्रोजेक्ट की टाइम एंट्री, दरों और राशियों के बिना — केवल time:read के साथ। |
ventiondesk_get_project_report | रिपोर्ट के लिए प्रोजेक्ट की स्थिति, पैसे के बिना — केवल stats:read के साथ। |
ventiondesk_list_roadmap | किसी प्रोजेक्ट के रोडमैप चरण — केवल roadmap:write के साथ। |
ventiondesk_create_roadmap_phase | एक रोडमैप चरण बनाता है। |
ventiondesk_update_roadmap_phase | किसी चरण को बदलता है, क्रम में लगाता है या पूरा चिह्नित करता है। |
ventiondesk_create_idea | एक नया आइडिया बनाता है — केवल ideas:write के साथ। |
tickets:reply के बिना Claude जवाब ड्राफ़्ट के रूप में तैयार करता है और कोई व्यक्ति उन्हें भेजता है। इनवॉइस फ़ाइनल करने, भेजने या भुगतान करने के लिए कोई टूल नहीं है, न ही कोटेशन भेजने, स्वीकार करने या अस्वीकार करने, त्रुटियाँ छिपाने या हटाने, कोई चरण हटाने या आइडिया पढ़ने, बदलने और हटाने के लिए।
4. नतीजे (Results)
Claude हर टास्क पर छह में से एक नतीजे के साथ रिपोर्ट करता है:
| नतीजा | किस रूप में दिखता है | असर |
|---|---|---|
arbeitet | काम जारी है | प्रगति अपडेट। टास्क “काम जारी” रहता है। |
kontrolle | रिव्यू ज़रूरी | लागू और डिलीवर किया गया। स्थिति “रिव्यू के लिए” (रिव्यू कॉलम); सबूत ज़रूरी है। |
frage | आपके लिए सवाल | सवाल। स्थिति “सवाल”; जब तक कोई जवाब न दे, टास्क दोबारा नहीं लिया जाता। |
master | मालिक के करने के लिए | मालिक के पास, स्थिति बदले बिना — उदाहरण के लिए ऐसा कदम जिस तक Claude की पहुँच नहीं है। |
blockiert | अवरुद्ध | आगे नहीं बढ़ सकता। टास्क “काम जारी” रहता है और किसी व्यक्ति के पास है। |
erledigt | पूरा | पूरा। स्थिति “पूरा”; सबूत ज़रूरी है। |
“सवाल”, “रिव्यू ज़रूरी”, “मालिक के करने के लिए” और “अवरुद्ध” का जवाब आप टास्क के विवरण में मंज़ूरी या अस्वीकृति से देते हैं — देखें टास्क और बोर्ड। इसके बाद टास्क Claude के पास वापस जाता है।
/aufgaben जैसा एक राउंड, बिना फ़ाइल सिस्टम के भी (ब्राउज़र या ऐप में Claude): “Work on the next open VentionDesk task” कहना काफ़ी है। Claude अगला टास्क लेता है — रनर जैसे ही चुनाव से —, विवरण, अस्वीकृतियों समेत इतिहास और प्रोजेक्ट (रिपॉज़िटरी, लाइव पता, बोर्ड लिंक) पढ़ता है, स्क्रीनशॉट केवल ज़रूरत होने पर लाता है (withAttachments, अधिकतम तीन इमेज, हर एक 1 MB, बाक़ी फ़ाइलें एक घंटे तक मान्य लिंक के रूप में), नतीजा सबूत के साथ रिपोर्ट करता है और राउंड बंद करता है (टास्क लेना, रिपोर्ट करना और रन बंद करना ऊपर की तालिका में हैं)। टास्क लेते समय मिला runId Claude रिपोर्ट और समापन तक आगे देता है; 30 मिनट तक बिना किसी संकेत वाला रन टाइमआउट माना जाता है।
Claude केवल वे टास्क लेता है जो किसी को नहीं या Claude को सौंपे गए हैं और जो न रुके हुए हैं, न रिव्यू में और न पूरे। जिस टास्क में Claude अनुमत संख्या जितनी बार विफल हो चुका है (डिफ़ॉल्ट: तीन प्रयास, maxAttempts से बदला जा सकता है), उसे VentionDesk फिर नहीं देता; किसी व्यक्ति का हर जवाब गिनती को फिर से शून्य कर देता है।
5. कमिट को टास्क से जोड़ना (Linking commits to tasks)
अगर किसी कमिट मैसेज में यह पंक्ति हो
VentionDesk-Task: <task ID>
तो VentionDesk कमिट को टास्क से जोड़ देता है — बशर्ते GitHub जुड़ा हो और प्रोजेक्ट में रिपॉज़िटरी दर्ज हो। ID टास्क का UUID है, जैसा API और टूल लौटाते हैं।
6. बिना MCP: टास्क रनर और API (Without MCP: the task runner and the API)
अगर आप Claude या किसी दूसरे टूल को बिना MCP के काम करने देते हैं, तो वह यही एंडपॉइंट सीधे इस्तेमाल करता है:
- रन शुरू करें (वैकल्पिक, स्कोप
agent:run):POST /v1/agent/runs; काम के दौरानPOST /v1/agent/runs/:id/heartbeat, अंत मेंPOST /v1/agent/runs/:id/finish। जीवित होने के संकेत के बिना रन कुछ समय बाद रद्द के रूप में चिह्नित हो जाता है। - लें:
GET /v1/tasks?projectSlug=<slug>&claimable=true, फिरPOST /v1/tasks/:id/claim। - रिपोर्ट करें:
POST /v1/tasks/:id/resultके साथstate(arbeitet,kontrolle,frage,master,blockiert,erledigt),summaryMd,detailsMdऔरkontrolleतथाerledigtके साथevidenceमें सबूत। - नए बनाएँ:
POST /v1/tasks।
VentionDesk ख़ुद इसके लिए बिना डिपेंडेंसी वाली Node स्क्रिप्ट से बना एक छोटा टास्क रनर इस्तेमाल करता है (pull.mjs लेता है, push.mjs --state के साथ रिपोर्ट करता है, create.mjs बनाता है, finish.mjs रन बंद करता है), जिसे एनवायरनमेंट वेरिएबल VENTIONDESK_API_KEY और VENTIONDESK_API_URL से चलाया जाता है। यह पैकेज के रूप में प्रकाशित नहीं है; Claude Code के लिए ऊपर वाला MCP तरीका ज़्यादा आसान है।
पैरामीटर के साथ सभी एंडपॉइंट: API रेफ़रेंस।