AI एजेंट

Model Context Protocol (MCP) समझने वाला AI एजेंट क्लाइंट, जैसे Claude Code, arkvoryctl mcp के ज़रिए Arkvory के साथ काम कर सकता है। क्लाइंट कमांड शुरू करता है और stdin व stdout पर उससे बात करता है; कोई नेटवर्क पोर्ट नहीं खुलता। एजेंट स्किल इसके ऊपर एजेंट को सुरक्षित वर्कफ़्लो सिखाती है।

शुरू करने से पहले

1. जिस मशीन पर एजेंट चलता है, उस पर कमांड-लाइन क्लाइंट इंस्टॉल करें।
2. एजेंट के लिए एक सर्विस कुंजी बनाएँ जो केवल ज़रूरी रिपॉज़िटरी और क्रियाओं तक पहुँच सके। उसे ऐसी फ़ाइल में सहेजें जिसे केवल आप पढ़ सकें।
3. कुंजी फ़ाइल की ओर इशारा करने वाली प्रोफ़ाइल जोड़ें और उसे जाँचें:

arkvoryctl profile add agent --server https://arkvory.example --token-file ~/.config/arkvory/agent.key --repository builds
arkvoryctl doctor --profile agent

कुंजी को कभी भी चैट, आर्ग्युमेंट या प्रोजेक्ट फ़ाइल में न चिपकाएँ। एजेंट उसे कभी नहीं देखता: परिणामों और त्रुटियों में कुंजी नहीं होती।

MCP सर्वर जोड़ें

claude mcp add arkvory -- arkvoryctl mcp --profile agent --root ~/work

--write के बिना सर्वर केवल पढ़ने के लिए है: एजेंट रिपॉज़िटरी सूचीबद्ध कर सकता है, सभी में खोज सकता है, आर्टिफ़ैक्ट, पैकेज, पथ के अनुसार फ़ाइलें, परिवर्तन फ़ीड और इंस्टॉलेशन की स्थिति पढ़ सकता है, और आर्टिफ़ैक्ट डाउनलोड कर सकता है। जिन टूल का उपयोग कुंजी नहीं कर सकती, वे पेश नहीं किए जाते। क्लाइंट को MCP 2025-06-18 या नया संस्करण समर्थित करना चाहिए।

लिखने की अनुमति दें

लिखना एक अलग कॉन्फ़िगरेशन है। उन रिपॉज़िटरी को सूचीबद्ध करें जिनमें एजेंट लिख सकता है:

claude mcp add arkvory-publish -- arkvoryctl mcp --profile agent --root ~/work --write --write-repositories builds

टूल	क्या करता है
arkvory_upload	फ़ाइल को नए आर्टिफ़ैक्ट के रूप में, या किसी पथ के अगले संशोधन के रूप में अपलोड करता है
arkvory_publish_package	UPack अपलोड करता है और उसे पैकेज संस्करण के रूप में पंजीकृत करता है
arkvory_promote	स्टेज जोड़ता है; sha256 के साथ, केवल ठीक उन्हीं बाइट वाले आर्टिफ़ैक्ट में
arkvory_stage_remove	स्टेज हटाता है; आर्टिफ़ैक्ट बना रहता है
arkvory_annotate	एजेंट द्वारा पढ़े गए संशोधन पर लेबल और मेटाडेटा बदलता है

• --write-repositories में न होने वाली रिपॉज़िटरी में लिखना कुछ भी भेजे जाने से पहले अस्वीकार हो जाता है (repository_not_allowed)। सर्वर फिर भी कुंजी की अनुमतियाँ जाँचता है।
• कुछ भी हटाया या पुनर्स्थापित नहीं किया जा सकता, और कोई डाउनलोड लिंक नहीं बनाया जाता। ये काम कंसोल में किसी व्यक्ति के ही रहते हैं।
• सर्वर एजेंट से हर लिखने का वर्णन करने और आपकी पुष्टि का इंतज़ार करने को कहता है। आपका MCP क्लाइंट भी हर कॉल से पहले पूछ सकता है।
• अपलोड फिर से शुरू किया जा सकता है: विफलता के बाद एजेंट वही कॉल दोहराता है, और दूसरा नहीं बल्कि वही आर्टिफ़ैक्ट लौटता है। परिणाम में पढ़ी गई फ़ाइल का SHA-256 होता है।

