Phase 13: Tools & Protocols

أساسيات المفاوضات المشتركة: طلبات العدالة عن الجنسية و JSON-RPC

لا يوجد في MCP الحديث أي ضغط يد ولا جلسة بروتوكول. يجب أن يحمل كل طلب ما يكفي من البيانات المعدنية لفهمها وافق عليها ، وتوجيهها ، وإعادة تجربتها بمفردها.

Type: Learn

Languages: Python

Prerequisites: Phase 13, Lessons 01 through 05

Time: ~55 minutes

أهداف التعلم

تمييز أساسيات خادم MCP عن ميزاتها من جانب العميل.
إعداد طلبات وردات JSON-RPC 2.0 صالحة لـ MCP 2026-07-28. . .
ربط نسخة بروتوكول، قدرات العميل، و هوية العميل لكل طلب.
استخدامserver/discoverو التعاملUnsupportedProtocolVersionErrorبدون ضغط يد
تتبع طلب واحد مستقل من التحقق من التحقق من التحقق من النتيجة الكاملة.

المشكلة

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

المفوضية2026-07-28يزيل هذا الغموض. قاعدة البروتوكول غير ذات الوضع. يجب على الخادم أن يقرر كيفية التعامل مع الطلب الحالي من الطلب الحالي، وليس من تاريخ الاتصال.

هذا يغير النموذج العقلي، السلسلة القديمة كانت الاتصال أولاً، الضغط الثاني، العمليات الثالثة. السلسلة الحديثة أسهل:

العميل يرسل طلباً لوصف نفسه
يقوم الخادم بتؤكيد نسخة الطلب وقدراته
الخادم يتعامل مع الطريقة.
يعيد الخادم نتيجة منخفضة أو خطأ JSON-RPC.

الطلب التالي يكرر نفس العملية من الصفر.

المفهوم

أساسيات الخادم

خادمات MCP تعرض ثلاثة بدائيات أساسية:

Toolsهي أفعال يتم التحكم فيها على النموذج، والتي تم اكتشافها مع tools/listويتم استدعائهاtools/call. . .
Resourcesهي بيانات مع عنوان URI، والتي تم اكتشافها مع resources/listو تم استردادهم معresources/read. . .
Promptsهي نماذج قابلة للاستعمال، اكتشفت مع prompts/listوترجمة مع prompts/get. . .

تبقى الجذور والاستعراض والقطع الأحيائية في 2026-07-28مخططات التوافق، لكنها تعتبر من السن. يجب أن تستخدم التنفيذات الجديدة أدوات صريحة أو مدخلات موارد للجذر، و APIات مزود النموذج المباشرة للاستعراض، و stderr أو OpenTelemetry لتحقيق السجلات. لا يزال الإجراء متاحًا من خلال طلبات رحلة متعددة، حيث يعيد الخادم طلب إدخال والعميل عملية التشغيل الأصلية. الخادم الحديث لا يبدأ طلب JSON-RPC مستقل.

غلافات JSON-RPC

يستخدم MCP JSON-RPC 2.0:

الطلب:{jsonrpc, id, method, params}
رد: {jsonrpc, id, result}أو{jsonrpc, id, error}
الإخطار: {jsonrpc, method, params}بدون أيid

الطلبidيرتبط رد فعل واحد. لا يخلق جلسة بروتوكول.

البيانات المطلوبة من الطلب

كل طلب حديث يحمل_metaالجهاز الداخليparams:

json{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "course-client",
        "version": "1.0.0"
      }
    }
  }
}

الإصدار البروتوكول والقدرات العميل مطلوبة. يوصى بهوية العميل. إنها بيانات عرض وتحليل التحريف ذاتية الإبلاغ، وليس اعتماد أمني.

يجب على الخادم عدم استنتاج أي من هذه القيم من طلب سابق أو عملية استديو أو اتصال HTTP أو عنوان نقل وحده.

النتائج الكاملة و هوية الخادم

كل نتيجة حديثة ناجحة تتضمنresultTypeالنتيجة النهائية الطبيعية تستخدم"complete"يجب أن يُعرف الخوادم نفسها أيضاً في البيانات المعدنية الناتجة:

json{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "resultType": "complete",
    "tools": [],
    "ttlMs": 30000,
    "cacheScope": "public",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "notes-server",
        "version": "1.0.0"
      }
    }
  }
}

tools/list،resources/list،prompts/list،resources/templates/list،resources/readوserver/discoverهي نتائج قابلة للتخفيض.ttlMsوcacheScope. الاختلالات الآمنة هيttlMs: 0وcacheScope: "private". يجب أن يكون عناصر القائمة مرتبة تحديدية بحيث تخلق الردود المتكافئة مفاتيح الاحتفاظ المستقرة و سياق النموذج المستقيم.

اكتشاف بدون ضغط يد

كل خادم حديث يجب أن ينفذserver/discover. العميل قد يطلبها قبل طريقة أخرى لاسترداد:

supportedVersions
الخادمcapabilities
استخدام اختياري instructions
الهوية الخادم في النتيجة _meta
إشارات التخزين

الاكتشاف مفيد، لكنه ليس بوابة.tools/listأولاً لأن هذا الطلب يحمل بالفعل نسخة بروتوكولها وقدراتها.

إذا لم يتم دعم النسخة المطلوبة ، يعيد الخادم رمز JSON-RPC -32022مع:

json{
  "requested": "2027-01-01",
  "supported": ["2026-07-28"]
}

