سير عمل التكامل

ما ستتعلمه

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

طرق التكامل

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

أنماط التكامل الشائعة

سير عمل تطوير قواعد البيانات

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

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

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

AGENTS.md:

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

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

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

تطوير API مع الأمان

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

المكونات:

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

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

إمكانية الوصول للواجهة الأمامية

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

سير العمل:

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

أمثلة على تكوين MCP

فهم MCP

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

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

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

الإعداد الأساسي

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

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}

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

{
  "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}"
      }
    }
  }
}

التوضيح:

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

بيئات متعددة

{
  "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 مع سلوك القراءة فقط داخليًا بحسب تطبيقها. راجع وثائق الخادم المحدد للتعرف على خيارات التحكم في الوصول.

تكامل مساحة العمل

التكوين الخاص بالمشروع

الإعداد:

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

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

{
  "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"
      ]
    }
  }
}

تعاون الفريق

معايير AGENTS.md المشتركة

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

# 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: قواعد أساسية

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

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

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

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

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

التركيبات الاستراتيجية

أفضل ممارسات توثيق الفريق

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

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

حل المشكلات

انظر أيضًا