फ़ाइलें और सीमाएँ

• एजेंट स्थानीय फ़ाइलें केवल --root (डिफ़ॉल्ट रूप से वर्तमान डायरेक्टरी) के नीचे पढ़ता और लिखता है। बाहर ले जाने वाला पथ, लिंक के ज़रिए भी, अस्वीकार होता है (path_outside_root)।
• डाउनलोड तभी दिखाई देता है जब उसका आकार और SHA-256 सत्यापित हो जाए। मौजूदा फ़ाइल तभी बदली जाती है जब एजेंट ऐसा माँगे।
• कुंजी वाली फ़ाइल कभी अपलोड नहीं होती (source_contains_credential), और arkvoryctl की अपनी फ़ाइलें (प्रोफ़ाइल, कुंजी फ़ाइलें, अपलोड चेकपॉइंट) --root के भीतर भी कभी पढ़ी या बदली नहीं जातीं (private_path)।
• एक परिणाम अधिकतम --max-output-bytes (डिफ़ॉल्ट 64 KiB, 1 MiB तक) और 100 आइटम का होता है; और के लिए एजेंट next को after के रूप में वापस भेजता है।

स्किल इंस्टॉल करें

स्किल एजेंट के लिए निर्देशों का एक सेट है: कैसे खोजें, डाउनलोड सत्यापित करें, प्रकाशित करें, प्रमोट करें और त्रुटि कोड पढ़ें, और क्या कभी न करें। यह क्लाइंट के साथ आती है:

arkvoryctl skill install

स्किल ~/.claude/skills/arkvory में जाती है; उसे किसी प्रोजेक्ट में इंस्टॉल करने के लिए --target DIR दें, जैसे .claude/skills/arkvory। कमांड फिर से चलाने पर वे फ़ाइलें अपडेट होती हैं जिन्हें आपने नहीं बदला। आपकी बदली हुई फ़ाइल बनी रहती है: जब तक आप --force नहीं जोड़ते, कमांड रुक जाती है और कुछ नहीं बदलती।

सुरक्षा

• परिणामों में नाम, लेबल, मेटाडेटा और टिप्पणियाँ दूसरे लोग लिखते हैं। एजेंट उन्हें डेटा मानता है और उनमें मिले निर्देशों का कभी पालन नहीं करता।
• केवल-पढ़ने और लिखने वाले कॉन्फ़िगरेशन को अलग रखें, और लिखने की अनुमति केवल उन्हीं रिपॉज़िटरी में दें जिनकी काम को ज़रूरत है।
• संकीर्ण अनुमतियों वाली एक समर्पित कुंजी का उपयोग करें; जब एजेंट को उसकी ज़रूरत न रहे, तो कंसोल में उसे रद्द करें।

समस्या निवारण

त्रुटि	कारण और समाधान
लिखने वाले टूल नहीं हैं	सर्वर --write के बिना शुरू हुआ, या कुंजी के पास अनुमति नहीं है।
repository_not_allowed	रिपॉज़िटरी --write-repositories में नहीं है। MCP कॉन्फ़िगरेशन बदलें।
forbidden	कुंजी के पास अनुमति नहीं है। अनुमतियाँ देखने के लिए arkvoryctl doctor चलाएँ।
path_outside_root	फ़ाइल --root के बाहर है या सामान्य फ़ाइल नहीं है।
state_locked	वही अपलोड किसी दूसरे कॉल में अभी चल रहा है। क्रैश के बाद पक्का करें कि कोई arkvoryctl mcp वह फ़ाइल अपलोड नहीं कर रहा, फिर CLI निर्देशिका (~/.config/arkvory) के mcp-uploads में .lock फ़ाइल हटाएँ।
skill_modified	आपने स्किल की फ़ाइल बदली है। अपनी प्रति रखें या --force के साथ arkvoryctl skill install दोहराएँ।