मॉडल संदर्भ प्रोटोकॉल (MCP)

दस्तावेज़ मानचित्र: अवलोकन और आर्किटेक्चर · क्लाइंट · डायनेमिक प्रबंधक · सर्वर लेखन · सुरक्षा · परीक्षण

MCP किसी AI एप्लिकेशन को किसी अन्य प्रक्रिया या सेवा के स्वामित्व वाली क्षमताओं को खोजने और उपयोग करने का एक मानक तरीका प्रदान करता है। कोई सर्वर ये प्रकाशित कर सकता है:

• टूल जो कार्य करते हैं;
• संसाधन जो पढ़ने योग्य संदर्भ लौटाते हैं;
• प्रॉम्प्ट जो पुन: उपयोग योग्य संदेश टेम्पलेट प्रदान करते हैं; और
• पूर्णता सुझाव जो किसी क्लाइंट को प्रॉम्प्ट या संसाधन तर्क भरने में सहायता करते हैं।

ADK-Rust आमतौर पर MCP क्लाइंट होता है। McpToolset खोजे गए MCP टूल को सामान्य ADK-Rust Tool मानों में बदल देता है, ताकि कोई LlmAgent उनका चयन और आह्वान कर सके। फ़्रेमवर्क संसाधनों, प्रॉम्प्ट, पूर्णता, सदस्यताओं, जानकारी-प्राप्ति और वार्तित कार्य जीवनचक्र को भी उजागर करता है। MCP सर्वर लेखन और उन्नत प्रोटोकॉल कार्य के लिए, ADK-Rust अपने द्वारा उपयोग किए जाने वाले सटीक rmcp SDK संस्करण को पुनः निर्यात करता है।

ADK-Rust 2 आधिकारिक Rust SDK, rmcp 3.1 का उपयोग करता है। क्लाइंट MCP 2025-11-25 की घोषणा करता है और उनके पुराने हैंडशेक के माध्यम से 2026-07-28 सर्वरों से जुड़ता है। examples/mcp_protocol_revisions बंडल किए गए सर्वर के विरुद्ध दोनों संशोधनों और SEP-2663 कार्य विस्तार को प्रदर्शित करता है।

आर्किटेक्चर

Rendering architecture…

दो अलग-अलग परतें हैं:

1. McpToolset एक आरंभ किए गए MCP क्लाइंट कनेक्शन का स्वामित्व रखता है। यह सर्वर की क्षमताओं को खोजता है और उन्हें ADK-Rust के अनुरूप ढालता है।
2. McpServerManager स्थानीय stdio सर्वरों की बदलती रजिस्ट्री का स्वामित्व रखता है। यह उन कनेक्शनों को प्रारंभ, मॉनिटर, पुनः प्रारंभ, अद्यतन, सक्षम, अक्षम, स्थायी रूप से सुरक्षित और एकत्रित करता है।

प्रबंधक टूल की अनुमति प्रदान नहीं करता। संगत कॉन्फ़िगरेशन पढ़ते समय यह autoApprove को बनाए रखता है, लेकिन एप्लिकेशन को अपनी सामान्य ADK-Rust प्राधिकरण और अनुमति नीति लागू करनी होगी।

इंस्टॉल करें

स्थानीय stdio MCP समर्थन वैकल्पिक रूप से सक्षम किया जाता है:

[dependencies]
adk-tool = { version = "2.1.0", features = ["mcp"] }

दूरस्थ सेवाओं से कनेक्ट करते समय Streamable HTTP जोड़ें:

adk-tool = { version = "2.1.0", features = ["mcp", "http-transport"] }

लेगेसी सैंपलिंग कॉलबैक के लिए अलग mcp-sampling फ़ीचर आवश्यक है। MCP प्रोजेक्ट ने SEP-2577 के माध्यम से सैंपलिंग, रूट्स और लॉगिंग को बहिष्कृत कर दिया है; संगत डिप्लॉयमेंट बनाए रखते समय ही उन APIs का उपयोग करें।

एक स्थानीय सर्वर से कनेक्ट करें

use adk_tool::{
    McpToolset,
    mcp::rmcp::{ServiceExt, transport::TokioChildProcess},
};
use std::sync::Arc;
use tokio::process::Command;

