دليل خادم MCP: الإعداد والأمثلة وأول أداة للمبتدئين

يستطيع مساعدك بالذكاء الاصطناعي أن يكتب قصيدة سونيتة عن جداول البيانات، لكن إن سألته عن حجم ملف على حاسوبك المحمول، فسيكتفي بهزّ كتفيه. يسدّ بروتوكول سياق النموذج (Model Context Protocol) هذه الفجوة. خادم MCP برنامج صغير يمنح المساعد قدرات حقيقية: قراءة مجلد، والاستعلام من قاعدة بيانات، واستدعاء API، وحتى توليد صورة. يبني هذا الدليل خادمًا من مجلد فارغ، وينتهي بأول أداة تعمل خلال نحو عشرين دقيقة، ولا يتطلب أي خبرة سابقة في البروتوكولات.

ستثبّت SDK، وتكتب أداة، وتختبرها في Inspector، وتربطها بعميل حقيقي، ثم ترى كيف يعمل النمط نفسه على توليد الصور والفيديو في PicassoIA. كل شيء يعمل بلغة Python بسيطة، فإذا كنت تستطيع قراءة دالة، فستتابع الدليل دون صعوبة.

ماذا يفعل خادم MCP؟

تشبيه USB-C

قبل USB-C، كان لكل جهاز كابل خاص به. يفعل MCP للذكاء الاصطناعي ما فعله ذلك المنفذ الواحد للأجهزة. بدونه، يحتاج كل مساعد إلى شيفرة مخصصة لكل خدمة، أي ما يعادل عدد المساعدين × عدد الخدمات من الروابط البرمجية. أما معه، فتكتب خادمًا واحدًا ويستطيع أي عميل متوافق مع MCP استخدامه.

قدّمت Anthropic البروتوكول في أواخر 2024، ومنذ ذلك الحين تبنّته تطبيقات محادثة كثيرة، ومحررات أكواد، وأطر عمل للوكلاء. هذا التبنّي هو السبب الحقيقي للاهتمام به: الأداة التي تبنيها اليوم لا تقتصر على منتج واحد، والمهارات التي تكتسبها تنتقل إلى كل عميل يفهم البروتوكول.

المضيف والعميل والخادم

تظهر ثلاثة أدوار في كل محادثة MCP، وكثيرًا ما يخلط المبتدئون بينها.

تنتقل الرسائل بصيغة JSON-RPC 2.0. يتحدث الخادم المحلي عبر stdio: يشغّل المضيف سكربتك كعملية فرعية، ويتبادل الرسائل عبر مدخلاتها ومخرجاتها. أما الخادم البعيد فيتحدث عبر Streamable HTTP، وهذه هي الطريقة التي تعمل بها الموصلات المستضافة.

إليك ما يحدث عندما تطرح سؤالًا:

1. يشغّل المضيف خادمك، ويسأل عميله: "ماذا تستطيع أن تفعل؟"
2. يردّ الخادم بقائمة الأدوات ومخطط كل واحدة منها.
3. تطرح سؤالًا. يقرر النموذج أن أداة ما مناسبة فيُصدر استدعاءً مع معاملات.
4. يعرض المضيف طلب إذن، ثم يمرّر الاستدعاء إلى خادمك.
5. تعمل دالتك، وتعود النتيجة، ويكتب النموذج الإجابة النهائية.

الأدوات والموارد والأوامر النصية

يستطيع الخادم أن يقدّم ثلاثة أنواع من الأشياء، ولكل منها جهة مختلفة تتحكم فيه.

💡 ابدأ بالأدوات أولًا. فهي أكثر العناصر دعمًا، وأداة واحدة تعمل تعلّمك معظم ما يطلبه البروتوكول منك.

إعداد بيئة العمل

ما الذي تحتاجه

جهّز أربعة أشياء قبل كتابة أي شيفرة:

• Python 3.10 أو أحدث. تحقق من ذلك بالأمر python --version.
• Node.js 18 أو أحدث، ويلزم فقط لأداة التصحيح Inspector، التي تعمل عبر npx.
• طرفية (Terminal) ومحرر أكواد من أي نوع، حتى لو كان بسيطًا.
• عميل MCP، مثل Claude Desktop أو Claude Code أو محرر متوافق.

تعمل الخطوات على Windows و macOS و Linux جميعًا. الأمر الوحيد الذي يتغير هو أمر تفعيل البيئة الافتراضية، والشيفرة أدناه متطابقة على كل الأنظمة.

Python أم TypeScript؟

توجد حزم SDK رسمية لعدة لغات. اثنتان منها الخيار الأكثر أمانًا لأول خادم:

يستخدم هذا الدليل لغة Python. المفاهيم، من الأدوات إلى وسائل النقل، تنتقل إلى كل حزمة SDK أخرى دون تغيير.

اكتب أول أداة لك

أنشئ المشروع

أنشئ مجلدًا، وأضف بيئة معزولة، ثم ثبّت SDK:

