بناء خادم Python MCP من الصفر

أصبح بروتوكول سياق النموذج (Model Context Protocol - MCP) الآن معياراً صناعياً، حيث وصل إلى 97 مليون عملية تحميل شهرياً لـ SDK. تستخدمه كل أداة ذكاء اصطناعي رئيسية. معظم الأدلة تكتفي بإظهار كيفية تثبيت الخوادم الموجودة بالفعل، لكن هذا الدليل يوضح لك كيفية بناء خادمك الخاص باستخدام Python و GitHub API.

ما هو MCP؟

هو بروتوكول يتيح لعملاء الذكاء الاصطناعي (AI clients) استدعاء خدمات خارجية. يقوم الخادم الخاص بك بمعالجة الطلبات من أدوات مثل Claude أو Cursor.

الأجزاء الثلاثة الأساسية لـ MCP:

  • الأدوات (Tools): وظائف يستدعيها الذكاء الاصطناعي لاتخاذ إجراء أو الحصول على بيانات.
  • الموارد (Resources): نقاط نهاية بيانات للقراءة فقط مثل الملفات أو سجلات قواعد البيانات.
  • المطالبات (Prompts): قوالب تعليمات قابلة لإعادة الاستخدام لضمان سير عمل متسق.

إعداد مشروعك

أنشئ مجلداً وثبّت المكتبات اللازمة باستخدام uv:

mkdir github-mcp-server
cd github-mcp-server
uv init .
uv add "mcp[cli]" httpx

بناء الخادم

استخدم FastMCP للقيام بالمهام الشاقة. يستخدم خادم MCP الجيد ثلاثة ملفات محددة: server.py و pyproject.toml وملف .env اختياري لرمز (token) GitHub الخاص بك.

نصائح احترافية للتطوير:

  • استخدم نماذج Pydantic لنتائج الأدوات. يمنح هذا الذكاء الاصطناعي بيانات مهيكلة بدلاً من النصوص غير المنظمة.
  • اكتب docstrings واضحة. يقرأها الذكاء الاصطناعي ليقرر متى يستخدم أداتك.
  • قم بتقييد المدخلات الرقمية (Clamp numeric inputs). غالباً ما ترسل نماذج الذكاء الاصطناعي أرقاماً غير متوقعة مثل 0 أو 100.
  • تعامل مع الاستثناءات (Exceptions). أي عطل في خادمك قد يؤدي إلى قطع الاتصال بالكامل.

الاختبار والنشر

لا تنتظر لتجربته في Claude. استخدم MCP Inspector أولاً. قم بتشغيل:

uv run mcp dev server.py

يفتح هذا واجهة محلية على http://localhost:5173. يمكنك اختبار الأدوات والموارد والمطالبات في مكان واحد.

الاتصال بـ Claude Desktop: قم بتحديث ملف الإعداد الخاص بك لتضمين خادمك. استخدم المسار الكامل لملف server.py. استخدم دائماً uv run بدلاً من أمر python المجرد لتجنب أخطاء البيئة.

الاتصال بـ Claude Code: استخدم أمر CLI:

claude mcp add github-tools -- uv run python /path/to/server.py

يتيح لك بناء خوادم MCP مخصصة جلب بيانات حية إلى سير عمل الذكاء الاصطناعي الخاص بك.

Source: https://dev.to/moksh/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide-397k

Optional learning community: https://t.me/GyaanSetuAi