MCP रनटाइम जीवनचक्र

यह दस्तावेज़ वर्णन करता है कि MCP सर्वर coding-agent रनटाइम में कैसे खोजे, कनेक्ट किए, टूल्स के रूप में एक्सपोज़ किए, रिफ्रेश किए और बंद किए जाते हैं।

जीवनचक्र एक नज़र में

1. SDK स्टार्टअप discoverAndLoadMCPTools() कॉल करता है (जब तक MCP अक्षम न हो)।
2. डिस्कवरी (loadAllMCPConfigs) कैपेबिलिटी स्रोतों से MCP सर्वर कॉन्फ़िग रिज़ॉल्व करता है, अक्षम/प्रोजेक्ट/Exa एंट्रीज़ को फ़िल्टर करता है, और स्रोत मेटाडेटा संरक्षित रखता है।
3. मैनेजर कनेक्ट चरण (MCPManager.connectServers) प्रति-सर्वर कनेक्ट + tools/list को समानांतर में शुरू करता है।
4. फास्ट स्टार्टअप गेट 250ms तक प्रतीक्षा करता है, फिर लौटा सकता है:
   • पूरी तरह लोड हुए MCPTools,
   • प्रति सर्वर विफलताएँ,
   • या अभी भी लंबित सर्वरों के लिए कैश्ड DeferredMCPTools।
5. SDK वायरिंग MCP टूल्स को सेशन के लिए रनटाइम टूल रजिस्ट्री में मर्ज करता है।
6. लाइव सेशन /mcp फ्लो (disconnectAll + पुनः खोज + session.refreshMCPTools) के माध्यम से MCP टूल्स को रिफ्रेश कर सकता है।
7. टियरडाउन तब होता है जब कॉलर disconnectServer/disconnectAll इनवोक करते हैं; मैनेजर डिस्कनेक्ट किए गए सर्वरों के लिए MCP टूल रजिस्ट्रेशन भी हटाता है।

डिस्कवरी और लोड चरण

SDK से एंट्री पथ

createAgentSession() (src/sdk.ts में) जब enableMCP true होता है (डिफ़ॉल्ट) तब MCP स्टार्टअप करता है:

• discoverAndLoadMCPTools(cwd, { ... }) कॉल करता है,
• authStorage, कैश स्टोरेज, और mcp.enableProjectConfig सेटिंग पास करता है,
• हमेशा filterExa: true सेट करता है,
• प्रति-सर्वर लोड/कनेक्ट त्रुटियाँ लॉग करता है,
• लौटाए गए मैनेजर को toolSession.mcpManager और सेशन रिज़ल्ट में संग्रहीत करता है।

यदि enableMCP false है, तो MCP डिस्कवरी पूरी तरह स्किप हो जाती है।

कॉन्फ़िग डिस्कवरी और फ़िल्टरिंग

loadAllMCPConfigs() (src/mcp/config.ts) कैपेबिलिटी डिस्कवरी के माध्यम से कैनोनिकल MCP सर्वर आइटम लोड करता है, फिर लिगेसी MCPServerConfig में कन्वर्ट करता है।

फ़िल्टरिंग व्यवहार:

• enableProjectConfig: false प्रोजेक्ट-स्तरीय एंट्रीज़ (_source.level === "project") को हटाता है।
• enabled: false सर्वर कनेक्ट प्रयासों से पहले स्किप किए जाते हैं।
• Exa सर्वर डिफ़ॉल्ट रूप से फ़िल्टर किए जाते हैं और API कुंजियाँ नेटिव Exa टूल इंटीग्रेशन के लिए निकाली जाती हैं।

परिणाम में configs और sources (मेटाडेटा जो बाद में प्रोवाइडर लेबलिंग के लिए उपयोग होता है) दोनों शामिल हैं।

डिस्कवरी-स्तरीय विफलता व्यवहार

discoverAndLoadMCPTools() दो विफलता वर्गों में अंतर करता है:

• डिस्कवरी हार्ड विफलता (manager.discoverAndConnect से अपवाद, आमतौर पर कॉन्फ़िग डिस्कवरी से): एक खाली टूल सेट और एक सिंथेटिक त्रुटि { path: ".mcp.json", error } लौटाता है।
• प्रति-सर्वर रनटाइम/कनेक्ट विफलता: मैनेजर errors मैप के साथ आंशिक सफलता लौटाता है; अन्य सर्वर जारी रहते हैं।

