بروتوكول سياق النموذج (MCP)

خريطة التوثيق: نظرة عامة والبنية · العميل · المدير الديناميكي · تأليف الخادم · الأمان · الاختبار

يوفّر MCP لتطبيق الذكاء الاصطناعي طريقةً قياسية لاكتشاف الإمكانات التي تملكها عملية أو خدمة أخرى واستخدامها. ويمكن للخادم نشر:

• أدوات تنفّذ الإجراءات؛
• موارد تُعيد سياقًا قابلًا للقراءة؛
• موجّهات توفّر قوالب رسائل قابلة لإعادة الاستخدام؛ و
• اقتراحات الإكمال التي تساعد العميل على ملء وسيطات الموجّه أو المورد.

يكون ADK-Rust عادةً هو عميل MCP. يحوّل McpToolset الأدوات MCP المكتشفة إلى قيم ADK-Rust Tool عادية، بحيث يمكن لـ LlmAgent اختيارها واستدعاؤها. كما يوفّر الإطار الموارد والموجّهات والإكمال والاشتراكات والاستجلاء ودورة حياة المهام المتفاوض عليها. ولتأليف الخوادم MCP والعمل المتقدم على البروتوكول، يعيد ADK-Rust تصدير إصدار SDK الدقيق من rmcp الذي يستخدمه.

يستخدم ADK-Rust 2 ‏rmcp 3.1، وهو SDK الرسمي للغة Rust. يعلن العميل عن 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?;

تعيد أساليب التسهيل قائمة فارغة عندما لا يطبّق خادم أقدم سرد الموارد أو المطالبات. وتعيد العمليات التي تستهدف موردًا أو مطالبةً مُعلنة خطأً عند فشل الاستدعاء البعيد.

الإدارة الديناميكية للخوادم

استخدم McpServerManager عندما يحتاج التطبيق إلى مجموعة من عمليات MCP الفرعية المحلية بدلًا من اتصال ثابت واحد.

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-key المخصصة، والاسترداد المحدود عند انتهاء صلاحية جلسة HTTP.

ينفّذ OAuth2Config طلب رمز مميز ثابتًا ببيانات اعتماد العميل وفق الإصدار 2.0 من OAuth. وهو مفيد لخادم ذي نقطة نهاية معروفة للرموز المميزة. لكنه ليس تدفق التفويض الكامل لـ MCP: فهو لا ينفّذ اكتشاف بيانات التعريف للمورد المحمي، أو اكتشاف خادم التفويض، أو التفويض عبر المتصفح، أو PKCE، أو التفاوض على مؤشرات المورد. استخدم rmcp's authorization 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 لا يملك بعد قناة محايدة تجاه البروتوكول لاستئناف التنفيذ وتوفير ذلك الإدخال المفقود. صمّم هذا التفاعل صراحةً ضمن سير العمل المسؤول عنه.

خريطة الإمكانات

اختيار الحد الفاصل

استخدم FunctionTool بلغة Rust عندما تكون الإمكانية تابعة للعملية والإصدار نفسيهما. استخدم MCP عندما يتولى برنامج أو فريق أو لغة أو حد أمني أو عملية نشر أخرى هذه الإمكانية، وينبغي لها نشر عقدها الخاص.

في عمليات النشر الإنتاجية:

• اعرض أصغر مجموعة أدوات مفيدة؛
• افصل الإجراءات للقراءة فقط عن الإجراءات المؤثرة؛
• أبقِ الأسرار خارج وسائط سطر الأوامر وملفات mcp.json المضمّنة في المستودع؛
• صادِق خوادم HTTP البعيدة وقيّد نطاق بيانات الاعتماد بشدة؛
• تعامل مع أوصاف الأدوات والمحتوى المُعاد من الخادم على أنه إدخال غير موثوق؛
• أبقِ التفويض والموافقة من ADK-Rust حول تنفيذ الأدوات؛
• حدّد مهلات الاتصال والأدوات والمهام؛ و
• سجّل استدعاءات الأدوات والموافقات والأخطاء وتغييرات دورة حياة الخادم.

الحدود الحالية

• يدير McpServerManager العمليات الابنة المحلية عبر stdio. تستخدم خدمات HTTP البعيدة McpHttpClientBuilder وإعدادات مملوكة للتطبيق.
• تكتشف فحوصات صحة المدير اتصالات MCP المغلقة؛ ولا تستدعي أداة فحص صحة على مستوى الأعمال.
• تُسلسل تغييرات السجل أثناء إكمال الابن مصافحة MCP.
• autoApprove هو توافق الإعدادات، وليس فرض التفويض.
• مساعد OAuth المضمّن مخصص لبيانات اعتماد العميل، وليس التدفق الكامل لاكتشاف MCP OAuth وتفويض المستخدم.

تُذكر هذه الحدود لضمان بقاء قرارات النشر واضحة وصريحة.

المراجع

• مواصفة MCP لعام 2025-11-25
• SDK الرسمية للغة Rust (rmcp)
• توثيق rmcp 3.1 API
• تطبيع المخطط مع مراعاة المزوّد