Technical Tutorials

يتطور مشهد تكامل الذكاء الاصطناعي بسرعة. بينما ظل OpenAPI المعيار الذهبي لتوثيق واجهات REST API لفترة طويلة، فإن بروتوكول سياق النموذج (MCP) يبرز كمعيار فعلي لتمكين وكلاء الذكاء الاصطناعي من التفاعل مع الأدوات ومصادر البيانات. ومع ذلك، تواجه العديد من المؤسسات تحدياً: فهي تمتلك مواصفات OpenAPI شاملة، لكنها بحاجة إلى كشف هذه القدرات لنماذج اللغة الكبيرة (LLMs) عبر MCP. يستكشف هذا المنشور كيف تقارن هاتان المواصفاتان ببعضهما البعض، وكيف يمكن بناء جسر فعّال بينهما لتحقيق التشغيل البيني عبر البروتوكولات.

فهم الاختلافات الجوهرية

في جوهرهما، كلاهما MCP وOpenAPI يعتمدان على تعريفات JSON Schema، لكن فلسفات التصميم الخاصة بهما تختلف بشكل كبير. تم تصميم OpenAPI لتوثيق واجهات API التي يمكن للقراءة البشرية، ولعقود الطلب/الاستجابة الصارمة. يركز على طرق HTTP والمسارات ومخططات الأمان. من ناحية أخرى، تم تصميم MCP للتواصل بين الآلات، وتحديداً لنماذج اللغة الكبيرة لاكتشاف الأدوات واستدعائها. إنه يجرد تفاصيل HTTP ويركز على الأوصاف الدلالية التي تساعد النماذج على فهم النية والاستخدام.

تشمل الاختلافات الرئيسية ما يلي:

طبقة النقل: يفترض OpenAPI استخدام HTTP/HTTPS. أما MCP فهو غير مرتبط بطبقة النقل، وغالباً ما يستخدم stdio أو HTTP القابل للتدفق (Streamable HTTP).
دقة المخطط (Schema Granularity): يتطلب OpenAPI نمطاً صارماً لجميع أجسام الطلبات. غالباً ما يقبل MCP مدخلات مرنة، ويعتمد على النموذج لتحويل حجة اللغة الطبيعية إلى بيانات منظمة.
غرض الوصف: تساعد أوصاف OpenAPI المطورين في تنفيذ العملاء (Clients). بينما تساعد أوصاف MCP نماذج اللغة الكبيرة على تحديد متى وكيف تستخدم أداة معينة.

مقارنة تعريفات الأدوات

يتم تعيين "عملية" (operation) في OpenAPI إلى "أداة" (tool) في MCP. دعونا ننظر إلى مثال عملي. افترض أن لدينا دالة بسيطة للبحث في قاعدة بيانات.

تعريف OpenAPI 3.0:


openapi: 3.0.0
info:
  title: Search API
  version: 1.0.0
paths:
  /search:
    post:
      operationId: searchItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The search term
              required:
                - query
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object

تعريف أداة MCP:


{
  "name": "search_items",
  "description": "Searches the product database for items matching the provided query. Returns a list of products with name and price.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The keyword or phrase to search for in product names or descriptions."
      }
    },
    "required": ["query"]
  }
}

لاحظ كيف يتضمن تعريف MCP حقل "description" أكثر تفصيلاً. هذا أمر حاسم لأن نماذج اللغة الكبيرة تعتمد على هذا النص لفائدة الأداة. تعتمد مواصفة OpenAPI على `operationId` وهيكل المسار، وهو أقل بديهية لنموذج يحاول الاستدلال حول الإجراءات.

استراتيجيات التشغيل البيني

عند التحويل من OpenAPI إلى MCP، أو العكس، يجب ألا تعتمد على تحويل JSON بسيط بنسبة 1:1. بدلاً من ذلك، فكر في الاستراتيجيات التالية:

الإثراء الدلالي: استخدم نموذج لغة كبيرة لتوليد أوصاء محسنة لأدوات MCP بناءً على مواصفة OpenAPI. قد تقول الوثيقة الأصلية "احصل على معرف المستخدم"، لكن يجب أن يقول وصف أداة MCP "يسترجع المعرف الفريد للمستخدم الموثق حالياً". يساعد هذا السياق النموذج على استخدام الأداة بشكل صحيح.
تسطيح المعاملات: غالباً ما يستخدم OpenAPI كائنات متداخلة في أجسام الطلبات. يعمل MCP بشكل أفضل مع مخططات مدخلات مسطحة وبسيطة. قم بتسطيح هياكل JSON المتداخلة إلى معاملات فردية كلما أمكن ذلك لتقليل الغموض بالنسبة لنموذج اللغة الكبيرة.
تجريد معالجة الأخطاء: يحدد OpenAPI رموز حالة HTTP. عادةً ما تُرجع أدوات MCP كائن نتيجة واحد. يجب أن يلتقط تنفيذ خادم MCP الخاص بك أخطاء HTTP من واجهة OpenAPI الأساسية وتحويلها إلى رسائل خطأ ذات معنى ضمن استجابة MCP، بدلاً من كشف أخطاء 404 الخام للنموذج.

أفضل الممارسات في التنفيذ

لبناء جسر متين، قم بتغليف عميل OpenAPI الخاص بك داخل خادم MCP. يعمل خادم MCP كمحول (Adapter). يستقبل استدعاء الأداة من نموذج اللغة الكبيرة، ويكوّن طلب HTTP المعرّف في مواصفة OpenAPI، وينفذه، ثم ينسق الاستجابة مرة أخرى إلى نتيجة متوافقة مع MCP.


// Pseudo-code for an MCP Server handler
async function handleSearchTool(args) {
  // 1. Validate args against MCP inputSchema
  if (!args.query) throw new McpError("Missing query");

  // 2. Construct HTTP request based on OpenAPI logic
  const response = await fetch("https://api.example.com/search", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: args.query })
  });

  // 3. Handle errors
  if (!response.ok) {
    return { content: [{ type: "text", text: `Search failed: ${response.statusText}` }] };
  }

  // 4. Format success response for MCP
  const data = await response.json();
  return {
    content: [{
      type: "text",
      text: `Found ${data.length} items: ${data.map(i => i.name).join(", ")}`
    }]
  };
}

الخلاصة

OpenAPI وMCP ليسا منافسين بل معيارين متكاملين. يحدد OpenAPI العقد لسلوك واجهتك البرمجية، بينما يحدد MCP الواجهة لكيفية إدراك وكلاء الذكاء الاصطناعي لهذا السلوك والتفاعل معه. من خلال فهم الاختلافات في دقة المخطط والنية الوصفية، يمكنك بناء محولات فعالة تكشف واجهات REST API الحالية الخاصة بك لعالم وكلاء الذكاء الاصطناعي. مع نمو تبنّي MCP، سيكون الحفاظ على تعيين واضح بين مواصفات OpenAPI الخاصة بك وتعريفات أدوات MCP أمراً أساسياً لأي شخص يبني تطبيقات مدعومة بالذكاء الاصطناعي قابلة للتوسع.