let command = Command::new("./target/release/company-mcp");
let client = ().serve(TokioChildProcess::new(command)?).await?;

let toolset = McpToolset::new(client)
    .with_name("company_tools")
    .with_tools(&["find_customer", "read_order", "request_refund"]);

let agent = LlmAgentBuilder::new("support")
    .model(model)
    .toolset(Arc::new(toolset.clone()))
    .build()?;

// Keep the token when the application owns the process lifecycle.
let shutdown = toolset.cancellation_token().await;
// ... run the agent ...
shutdown.cancel();

McpToolset सर्वर के इनपुट और आउटपुट स्कीमा को अक्षुण्ण रखता है। प्रत्येक मॉडल एडाप्टर मॉडल अनुरोध बनाने पर अपने प्रदाता के लिए एक प्रति को सामान्यीकृत करता है। इससे वही MCP सर्वर Gemini, OpenAI, Anthropic और अन्य प्रदाताओं के साथ स्रोत स्कीमा को नुकसान पहुँचाए बिना काम कर सकता है।

टूल से आगे प्रोटोकॉल का उपयोग करें

use serde_json::json;

let resources = toolset.list_resources().await?;
let templates = toolset.list_resource_templates().await?;
let contents = toolset.read_resource("company://policy/refunds").await?;

let prompts = toolset.list_prompts().await?;
let prompt = toolset
    .get_prompt(
        "investigate_order",
        Some(serde_json::Map::from_iter([
            ("order_id".to_string(), json!("ORD-1042")),
        ])),
    )
    .await?;

let suggestions = toolset
    .complete_prompt_argument("investigate_order", "order_id", "ORD-", None)
    .await?;

toolset.subscribe_resource("company://inventory/sku-42").await?;
// ... receive notifications in a custom ClientHandler ...
toolset.unsubscribe_resource("company://inventory/sku-42").await?;

जब कोई पुराना सर्वर संसाधन या प्रॉम्प्ट सूचीकरण लागू नहीं करता, तो सुविधा विधियाँ एक खाली सूची लौटाती हैं। घोषित संसाधन या प्रॉम्प्ट पर किए गए संचालन में दूरस्थ कॉल विफल होने पर त्रुटि लौटती है।

डायनामिक सर्वर प्रबंधन

जब एप्लिकेशन को एक स्थिर कनेक्शन के बजाय स्थानीय MCP चाइल्ड प्रोसेस के समूह की आवश्यकता हो, तब McpServerManager का उपयोग करें।

use adk_tool::mcp::manager::{McpServerConfig, McpServerManager};
use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;

let manager = Arc::new(McpServerManager::from_json_file("mcp.json")?
    .with_name("product_mcp_servers")
    .with_health_check_interval(Duration::from_secs(15))
    .with_grace_period(Duration::from_secs(2)));

let outcomes = manager.start_all().await;
for (server_id, outcome) in outcomes {
    if let Err(error) = outcome {
        eprintln!("{server_id} did not start: {error}");
    }
}
manager.start_monitoring();

let agent = LlmAgentBuilder::new("operator")
    .model(model)
    .toolset(manager.clone())
    .build()?;

रनटाइम रजिस्ट्री निम्नलिखित का समर्थन करती है:

manager.add_server("billing".into(), billing_config).await?;
manager.start_server("billing").await?;

manager.update_server("billing", replacement_config).await?;
manager.disable_server("billing").await?;
manager.enable_server("billing").await?;

manager.save_json_file("mcp.json").await?;
manager.remove_server("billing").await?;
manager.shutdown().await?;

जब दो सर्वर एक ही टूल नाम प्रकाशित करते हैं, तो समेकित टूलसेट दोनों नामों के आगे {server_id}__{tool_name} जोड़ता है। विशिष्ट नाम अपरिवर्तित रहते हैं।

