بناء خادم MCP لـ JackAI Nexus

يشرح هذا الدليل كيفية بناء خادم MCP (بروتوكول سياق النموذج) يتصل بـ JackAI Nexus. يقوم خادم MCP الخاص بك بتوفير الأدوات والموارد والتعليمات التي يمكن لمساعد AI استخدامها أثناء المحادثات.

---

البداية السريعة

1. تثبيت MCP SDK

pip install "mcp>=1.0.0"

2. إنشاء الخادم

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My Business Tools")

@mcp.tool()
def get_product_info(product_id: str) -> str:
    """Get product details by ID."""
    # منطق العمل الخاص بك هنا
    return f"Product {product_id}: Widget Pro, $29.99"

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

3. الاتصال بـ Nexus

في لوحة تحكم JackAI Nexus:

1. اذهب إلى مساعدات AI > اختر مساعدك > خوادم MCP
2. انقر إضافة خادم MCP
3. أدخل:
   • رابط الخادم: https://your-server.com/mcp
   • النقل: Streamable HTTP
   • رمز المصادقة: الرمز السري (اختياري)
4. انقر اختبار الاتصال للتحقق

---

إعداد الخادم

النقل

استخدم Streamable HTTP (موصى به). سيستمع خادمك على نقطة نهاية /mcp واحدة.

mcp.run(transport="streamable-http")

المنفذ الافتراضي هو 8000. لتغييره:

mcp.settings.port = 8100
mcp.settings.host = "0.0.0.0"

المصادقة

احمِ خادمك برمز Bearer:

import os

MCP_AUTH_TOKEN = os.getenv("MCP_AUTH_TOKEN", "your-secret-token")

# يتعامل MCP SDK مع مصادقة Bearer تلقائياً
# يرسل Nexus: Authorization: Bearer <token>

في Nexus، أدخل نفس الرمز في حقل رمز المصادقة.

المضيفات المسموحة

إذا كان خادمك خلف reverse proxy، اسمح باسم المضيف:

from mcp.server.fastmcp.server import TransportSecuritySettings

mcp.settings.transport_security = TransportSecuritySettings(
    enable_dns_rebinding_protection=True,
    allowed_hosts=[
        "localhost",
        "127.0.0.1",
        "mcp.your-domain.com",
    ],
)

---

الأدوات

الأدوات هي دوال يمكن لـ AI استدعاؤها أثناء المحادثات. تستقبل معاملات وترجع نصاً.

أداة بسيطة (نص عادي)

@mcp.tool()
def get_order_status(order_id: str) -> str:
    """Check the status of a customer order.

    Args:
        order_id: The order ID to look up
    """
    # استعلام من قاعدة البيانات/API
    return f"Order {order_id}: Shipped, arriving March 15"

القواعد الأساسية:

• الأدوات ترجع نصاً — يتولى Nexus إرساله للعميل
• وصف الدالة (docstring) يصبح وصف الأداة الذي يراه AI
• استخدم type hints للمعاملات — تصبح مخطط الإدخال
• المعاملات الاختيارية تستخدم Optional[str] = None

أداة مع رد وسائط

لإرسال ملفات (PDF، صور، صوت) للعميل، أرجع نص JSON يحتوي على مفتاح media. يكتشف Nexus هذا التنسيق ويرسل المرفقات عبر منصة المراسلة (WhatsApp، Messenger، إلخ).

مستند (PDF)

import json

@mcp.tool()
def send_catalog(category: str) -> str:
    """Send a product catalog PDF to the customer.

    Args:
        category: Product category (e.g., 'electronics', 'furniture')
    """
    pdf_url = f"https://your-server.com/catalogs/{category}.pdf"

    return json.dumps({
        "text": f"Here is our {category} catalog.",
        "media": [{
            "type": "document",
            "url": pdf_url,
            "filename": f"{category}-catalog.pdf",
            "mime_type": "application/pdf"
        }]
    })

صورة

@mcp.tool()
def send_product_image(product_id: str) -> str:
    """Send a product image to the customer.

    Args:
        product_id: The product ID
    """
    image_url = f"https://your-server.com/images/{product_id}.jpg"

    return json.dumps({
        "text": "Here is the product image.",
        "media": [{
            "type": "image",
            "url": image_url,
            "filename": f"{product_id}.jpg",
            "mime_type": "image/jpeg"
        }]
    })

صوت / رسالة صوتية

@mcp.tool()
def send_audio_guide(topic: str) -> str:
    """Send a pre-recorded audio explanation.

    Args:
        topic: The topic to explain
    """
    audio_url = f"https://your-server.com/audio/{topic}.opus"

    return json.dumps({
        "text": "Here is an audio explanation about the topic.",
        "media": [{
            "type": "audio",
            "url": audio_url,
            "filename": f"{topic}.opus",
            "mime_type": "audio/ogg"
        }]
    })

تنسيق رد الوسائط

{
  "text": "نص الرسالة المعروض للعميل",
  "media": [
    {
      "type": "document | image | audio",
      "url": "https://your-server.com/path/to/file",
      "filename": "display-name.pdf",
      "mime_type": "application/pdf"
    }
  ]
}

ملاحظات مهمة:

• يجب أن يكون url متاحاً للعامة — يقوم Nexus بتحميل الملف من جهة الخادم
• يُدعم إرسال عدة مرفقات في رد واحد
• تُرسل الوسائط قبل الرسالة النصية
• إذا أرجعت الأداة نصاً عادياً (بدون مفتاح media)، تعمل كرد نصي عادي — لا حاجة لتغيير شيء
• حقل text هو ما يستخدمه AI كنتيجة الأداة لسياق المحادثة

---

الموارد

الموارد تضيف معرفة إلى سياق AI. وهي نصوص للقراءة فقط يمكن لـ AI الرجوع إليها أثناء المحادثات.

@mcp.resource("myapp://company-info")
def company_info() -> str:
    """Company overview, contact details, and policies."""
    return """COMPANY INFO
    Name: Acme Corp
    Phone: +1-555-0100
    Email: [email protected]
    Hours: Mon-Fri 9am-6pm

    RETURN POLICY
    30-day returns on all products..."""


@mcp.resource("myapp://pricing")
def pricing() -> str:
    """Current product pricing and discount tiers."""
    return """PRICING
    Widget Pro: $29.99
    Widget Plus: $49.99
    Enterprise: Contact sales

    DISCOUNTS
    10+ units: 10% off
    50+ units: 20% off"""

أفضل الممارسات:

• استخدم الموارد للمعرفة الثابتة (معلومات الشركة، الأسئلة الشائعة، الأسعار، السياسات)
• اجعل محتوى الموارد مركزاً وموجزاً
• يقرأ AI جميع الموارد كسياق — لا تضمّن بيانات غير ذات صلة
• مخطط URI اختياري (مثل myapp://، company://)

---

التعليمات

التعليمات توفر إرشادات سلوكية لـ AI. تحدد كيف يجب أن يتفاعل AI مع العملاء.

@mcp.prompt()
def customer_service_guidelines() -> str:
    """Role definition and behavior rules for the AI assistant."""
    return """CUSTOMER SERVICE GUIDELINES

    ROLE: You are a customer service agent for Acme Corp.

    RULES:
    1. Be polite and professional
    2. Answer questions using the provided resources
    3. If you don't know, say so — don't make up information
    4. For complaints, collect details and escalate
    5. Keep responses short and helpful"""


@mcp.prompt()
def conversation_flow() -> str:
    """Step-by-step conversation flow."""
    return """CONVERSATION FLOW

    STEP 1: Greet the customer
    STEP 2: Identify their need
    STEP 3: Provide information using tools
    STEP 4: Guide to next steps
    STEP 5: Escalate if needed"""

نصائح:

• التعليمات توجه سلوك AI — حدد الدور والنبرة والقواعد
• أشر إلى أسماء الأدوات في التعليمات حتى يعرف AI متى يستخدمها
• اجعل التعليمات واضحة ومحددة

---

مثال كامل

خادم MCP بسيط وكامل:

#!/usr/bin/env python
"""My Business MCP Server"""
import json
import os
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My Business Tools")

# --- الإعدادات ---
SITE_URL = os.getenv("SITE_URL", "https://my-business.com")
MCP_PORT = int(os.getenv("MCP_PORT", "8100"))

# --- الموارد (سياق AI) ---
@mcp.resource("biz://company-info")
def company_info() -> str:
    """Company overview and contact information."""
    return "Company: My Business Inc. Phone: +1-555-0100..."

# --- التعليمات (سلوك AI) ---
@mcp.prompt()
def guidelines() -> str:
    """Customer service behavior rules."""
    return "You are a helpful assistant for My Business Inc..."

# --- الأدوات (إجراءات AI) ---
@mcp.tool()
def get_product_info(product: str) -> str:
    """Get information about a product.
    Args:
        product: Product name or ID
    """
    return f"Product details for {product}..."

@mcp.tool()
def send_catalog(category: str) -> str:
    """Send a product catalog PDF.
    Args:
        category: Product category
    """
    return json.dumps({
        "text": f"Here is our {category} catalog.",
        "media": [{
            "type": "document",
            "url": f"{SITE_URL}/catalogs/{category}.pdf",
            "filename": f"{category}-catalog.pdf",
            "mime_type": "application/pdf"
        }]
    })

# --- التشغيل ---
if __name__ == "__main__":
    mcp.settings.port = MCP_PORT
    mcp.settings.host = "0.0.0.0"
    mcp.run(transport="streamable-http")

---

النشر

Docker

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "server.py"]

# docker-compose.yml
services:
  mcp_server:
    build: .
    ports:
      - "127.0.0.1:8100:8100"
    environment:
      - MCP_AUTH_TOKEN=your-secret-token
      - SITE_URL=https://your-domain.com
    restart: always

HTTPS

يتصل Nexus بخادمك عبر HTTPS. الخيارات:

• Cloudflare proxy (موصى به) — SSL مجاني، اضبط DNS على proxied (السحابة البرتقالية)
• Let's Encrypt — استخدم certbot مع nginx
• Cloudflare Origin Certificate — لوضع Full (strict) SSL

مثال nginx reverse proxy:

server {
    listen 443 ssl;
    server_name mcp.your-domain.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;
    }
}

---

إعدادات الاتصال في Nexus

المعاملات الثابتة

استخدم المعاملات الثابتة لحقن سياق تحتاجه كل استدعاءات الأدوات (مثل معرف المستأجر، مفاتيح API). تُضاف تلقائياً لجميع استدعاءات الأدوات من Nexus.

فلتر الأدوات

افتراضياً، جميع الأدوات المكتشفة مفعّلة. يمكنك اختيار أدوات محددة لتفعيلها إذا أردت أن يستخدم AI مجموعة فرعية فقط.

---

استكشاف الأخطاء