mkdir word-counter
cd word-counter
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

نسخ الأمر النصي

تثبّت الإضافة [cli] الأمر mcp، الذي يتضمن مشغّلًا تطويريًا للاختبارات السريعة.

أداتك في 15 سطرًا

أنشئ server.py بهذا المحتوى:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("word-counter")

@mcp.tool()
def count_words(text: str) -> dict:
    """Count the words, characters and lines in a piece of text."""
    return {
        "words": len(text.split()),
        "characters": len(text),
        "lines": len(text.splitlines()),
    }

if __name__ == "__main__":
    mcp.run(transport="stdio")

نسخ الأمر النصي

ثلاثة تفاصيل تقوم بكل العمل:

1. النص التوثيقي (docstring) هو ما يقرأه النموذج ليقرر متى يستدعي الأداة. اكتبه كوصف وظيفي من سطر واحد.
2. تلميحات الأنواع (text: str) تصبح مخطط JSON الذي يخبر العميل بالمعاملات الموجودة ونوع كل منها.
3. القيمة المرجعة تُحوَّل إلى نص متسلسل وتُرسل إلى النموذج بوصفها نتيجة الأداة.

عندما يتصل عميل، يطلب من خادمك قائمة الأدوات. يردّ FastMCP باسم count_words، ويجعل النص التوثيقي وصفها، ومخطط إدخال مولّدًا من التوقيع: كائن فيه خاصية نصية واحدة مطلوبة اسمها text. هذا المستند الصغير بصيغة JSON هو كل ما يعرفه النموذج عن دالتك، ولهذا تهم التسمية والصياغة أكثر من الشيفرة الذكية.

💡 إذا لم تُستدعَ أداة أبدًا، فالسبب في الغالب نص توثيقي غامض، وليس خطأ في شيفرتك.

اختبرها في Inspector

لا تربط تطبيق محادثة بعد. صحّح الأخطاء في MCP Inspector، وهو منصة اختبار تعمل في المتصفح:

npx @modelcontextprotocol/inspector python server.py

نسخ الأمر النصي

تفتح صفحة محلية. ثم:

1. انقر Connect لتشغيل خادمك.
2. افتح تبويب Tools واضغط List Tools. يجب أن تظهر count_words.
3. اختر الأداة، واكتب جملة في حقل text، ثم شغّلها.
4. تحقق من أن نتيجة JSON تُظهر الأعداد الصحيحة.

⚠️ لا تستخدم print() أبدًا في خادم stdio. المخرجات القياسية هي قناة الرسائل، وأي طباعة عشوائية تُفسد الرسائل. أرسل السجلات إلى stderr، أو استخدم وحدة logging في Python.

اربطها بعميل حقيقي

بعد أن يُظهر Inspector علامة النجاح، سجّل الخادم لدى عميل. بالنسبة إلى Claude Desktop، أضف هذا إلى ملف claude_desktop_config.json:

{
  "mcpServers": {
    "word-counter": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

نسخ الأمر النصي

بالنسبة إلى Claude Code، يؤدي أمر واحد المهمة نفسها:

claude mcp add word-counter -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

نسخ الأمر النصي

أعد تشغيل التطبيق بالكامل، ثم اسأل: "كم عدد الكلمات في هذه الفقرة؟" متبوعًا بنص ما. سيطلب العميل الإذن، ويشغّل count_words، ويجيب بالأرقام الدقيقة بدلًا من التخمين.

إذا لم يظهر شيء، فتحقق من هذه النقاط بالترتيب:

• المسارات المطلقة فقط. المسارات النسبية تفشل لأن المضيف يشغّل العملية من مجلده هو.
• أشِر إلى مترجم البيئة الافتراضية. الأمر python المجرد يجد غالبًا نسخة أخرى دون SDK.
• أغلق التطبيق بالكامل. إغلاق النافذة يترك التطبيق غالبًا قيد التشغيل في علبة النظام.
• اقرأ السجلات. تكتب العملاء سجلات لكل خادم تُظهر تتبع الخطأ بدقة.

عندما لا يكفي السكربت المحلي، بدّل وسيلة النقل باستخدام mcp.run(transport="streamable-http")، واستضفه خلف HTTPS وأضف المصادقة. تبقى شيفرة الأداة كما هي تمامًا، وهذه هي الفائدة الخفية للبناء على بروتوكول.

ثلاثة أمثلة تستحق النسخ

مورد للقراءة فقط

تعرض الموارد البيانات عبر URI. يقدّم هذا المثال ملف ملاحظات:

from pathlib import Path

@mcp.resource("notes://today")
def todays_notes() -> str:
    """Return the contents of today's notes file."""
    return Path("notes/today.md").read_text(encoding="utf-8")

نسخ الأمر النصي

يستطيع التطبيق إرفاقه كسياق دون أن يستدعي النموذج أي شيء. ويمكن للموارد أيضًا استخدام قوالب URI مثل notes://{date}، فتخدم دالة واحدة عائلة كاملة من الملفات.

قالب أمر نصي

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

@mcp.prompt()
def review_code(code: str) -> str:
    """Ask for a short, friendly code review."""
    return f"Review this code and list the three most important fixes:\n\n{code}"

نسخ الأمر النصي

أداة تستدعي API

معظم الخوادم الحقيقية تغلّف خدمة ويب. يتحقق هذا المثال مما إذا كان موقع ما يعمل:

import httpx

@mcp.tool()
async def check_site(url: str) -> str:
    """Return the HTTP status code of a website."""
    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.get(url, follow_redirects=True)
    return f"{url} answered with status {response.status_code}"

نسخ الأمر النصي

يأتي httpx مع SDK أصلًا، وتصريح الدالة بأنها async يتيح للخادم أن يبقى مستجيبًا أثناء انتظار الشبكة. استدعاءات الشبكة تفشل، لذلك التقط الاستثناء وأعد رسالة قصيرة واضحة. النموذج الذي يرى "انتهت مهلة الموقع بعد 10 ثوانٍ" يستطيع أن يتكيّف ويجرب شيئًا آخر، بينما يربكه تتبع خطأ خام.

أخطاء تُهدر عليك ساعات من وقتك

تساعد التسمية بقدر ما يساعد الجدول أعلاه. اختر أفعالًا تصف ما يحدث، مثل count_words أو check_site، واجعل كل أداة لها مهمة واحدة، واقصر المعاملات على القليل الذي يحتاجه النموذج فعلًا. أداة اسمها process بستة حقول اختيارية تدعو إلى التخمين الخاطئ.

أحكم قفل الوصول

الأداة شيفرة يستطيع النموذج تشغيلها على جهازك، فتعامل معها باحترام:

• فضّل القراءة فقط. أضف أدوات الكتابة أو الحذف فقط عندما تحتاجها فعلًا.
• تحقق من المدخلات. يجب أن ترفض أداة الملفات أي مسار خارج مجلد واحد تحدده.
• أبقِ الأسرار خارج الشيفرة. مرّر الرموز عبر حقل env في إعداد العميل، فيبقيها بعيدة عن مستودعك.
• اقرأ طلب الإذن. لا توافق على استدعاء أداة لا تستطيع تفسيره.

اربط PicassoIA عبر MCP

ما يقدمه الموصل

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

من الداخل، يتبع API نمطًا مألوفًا: ينشئ تنبؤًا، ثم يستعلم عن حالته بشكل متكرر، ثم يجلب النتيجة. تستخدم الطلبات رمز Bearer، ويمكن أن يصل طول الأمر النصي إلى 4,000 حرف، ويتيح الحساب تشغيل حتى 5 تنبؤات في الوقت نفسه، مشتركة بين الرموز واتصالات MCP. أدر الاتصالات من صفحة MCP في حسابك على PicassoIA، وتحقق من خطتك لمعرفة ما يتضمنه الوصول إلى MCP.

اكتب مسودة الأداة بمساعدة نموذج لغوي

لست مضطرًا إلى كتابة كل أداة بيدك. تحوّل النماذج اللغوية الكبيرة (LLM) جملة عادية إلى مسودة أولى تستطيع اختبارها في Inspector:

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

توليد الصور من المحادثة

بعد الاتصال يصبح سير العمل قصيرًا:

1. افتح محادثتك التي تدعم MCP، وتأكد من أن موصل PicassoIA نشط.
2. صف اللقطة بتفاصيل محددة: الشخص، والعدسة، والإضاءة، والمزاج. جملة مثل "كوب خزفي على مكتب من خشب البلوط، إضاءة نافذة ناعمة من اليسار، عدسة 50mm" أفضل من "صورة قهوة جميلة".
3. اطلب من المساعد استدعاء PicassoIA Image وانتظر النتيجة.
4. حسّن الصورة باستخدام PicassoIA Image Editor Pro بدلًا من البدء من جديد.
5. حرّك أفضل إطار باستخدام PicassoIA Video.

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

💡 التوليد غير متزامن. إذا أبلغ العميل عن حالة "pending"، فهذا يعني أنه يستعلم عن الحالة، وليس أن هناك فشلًا.

جرّبه على Picasso IA اليوم

لديك الآن القطع كلها: خادم، وأول أداة، واختبار في Inspector، واتصال بالعميل. أضف أداة ثانية هذا الأسبوع، وحوّل أحد سكربتاتك الخاصة إلى خادم، وشاهد كيف يصبح مساعدك مفيدًا بسرعة.

ثم وظّف الجانب الإبداعي. توجّه إلى Picasso IA، واختر نموذجًا مثل PicassoIA Image، وولّد أول صورة لك من جملة واحدة. جرّب الإضاءة والعدسات والمزاج، وأرسل أفضل نتيجة إلى Seedance 2.5 Lite لتحريكها، وشاهد إلى أي مدى يمكن أن يذهب أمر نصي جيد واحد.