अतः जब व्यक्तिगत MCP सर्वर विफल होते हैं तो स्टार्टअप पूरे एजेंट सेशन को विफल नहीं करता।

मैनेजर स्टेट मॉडल

MCPManager अलग-अलग रजिस्ट्रीज़ के साथ रनटाइम जीवनचक्र ट्रैक करता है:

• #connections: Map<string, MCPServerConnection> — पूरी तरह कनेक्टेड सर्वर।
• #pendingConnections: Map<string, Promise<MCPServerConnection>> — हैंडशेक प्रगति में।
• #pendingToolLoads: Map<string, Promise<{ connection, serverTools }>> — कनेक्टेड लेकिन टूल्स अभी लोड हो रहे हैं।
• #tools: CustomTool[] — कॉलर्स को एक्सपोज़ किया गया वर्तमान MCP टूल व्यू।
• #sources: Map<string, SourceMeta> — कनेक्ट पूरा होने से पहले भी प्रोवाइडर/स्रोत मेटाडेटा।

getConnectionStatus(name) इन मैप्स से स्टेटस प्राप्त करता है:

• connected यदि #connections में है,
• connecting यदि पेंडिंग कनेक्ट या पेंडिंग टूल लोड में है,
• disconnected अन्यथा।

कनेक्शन स्थापना और स्टार्टअप टाइमिंग

प्रति-सर्वर कनेक्ट पाइपलाइन

connectServers() में प्रत्येक खोजे गए सर्वर के लिए:

1. स्रोत मेटाडेटा स्टोर/अपडेट करें,
2. यदि पहले से कनेक्टेड/पेंडिंग है तो स्किप करें,
3. ट्रांसपोर्ट फ़ील्ड्स वैलिडेट करें (validateServerConfig),
4. ऑथ/शेल प्रतिस्थापन रिज़ॉल्व करें (#resolveAuthConfig),
5. connectToServer(name, resolvedConfig) कॉल करें,
6. listTools(connection) कॉल करें,
7. टूल परिभाषाएँ कैश करें (MCPToolCache.set) सर्वोत्तम-प्रयास।

connectToServer() व्यवहार (src/mcp/client.ts):

• stdio या HTTP/SSE ट्रांसपोर्ट बनाता है,
• MCP initialize + notifications/initialized करता है,
• टाइमआउट उपयोग करता है (config.timeout या 30s डिफ़ॉल्ट),
• init विफलता पर ट्रांसपोर्ट बंद करता है।

फास्ट स्टार्टअप गेट + डिफ़र्ड फ़ॉलबैक

connectServers() इनके बीच एक रेस पर प्रतीक्षा करता है:

• सभी कनेक्ट/टूल-लोड कार्य सेटल हो जाएँ, और
• STARTUP_TIMEOUT_MS = 250।

250ms के बाद:

• पूर्ण हुए कार्य लाइव MCPTools बन जाते हैं,
• अस्वीकृत कार्य प्रति-सर्वर त्रुटियाँ उत्पन्न करते हैं,
• अभी भी लंबित कार्य:
  • यदि उपलब्ध हो तो कैश्ड टूल परिभाषाओं (MCPToolCache.get) का उपयोग करके DeferredMCPTools बनाते हैं,
  • अन्यथा उन लंबित कार्यों के सेटल होने तक प्रतीक्षा करते हैं।

यह एक हाइब्रिड स्टार्टअप मॉडल है: कैश उपलब्ध होने पर तेज़ रिटर्न, कैश न होने पर शुद्धता के लिए प्रतीक्षा।

बैकग्राउंड पूर्णता व्यवहार

प्रत्येक लंबित toolsPromise की एक बैकग्राउंड कंटिन्यूएशन भी होती है जो अंततः:

• #replaceServerTools के माध्यम से मैनेजर स्टेट में उस सर्वर के टूल स्लाइस को बदलती है,
• कैश लिखती है,
• स्टार्टअप के बाद ही विलंबित विफलताएँ लॉग करती है (allowBackgroundLogging)।

टूल एक्सपोज़र और लाइव-सेशन उपलब्धता

स्टार्टअप रजिस्ट्रेशन

discoverAndLoadMCPTools() मैनेजर टूल्स को LoadedCustomTool[] में कन्वर्ट करता है और पथों को सजाता है (mcp:<server> via <providerName> जब ज्ञात हो)।

createAgentSession() फिर इन टूल्स को customTools में पुश करता है, जो mcp_<server>_<tool> जैसे नामों के साथ रैप और रनटाइम टूल रजिस्ट्री में जोड़े जाते हैं।

टूल कॉल

• MCPTool पहले से कनेक्टेड MCPServerConnection के माध्यम से टूल्स कॉल करता है।
• DeferredMCPTool कॉल करने से पहले waitForConnection(server) की प्रतीक्षा करता है; यह कैश्ड टूल्स को कनेक्शन तैयार होने से पहले अस्तित्व में रहने देता है।

दोनों संरचित टूल आउटपुट लौटाते हैं और ट्रांसपोर्ट/टूल त्रुटियों को MCP error: ... टूल कंटेंट में कन्वर्ट करते हैं (abort वैसा ही रहता है)।

रिफ्रेश/रीलोड पथ (स्टार्टअप बनाम लाइव रीलोड)

प्रारंभिक स्टार्टअप पथ

• sdk.ts में एकबारगी डिस्कवरी/लोड,
• टूल्स प्रारंभिक सेशन टूल रजिस्ट्री में रजिस्टर किए जाते हैं।

इंटरैक्टिव रीलोड पथ

/mcp reload पथ (src/modes/controllers/mcp-command-controller.ts) करता है:

1. mcpManager.disconnectAll(),
2. mcpManager.discoverAndConnect(),
3. session.refreshMCPTools(mcpManager.getTools())।

session.refreshMCPTools() (src/session/agent-session.ts) सभी mcp_ टूल्स हटाता है, नवीनतम MCP टूल्स को पुनः रैप करता है, और टूल सेट को पुनः सक्रिय करता है ताकि MCP परिवर्तन सेशन पुनरारंभ किए बिना लागू हों।

विलंबित कनेक्शनों के लिए एक फॉलो-अप पथ भी है: किसी विशिष्ट सर्वर की प्रतीक्षा के बाद, यदि स्टेटस connected हो जाता है, तो यह session.refreshMCPTools(...) पुनः चलाता है ताकि नए उपलब्ध टूल्स इन-सेशन पुनः बाउंड हों।

हेल्थ, रीकनेक्ट, और आंशिक विफलता व्यवहार

वर्तमान रनटाइम व्यवहार जानबूझकर न्यूनतम है:

• मैनेजर/क्लाइंट में कोई स्वायत्त हेल्थ मॉनिटर नहीं।
• जब ट्रांसपोर्ट ड्रॉप होता है तो कोई स्वचालित रीकनेक्ट लूप नहीं।
• मैनेजर ट्रांसपोर्ट onClose/onError को सब्सक्राइब नहीं करता; स्टेटस रजिस्ट्री-आधारित है।
• रीकनेक्ट स्पष्ट है: रीलोड फ्लो या सीधा connectServers() इनवोकेशन।

संचालन की दृष्टि से:

• एक सर्वर विफल होने से स्वस्थ सर्वरों के टूल्स नहीं हटते,
• कनेक्ट/लिस्ट विफलताएँ प्रति सर्वर पृथक हैं,
• टूल कैश और बैकग्राउंड अपडेट सर्वोत्तम-प्रयास हैं (चेतावनियाँ/त्रुटियाँ लॉग होती हैं, कोई हार्ड स्टॉप नहीं)।

टियरडाउन सेमेंटिक्स

सर्वर-स्तरीय टियरडाउन

disconnectServer(name):

• पेंडिंग एंट्रीज़/स्रोत मेटाडेटा हटाता है,
• कनेक्टेड होने पर ट्रांसपोर्ट बंद करता है,
• मैनेजर स्टेट से उस सर्वर के mcp_ टूल्स हटाता है।

ग्लोबल टियरडाउन

disconnectAll():

• Promise.allSettled के साथ सभी सक्रिय ट्रांसपोर्ट बंद करता है,
• पेंडिंग मैप्स, स्रोत, कनेक्शन, और मैनेजर टूल सूची साफ़ करता है।

वर्तमान वायरिंग में, स्पष्ट टियरडाउन MCP कमांड फ्लो (रीलोड/रिमूव/डिसेबल के लिए) में उपयोग किया जाता है। स्टार्टअप पथ में कोई अलग स्वचालित मैनेजर डिस्पोज़ल हुक नहीं है; जब कॉलर्स को निर्धारक MCP शटडाउन की आवश्यकता होती है तो वे मैनेजर डिस्कनेक्ट विधियों को इनवोक करने के लिए ज़िम्मेदार हैं।

विफलता मोड और गारंटी

परिदृश्य	व्यवहार	हार्ड फेल बनाम सर्वोत्तम-प्रयास
डिस्कवरी थ्रो करती है (कैपेबिलिटी/कॉन्फ़िग लोड पथ)	लोडर खाली टूल्स + सिंथेटिक .mcp.json त्रुटि लौटाता है	सर्वोत्तम-प्रयास सेशन स्टार्टअप
अमान्य सर्वर कॉन्फ़िग	सर्वर वैलिडेशन त्रुटि एंट्री के साथ स्किप	सर्वोत्तम-प्रयास प्रति सर्वर
कनेक्ट टाइमआउट/init विफलता	सर्वर त्रुटि रिकॉर्ड; अन्य जारी	सर्वोत्तम-प्रयास प्रति सर्वर
स्टार्टअप पर tools/list अभी भी लंबित, कैश हिट के साथ	डिफ़र्ड टूल्स तुरंत लौटाए जाते हैं	सर्वोत्तम-प्रयास तेज़ स्टार्टअप
स्टार्टअप पर tools/list अभी भी लंबित, कैश के बिना	स्टार्टअप लंबित के सेटल होने तक प्रतीक्षा करता है	शुद्धता के लिए हार्ड वेट
विलंबित बैकग्राउंड टूल-लोड विफलता	स्टार्टअप गेट के बाद लॉग	सर्वोत्तम-प्रयास लॉगिंग
रनटाइम ड्रॉप्ड ट्रांसपोर्ट	कोई स्वचालित रीकनेक्ट नहीं; रीकनेक्ट/रीलोड तक भविष्य के कॉल विफल	मैनुअल कार्रवाई द्वारा सर्वोत्तम-प्रयास रिकवरी

सार्वजनिक API सतह

src/mcp/index.ts बाहरी कॉलर्स के लिए लोडर/मैनेजर/क्लाइंट APIs को पुनः निर्यात करता है। src/sdk.ts एक सुविधा रैपर के रूप में discoverMCPServers() एक्सपोज़ करता है जो समान लोडर रिज़ल्ट शेप लौटाता है।

कार्यान्वयन फ़ाइलें

• src/mcp/loader.ts — लोडर फ़साड, डिस्कवरी त्रुटि सामान्यीकरण, LoadedCustomTool रूपांतरण।
• src/mcp/manager.ts — जीवनचक्र स्टेट रजिस्ट्रीज़, समानांतर कनेक्ट/लिस्ट फ्लो, रिफ्रेश/डिस्कनेक्ट।
• src/mcp/client.ts — ट्रांसपोर्ट सेटअप, इनिशियलाइज़ हैंडशेक, लिस्ट/कॉल/डिस्कनेक्ट।
• src/mcp/index.ts — MCP मॉड्यूल API निर्यात।
• src/sdk.ts — सेशन/टूल रजिस्ट्री में स्टार्टअप वायरिंग।
• src/mcp/config.ts — मैनेजर द्वारा उपयोग किया जाने वाला कॉन्फ़िग डिस्कवरी/फ़िल्टरिंग/वैलिडेशन।
• src/mcp/tool-bridge.ts — MCPTool और DeferredMCPTool रनटाइम व्यवहार।
• src/session/agent-session.ts — refreshMCPTools लाइव रीबाइंडिंग।
• src/modes/controllers/mcp-command-controller.ts — इंटरैक्टिव रीलोड/रीकनेक्ट फ्लो।
• src/task/executor.ts — पैरेंट मैनेजर कनेक्शनों के माध्यम से सबएजेंट MCP प्रॉक्सिंग।