Blog

بسرعة بناء خادم MCP لـ Claude Code

Audrey Lopez

Audrey Lopez

12 يونيو 2025

بسرعة بناء خادم MCP لـ Claude Code

بروتوكول سياق النموذج (MCP) يُحدث ثورة في كيفية تفاعل المساعدين المدعمين بالذكاء الاصطناعي مع الأدوات ومصادر البيانات الخارجية. فكر في MCP كمنفذ USB-C عالمي لتطبيقات الذكاء الاصطناعي - فهو يوفر طريقة موحدة لربط Claude Code بأي مصدر بيانات أو واجهة برمجة تطبيقات (API) أو أداة يمكنك تخيلها تقريبًا. سيرشدك هذا الدليل الشامل خلال بناء خادم MCP الخاص بك من الصفر، مما يمكّن Claude Code من الوصول إلى وظائف مخصصة توسع قدراته إلى ما هو أبعد بكثير من ميزاته المضمنة.

سواء كنت ترغب في دمج قواعد البيانات، أو واجهات برمجة التطبيقات (APIs)، أو أنظمة الملفات، أو إنشاء أدوات مخصصة بالكامل، يوفر MCP الأساس لقابلية توسع لا حدود لها. بحلول نهاية هذا البرنامج التعليمي، سيكون لديك خادم MCP يعمل وستفهم كيفية توسيعه لأي حالة استخدام.

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API) تولد توثيقًا رائعًا لواجهات برمجة التطبيقات؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معًا بأقصى إنتاجية؟

Apidog يلبي جميع مطالبك، ويحل محل Postman بسعر أقل بكثير!
زر

ما هو خادم MCP ولماذا يتحدث عنه الجميع

ما الذي يميز MCP

MCP (بروتوكول سياق النموذج) هو بروتوكول مفتوح طورته Anthropic يمكّن نماذج الذكاء الاصطناعي من التواصل مع الخوادم الخارجية من خلال واجهة موحدة. على عكس عمليات دمج واجهات برمجة التطبيقات التقليدية حيث تقوم بتضمين نقاط نهاية محددة بشكل ثابت في التعليمات البرمجية، يوفر MCP طريقة منظمة للمساعدين المدعمين بالذكاء الاصطناعي لاكتشاف وفهم واستخدام الأدوات الخارجية ديناميكيًا.

تكمن عبقرية MCP في قابليته للاكتشاف. عندما يتصل Claude Code بخادم MCP الخاص بك، فإنه يتعلم تلقائيًا الأدوات المتاحة، وكيفية استخدامها، والمعلمات التي تقبلها. هذا يعني أنه يمكنك إضافة وظائف جديدة دون تحديث Claude Code نفسه.

تعمق في بنية MCP

يتبع البروتوكول بنية العميل والخادم مع أدوار محددة بوضوح:

شرح تدفق الاتصال

عندما يحتاج Claude Code إلى استخدام أداة خارجية، إليك ما يحدث:

  1. مرحلة الاكتشاف: يستعلم Claude Code من خادمك عن الأدوات المتاحة
  2. التحقق من المخطط (Schema): يستجيب خادمك بتعريفات الأدوات ومخططات الإدخال
  3. اختيار الأداة: يختار Claude Code الأدوات المناسبة بناءً على طلبات المستخدم
  4. مرحلة التنفيذ: يرسل Claude Code استدعاءات الأدوات بمعلمات تم التحقق منها
  5. معالجة النتائج: يعالج خادمك الطلب ويعيد نتائج منظمة

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

المتطلبات الأساسية وإعداد البيئة

تحليل متطلبات النظام

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

لتطوير Python:

لتطوير TypeScript/JavaScript:

التبعيات الأساسية:

إعداد البيئة خطوة بخطوة

1. تثبيت واجهة سطر الأوامر لـ Claude Code (Claude Code CLI)

واجهة سطر الأوامر لـ Claude Code هي أداتك الأساسية لإدارة خوادم MCP. قم بتثبيتها عالميًا لضمان الوصول إليها من أي دليل:

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

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

2. التحقق من التثبيت

تحقق من تثبيت Claude Code بشكل صحيح وإمكانية الوصول إليه:

# Verify installation and check version
claude --version

# Check available commands
claude --help

3. إعداد الأذونات الحرج للمرة الأولى

هذه الخطوة ضرورية للغاية وغالبًا ما يتم تجاهلها:

# Run initial setup with permissions bypass
claude --dangerously-skip-permissions

ما يفعله هذا الأمر:

لماذا هو مطلوب: بدون هذه الخطوة، لا يمكن لخوادم MCP إنشاء اتصالات آمنة مع Claude Code، مما يؤدي إلى فشل المصادقة وانتهاء مهلة الاتصال.

اعتبارات الأمان: علامة --dangerously-skip-permissions آمنة لبيئات التطوير ولكنها تتجاوز مطالبات الأمان العادية. في بيئات الإنتاج، راجع كل طلب إذن بعناية.

التكوين الحرج: فهم نطاقات MCP

لماذا نطاقات التكوين مهمة