स्वास्थ्य मॉनिटर बंद MCP कनेक्शन का पता लगाता है। कॉन्फ़िगर किया गया RestartPolicy घातीय बैकऑफ़ के साथ सीमित पुनःप्रयास को नियंत्रित करता है। यह कनेक्शन पर्यवेक्षण है, एप्लिकेशन-स्तरीय स्वास्थ्य जाँच नहीं: जब आपको सर्वर के बैकिंग डेटाबेस या बाहरी API की पुष्टि करनी हो, तो डोमेन टूल या अलग सेवा प्रोब का उपयोग करें।

नियतात्मक उदाहरण चलाएँ:

cargo run --manifest-path examples/mcp_manager/Cargo.toml

यह एक वास्तविक Rust MCP चाइल्ड सर्वर शुरू करता है और डिस्कवरी, टूल कॉल, रनटाइम में जोड़ने/सक्षम करने/अपडेट करने/अक्षम करने/हटाने, कॉन्फ़िगरेशन स्थायित्व और शटडाउन का परीक्षण करता है। यह पैकेज डाउनलोड नहीं करता और इसके लिए API कुंजी आवश्यक नहीं है।

रिमोट स्ट्रीमेबल HTTP

use adk_tool::{McpAuth, McpHttpClientBuilder};
use std::time::Duration;

let toolset = McpHttpClientBuilder::new("https://mcp.example.com/mcp")
    .with_auth(McpAuth::bearer(std::env::var("MCP_TOKEN")?))
    .header("X-Tenant-ID", "tenant-42")
    .timeout(Duration::from_secs(30))
    .reinit_on_expired_session(true)
    .connect()
    .await?;

बिल्डर अनुरोध टाइमआउट, कस्टम हेडर, बियरर टोकन, कस्टम API-कुंजी हेडर और HTTP सत्र समाप्त होने पर सीमित रिकवरी लागू करता है।

OAuth2Config एक निश्चित OAuth 2.0 क्लाइंट-क्रेडेंशियल टोकन अनुरोध लागू करता है। यह ज्ञात टोकन एंडपॉइंट वाले सर्वर के लिए उपयोगी है। यह संपूर्ण MCP प्राधिकरण प्रवाह नहीं है: यह संरक्षित-संसाधन मेटाडेटा डिस्कवरी, प्राधिकरण-सर्वर डिस्कवरी, ब्राउज़र प्राधिकरण, PKCE या संसाधन-सूचक वार्ता नहीं करता। जब परिनियोजन में उस प्रवाह की आवश्यकता हो, तो rmcp के प्राधिकरण APIs या बाहरी पहचान घटक का उपयोग करें।

जानकारी अनुरोध

MCP सर्वर को ऐसी जानकारी की आवश्यकता हो सकती है जिसे टूल तर्कों में शामिल नहीं किया गया था। उस स्थिति में यह क्लाइंट को जानकारी अनुरोध वापस भेज सकता है। एप्लिकेशन तय करता है कि अनुरोध किसी व्यक्ति को कैसे दिखाना है और उसे स्वीकार, अस्वीकार या रद्द करना है।

let toolset = McpToolset::with_elicitation_handler(
    transport,
    Arc::new(MyElicitationHandler),
).await?;

ADK-Rust फ़ॉर्म और URL दोनों के लिए अनुरोध करता है। हैंडलर की त्रुटि या पैनिक को अस्वीकृति में बदल दिया जाता है, ताकि MCP कनेक्शन उपयोग योग्य बना रहे। परिणामस्वरूप प्राप्त मानों को सत्यापित करें और किसी महत्वपूर्ण अनुरोध को स्वीकार करने से पहले अनुप्रयोग में सहमति के नियम लागू करें।

पूर्ण सर्वर और इंटरैक्टिव क्लाइंट के लिए examples/mcp_elicitation देखें।

लंबे समय तक चलने वाले MCP कार्य

MCP 2025-11-25 किसी टूल कॉल को प्रोटोकॉल कार्य में बदल सकता है। ADK-Rust कार्य प्रवाह का उपयोग केवल तभी करता है जब सर्वर ने tasks.requests.tools.call पर बातचीत की हो और टूल आवश्यक या वैकल्पिक कार्य समर्थन घोषित करता हो।

use adk_tool::McpTaskConfig;
use std::time::Duration;

let toolset = McpToolset::new(client).with_task_support(
    McpTaskConfig::enabled()
        .poll_interval(Duration::from_secs(1))
        .timeout(Duration::from_secs(120))
        .max_attempts(120),
);

कार्य मोड के लिए, ADK-Rust:

1. आधिकारिक कार्य मेटाडेटा के साथ tools/call भेजता है;
2. बनाए गए कार्य को प्राप्त करता है;
3. सर्वर द्वारा सुझाए गए अंतराल का उपयोग करके tasks/get की स्थिति पूछता है;
4. tasks/result के माध्यम से अंतिम पेलोड पढ़ता है; और
5. अपना स्थानीय टाइमआउट या स्थिति-जाँच सीमा पूरी होने पर tasks/cancel कॉल करता है।

input_required को टाइप की गई त्रुटि के रूप में लौटाया जाता है, क्योंकि सामान्य ADK टूल कॉल में उस अनुपलब्ध इनपुट को उपलब्ध कराने के लिए अभी तक प्रोटोकॉल-निरपेक्ष पुनःआरंभ चैनल नहीं है। उस परस्पर क्रिया को स्वामित्व वाले वर्कफ़्लो में स्पष्ट रूप से डिज़ाइन करें।

क्षमता मानचित्र

सीमा का चयन

जब क्षमता उसी प्रक्रिया और रिलीज़ से संबंधित हो, तो Rust FunctionTool का उपयोग करें। जब किसी अन्य प्रोग्राम, टीम, भाषा, सुरक्षा सीमा या परिनियोजन के पास क्षमता का स्वामित्व हो और उसे अपना अनुबंध प्रकाशित करना चाहिए, तो MCP का उपयोग करें।

उत्पादन परिनियोजनों के लिए:

• उपयोगी टूल का सबसे छोटा सेट उपलब्ध कराएँ;
• केवल-पठन और महत्वपूर्ण कार्रवाइयों को अलग रखें;
• रहस्यों को कमांड-लाइन तर्कों और कमिट की गई mcp.json फ़ाइलों से बाहर रखें;
• रिमोट HTTP सर्वरों को प्रमाणित करें और क्रेडेंशियल्स का दायरा सीमित रखें;
• टूल विवरणों और सर्वर द्वारा लौटाई गई सामग्री को अविश्वसनीय इनपुट मानें;
• टूल निष्पादन के आसपास ADK-Rust प्राधिकरण और अनुमोदन बनाए रखें;
• कनेक्शन, टूल और कार्य के टाइमआउट की सीमा निर्धारित करें; और
• टूल कॉल, अनुमोदन, त्रुटियों और सर्वर जीवनचक्र में होने वाले बदलावों को रिकॉर्ड करें।

वर्तमान सीमाएँ

• McpServerManager स्थानीय stdio चाइल्ड प्रक्रियाओं का प्रबंधन करता है। रिमोट HTTP सेवाएँ McpHttpClientBuilder और एप्लिकेशन-स्वामित्व वाले कॉन्फ़िगरेशन का उपयोग करती हैं।
• प्रबंधक की स्वास्थ्य जाँचें बंद MCP कनेक्शनों का पता लगाती हैं; वे व्यावसायिक-स्तर के स्वास्थ्य टूल को कॉल नहीं करतीं।
• जब कोई चाइल्ड अपना MCP हैंडशेक पूरा करता है, तब तक रजिस्ट्री में बदलाव क्रमबद्ध किए जाते हैं।
• autoApprove कॉन्फ़िगरेशन संगतता है, प्राधिकरण प्रवर्तन नहीं।
• अंतर्निहित OAuth हेल्पर क्लाइंट क्रेडेंशियल्स है, संपूर्ण MCP OAuth डिस्कवरी और उपयोगकर्ता-प्राधिकरण प्रवाह नहीं।

इन सीमाओं को इसलिए स्पष्ट किया गया है ताकि परिनियोजन संबंधी निर्णय स्पष्ट बने रहें।

संदर्भ

• MCP विनिर्देशन 2025-11-25
• आधिकारिक Rust SDK (rmcp)
• rmcp 3.1 API दस्तावेज़ीकरण
• प्रदाता-जागरूक स्कीमा सामान्यीकरण