MCP सेवा

AWR अपना वर्क लेजर MCP (Model Context Protocol) के माध्यम से प्रस्तुत करता है — यह वह मानक प्रोटोकॉल है जो किसी एजेंट होस्ट — जैसे कोडिंग असिस्टेंट या डेस्कटॉप AI क्लाइंट — को टूल खोजने और कॉल करने देता है। MCP सेवा वह तरीका है जिससे आपका एजेंट प्रोजेक्ट स्थिति पढ़ता है, कॉन्टेक्स्ट कम्पाइल करता है, साक्ष्य दर्ज करता है, और खुद CLI को शेल से बुलाए बिना काम को आगे बढ़ाता है। इसे चलाने के दो तरीके हैं:

• stdio — एक लोकल प्रोसेस जिसे आपका क्लाइंट सीधे चलाता है, एक बार में एक प्रोजेक्ट। यह क्लासिक सेटअप है और उपलब्ध बना हुआ है।
• साझा HTTP — एक Streamable HTTP एंडपॉइंट जो कई प्रोजेक्टों और कई स्वतंत्र क्लाइंटों को सेवा देता है। npm और PyPI दोनों पैकेज में यह क्षमता शामिल है।

यह लेख साझा HTTP सेवा पर केंद्रित है, जिसे आप तब चलाते हैं जब एक से अधिक व्यक्ति या एजेंट को वही प्रोजेक्ट चाहिए। कनेक्ट होने के बाद एजेंट इन टूल से क्या करते हैं, इसके लिए Agents देखें। उन्हीं ऑपरेशन के मानव-मुखी समकक्ष के लिए AWR CLI देखें।

साझा सेवा कैसे काम करती है

आप सर्वर पर प्रत्येक प्रोजेक्ट को awr init से इनिशियलाइज़ करते हैं, फिर उसके कैनोनिकल निरपेक्ष रूट को उस project_id के साथ पंजीकृत करते हैं जो मिलता है:

awr --json status

AWR स्टार्टअप पर और हर रिक्वेस्ट पर उस पहचान सत्यापित करता है। स्रोत फ़ाइलें और हर प्रोजेक्ट का .awr डेटाबेस अलग रहते हैं — सेवा रिपॉज़िटरी क्लोन नहीं करती, क्लाइंट फ़ाइलसिस्टम माउंट नहीं करती, और न प्रोजेक्ट लेजर मर्ज करती है। क्लाइंटों को सेवा तक नेटवर्क पहुँच चाहिए, लोकल AWR एक्ज़िक्यूटेबल नहीं, और प्रोजेक्ट फ़ाइलें सर्वर पर पठनीय होनी चाहिए: क्लाइंट लैपटॉप का पथ दूरस्थ रूप से पठनीय नहीं बन जाता। कोई साझा "वर्तमान प्रोजेक्ट" नहीं है — हर प्रोजेक्ट टूल एक स्पष्ट project तर्क लेता है, और मनमाना सर्वर पथ खोलने का कोई टूल नहीं है।

सेवा कॉन्फ़िगर करना

पब्लिक रिपॉज़िटरी के बाहर एक ऑपरेटर-स्वामित्व वाली TOML फ़ाइल बनाएँ:

version = 1
allowed_hosts = ["awr.internal.example"]

[[projects]]
key = "billing"
root = "/srv/projects/billing"
project_id = "<actual project ID>"

[[projects]]
key = "support"
root = "/srv/projects/support"
project_id = "<actual project ID>"

[[clients]]
id = "engineering"
token_env = "AWR_ENGINEERING_TOKEN"
write = ["billing", "support"]

[[clients]]
id = "reviewer"
token_env = "AWR_REVIEWER_TOKEN"
read = ["billing"]

प्रत्येक क्लाइंट प्रविष्टि एक एनवायरनमेंट वेरिएबल का नाम देती है जिसमें उसका बियरर क्रेडेंशियल होता है। कम से कम 32 वर्णों के अलग-अलग, यादृच्छिक रूप से बने क्रेडेंशियल दें। write अनुमति में रीड एक्सेस शामिल होता है; read अनुमति प्रोजेक्ट नहीं बदल सकती। क्रेडेंशियल रोटेशन के दौरान क्लाइंट ID स्थिर रखें — वार्तालाप और रिक्वेस्ट बाइंडिंग क्लाइंट ID से जुड़ती हैं, और इसे बदलने से एक अलग स्कोप बनता है। कॉन्फ़िगरेशन बदलाव केवल सेवा रीस्टार्ट के बाद प्रभावी होते हैं।

सेवा चलाना

awr-mcp --registry /etc/awr/service.toml --listen 127.0.0.1:8080

हर HTTP रिक्वेस्ट प्रमाणित होती है। अंतर्निहित तंत्र स्थिर बियरर प्रमाणीकरण है — OAuth ऑथराइज़ेशन सर्वर या एंटरप्राइज़ आइडेंटिटी प्रोवाइडर नहीं। दूरस्थ पहुँच के लिए, किसी प्रमाणित डिप्लॉयमेंट सीमा पर HTTPS समाप्त करें और बैकएंड तक सीधी पहुँच सीमित रखें। अतिरिक्त एक्सेस नियंत्रण:

• Origin तब तक अस्वीकृत रहते हैं जब तक allowed_origins में स्पष्ट रूप से सूचीबद्ध न हों; नेटिव क्लाइंट आम तौर पर Origin हेडर नहीं भेजते।
• SDK allowed_hosts की जाँच करता है; कुछ कॉन्फ़िगर न होने पर डिफ़ॉल्ट लूपबैक होस्ट होते हैं।
• सेवा Origin सत्यापित करती है लेकिन ब्राउज़र CORS preflight लागू नहीं करती, इसलिए ब्राउज़र फ्रंटएंड को उचित गेटवे चाहिए।

Unix पर, SIGTERM और Ctrl-C नई रिक्वेस्ट स्वीकार करना सौम्य रूप से बंद कर देते हैं और सक्रिय HTTP काम को पूरा होने देते हैं। क्लाइंट डिस्कनेक्ट करना या सेवा रीस्टार्ट करना कभी AWR वर्क सत्र समाप्त नहीं करता — प्रोटोकॉल कनेक्शन और स्थायी सत्र अलग-अलग पहचान हैं। AWR कोई सिस्टम डेमॉन इंस्टॉल नहीं करता — स्टार्टअप और रीस्टार्ट के लिए अपने डिप्लॉयमेंट के प्रोसेस सुपरवाइज़र का उपयोग करें। लोकल, एकल-क्लाइंट उपयोग के लिए stdio कमांड बना हुआ है:

awr-mcp --project /absolute/project

क्लाइंट कनेक्ट करना

प्रत्येक MCP क्लाइंट को Streamable HTTP के लिए उसी सेवा URL के साथ /mcp पथ पर कॉन्फ़िगर करें, साथ में उस क्लाइंट के क्रेडेंशियल तंत्र से दिया गया अपना बियरर क्रेडेंशियल Authorization: Bearer … हेडर में। कनेक्ट होने के बाद, अपने क्रेडेंशियल के लिए अधिकृत प्रोजेक्ट कुंजियाँ खोजने हेतु awr_projects_list कॉल करें। फिर हर प्रोजेक्ट टूल को project चाहिए:

{"project": "billing", "work": "INVOICE-001"}

टूल

साझा HTTP सेवा कुल 21 टूल प्रस्तुत करती है (stdio पर 20, जिसमें प्रोजेक्ट-सूची टूल नहीं होता)। वे तीन समूहों में बँटते हैं।

कार्य और कॉन्टेक्स्ट टूल

ये रोज़मर्रा की CLI क्रियाओं के समकक्ष हैं:

सत्र और निरंतरता टूल

सत्र किसी वार्तालाप को काम की एक इकाई से बाँधते हैं। अपने होस्ट से एक स्थिर conversation पहचानकर्ता दें — HTTP कनेक्शन पहचानकर्ता नहीं। किसी अन्य प्रोजेक्ट या क्लाइंट के तहत वही वार्तालाप स्ट्रिंग एक अलग बाइंडिंग है।

लंबित प्रतीक्षा कार्य संक्रमण और resume को तब तक ब्लॉक करती है जब तक होस्ट उत्तर दर्ज न करे। उत्तर वह ब्लॉक हटा देता है लेकिन कार्य स्थिति नहीं बदलता और न ही होस्ट के अगले टर्न को शेड्यूल करता है — आपका होस्ट सत्र का निरीक्षण करता है, ताज़ा कॉन्टेक्स्ट कम्पाइल करता है, और तय करता है कि जारी रखना है या उत्तराधिकारी बनाना है।

