# سير عمل التكامل (/ar/docs/verdent-for-vscode/advanced-features/integrations)

> أنماط عملية لدمج Verdent مع الأدوات والخدمات الخارجية



### ما ستتعلمه [#ما-ستتعلمه]

سير عمل تكامل عملي يجمع بين الوكلاء الفرعيين المخصصين والقواعد وخوادم MCP لسيناريوهات تطوير من واقع الحياة الفعلية.

***

## طرق التكامل [#طرق-التكامل]

| الطريقة                       | الأفضل لـ                                     | التكوين                     |
| ----------------------------- | --------------------------------------------- | --------------------------- |
| **الوكلاء الفرعيون المخصصون** | المهام المتخصصة المعتمدة على الذكاء الاصطناعي | `~/.verdent/subagents/*.md` |
| **القواعد (AGENTS.md)**       | معايير الفريق والسلوك                         | جذر المشروع `AGENTS.md`     |
| **خوادم MCP**                 | الأدوات الخارجية المتوافقة مع البروتوكول      | `.mcp.json` (جذر المشروع)   |

**الفلسفة:** اجمع بين الطرق لإنشاء سير عمل شامل مصمم خصيصًا لاحتياجاتك.

***

## أنماط التكامل الشائعة [#أنماط-التكامل-الشائعة]

### سير عمل تطوير قواعد البيانات [#سير-عمل-تطوير-قواعد-البيانات]

**الحزمة:** الوكيل الفرعي لمراجعة الترحيل + معايير AGENTS.md + خادم PostgreSQL MCP

**الوكيل الفرعي:**

```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```

**AGENTS.md:**

```markdown
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
```

**MCP:** خادم PostgreSQL لتنفيذ الاستعلامات، وفحص المخططات، والتحقق من صحة الترحيل

**سير العمل:** كتابة الترحيل ← يتحقق منه @migration-reviewer ← اختبار MCP على بيئة staging ← توثيق طلب السحب

***

### تطوير API مع الأمان [#تطوير-api-مع-الأمان]

**الحزمة:** مدقق الأمان + قواعد AGENTS.md + أداة اختبار API مخصصة

**المكونات:**

* **الوكيل الفرعي:** `@api-security-auditor` - التحقق من صحة المدخلات، حقن SQL، المصادقة، تحديد معدل الطلبات
* **القواعد:** جميع نقاط النهاية تتطلب مراجعة أمنية، وتحديد معدل الطلبات على APIات العامة
* **الأدوات الخارجية:** اختبار تلقائي لنقاط النهاية وفحوصات أمنية عبر تكامل مخصص

**النتيجة:** مراجعة أمنية تلقائية قبل الموافقة على طلب السحب.

<Note>
  يمكن دمج أدوات اختبار API والفحص الأمني عبر تطبيقات خادم MCP مخصصة أو طرق تكامل أخرى، بحسب الأدوات التي تستخدمها.
</Note>

***

### إمكانية الوصول للواجهة الأمامية [#إمكانية-الوصول-للواجهة-الأمامية]

**الحزمة:** مدقق إمكانية الوصول + قواعد WCAG + تكامل Lighthouse

**سير العمل:**

```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```

<Note>
  يمكن دمج Lighthouse وأدوات إمكانية الوصول الأخرى من خلال خوادم MCP مخصصة أو تكامل خطوط أنابيب CI/CD، بحسب سير عملك.
</Note>

***

## أمثلة على تكوين MCP [#أمثلة-على-تكوين-mcp]

### فهم MCP [#فهم-mcp]

**بروتوكول سياق النموذج (MCP)** هو بروتوكول مفتوح يوحّد كيفية تزويد التطبيقات بالسياق للوكلاء LLM. خوادم MCP هي ملفات تنفيذية تطبّق البروتوكول. إنها ليست اتصالات بقواعد بيانات أو نقاط نهاية API، بل برامج تعمل وتتواصل عبر JSON-RPC 2.0.

**المفاهيم الأساسية:**

* **خوادم MCP**: ملفات تنفيذية (حزم Node.js، سكريبتات Python، وغيرها) تطبّق بروتوكول MCP
* **التكوين**: يخبر Verdent كيفية تشغيل الخادم (`command` + `args`)
* **الاتصال**: تتعامل الخوادم مع منطقها التجاري الخاص (الاستعلامات، استدعاءات API، وغيرها)

### الإعداد الأساسي [#الإعداد-الأساسي]

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

<CodeGroup>
  ```json PostgreSQL Server
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      }
    }
  }
  ```

  ```json GitHub Server
  {
    "mcpServers": {
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```

  ```json Multiple Servers
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      },
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```
</CodeGroup>

**التوضيح:**

