خادم MCP

تعريض قدرات التطبيق المحددة للعملاء المحليين لـ MCP

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

الخادم مدمج في التطبيق الجاري. إنه ليس خدمة سطر أوامر منفصلة، وليس خدمة إنترنت عامة. ابدأه فقط عندما تريد أن يتصل عميل MCP.

ما يمكن لـ MCP التحكم فيه

يعرض MCP قدرات المجال التي ينشرها التطبيق بشكل صريح. إنه ليس سطح تحكم عن بُعد عام لنافذة التطبيق.

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

تحكمات الصفحة

  • ابدأ يستضيف نقطة نهاية MCP.
  • توقف ينهي نقطة نهاية MCP ويحرر المنفذ.
  • العنوان يحدد العنوان المحلي للاستماع عليه.
  • المنفذ يحدد منفذ TCP.
  • نقطة النهاية المكونة تظهر عنوان URL الذي يجب إعطاؤه لعميل MCP.
  • نسخ عنوان URL ينسخ نقطة النهاية المكونة.
  • رمز الحامل هو الرمز الذي يجب على العملاء إرساله مع الطلبات.
  • نسخ الرمز ينسخ الرمز.
  • إعادة توليد الرمز ينشئ رمزًا جديدًا ويجعل الرمز القديم غير صالح بعد إعادة تشغيل الخادم.
  • الوحدات تسرد وحدات MCP المعلنة من قبل التطبيق.
  • مفعل أو معطل يتحكم فيما إذا كانت الوحدة تساهم بالأدوات في الخادم.
  • السجل يظهر بدء الخادم، توقفه، الطلبات، الرفض، ورسائل استدعاء الأدوات.
  • مسح في قائمة النقر الأيمن على السجل يمسح السجل المرئي للصفحة.

نقطة النهاية الافتراضية هي:

http://127.0.0.1:50507/mcp

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

العنوان والمنفذ

استخدم 127.0.0.1 عندما يعمل عميل MCP على نفس الكمبيوتر. هذا هو الإعداد الأكثر أمانًا وشيوعًا.

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

لا تعرض نقطة نهاية MCP من خلال إعادة توجيه منفذ الموجه، أو Wi-Fi العامة، أو VPNs غير الموثوقة، أو قواعد جدار الحماية الموجهة للإنترنت. يمكن لأدوات MCP طلب إجراءات حقيقية من التطبيق، لذا تعامل مع نقطة النهاية والرمز مثل مفتاح تحكم محلي.

الاتصال بعميل

استخدم عميل HTTP MCP قابل للبث. قم بتكوين العميل مع:

  1. عنوان URL لنقطة النهاية: نقطة النهاية المكونة المعروضة على الصفحة.
  2. رأس التفويض: Authorization: Bearer your-token.

تطلب معظم العملاء عنوان URL ورمز حامل أو رأس مخصص. إذا كان عميلك يخزن الرؤوس بشكل منفصل، استخدم:

Header name: Authorization
Header value: Bearer your-token

استبدل your-token بالرمز المعروض على صفحة خادم MCP. لا تتضمن علامات الاقتباس حول الرمز.

شكل الطلب الفني

ترسل عملاء MCP عادةً هذه الطلبات نيابةً عنك. التفاصيل أدناه مفيدة عند تكوين أو تصحيح عميل.

تقبل نقطة النهاية طلبات HTTP POST إلى /mcp. يجب على العميل تضمين رمز الحامل عندما يتم تكوين رمز.

طلب التهيئة:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"local-client","version":"1.0"}}}

إشعار التهيئة:

{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}

قائمة الأدوات:

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

استدعاء أداة:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"module_tool_name","arguments":{}}}

يعيد الخادم نتائج أدوات منظمة. يتم إرجاع الرفض المتوقع من التطبيق، مثل عدم توفر إجراء مطلوب، كنتائج أدوات عادية مع ok مضبوط على false.

حالات الخادم

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

تقدم منطقة السجل الرسالة الدقيقة للفشل والطلبات المرفوضة.

ملاحظات الأمان

يستخدم خادم MCP HTTP محلي نصي بالإضافة إلى تفويض رمز الحامل. يحمي الرمز مسار الطلب، لكن الاتصال غير مشفر. استخدم الاتصال المحلي للعملاء على نفس الكمبيوتر كلما كان ذلك ممكنًا. استخدم الربط عبر LAN فقط على الشبكات والآلات التي تثق بها.

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

استكشاف الأخطاء وإصلاحها

إذا كان زر البدء معطلاً:

  • قم بتمكين وحدة واحدة على الأقل.
  • تأكد من أن العنوان ليس فارغًا.
  • تأكد من أن المنفذ بين 1 و 65535.
  • تأكد من أن رمز الحامل ليس فارغًا.
  • توقف عن الخادم قبل تغيير العنوان أو المنفذ أو رمز الحامل.

إذا فشل زر البدء:

  • قد تكون عملية أخرى تستخدم المنفذ بالفعل.
  • قد لا يكون العنوان مخصصًا لهذا الكمبيوتر.
  • اختر منفذًا أو عنوانًا آخر وحاول مرة أخرى.
  • تحقق من السجل للحصول على رسالة الفشل الدقيقة.

إذا لم يتمكن العميل من الاتصال:

  • تأكد من أن الخادم يظهر كـ بدأ.
  • تأكد من أن عنوان URL للعميل يتطابق تمامًا مع نقطة النهاية المكونة.
  • استخدم 127.0.0.1 فقط للعملاء على نفس الكمبيوتر.
  • لجهاز كمبيوتر آخر على LAN، استخدم عنوان IPv4 LAN لهذا الكمبيوتر وتأكد من أن قواعد جدار الحماية تسمح بالاتصال.
  • تأكد من أن العميل يدعم MCP HTTP القابل للبث، وليس MCP الخاص بـ stdio فقط.

إذا تلقى العميل 401 Unauthorized :

  • أضف رأس Authorization.
  • تأكد من أن الرأس يبدأ بـ Bearer .
  • تأكد من أن الرمز ليس فارغًا.

إذا تلقى العميل 403 Forbidden :

  • تأكد من أن الرمز يتطابق تمامًا مع رمز الحامل الحالي.
  • إذا قمت بإعادة توليد الرمز، قم بتحديث العميل.
  • إذا كان الطلب يتضمن رأس الأصل، تأكد من أنه يأتي من أصل محلي مسموح به.

إذا تلقى العميل 405 Method Not Allowed :

  • من المحتمل أن يكون العميل يستخدم HTTP GET.
  • قم بتكوين العميل لاستدعاءات أدوات HTTP القابلة للبث التي ترسل POST /mcp.

إذا لم تظهر الأدوات المتوقعة:

  • تأكد من أن بطاقة الوحدة المطابقة مفعلة.
  • توقف وابدأ خادم MCP بعد تغيير تمكين الوحدة.
  • تأكد من أن العميل قد قام بتحديث أو إعادة الاتصال بعد إعادة تشغيل الخادم.