يختار العميل نسخة حديثة تدعمها المتبادلة ويجرب مرة أخرى مع معرف طلب JSON-RPC الجديد.

دورة حياة طلب واحد

تتبع طلب حديث في هذا الترتيب:

تحليل غلاف JSON-RPC واحد.
تأكّدjsonrpcهو"2.0"، وidموجودةmethodهو سلسلة، و paramsهو كائن
احتاج إلى موضوع سلسلة الإصدار والقدرة في params._meta؛ المعلومات المتحولة أو المفقودة هي-32602. . .
عند حدود HTTP، مقارنة الإصدار، والطريقة، والعناوين الاسم المطبقة مع الجسم.-32020حتى عندما لا يتم دعم إحدى قيم الإصدارين.
بعد أن يتم تأسيس المساواة، رفض نسخة متطابقة ولكن غير مدعومة مع -32022. . .
تحقق من القدرات المطلوبة ثم اتجهmethodوتؤكد الحجج الخاصة بالوسيلة.
تحديد المصداقية وافق على العملية الملموسة قبل أن يبدأ معالجها.
أعد نتيجة كاملة مع هوية الخادم.
انسى البيانات المعدلة للاتفاقية

هذا الأمر يمنع اثنين من المكونات من تفسير المكالمات المختلفة.Mcp-Name: notes.readبينما الأصل ينفذparams.name: notes.deleteكما أنها تحتفظ بإدخال غير مصمم، وارتباك الرأس، وتفاوض الإصدارات، وفشل القدرة، والإذن، وفشل المعاملة كدليل واضح.

إغلاق stdin أو استجابة HTTP ينهي نشاط النقل. لا ينهي جلسة بروتوكول لأن MCP الحديث لا يوجد جلسة بروتوكول.

التوافق الصريح مع التراث

الإصدارات من خلال 2025-11-25استخدامinitialize،notifications/initialized، وقدرات اتصال مستوى، وعلى سابقة Streamable HTTP، جلسات بروتوكول اختيارية. هذا السلوك لا يزال ذي صلة عندما يتحدث عميل عصر مزدوج إلى خادم قديم.

حافظ على الفترات منفصلة. يتم تحديد طلب حديث عن طريق البيانات المطلوبة لكل طلب. يتم اختيار اتصال سابق فقط من خلال مسار العودة الموثوق. لا ترسل initializeكالتخلفة لـ2026-07-28الخادم

لذلك، فإن "لا جنسية" لها معنى محدد في العصر.2026-07-28، هو بروتوكول غير متغير: كل طلب عادي يمكن تفسيره بشكل مستقل ولا توجد جلسة MCP.2025-11-25إن إعدادات التشغيل والتحديث والإمكانيات المفروضة تنتمي إلى اتصال، لذلك قد يحافظ مُعدل التوافق على حالة الاتصال القديمة. لا يعتبر تنفيذ عصر مزدوج جهازًا واحدًا مسموحًا. إنه جوهر حديث غير حكومي إلى جانب مُعدل قديم مع اتخاذ قرار تحديد صريح قبل تشغيل أي من المصفحات.

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

استخدمها

code/main.pyيقوم ببناء وتؤكيد وتتبع وإرسال رسائل MCP الحديثة دون إطار.

bashpython3 code/main.py
python3 -m unittest discover code/tests -v

انتبه لثلاثة مستحيلات في الخروج:

كل طلب يكرر طلبه_metaالحقول
كل نتيجة ناجحة هيresultType: "complete"وتشمل هوية الخادم.
يتم ترتيب نتيجة القائمة بشكل محدد ولديها إشارات مخزن مخزن صريحة.

أرسله

هذه الدروس تُسافرoutputs/skill-mcp-handshake-tracer.md. يظل اسم الملف التاريخي مستقراً، لكن الفن أصبح الآن متابعاً لطلبات بلا بيان، فإنه يُدقق كل رسالة بشكل مستقل ويعدّب حركة المرور القديمة فقط عندما تكون موجودة حقًا.

التمارين

تغيير نسخة بروتوكول طلب واحد إلى 2027-01-01تأكد من أن رمز الخطأ هو-32022والبيانات تعلن عن النسخة المدعومة.
إزالةio.modelcontextprotocol/clientCapabilitiesتأكد من أن الخادم لا يستخدم إمكانات الطلب الأول.
قم بإعكس سجل أداة في الذاكرة. تأكيد tools/listلا يزال يعود نفس الترتيب التحديدي.
التغييرcacheScopeمنpublicإلىprivate- شرح السياقات التي يمكن إعادة استخدام الاستجابة في كل حالة.
إضافة اختيارية clientInfoاختبار التخلي عن المعلومات. يجب أن تظل الطلب صالحاً لأن هوية العميل توصي بها وليس مطلوبة.

الشروط الرئيسية

Term	Meaning
Stateless protocol	Every request supplies the metadata needed to interpret it
Request metadata	Version, client capabilities, and recommended client identity in `params._meta`
`server/discover`	Mandatory server method for versions, capabilities, instructions, and identity
`resultType`	Discriminator on every successful modern result
Cacheable result	Result that includes required `ttlMs` and `cacheScope` hints
Protocol era	Modern per-request metadata or legacy connection-scoped initialization
Transport lifetime	Process, connection, or response-stream lifetime, not protocol session state
`-32022`	Unsupported protocol version error with requested and supported versions