* `mcpServers` - مفتاح المستوى الأعلى المطلوب لتكوين MCP
* `command` - الملف التنفيذي المراد تشغيله (يكون غالبًا `npx` لحزم Node.js)
* `args` - المعطيات (arguments) الممررة إلى الأمر (اسم الحزمة، سلاسل الاتصال، وغيرها)
* `env` - متغيرات البيئة للمصادقة/التكوين

### بيئات متعددة [#بيئات-متعددة]

```json
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}
```

**أفضل الممارسات:** استخدم متغيرات البيئة لسلاسل الاتصال للحفاظ على أمان بيانات الاعتماد. تتعامل خوادم MCP مع سلوك القراءة فقط داخليًا بحسب تطبيقها. راجع وثائق الخادم المحدد للتعرف على خيارات التحكم في الوصول.

<Tip>
  **تعرّف على المزيد حول MCP:**

  * [مواصفات بروتوكول سياق النموذج](https://modelcontextprotocol.io/specification)
  * [سجل خوادم MCP](https://mcp.so/servers) - استعرض خوادم MCP المتاحة
  * [خوادم MCP الرسمية](https://github.com/modelcontextprotocol) - PostgreSQL، وGitHub، ونظام الملفات، وغيرها
</Tip>

***

## تكامل مساحة العمل [#تكامل-مساحة-العمل]

### التكوين الخاص بالمشروع [#التكوين-الخاص-بالمشروع]

**الإعداد:**

1. خزّنه في جذر المشروع: `.mcp.json`
2. اعتمده في نظام التحكم في الإصدارات لمشاركته مع الفريق
3. يستخدم أعضاء الفريق تلقائيًا خوادم MCP الخاصة بالمشروع

**مثال على الخدمات الصغيرة (Microservices):**

```json
{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}
```

<Note>
  للخدمات الإضافية مثل Kafka، ستحتاج إلى تطبيق خادم MCP متوافق. يسرد سجل خوادم MCP الرسمي على [mcp.so/servers](https://mcp.so/servers) الخوادم المتاحة من المجتمع.
</Note>

***

## تعاون الفريق [#تعاون-الفريق]

### معايير AGENTS.md المشتركة [#معايير-agentsmd-المشتركة]

اعتمد التوثيق في نظام التحكم في الإصدارات لضمان الاتساق على مستوى الفريق:

```markdown
# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
```

**الفوائد:** سلوك متسق، معايير مُطبّقة إلزاميًا، وضوابط جودة تلقائية.

***

## تنسيق الوكلاء المتعددين [#تنسيق-الوكلاء-المتعددين]

### سير عمل ميزة معقدة [#سير-عمل-ميزة-معقدة]

**مثال:** نقطة نهاية دفع جديدة

```
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
```

**النتيجة:** نقطة نهاية تمت مراجعتها بالكامل مع تطبيق أفضل ممارسات الأمان وقواعد البيانات.

***

## أفضل ممارسات التكامل [#أفضل-ممارسات-التكامل]

### التبني التدريجي [#التبني-التدريجي]

**المرحلة 1:** قواعد أساسية

```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**المرحلة 2:** إضافة وكيل فرعي متخصص

```markdown
## Code Review
- Run @security-reviewer before PR
```

**المرحلة 3:** دمج MCP

```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### التركيبات الاستراتيجية [#التركيبات-الاستراتيجية]

| التركيبة                   | الغاية                                                  | مثال                                    |
| -------------------------- | ------------------------------------------------------- | --------------------------------------- |
| القواعد + الوكلاء الفرعيون | تحدد القواعد *متى*، ويقوم الوكلاء الفرعيون بـ *التحليل* | AGENTS.md: "راجع مع @security-reviewer" |
| القواعد + MCP              | تحدد القواعد *أي* خوادم، ويقوم MCP بـ *الوصول*          | AGENTS.md: "استخدم db-staging فقط"      |
| الوكلاء الفرعيون + MCP     | يستخدم الوكيل الفرعي MCP لجلب *بيانات خارجية*           | يستعلم مدقق الأمان نقاط نهاية API       |

### أفضل ممارسات توثيق الفريق [#أفضل-ممارسات-توثيق-الفريق]

عند توثيق التكاملات لفريقك، أدرج ما يلي:

* **الوكلاء الفرعيون المخصصون**: اذكر اسم كل وكيل فرعي، والغاية منه، ومتى يجب استدعاؤه
* **قواعد AGENTS.md**: وثّق القواعد مع تبرير منطقي يوضّح "السبب" وراء كل معيار
* **خوادم MCP**: صف الغاية من كل خادم، ومستوى الوصول (قراءة فقط/كتابة)، ومتى يجب استخدامه
* **سير عمل التكامل**: قدّم أمثلة على سير العمل توضّح كيفية عمل المكونات معًا
* **حل المشكلات**: وثّق المشكلات الشائعة الخاصة بإعدادك وحلولها

<Tip>
  اعتمد وثائق التكامل جنبًا إلى جنب مع ملفات `.mcp.json` و`AGENTS.md` الخاصة بك حتى يتمكن أعضاء الفريق الجدد من فهم إعدادك بسرعة.
</Tip>

***

## حل المشكلات [#حل-المشكلات]

<Tabs>
  <Tab title="مشكلات الوكيل الفرعي">
    **المشكلة:** لا يتم استدعاء الوكيل الفرعي عند التوقع

    **تحقق من:**

    **الموقع**: الملف موجود في `~/.verdent/subagents/[name].md`

    **بيانات YAML الأولية (Frontmatter)**: صياغة صحيحة تتضمن الحقلين المطلوبين `name` و`description`

    **سياسة الاستدعاء**: تتطابق مع الاستخدام (الوضع الصارم يتطلب إشارة @ صريحة)

    **الوصف**: `description` الوكيل يصف بدقة الحالات التي يجب فيها استخدام الوكيل الفرعي

    **إعادة التشغيل**: جرّب إعادة تشغيل Verdent لإعادة تحميل تعريفات الوكلاء الفرعيين

    ***

    **الأسباب الشائعة:**

    * خطأ إملائي في اسم ملف الوكيل الفرعي أو في إشارة @
    * صياغة YAML غير صحيحة في البيانات الأولية
    * `description` الوكيل الفرعي لا يتطابق مع سياق المهمة
  </Tab>

  <Tab title="مشكلات AGENTS.md">
    **المشكلة:** قواعد AGENTS.md لا تُطبَّق

    **تحقق من:**

    **الموقع**: الملف موجود في جذر المشروع

    **الصياغة**: Markdown صحيح بدون أخطاء تحليل

    **أسلوب التوجيه**: استخدم أوامر محددة ("استخدم دائمًا..." بدلًا من "حاول أن...")

    **الجلسة**: ابدأ محادثة جديدة لاختبار تطبيق القاعدة من جديد

    **التعارضات**: تحقق مما إذا كانت قواعد المستخدم تتجاوز قواعد المشروع دون قصد

    ***

    **الأسباب الشائعة:**

    * وجود AGENTS.md في مجلد خاطئ (يجب أن يكون في جذر المشروع)
    * تعليمات غامضة يفسرها الذكاء الاصطناعي بشكل مختلف
    * تُطبَّق القواعد لكن النتائج ليست كما هو متوقع (نقّح الصياغة)
  </Tab>

  <Tab title="مشكلات خادم MCP">
    **المشكلة:** فشل خادم MCP في البدء أو الاتصال

    **تحقق من:**

    **الصياغة**: يحتوي `.mcp.json` على JSON صحيح (استخدم `jq` للتحقق)

    **البنية**: المفتاح المطلوب `mcpServers` موجود في المستوى الأعلى

    **تكوين الخادم**: يحدد كل خادم `command` و`args` بشكل صحيح

    **الحزمة**: حزمة خادم MCP قابلة للوصول (يقوم `npx` بتنزيل الحزم تلقائيًا؛ العلم `-y` يتجاوز مطالبة التأكيد)

    **البيئة**: المتغيرات في كائن `env` مضبوطة بشكل صحيح في shell الخاص بك

    **الأذونات**: الملف التنفيذي للخادم يملك أذونات تنفيذ مناسبة

    ***

    **الأسباب الشائعة:**

    * خطأ إملائي في JSON (فاصلة مفقودة، قوس غير مغلق)
    * اسم حزمة خاطئ في مصفوفة args
    * متغيرات بيئة مفقودة أو غير صحيحة
    * جدار حماية/شبكة تحظر تثبيت حزمة npx

    ***

    **خطوات التصحيح:**

    1. تحقق من صحة JSON: `cat .mcp.json | jq .`
    2. اختبر الأمر يدويًا: `npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
    3. تحقق من البيئة: `echo $GITHUB_TOKEN`
    4. راجع سجلات Verdent لمعرفة رسائل الخطأ المحددة
  </Tab>
</Tabs>

***

## انظر أيضًا [#انظر-أيضًا]

<CardGroup cols="2">
  <Card title="دليل قابلية التوسع" icon="puzzle-piece" href="/docs/verdent-for-vscode/advanced-features/extensibility">
    نظرة شاملة على طرق التوسيع
  </Card>

  <Card title="تكامل MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    تفاصيل بروتوكول سياق النموذج
  </Card>
</CardGroup>