تحويل مواصفات OpenAPI إلى خادم MCP: البنية والحالات الهامشية

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

الثلاثاء في نورثويند. تتلقى بريا، قائدة قسم التكامل في فريق منصة اللوجستيات، تذكرة: "اجعل خدمة تتبع الشحنات (shipment-tracking-svc) قابلة للاستدعاء بواسطة وكيل تحسين المسار." تحتوي الخدمة على 47 نقطة نهاية REST، ومواصفات OpenAPI 3.1 مُصانة، ومصادقة OAuth2، وترحيل قائم على المؤشر، ونقطتي نهاية لخطافات الويب، ونقطة نهاية بث لبيانات تتبع الشاحنات الحية. صندوق أدوات MCP الخاص بالوكيل يحتوي حاليًا على 12 أداة عبر ثلاث خدمات أخرى، تم ترميز كل منها يدويًا على مدار أسبوع تقريبًا. سبع وأربعون نقطة نهاية بهذا المعدل ستستهلك معظم ربع وقت الهندسة.

تصف مواصفات OpenAPI الخدمة بالفعل في شكل قابل للقراءة آليًا — المسارات، والمعلمات، والمخططات، وأشكال الاستجابة، وحتى نطاقات OAuth2 لكل عملية. لا يضيف أي من الترميز اليدوي الذي كانت تقوم به معلومات لا تحتوي عليها المواصفات بالفعل. كان العمل في معظمه ترجمة من لغة مخطط إلى أخرى، مع مجموعة صغيرة من الحالات الهامشية المحددة جيدًا. هذا العمل ينتمي إلى خطوة بناء، وليس إلى ربع من وقت الهندسة.

تشرح هذه المقالة خوارزمية التحويل — ما الذي يتم تعيينه بسلاسة، وما الذي لا يتم، والأجزاء التشغيلية (المصادقة، والتحقق من الصحة، وجودة الوصف) التي تجعل الخادم المُنشأ قابلاً للاستخدام بالفعل.

1. خوارزمية التحويل: من مسار OpenAPI إلى أداة MCP

يقوم التحويل بمعالجة مستند OpenAPI ويُصدر أداة MCP واحدة لكل زوج (مسار، طريقة). لكل زوج، يحسب أربعة أشياء: اسم الأداة، والوصف، ومخطط الإدخال، و (حيث يدعمها إصدار MCP المستهدف) مخطط الإخراج.

اسم الأداة. يُفضل استخدام operationId إذا قدمه مؤلف المواصفات — operationIds هي معرفات اصطلاحية، وعادة ما يتم اختيارها بالفعل لسهولة القراءة. إذا كانت غائبة، يتم توليفها من الطريقة والمسار: تحويل الطريقة إلى أحرف صغيرة، إلحاق المسار مع استبدال الأحرف غير الأبجدية الرقمية بشرطات سفلية، دمج الشرطات السفلية المكررة. GET /users/{user_id}/repos يصبح get_users_user_id_repos. الشكل المُولف صالح نحويًا ولكنه مطول؛ operationIds هي الأفضل حيثما وجدت.

وصف الأداة. يُفضل الملخص، ثم الوصف، ثم جزء مُولّد من الطريقة + المسار. يغطي القسم 6 سبب أهمية هذا الحقل الذي يبدو ثانويًا أكثر مما يتوقع الناس.

مخطط الإدخال. دمج لمعلمات المسار، ومعلمات الاستعلام، ومخطط نص الطلب في كائن مخطط JSON واحد، مع علامات الإلزامي/الاختياري الصحيحة. التفاصيل في القسم 2.

مخطط الإخراج. المخطط المرفق بأول استجابة 2xx لتطبيق/json. أنواع المحتوى الأخرى والاستجابات غير 2xx لا يتم تمثيلها. التفاصيل في القسم 3.

YAML — عنصر مسار OpenAPI (مقتطف من خدمة تتبع الشحنات)