أحد أكثر الأخطاء شيوعًا عند بناء خوادم MCP هو إدارة نطاق التكوين غير الصحيحة. فهم النطاقات أمر بالغ الأهمية لأنها تحدد مكان وزمان توفر خادم MCP الخاص بك لـ Claude Code. يقضي العديد من المطورين ساعات في تصحيح أخطاء "الخادم غير موجود" التي تنبع من سوء تكوين النطاق.

يستخدم Claude Code نظام تكوين هرمي مصمم لتوفير المرونة مع الحفاظ على الأمان. كل نطاق يخدم غرضًا محددًا ولديه حالات استخدام مختلفة.

شرح تسلسل نطاق التكوين الهرمي

1. نطاق المشروع (.mcp.json) - الأولوية القصوى

الموقع: دليل جذر المشروع في ملف .mcp.json

الغرض: خوادم MCP خاصة بالمشروع يجب أن تكون متاحة فقط عند العمل في ذلك المشروع المحدد

حالة الاستخدام: اتصالات قاعدة البيانات الخاصة بمشروع، أدوات فحص التعليمات البرمجية (linters) الخاصة بالمشروع، أو أدوات بناء مخصصة

متى يكون نطاق المشروع مناسبًا:

2. نطاق المستخدم (-scope user) - التكوين العام

الموقع: تكوين دليل المستخدم الرئيسي

الغرض: خوادم MCP متاحة عالميًا عبر جميع المشاريع والأدلة

حالة الاستخدام: أدوات عامة مثل واجهات برمجة تطبيقات الطقس، أدوات الآلة الحاسبة، أو أدوات النظام المساعدة

لماذا يُفضل نطاق المستخدم عادةً:

3. النطاق المحلي (افتراضي) - خاص بالدليل

الموقع: سياق دليل العمل الحالي

الغرض: إعدادات خادم MCP سريعة ومؤقتة

القيود: يعمل فقط عندما تقوم بتشغيل Claude Code من ذلك الدليل المحدد

أخطاء التكوين الشائعة

❌ نهج خاطئ (النطاق المحلي - وظائف محدودة):

claude mcp add my-server python3 /path/to/server.py

المشكلة: يعمل هذا الخادم فقط عندما تكون في الدليل المحدد الذي قمت بتسجيله فيه.

✅ نهج صحيح (نطاق المستخدم - وصول عالمي):

claude mcp add --scope user my-server python3 /path/to/server.py

الفائدة: يعمل هذا الخادم من أي دليل على نظامك.

التخطيط الاستراتيجي للأدلة

هيكل الدليل الموصى به

أنشئ هيكل دليل منظم جيدًا لسهولة الصيانة على المدى الطويل:

# Create permanent storage location
mkdir -p ~/.claude-mcp-servers/

# Organize by functionality
mkdir -p ~/.claude-mcp-servers/apis/
mkdir -p ~/.claude-mcp-servers/utilities/
mkdir -p ~/.claude-mcp-servers/development/

فوائد الهيكل المنظم

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

تشخيص مشكلات النطاق

إذا لم يظهر خادم MCP الخاص بك، اتبع هذا التسلسل التشخيصي:

  1. تحقق من تكوين النطاق الحالي:
claude mcp list
  1. تحقق من أنك لست في دليل به نطاق مشروع متعارض:
ls .mcp.json
  1. اختبر من أدلة مختلفة:
cd ~ && claude mcp list
cd /tmp && claude mcp list

إصلاح مشكلات النطاق

المشكلة: الخادم يعمل فقط في دليل واحد

الحل: إزالة التكوين المحلي وإعادة إضافته بنطاق المستخدم

# Remove problematic local configuration
claude mcp remove my-server

# Re-add with global user scope
claude mcp add --scope user my-server python3 /path/to/server.py

بناء أول خادم MCP خاص بك

فهم عملية التطوير

يتضمن بناء خادم MCP فهم كل من بروتوكول MCP والمتطلبات المحددة لحالة الاستخدام الخاصة بك. سنبدأ بخادم "Hello World" أساسي لفهم الأساسيات، ثم نبني على هذا الأساس.

تتبع عملية التطوير هذه المراحل:

  1. إعداد هيكل الخادم: إنشاء هيكل الملفات الأساسي ونقطة الدخول
  2. تطبيق البروتوكول: تطبيق أساليب MCP المطلوبة
  3. تعريف الأداة: تحديد الأدوات التي يوفرها خادمك
  4. التسجيل والاختبار: إضافة الخادم إلى Claude Code والتحقق من الوظائف
  5. التحسين والإنتاج: إضافة وظائف حقيقية ومعالجة الأخطاء

الخطوة 1: أساس المشروع وهيكله

إنشاء بيئة التطوير

أولاً، قم بإنشاء بيئة تطوير مناسبة لخادم MCP الخاص بك:

# Navigate to your MCP servers directory
cd ~/.claude-mcp-servers/

# Create a new server project
mkdir my-first-server
cd my-first-server

# Initialize the project structure
touch server.py
touch requirements.txt
touch .env

لماذا هذا الهيكل مهم

فهم متطلبات خادم MCP

يجب على كل خادم MCP تطبيق ثلاث أساليب JSON-RPC أساسية:

  1. initialize: ينشئ الاتصال ويعلن عن قدرات الخادم
  2. tools/list: يعيد الأدوات المتاحة ومخططاتها

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل