منشئ MCP

# دليل تطوير خادم MCP

## نظرة عامة

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

---

# العملية

## 🚀 سير العمل عالي المستوى

يتضمن إنشاء خادم MCP عالي الجودة أربع مراحل رئيسية:

### المرحلة 1: البحث المعمق والتخطيط

#### 1.1 فهم تصميم MCP الحديث

**تغطية API مقابل أدوات سير العمل:** حقق التوازن بين تغطية نقاط نهاية API الشاملة وأدوات سير العمل المتخصصة. يمكن أن تكون أدوات سير العمل أكثر ملاءمة للمهام المحددة، بينما توفر التغطية الشاملة للعملاء المرونة لتكوين العمليات. يختلف الأداء باختلاف العميل—قد يستفيد بعض العملاء من تنفيذ الأكواد التي تجمع الأدوات الأساسية، بينما يعمل البعض الآخر بشكل أفضل مع سير العمل ذي المستوى الأعلى. في حالة عدم التأكد، أعط الأولوية للتغطية الشاملة للـ API.

**تسمية الأدوات وقابلية الاكتشاف:** تساعد أسماء الأدوات الواضحة والموصوفة الوكلاء على العثور على الأدوات المناسبة بسرعة. استخدم بادئات متسقة (على سبيل المثال، `github_create_issue`، `github_list_repos`) وتسمية موجهة نحو الإجراء.

**إدارة السياق:** يستفيد الوكلاء من أوصاف الأدوات الموجزة والقدرة على تصفية/ترقيم النتائج. صمم الأدوات التي ترجع بيانات مركزة وذات صلة. يدعم بعض العملاء تنفيذ الأكواد الذي يساعد الوكلاء على تصفية ومعالجة البيانات بكفاءة.

**رسائل الخطأ القابلة للتنفيذ:** يجب أن توجه رسائل الخطأ الوكلاء نحو الحلول برقترحات محددة والخطوات التالية.

#### 1.2 دراسة توثيق بروتوكول MCP

**التنقل في مواصفات MCP:**

ابدأ بخريطة الموقع للعثور على الصفحات ذات الصلة: `https://modelcontextprotocol.io/sitemap.xml`

ثم اجلب صفحات محددة بصيغة `.md` للحصول على تنسيق markdown (على سبيل المثال، `https://modelcontextprotocol.io/specification/draft.md`).

الصفحات الرئيسية المراجعة: - نظرة عامة على المواصفات والهندسة المعمارية - آليات النقل (HTTP قابل للبث، stdio) - تعريفات الأدوات والموارد والمحفزات

#### 1.3 دراسة توثيق الإطار

**المجموعة الموصى بها:** - **اللغة**: TypeScript (دعم SDK عالي الجودة وتوافقية جيدة في بيئات التنفيذ العديدة، على سبيل المثال MCPB. بالإضافة إلى أن نماذج الذكاء الاصطناعي جيدة في إنشاء أكواد TypeScript، مما يستفيد من استخدامه الواسع والكتابة الثابتة وأدوات linting الجيدة) - **النقل**: HTTP قابل للبث للخوادم البعيدة، باستخدام JSON بدون حالة (أبسط في التوسع والصيانة، على عكس الجلسات الحالتية والاستجابات المتدفقة). stdio للخوادم المحلية.

**حمل توثيق الإطار:**

- **أفضل ممارسات MCP**: [📋 اعرض أفضل الممارسات](./reference/mcp_best_practices.md) - المبادئ الأساسية

**لـ TypeScript (موصى به):** - **TypeScript SDK**: استخدم WebFetch لتحميل `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` - [⚡ دليل TypeScript](./reference/node_mcp_server.md) - أنماط وأمثلة TypeScript

**لـ Python:** - **Python SDK**: استخدم WebFetch لتحميل `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - [🐍 دليل Python](./reference/python_mcp_server.md) - أنماط وأمثلة Python

#### 1.4 خطط تنفيذك

**افهم API:** راجع توثيق API للخدمة لتحديد نقاط النهاية الرئيسية ومتطلبات المصادقة وطرز البيانات. استخدم البحث عبر الويب و WebFetch حسب الضرورة.

**اختيار الأدوات:** أعط الأولوية للتغطية الشاملة للـ API. اسرد نقاط النهاية للتنفيذ، بدءا من العمليات الأكثر شيوعا.

---

### المرحلة 2: التنفيذ

#### 2.1 إعداد هيكل المشروع

راجع الأدلة الخاصة باللغة لإعداد المشروع: - [⚡ دليل TypeScript](./reference/node_mcp_server.md) - هيكل المشروع، package.json، tsconfig.json - [🐍 دليل Python](./reference/python_mcp_server.md) - تنظيم الوحدات والاعتماديات

#### 2.2 تنفيذ البنية الأساسية

أنشئ أدوات مشتركة: - عميل API مع المصادقة - مساعدات معالجة الأخطاء - صيغة الاستجابة (JSON/Markdown) - دعم الترقيم

#### 2.3 تنفيذ الأدوات

لكل أداة:

**مخطط الإدخال:** - استخدم Zod (TypeScript) أو Pydantic (Python) - أدرج القيود والأوصاف الواضحة - أضف أمثلة في أوصاف الحقول

**مخطط الإخراج:** - عرف `outputSchema` حيث يكون ممكنا للبيانات المنظمة - استخدم `structuredContent` في استجابات الأداة (ميزة TypeScript SDK) - يساعد العملاء على فهم ومعالجة مخرجات الأداة

**وصف الأداة:** - ملخص موجز للوظيفة - أوصاف المعاملات - مخطط نوع الإرجاع

**التنفيذ:** - Async/await لعمليات الإدخال/الإخراج - معالجة الأخطاء الصحيحة برسائل قابلة للتنفيذ - دعم الترقيم حيث ينطبق - أرجع محتوى نصيا وبيانات منظمة عند استخدام SDK الحديثة

**التعليقات التوضيحية:** - `readOnlyHint`: true/false - `destructiveHint`: true/false - `idempotentHint`: true/false - `openWorldHint`: true/false

---

### المرحلة 3: المراجعة والاختبار

#### 3.1 جودة الكود

راجع: - لا توجد أكواد مكررة (مبدأ DRY) - معالجة الأخطاء المتسقة - تغطية نوع كاملة - أوصاف أدوات واضحة

#### 3.2 البناء والاختبار

**TypeScript:** - شغل `npm