लेखन, रिवीज़न और अनिश्चित परिणाम

हर साझा HTTP लेखन को दो चीज़ें चाहिए:

• क्लाइंट-जनित, स्थिर request_id (256 बाइट तक),
• आपका आखिरी बार देखा गया expected_revision।

{
  "project": "billing",
  "request_id": "host-turn-42-start",
  "expected_revision": 120,
  "work": "INVOICE-001",
  "conversation": "invoice-review",
  "agent": "billing-assistant",
  "provider": "example-provider",
  "model": "example-model",
  "claim": true
}

ठीक वही रिक्वेस्ट ID और तर्क दोहराने पर क्रिया दोबारा चलाए बिना दर्ज परिणाम लौटता है, इसलिए टाइमआउट के बाद पुनः प्रयास सुरक्षित है। बदले हुए तर्कों के लिए नई ID चाहिए। अपने अगले लेखन के लिए लौटा project_revision सहेजें, और अगला रिवीज़न एक जोड़कर कभी न निकालें: रिक्वेस्ट जर्नल और डोमेन ऑपरेशन दोनों रिवीज़न खर्च करते हैं।

टाइमआउट या डिस्कनेक्ट के बाद, उसी प्रोजेक्ट और रिक्वेस्ट ID के साथ awr_operation_get कॉल करें। अधूरी रिक्वेस्ट write_outcome: unknown रिपोर्ट करती है; बाधित लेखन शायद पहले ही कमिट हो चुका हो, इसलिए बंद हुई HTTP रिस्पॉन्स स्ट्रीम से कभी विफलता का अनुमान न लगाएँ। awr_operation_recover तभी कमिट हुआ परिणाम दर्ज कर सकता है जब रिक्वेस्ट से कोई अद्वितीय टर्मिनल इवेंट बंधा हो — यह मूल टूल को कभी दोबारा नहीं बुलाता। रीड समवर्ती चल सकते हैं; लेखन प्रति प्रोजेक्ट क्रमबद्ध होते हैं, और अलग-अलग प्रोजेक्टों के स्वतंत्र लॉक होते हैं। पुराना लेखन संघर्ष लौटाता है — पुनः प्रयास से पहले वर्तमान स्थिति पढ़ें और पुनर्विचार करें।

वर्कस्ट्रीम रीड (विकास में)

विकास स्रोत एक रजिस्ट्री version = 2 जोड़ता है जो YAML वर्कस्ट्रीम लेजर इस्तेमाल करने वाले प्रोजेक्टों के लिए स्पष्ट रूप से सूचीबद्ध, अपरिवर्तनीय वर्कस्ट्रीम तक क्लाइंटों को केवल-पढ़ने की पहुँच देता है। ये ऑपरेटर-स्वामित्व अनुमतियाँ हैं: केवल प्रोजेक्ट-स्तरीय read/write अनुमतियाँ किसी भी आइसोलेटेड वर्कस्ट्रीम को अधिकृत नहीं करतीं।

[[clients.workstreams]]
project = "billing"
workstream_id = "<actual immutable workstream ID>"
authority_version = 1

अधिकृत क्लाइंट केवल-साझा awr_workstream टूल का उपयोग करते हैं, और यह जानने के लिए कि वे क्या पढ़ सकते हैं, action: "capabilities" और action: "list" से शुरुआत करते हैं। वर्तमान सीमाओं से अवगत रहें: यह एक्सटेंशन केवल रीड देता है — कोई म्यूटेशन, कंटेंट-फ़ाइल रीड या Team PostgreSQL ऑपरेशन नहीं — और इसे सक्षम करने वाले प्रोजेक्ट अधिकृत कार्यान्वयन उपलब्ध होने तक लेगसी साझा टूल, सभी लेखन सहित, अस्वीकार कर देते हैं। इस चरण में सक्षम करना और रीइंडेक्स लोकल ऑपरेटर क्रियाएँ हैं।

आगे कहाँ जाएँ

• Agents — कोई एजेंट इन टूल पर सत्र, क्लेम और चेकपॉइंट का उपयोग कैसे करता है।
• AWR CLI — वही डोमेन ऑपरेशन कमांड लाइन से, ऑपरेटर और डिबगिंग के लिए।
• ट्रबलशूटिंग — रिवीज़न संघर्ष, पुराने स्रोत और रिकवरी।