معيار كود وحدات MCP

لماذا يهم معيار الكود

كل موصل نُسلِّمه يبدو بالشكل ذاته. هذا ليس مصادفة — بل انضباط. عندما يصل تكامل ثانٍ، تصبح قدرات الوكيل أسهل في الاختبار والتدقيق والاستبدال لأن كل وحدة MCP تتبع البنية والتسمية وعقد الأخطاء ذاتها.

يحدّد هذا المستند المعيار لجميع وحدات MCP في الهيكل الأساسي لتنسيق IdeaBosque. ويغطي تخطيط الدليل، وتسجيل الأدوات، ومخططات الإدخال/الإخراج، ومعالجة الأخطاء، وتحديد المعدل، وتسجيل التدقيق، ومعالجة حدود PII.

بنية الدليل

تعيش كل وحدة MCP في دليلها الخاص تحت app/mcp_modules/ بتخطيط متّسق:

app/mcp_modules/<slug>/
  __init__.py
  module.py          # تسجيل الأدوات + المعالجات
  schemas.py         # نماذج Pydantic للإدخال/الإخراج
  tests/
    test_module.py
  README.md

تسجيل الأدوات

تُسجِّل كل وحدة أدواتها عبر واجهة قياسية. يكتشف الهيكل الأساسي للتنسيق الأدوات بمسح نقطة الدخول register_tools() — دون توصيل يدوي.

def register_tools(registrar):
    """تسجيل جميع الأدوات التي توفّرها هذه الوحدة."""
    registrar.tool(
        name="search_catalog",
        description="بحث في كتالوج المورّدين حسب SKU أو الاسم",
        input_schema=SearchCatalogInput,
        output_schema=SearchCatalogOutput,
        rate_limit=120,  # استدعاءات في الدقيقة
    )

معالجة الأخطاء

يجب أن تُطلق الوحدات استثناءات مُنمّطة، لا سلاسل نصية مجردة. يلتقط الهيكل الأساسي الفئات الفرعية لـ MCPToolError ويحوّلها إلى استجابات منظّمة يستطيع الوكيل التفكير فيها:

• MCPAuthError — بيانات الاعتماد مفقودة أو منتهية
• MCPRateLimitError — بلوغ حد المعدل في النظام العلوي
• MCPTimeoutError — تجاوز الاستدعاء للنظام العلوي المهلة المُهيّأة
• MCPValidationError — الإدخال لم يجتز التحقق من المخطط
• MCPUpstreamError — أعاد النظام العلوي حالة خطأ

تحديد المعدل

تُعلن كل أداة عن حد المعدل الخاص بها في استدعاء التسجيل. يفرض الهيكل الأساسي هذه الحدود لكل وكيل، ولكل أداة، ولكل نافذة زمنية. عند بلوغ حد، يستقبل الوكيل استجابة 429 مع ترويسة Retry-After — ولا يتعطّل ولا يُعيد المحاولة بشكل أعمى.

تسجيل التدقيق

تُسجَّل كل استدعاء أداة مع: الطابع الزمني، ومُعرّف الوكيل، واسم الأداة، وتجزئة الإدخال (لا الإدخال الخام — حد PII)، وحالة الإخراج، والمدة، والنظام العلوي. تُكتب السجلات بصيغة JSON منظّمة وتُرسَل إلى خط أنابيب المراقبة.

"كل استدعاء أداة مُسجّل وقابل للتدقيق" ليس ميزة نضيفها لاحقًا. إنه أوّل ما يطلبه المعيار.

معالجة حدود PII

يجب أن تُعلن الوحدات عن حقول الإدخال التي تحتوي على PII. يُجزّئ الهيكل الأساسي هذه الحقول قبل تسجيلها ولا يُرسل PII خامًا إلى خط أنابيب التدقيق. تُعلَّم حقول PII في المخطط:

class SearchCatalogInput(BaseModel):
    sku: str
    customer_name: str = Field(..., pii=True)
    region: str

عند ضبط pii=True، يستبدل مسجّل التدقيق القيمة بتجزئة SHA-256. لا يزال مُعالِج الأداة يستقبل القيمة الخام — تُطبَّق معالجة PII عند حد التسجيل، لا داخل منطق العمل.