إعداد بيئة تطوير MCP الخاصة بك

عشر دقائق من الإعداد، وبعدها تقضي بقية الدورة في كتابة كود الخادم بدل مصارعة بيئتك.

المتطلبات المسبقة

• بيئة تشغيل Python أو Node.js. كل SDK يحدد إصداره الأدنى بنفسه، وهذه الأرقام تتغير — راجع توثيق MCP SDK لمعرفة المتطلب الحالي بدل الاعتماد على رقم مكتوب في دورة.
• Claude Desktop، وهو ما ستختبر عليه.
• محرر كود. أي محرر يفي بالغرض.

تثبيت MCP SDK

تغطي الـ SDKs الرسمية لغات Python وTypeScript وC# وJava وKotlin وSwift، إضافة إلى SDKs من المجتمع للغات Rust وGo وغيرها. تستخدم هذه الدورة Python في الأمثلة، وTypeScript حيثما اختلف الأمر بشكل جوهري — فالبروتوكول واحد تحت السطح، والمفاهيم تنتقل إلى أي لغة تختارها.

# اعزل المشروع حتى لا تكسر ترقيات الـ SDK أعمالك الأخرى
python -m venv mcp-env
source mcp-env/bin/activate       # على Windows: mcp-env\Scripts\activate

# الـ SDK الآن في الإصدار الثاني. ثبّت رقم الإصدار الرئيسي حتى لا يعيد إصدار ثالث كتابة خادمك فجأة.
pip install 'mcp>=2,<3'

# اطبع الإصدار الذي حصلت عليه فعلاً واحتفظ به في ملف README
python -c "import importlib.metadata as m; print('mcp', m.version('mcp'))"

أول خادم MCP لك (Python)

أنشئ ملفاً باسم server.py:

from mcp.server import MCPServer

# اسم الخادم هو ما يظهر في سجلات المضيف وفي واجهة إعداداته
mcp = MCPServer(name="hello-mcp")


@mcp.tool()
def greet(name: str) -> str:
    """تحية شخص بالاسم."""
    return f"مرحباً، {name}!"


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

هذا هو الخادم بأكمله. ثلاثة أمور تستحق التسمية هنا، لأنها سبب كون هذا الكود أقصر مما توقعت:

• تلميحات الأنواع هي المخطط. التلميح name: str يتحول إلى inputSchema الذي يقرأه النموذج، فلن تكتب JSON Schema يدوياً إلا إذا أردت ذلك.
• نص التوثيق هو الوصف. هو النص الذي يقرر النموذج بناءً عليه استدعاء أداتك من عدمه، فهو يستحق عناية أكبر من جسم الدالة نفسه.
• mcp.run() يختار stdio افتراضياً، وهو ما يشغّله Claude Desktop.

شغّل الخادم قبل ربطه بأي شيء. خادم يبدأ نظيفاً ويتوقف عند Ctrl-C يكون قد استبعد نصف المشكلات التي كنت ستطاردها لاحقاً من خلال المضيف:

python server.py

تكوين Claude Desktop

أضف خادمك إلى ملف تكوين Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hello-mcp": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

اختبار خادمك

1. أعد تشغيل Claude Desktop
2. افتح محادثة جديدة
3. اسأل كلود: "استخدم أداة التحية لقول مرحباً لأليس"
4. سيستدعي كلود خادم MCP الخاص بك!

حين لا يعمل الأمر

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

الخطأ الذي يقع فيه الجميع: في خادم يعمل عبر stdio، المخرج القياسي هو قناة البروتوكول نفسها. أي print() شارد يحقن نصاً في مجرى JSON-RPC فينقطع الاتصال دون رسالة خطأ مفيدة. سجّل إلى ملف أو إلى مخرج الأخطاء، ولا تسجّل أبداً إلى المخرج القياسي.

التالي: بناء خادم حقيقي بأدوات وموارد. :::