paths:
  /users/{user_id}/repos:
    get:
      operationId: listUserRepos
      summary: List a user's repositories
      description: Returns repositories accessible to the
        authenticated user, owned by user_id, paginated by cursor.
      parameters:
        - name: user_id
          in: path
          required: true
          schema: { type: string }
        - name: per_page
          in: query
          schema: { type: integer, default: 30, maximum: 100 }
        - name: cursor
          in: query
          schema: { type: string, nullable: true }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepoListPage'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
      security:
        - oauth2: [repo:read]

JSON — أداة MCP مُولّدة

{
  "name": "list_user_repos",
  "description": "List a user's repositories. Returns repositories accessible to the authenticated user, owned by user_id, paginated by cursor.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "user_id":  { "type": "string" },
      "per_page": { "type": "integer", "default": 30, "maximum": 100 },
      "cursor":   { "type": "string", "nullable": true }
    },
    "required": ["user_id"]
  },
  "outputSchema": { "$ref": "#/$defs/RepoListPage" }
}

2. تعيين المعلمات: المسار، الاستعلام، ونص الطلب

معلمات المسار مطلوبة دائمًا وتصبح إدخالات إلزامية في مخطط الإدخال. معلمات الاستعلام اختيارية ما لم يتم تحديدها صراحةً كمطلوبة، وأي قيمة افتراضية تنتقل. عادةً ما يتم حذف الرؤوس من مدخلات الوكيل — لا ينبغي للوكيل اختيار نوع المحتوى — مع استثناءات واضحة للرؤوس التي تحمل معلومات دلالية (مثل X-Org-Id, X-Idempotency-Key).

تُعيّن نصوص طلبات application/json إلى كائن متداخل في مخطط الإدخال. يصبح نص الطلب بأكمله وسيطة منظمة واحدة، عادةً ما تُسمى باسم $ref الخاص بمخطط النص (لذا فإن نص الطلب الذي يشير إلى #/components/schemas/CreateRepoRequest يصبح خاصية "create_repo_request"). هذه هي الحالة الأوضح في التحويل، لأن نصوص طلبات OpenAPI هي بالفعل JSON Schema ومخطط الإدخال هو JSON Schema — فالتحويل هو في الغالب مجرد نسخ.

تُعد multipart/form-data و application/x-www-form-urlencoded حالات دعم جزئي. تقبل أدوات MCP وسيطات JSON؛ ويجب على الخادم المُنشأ إعادة تسلسل JSON إلى تنسيق النص المناسب قبل إعادة التوجيه. لا يوجد مكافئ واضح لعمليات تحميل الملفات الثنائية — السبب الأكثر شيوعًا لـ multipart — حيث يمكن لـ MCP تمرير سلاسل مشفرة بـ base64، لكن معظم واجهات برمجة التطبيقات لا تقبل ذلك على نقاط نهاية multipart. الإجابة الصريحة لعمليات تحميل الملفات الثنائية هي أنها غالبًا ما تتطلب أداة مبرمجة يدويًا بدلاً من الأداة المُنشأة.

3. مخططات الاستجابة: اختيار استجابة النجاح

يتم عرض استجابة النجاح فقط كمخطط إخراج للأداة (وفقط حيث يدعم إصدار MCP المستهدف outputSchema على الإطلاق — تمت إضافة الحقل في مراجعة مواصفات 2025-06-18، لذا تتجاهله بيئات التشغيل الأقدم). يختار التحويل أول استجابة 2xx (200، 201، 202) لمحتوى application/json. لا يتم عرض أنواع المحتوى الأخرى؛ ويتم إرجاع الاستجابات غير 2xx إلى الوكيل كأخطاء أداة، وليس كأشكال إخراج بديلة.

لهذا عواقب دقيقة: يرى الوكيل شكل استجابة مسار النجاح، ولا يرى أبدًا شكل استجابة الخطأ المنظمة. هذا هو الشيء الصحيح دائمًا تقريبًا — فالوكلاء لا يخططون بشكل مفيد بناءً على مخططات استجابة الأخطاء — ولكن هذا يعني أن معالجة الأخطاء يجب أن تكون عامة (رمز حالة HTTP بالإضافة إلى رسالة) بدلاً من أن تكون محددة النوع. بالنسبة لواجهات برمجة التطبيقات التي تحتوي على أخطاء منظمة غنية (تفاصيل التحقق، استجابات النجاح الجزئي)، يؤدي هذا إلى فقدان المعلومات.

وهنا أيضًا تظهر مشكلة الترحيل (pagination) لأول مرة: مخطط الإخراج لنقطة نهاية قائمة مصفحة هو شكل استجابة الصفحة الواحدة، وليس النتيجة الكاملة المتصورة للقائمة. يحصل الوكيل الذي يستدعي الأداة على صفحة واحدة، وليس القائمة بأكملها — مما يقودنا إلى القسم التالي.

4. الترحيل — عدم التوافق الأساسي في MCP

واجهات برمجة تطبيقات REST تستخدم الترحيل. أدوات MCP، بحكم تصميم البروتوكول، تُرجع نتائج فردية. التوفيق بينهما هو أصعب قرار في عملية التحويل. هناك ثلاثة خيارات حقيقية، لكل منها مقايضات مختلفة:

(أ) يجب أن يكون الوكيل ذكيًا بما يكفي للترحيل (العديد من النماذج تأخذ الصفحة الأولى وتتوقف). (ب) جلب الكل داخليًا: يقوم الخادم المُنشأ بالتكرار عبر الصفحات وإرجاع المجموع الكلي المسطح. يرى الوكيل نتيجة واحدة نظيفة؛ تتناسب زمن الاستجابة والذاكرة مع حجم النتيجة؛ كارثة زمن استجابة الذيل عند استعلام يضرب العديد من الصفحات. (ج) أداة صفحة تالية منفصلة: تُرجع الأداة الأولى صفحة بالإضافة إلى مؤشر (next_cursor)؛ تستجلب الأداة الثانية الصفحات اللاحقة بواسطة المؤشر. تكلفة متوقعة؛ يتضاعف مخزون أدوات الوكيل لكل نقطة نهاية مصفحة، والعلاقة بين الأداتين ليست واضحة دائمًا للنموذج. معظم المولدات (بما في ذلك TrueFoundry) تختار الخيار (أ) افتراضيًا. النهج الذي يجعل هذا يعمل هو جودة الوصف من القسم 6: يجب أن يوضح وصف الأداة عقد الترحيل صراحةً، مع تسمية معلمة المؤشر وتحديد تعليمات "استدعِ مرة أخرى باستخدام next_cursor للمزيد". بدون ذلك، يأخذ الوكلاء الصفحة الأولى بشكل موثوق ويعتبرون المهمة منتهية.

الخيار (ب) يكون صحيحًا أحيانًا — في مجموعات البيانات الصغيرة والمحدودة حيث يحتاج الوكيل حقًا إلى القائمة بأكملها (جدول تكوين من 50 صفًا، قائمة ثابتة من المناطق) — وعادة ما يكون خاطئًا لكل شيء آخر. يظهر الخيار (ج) في المجالات التي تكون فيها دلالات الصفحة التالية غير بسيطة (انتهاء صلاحية المؤشر، عزل اللقطة)، حيث يكون الفصل الصريح يستحق سطح الأداة الأكبر.

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

يقوم خادم MCP المُنشأ بإجراء طلبات HTTP إلى واجهة برمجة التطبيقات الأساسية؛ وتتطلب هذه الطلبات بيانات اعتماد. القاعدة المعمارية هي: الخادم المُنشأ لا يحتفظ ببيانات الاعتماد. بل توجد في البوابة، وتقوم البوابة بحقنها عند وقت الاستدعاء.

السلسلة، بالترتيب:

سلسلة حقن المصادقة لاستدعاء أداة مقابل خدمة تتبع الشحنات (shipment-tracking-svc)

1. User (or service identity) authenticates to the MCP gateway
   - Personal access token or OAuth, established once
   - Gateway stores no per-tool secrets in agent code

2. Gateway resolves which underlying-API token corresponds to this
   identity × this MCP server
   - Tokens live in the gateway's secret store
   - Refreshed automatically before expiry
   - Per-tool OAuth scopes enforced from the OpenAPI security spec

3. Gateway forwards the tool call to the generated MCP server with
   the resolved token already attached
   - Typically as an Authorization: Bearer header on the HTTP client
     the server uses for its outbound requests
   - The credential never lands in the generated server's code path

4. Generated MCP server constructs the HTTP request from the tool
   arguments and dispatches on the auth'd client
   - Pure function: (tool name, arguments, http_client) -> response

هذا هو نمط البوابة من المنشورات السابقة في هذه السلسلة المطبق على نوع معين من خوادم MCP. الفصل هو ما يجعل الخادم المُنشأ عديم الحالة وقابلًا للتخلص منه — إنه تحويل خالص، مع وجود بيانات الاعتماد، والتحكم في الوصول المستند إلى الدور (RBAC)، وتسجيل التدقيق، وتحديد المعدل في طبقة أعلى.

6. جودة وصف الأداة: توليد تلقائي مقابل تحسين بواسطة نماذج اللغة الكبيرة (LLM)

الأوصاف التي يتم إنشاؤها تلقائيًا صحيحة نحويًا ولكنها بائسة دلاليًا. عبارة "Get users user id repos" هي ما ينتجه المُركِّب لـ GET /users/{user_id}/repos عندما لا يحتوي مواصفات OpenAPI على ملخص أو وصف. في الممارسة العملية، يميل الوكلاء إلى اتخاذ خيارات أدوات أسوأ بناءً على أوصاف كهذه — يختارون الأداة الخاطئة، أو يملأون وسيطات خاطئة، أو يتجاهلون الأداة عندما كانت هي الصحيحة. يظهر التأثير بشكل أوضح في قوائم الأدوات حيث تحتوي عدة نقاط نهاية على أشكال متشابهة، ويجب على النموذج الاعتماد على الوصف للتمييز.

يمكن لخط أنابيب التحويل أن يقدم أداءً أفضل في ثلاث خطوات:

أولاً، يفضل استخدام حقلي الملخص والوصف في OpenAPI. يكتب مؤلفو المواصفات الجيدون هذه بشكل جيد؛ واستخدامها لا يكلف شيئًا.

ثانياً، إذا كان الملخص مفقودًا أو غير مفيد، طبق تمريرة تحسين باستخدام نموذج لغوي كبير (LLM): قم بتغذية المسار، والأسلوب، والمعلمات، ومخطط الاستجابة، وأي سلاسل توثيق لنموذج رخيص واطلب وصفًا سهل الاستخدام للوكيل. "استرداد جميع المستودعات التي يمكن للمستخدم المصادق عليه الوصول إليها، والمملوكة لمعرف مستخدم محدد، مقسمة إلى صفحات 30 لكل صفحة افتراضيًا؛ تُرجع بيانات تعريف المستودع بما في ذلك الاسم، والمالك، واللغة الأساسية، وطابع وقت آخر تحديث." بسعر Claude Haiku 4.5 (حوالي دولار واحد لكل مليون رمز إدخال، و5 دولارات لكل مليون رمز إخراج) يكون التحسين في حدود 0.0005 دولار لكل أداة ويحتاج فقط إلى التشغيل عند تغيير المواصفات.

ثالثاً، قم بتضمين أمثلة في الوصف للحجج غير الواضحة. غالبًا ما تحتاج سلاسل التنسيق، واتفاقيات المعرفات، وقيم التعداد إلى مثال لتكون واضحة. "user_id هو معرف المستخدم الرقمي (على سبيل المثال، '12345')، وليس اسم المستخدم."

تُدفع تكلفة الخطأ في هذا في كل مرة يعمل فيها الوكيل. بينما تُدفع تكلفة القيام بذلك بشكل صحيح مرة واحدة عند وقت الإنشاء وتُستهلك على كل استدعاء للأداة بعد ذلك.

مشكلة المدخلات الرديئة: جودة المواصفات تحدد جودة الأداة

يجعل التوليد التلقائي جودة المواصفات هي جودة التحويل. المشكلات الشائعة في العالم الحقيقي، تقريبًا بترتيب تأثيرها:

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

7. إدارة سطح الأدوات: عندما تتحول 500 نقطة نهاية إلى 500 أداة

يؤدي التحويل الساذج لنقطة نهاية واحدة لكل أداة لواجهة برمجة تطبيقات كبيرة إلى قائمة أدوات تصبح مشكلة بحد ذاتها. تنتج واجهة برمجة تطبيقات تحتوي على 500 نقطة نهاية خادم MCP يحتوي على 500 أداة؛ ويستهلك تحميل مخزون الأدوات هذا في سياق الوكيل عشرات الآلاف من الرموز قبل أن يقوم الوكيل بأي شيء مفيد، وتتدهور دقة اختيار الأداة للنموذج حسب التقارير مع زيادة عدد الأدوات المتاحة. خدمة تتبع الشحنات التي تحولها بريا تحتوي على 47 نقطة نهاية، وهو أمر يمكن إدارته؛ بينما لا يمكن إدارة واجهة REST عامة كبيرة (مثل Stripe، GitHub، AWS) يتم توليدها بالجملة.

أربع استراتيجيات عملية، عادة ما تكون مجتمعة:

التصفية على مستوى المشغل عند التسجيل. تسمح معظم المولدات (بما في ذلك مولد TrueFoundry، ويستخدم openapi-mcp-generator CLI امتدادات OpenAPI x-mcp لهذا الغرض) للمشغل باختيار نقاط النهاية التي سيتم كشفها. الافتراضي "كل شيء في المواصفات" نادرًا ما يكون صحيحًا بعد بضع عشرات من نقاط النهاية.

التجميع القائم على العلامات. تتوافق علامات OpenAPI مع التجميعات المنطقية؛ يمكن للبوابة كشف خادم MCP واحد لكل مجموعة علامات ("shipment-tracking-reads" للعمليات للقراءة فقط، و"shipment-tracking-admin" للعمليات التدميرية). يتوافق هذا بشكل طبيعي مع التحكم في الوصول المستند إلى الدور (RBAC) لكل أداة — حيث يرى الوكيل القارئ خادم القراءة فقط.

خوادم MCP الافتراضية (نمط TrueFoundry، ومفاهيم مماثلة موجودة في أماكن أخرى). خادم منطقي يجمع مجموعة فرعية منسقة من الأدوات عبر خوادم MCP مادية متعددة. يرى الوكيل مخزونًا صغيرًا من الأدوات خاصًا بالمهمة ("billing-agent-tools" يكشف عن 12 أداة مستمدة من Stripe، وخدمة الفواتير الداخلية، ونظام إدارة علاقات العملاء (CRM)) بدلاً من اتحاد كل الواجهات الخلفية.

الاكتشاف الديناميكي. لا يقوم الوكيل بتحميل قائمة الأدوات الكاملة مقدمًا. بدلاً من ذلك، تكشف البوابة عن أداة وصفية يمكن للوكيل استدعاؤها للبحث عن الأدوات أو تصفيتها حسب الوصف، مع إرجاع المجموعة الفرعية ذات الصلة بالمهمة فقط. هذا أكثر تعقيدًا في التنفيذ والتفكير فيه — حيث يجب أن يكون الوكيل ذكيًا بشأن الاكتشاف — ولكنه يتوسع بشكل أكبر من أي استراتيجية تصفية ثابتة.

تعتمد المجموعة الصحيحة على حالة الاستخدام. عادةً ما تستخدم منصة الوكلاء المخصصة لكل فريق تصفية المشغل + خوادم MCP الافتراضية وتتجنب الاكتشاف الديناميكي. يحتاج الوكيل للأغراض العامة الذي يُتوقع منه العمل عبر سطح أدوات المنصة بأكمله في النهاية إلى الاكتشاف الديناميكي لأنه لا يوجد تنسيق ثابت صغير بما يكفي.

8. أنماط HTTP غير المدعومة: Webhooks، والبث، وتنزيلات الملفات.

قائمة غير شاملة لما يصفه OpenAPI ولا يوجد له مكافئ واضح في MCP، اعتبارًا من منتصف عام 2026:

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

9. التحقق من صحة المخطط عند البوابة قبل كل استدعاء HTTP

يمر كل استدعاء أداة إلى خادم MCP المُنشأ عبر البوابة. تتحقق البوابة من صحة وسائط الاستدعاء مقابل مخطط الإدخال قبل إرسالها إلى الخادم، مما يكتشف ثلاث فئات من الأخطاء مبكرًا: عدم تطابق الأنواع (سلسلة نصية حيث يتطلب عددًا صحيحًا)، والحقول المطلوبة المفقودة (تجاهل الوكيل معلمة مسار مطلوبة)، وانتهاكات التعداد (مرر الوكيل قيمة غير موجودة في مجموعة التعداد).

يتم إرجاع خطأ التحقق إلى الوكيل في شكل منظم يمكنه فهمه، وليس كخطأ 400 خام من واجهة برمجة التطبيقات الأساسية:

JSON — خطأ التحقق الذي يتم إرجاعه إلى الوكيل عند استدعاء أداة خاطئ

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Argument validation failed for tool 'list_user_repos'."
  }],
  "errorDetails": {
    "type": "schema_validation",
    "tool": "list_user_repos",
    "issues": [
      { "path": "per_page", "code": "type",
        "expected": "integer", "got": "string", "value": "thirty" },
      { "path": "user_id", "code": "required" }
    ]
  }
}

لماذا عند البوابة وليس في الخادم المُنشأ؟ لسببين. أولاً، الاتساق — يحصل كل خادم MCP، سواء كان مُنشأً أو مكتوبًا يدويًا، على نفس سلوك التحقق. ثانيًا، يمكن للبوابة تطبيق سياسات التحقق (صارمة مقابل متساهلة، تنسيق أخطاء مخصص) دون تغيير الكود المُنشأ. يبقى الخادم المُنشأ أبسط ما يمكن: يدخل طلب متحقق منه، يخرج استدعاء HTTP، وتعود استجابة.

10. أسئلة متكررة

هل يجب علينا استخدام مولد؟ لماذا لا نكتب خادم MCP يدويًا؟

بالنسبة لواجهات برمجة التطبيقات التي تحتوي على أقل من عشر نقاط نهاية تقريبًا، أو حيث تحتاج الأدوات المُنشأة إلى معالجة لاحقة كبيرة (أسماء وسائط مخصصة، نقاط نهاية مدمجة، منطق عمل معقد)، يمكن أن يكون الترميز اليدوي معقولاً. بعد ذلك، يكون الخادم المُنشأ عادةً أقل تكلفة في الصيانة — عندما تضيف واجهة برمجة التطبيقات نقطة نهاية، يلتقطها التجديد تلقائيًا. تتغير الخوادم المكتوبة يدويًا بمرور الوقت.

كيف نتحكم في إصدارات الخادم المُنشأ؟

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

ماذا عن واجهات برمجة التطبيقات التي لا تحتوي على مواصفات OpenAPI؟

الحالة الصعبة. ثلاثة خيارات حقيقية، لا يوجد منها مثالي. (أ) إنشاء المواصفات من حركة المرور المرصودة أو من مصدر SDK — تقوم عدة أدوات بذلك بدقة متفاوتة. (ب) تخطي التحويل وكتابة خادم MCP يدويًا مباشرة. (ج) كتابة مواصفات OpenAPI يدويًا. الخيار (ج) يتطلب عملاً أكثر من (ب) لواجهة برمجة تطبيقات صغيرة وأقل لواجهة كبيرة، مع فائدة إضافية تتمثل في إنتاج مواصفات OpenAPI يمكن لبقية المؤسسة استخدامها.

كيف يتفاعل هذا مع تخصيص التكلفة لكل تتبع في بوابة الذكاء الاصطناعي؟

يطلق كل استدعاء أداة عبر بوابة MCP نطاق OTel يحمل بيانات تعريف الفريق والتطبيق من المنشورات السابقة في هذه السلسلة. تُنسب زمن استجابة الأداة، ومعدل النجاح، وأي تكلفة مرتبطة بواجهة برمجة التطبيقات الأساسية إلى الوكيل والفريق المستدعي.

ما هو مستوى التفصيل المناسب لنطاق المصادقة الخاص بالمولد؟

لكل أداة. تُترجم متطلبات الأمان الخاصة بمواصفات OpenAPI لكل عملية إلى قائمة بنطاقات OAuth2 (أو مخططات مصادقة أخرى)، وتفرض البوابة هذه المتطلبات على مستوى تفصيل الأداة، وليس على مستوى الخادم. يمكن لوكيل لديه نطاق قراءة على نقاط نهاية المستودعات ولكن ليس لديه نطاق كتابة استدعاء list_user_repos ولكن لا يمكنه delete_repo.

ما هو دور TrueFoundry؟

TrueFoundry بوابة MCP يشحن مولدًا من OpenAPI إلى MCP يعمل في مستوى التحكم بالبوابة. تتم عملية التحويل عند التسجيل؛ ويعمل الخادم المُنشأ كوكيل مُدار توجّهه البوابة. سلسلة حقن المصادقة، والتحقق من المخطط، والتحكم في الوصول المستند إلى الدور (RBAC)، وتسجيل التدقيق الموصوفة في هذا المنشور هي أساسيات البوابة التي يرثها الخادم المُنشأ بوجوده خلف البوابة — وهي نفس الأساسيات التي تنطبق على أي خادم MCP آخر مسجل لديها. المولد هو أحد الخيارات الإنتاجية المتعددة (Speakeasy، Stainless، FastMCP، وعدد قليل من البدائل مفتوحة المصدر تقوم بتحويلات مماثلة)؛ وعادة ما يعود الاختيار إلى مكان استضافة الخادم الناتج، وكيفية دمجه مع المصادقة والمراقبة الحالية للفريق، وما يديره الفريق بالفعل.

سبعة وأربعون نقطة نهاية، كل منها يستغرق أسبوع عمل مهندس، يمثل معظم ربع عمل هندسي. سبعة وأربعون نقطة نهاية عبر مولد هي خطوة بناء. العمل المتبقي — تنظيم الأوصاف، وتحديد استراتيجية ترقيم الصفحات لكل نقطة نهاية، والترميز اليدوي لنصف دزينة من العمليات التي لا تُترجم — هو عمل حقيقي ولكنه محدود. الميكانيكا ليست هي المكان الذي يجب أن تذهب إليه الهندسة.

المراجع

• بروتوكول سياق النموذج — المواصفات
• مواصفات OpenAPI 3.1
• TrueFoundry — من OpenAPI إلى خادم MCP
• Speakeasy — إنشاء خوادم MCP من OpenAPI
• Stainless — تحويل مواصفات OpenAPI إلى خوادم MCP
• FastMCP — إطار عمل خادم MCP بلغة بايثون مع تحويل OpenAPI
• openapi-mcp-generator (TypeScript)

Northwind، Priya، و shipment-tracking-svc هي أمثلة توضيحية؛ تعكس بنية التحويل، وقواعد التعيين، والحالات الهامشية كيفية عمل مولدات OpenAPI-to-MCP الإنتاجية (مثل TrueFoundry، Speakeasy، Stainless، FastMCP، والعديد من البدائل مفتوحة المصدر) اعتبارًا من مايو 2026. تستمر مواصفات OpenAPI و MCP في التطور؛ وقد تتغير التعيينات للميزات الأحدث (مثل OpenAPI webhooks، و MCP elicitations، وتوضيحات أدوات MCP مثل readOnlyHint) في المراجعات المستقبلية.

‍