mcpo (MCP-to-OpenAPI)

لماذا تستخدمه

الميزات الأساسية

فوري: أي MCP stdio يصبح HTTP+OpenAPI
واجهة Swagger /docs مولَّدة تلقائياً
JSON Schema لمدخلات ومخرجات الأدوات
OAuth مدعوم (client credentials + JWT)
تشغيل MCPs متعددة مغلَّفة في عملية واحدة
Python خفيف (FastAPI)، Apache 2.0

عرض مباشر

كيف يبدو في الممارسة

mcpo-openapi-mcp.replay ▶ جاهز

0/0

التثبيت

اختر العميل

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

افتح Claude Desktop → Settings → Developer → Edit Config. أعد التشغيل بعد الحفظ.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

يستخدم Cursor نفس مخطط mcpServers مثل Claude Desktop. إعدادات المشروع أولى من الإعدادات العامة.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

انقر على أيقونة MCP Servers في شريط Cline الجانبي، ثم "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

نفس الصيغة مثل Claude Desktop. أعد تشغيل Windsurf لتطبيق التغييرات.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcpo-openapi-mcp",
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  ]
}

يستخدم Continue مصفوفة من كائنات الخادم بدلاً من خريطة.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcpo-openapi-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "mcpo",
          "--",
          "uvx",
          "mcp-server-time"
        ]
      }
    }
  }
}

أضف إلى context_servers. يعيد Zed التحميل تلقائيًا عند الحفظ.

claude mcp add mcpo-openapi-mcp -- uvx mcpo -- uvx mcp-server-time

أمر من سطر واحد. تحقق باستخدام claude mcp list. احذف باستخدام claude mcp remove.

حالات الاستخدام

استخدامات عملية: mcpo (MCP-to-OpenAPI)

كيفية استدعاء خادم MCP من curl / Postman / OpenAI function-calling

👤 مطورو الباك-إند الذين لا يتحدث وقت تشغيلهم (بعد) MCP ⏱ ~15 min intermediate

متى تستخدمه: اخترت خادم MCP رائعاً لكن بنية الإنتاج الخاصة بك عبارة عن Python service / OpenAI Assistants API / شيء يريد HTTP+JSON.

المتطلبات الأساسية

أمر MCP الذي ستُشغّله عادة — مثل: uvx mcp-server-time أو npx -y @modelcontextprotocol/server-fetch

الخطوات

التغليف

Run uvx mcpo --port 8000 -- uvx mcp-server-time and confirm /docs is up.✓ تم النسخ

→ واجهة Swagger تُظهر الأدوات كنقاط نهاية
الاستدعاء من curl

Show me a working curl that calls the time tool with timezone=America/Los_Angeles.✓ تم النسخ

→ يُرجع الوقت الحالي + معلومات المنطقة الزمنية
الربط مع OpenAI

Generate a function-calling spec from /openapi.json that I can paste into the OpenAI API.✓ تم النسخ

→ المواصفة مُصدَرة؛ اختبار استدعاء سريع ينجح

النتيجة: خادم MCP يستطيع باك-إند غير MCP قيادته عبر HTTP.

المزالق

الأدوات طويلة التشغيل تنتهي مهلتها تحت إعدادات uvicorn الافتراضية — مرّر --timeout-keep-alive 600 إلى mcpo، أو ضع nginx أمامه مع مهل مطابقة

تشغيل عدة MCPs خلف خدمة HTTP واحدة

👤 مهندسو المنصات الذين يُوحّدون MCPs متعددة ⏱ ~30 min intermediate

متى تستخدمه: تريد URL واحد يستضيف MCPs الوقت والجلب ونظام الملفات كلٌّ منها بمسار بادئة خاص.

الخطوات

التكوين

Write the mcpo config for 3 servers — time at /time, fetch at /fetch, filesystem at /fs.✓ تم النسخ

→ config.yaml بـ 3 خدمات؛ mcpo يخدمها
إضافة OAuth

Configure JWT auth via the issuer of my Auth0 tenant. Endpoints require a valid token.✓ تم النسخ

→ الاستدعاءات بدون token تُرجع 401

النتيجة: نقطة دخول HTTP واحدة آمنة تستضيف MCPs متعددة.

المزالق

الأدوات تتعارض عندما يكشف خادمان نفس الاسم — mcpo تُضيف مساحة اسم بالبادئة؛ تعارضات الأدوات تُحل بمسار URL

استخدام MCP كجزء من مجموعة اختبار HTTP تكاملية

👤 فرق QA / SDET ⏱ ~25 min advanced

متى تستخدمه: تريد التحقق من سلوك خادم MCP بأدوات اختبار HTTP قياسية.

الخطوات

التشغيل في CI

Add a GitHub Actions job that runs mcpo wrapping our MCP, then runs Playwright/pytest against it.✓ تم النسخ

→ ملف workflow مكتوب؛ يجتاز محلياً
تأكيدات Schema

Snapshot /openapi.json. Fail the build if the schema changes without an explicit change in the source.✓ تم النسخ

→ حارس فروق schema في CI

النتيجة: خط أنابيب اختبار HTTP قياسي مُطبَّق على خادم MCP.

المزالق

متقلقل إن استورد MCP الأصلي تبعيات ثقيلة عند بدء التشغيل — أضف حلقة انتظار /healthz قبل تشغيل الاختبارات

اجمعها مع: github

التركيبات

اجمعها مع خوادم MCP أخرى لتحقيق نتائج x10

mcpo-openapi-mcp + filesystem

حفظ /openapi.json المولَّد في مستودعك للمراجعة

Save current /openapi.json to /api/contracts/$(date +%F).json.✓ تم النسخ

mcpo-openapi-mcp + github

فتح PR عند تغيير مواصفة OpenAPI

If the snapshot diff is non-empty, open a PR titled 'OpenAPI changed'.✓ تم النسخ

الأدوات

ما يوفره هذا الـ MCP

الأداة	المدخلات	متى تستدعيها	التكلفة
GET /docs	(browser)	استكشاف سطح الأداة بصرياً	free
GET /openapi.json	(none)	توليد الكود / مواصفات function-calling	free
POST /<tool>	JSON body matching tool input schema	استدعاء أداة MCP مُغلَّفة عبر HTTP	1 underlying MCP call

التكلفة والحدود

تكلفة التشغيل

حصة API: مرتبط بحصص MCP المُغلَّف
الرموز لكل استدعاء: يُضيف ~50 token عبئاً
التكلفة المالية: مجاني (Apache 2.0)
نصيحة: غلّف مرة واحدة لكل عملية؛ لا تُنشئ subprocess جديداً لكل طلب

الأمان

الصلاحيات والأسرار ونطاق الأثر

تخزين بيانات الاعتماد: مرور عبر إلى MCP المُغلَّف عبر env vars؛ mcpo نفسه لا يخزّن شيئاً

نقل البيانات الخارجي: حيثما كان سيُخرج MCP المُغلَّف

النشر الافتراضي غير مُصادَق عليه — ضع دائماً خلف OAuth أو شبكة خاصة

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

الأخطاء الشائعة وحلولها

404 على /tool

اسم الأداة في URL يجب أن يطابق تماماً اسم أداة MCP (حساس لحالة الأحرف)

تحقق: تحقق من /docs للمسار الصحيح

MCP الأصلي تعطّل

mcpo يُعيد التشغيل تلقائياً لكنه يُسجّل الخطأ — تحقق من stderr

OAuth 401 مع token صالح

تحقق من تطابق audience وissuer مع إعدادك؛ الخطأ الشائع هو غياب الشرطة المائلة الأخيرة

تحقق: فكّك تشفير JWT على jwt.io وقارن aud/iss

البدائل