منشئ MCP

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

## نظرة عامة

أنشئ خوادم MCP (بروتوكول سياق النموذج) التي تمكن نماذج اللغات الكبيرة (LLMs) من التفاعل مع الخدمات الخارجية من خلال أدوات مصممة جيدا. تقاس جودة خادم 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 لعمليات الإدخال/الإخراج - معالجة الأخطاء المناسبة برسائل قابلة للتنفيذ - دعم ترقيم الصفحات حيثما ينطبق ذلك - إرجاع كل من المحتوى النصي والبيانات المهيكلة عند استخدام SDKs الحديثة

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

---

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

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

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

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

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