بني بوابة OpenAPI لخدمات MCP المحلية باستعمال Open MCP Gateway

شنو هو Open MCP Gateway؟

Open MCP Gateway، اللي كيتختاصر بـ OMG، هو بوابة عالية الأداء كتعرض خدمات Model Context Protocol المنشورة محلياً عبر مسارات HTTP REST متوافقة مع OpenAPI 3.1.0. مبنية بـ Bun 1.4 وTypeScript ضمن منظومة Open WebUI، ولكنها مشروع مجتمعي وما عندها حتى علاقة رسمية بفريق Open WebUI.

البوابة كتكون بين عميل خارجي وخدمة MCP وحدة ولا أكثر. عميل بحال Open WebUI كيتواصل مع البوابة عبر HTTP ولا HTTPS، والبوابة كتدبّر وسائل النقل الأساسية ديال MCP وكتحوّل الأدوات ديالها لواجهة متوافقة مع OpenAPI.

OMG كدعم خدمات stdio الثنائية الأصلية، ومسارات stdio المبنية على سكريبتات Node ولا Bun، ووسائل النقل الشبكية SSE ولا HTTP. بهاد الطريقة يمكن توفير واجهة HTTP موحّدة لخدمات MCP اللي كتستعمل نماذج مختلفة فالتنفيذ والتواصل.

المزايا الرئيسية

• إخراج صارم وفق OpenAPI 3.1.0: مخططات إدخال الأدوات كيتحطّو تحت requestBody.content['application/json'].schema. وقيم operationId المُولّدة كتحافظ على الأسماء الأصلية ديال أدوات MCP بلا ما تزيد أسماء بحال tool_*_post.
• وسائل نقل متعددة لـ MCP: خدمات stdio الثنائية الأصلية، وstdio عبر السكريبتات، وSSE، وHTTP يمكن تدبيرها كاملة من خلال بوابة وحدة.
• مجمّع جلسات blue-green: جلسات الخدمات كتتبدّل مباشرة من ورا AsyncMutex، وهادشي كيسمح بتحديث الإعدادات بلا ما يقطع الطلبات اللي راه خدامة.
• تدبير دورة الحياة: البوابة كتوفّر تغليف البروتوكول، وإصلاح ذاتي لدورة الحياة، وإعادة تحميل فورية للخدمات المُدبّرة.
• تنظيم XDG متعدد المنصات: ملفات الإعدادات، وبيانات التطبيق، وحالة التشغيل، وملفات التخزين المؤقت كيبقاو خارج مستودع المصدر.
• بنيات مستقلة: Bun يقدر يجمّع البوابة فملف تنفيذي أصلي ما كيحتاج حتى اعتماد وقت التشغيل.
• دعم الوكيل العكسي: البوابة كتقرا رؤوس X-Forwarded-* باش يعكس servers.url المُولّد فـ OpenAPI العنوان الخارجي اللي كيشوفوه العملاء.

المتطلبات المسبقة

تشغيل المشروع من المصدر كيتطلب Bun 1.4 ولا أحدث. خاصك حتى خدمة MCP وحدة على الأقل باش تسجّلها. تقدر تكون هاد الخدمة ملفاً تنفيذياً أصلياً محلياً، ولا حزمة JavaScript أو TypeScript كتتشغّل عبر Bun، ولا خدمة MCP متوفرة عبر SSE ولا HTTP.

تثبيت وتشغيل البوابة

التشغيل من المصدر

دير clone ولا حمّل المستودع، دخل للمجلد ديالو، ثبّت الاعتماديات، وبدا أمر التطوير:

bun install
bun run dev

عملية التطوير كتقرا إعدادات البوابة من مجلد إعدادات XDG ديال المنصة، وماشي من المستودع نفسه.

بناء ملف تنفيذي مستقل

باش تنشئ ملفاً تنفيذياً أصلياً، شغّل:

bun run build

النتيجة كتتحط فـ build/mcp-gateway فالأنظمة الشبيهة بـ Unix، ولا فـ build/mcp-gateway.exe فـ Windows. الملف الثنائي المجمّع ما كيحتاجش لبيئة Bun منفصلة ملي كيتنشر.

فهم تنظيم مجلدات XDG

Open MCP Gateway كتفصل الملفات حسب الغرض ديالها. هادشي كيمنع البيانات المُولّدة، والإضافات المثبّتة، والسجلات، وملفات التخزين المؤقت من تلويث شجرة المصدر.

• الإعدادات: XDG_CONFIG_HOME فيه الملف الرئيسي mcp-gateway/config.json5.
• البيانات: XDG_DATA_HOME فيه مستودع إضافات MCP الخارجي وملف package.json ديالو.
• الحالة: XDG_STATE_HOME كيخزّن حالة التشغيل والسجلات الدائمة.
• التخزين المؤقت: XDG_CACHE_HOME كيخزّن وثائق المواصفات المخزّنة مؤقتاً وبيانات التشغيل المؤقتة.

المسار الرئيسي ديال الإعدادات هو:

$XDG_CONFIG_HOME/mcp-gateway/config.json5

الملف كيستعمل JSON5، وهادشي كيسمح بالتعليقات والفواصل الزائدة.

إعداد خدمات MCP

أنشئ مجلد الإعدادات إلا كان ضروري، ومن بعد زِد config.json5. المثال التالي كيسجّل ملفاً تنفيذياً أصلياً واحداً ديال MCP وخدمة MCP وحدة مبنية على حزمة:

{
    mcpServers: {
        // Native Binary Stdio
        codebase_memory: {
            command: "${HOME}/.local/bin/codebase-memory-mcp",
            args: [],
            env: {},
        },

        // Script Stdio
        another_mcp: {
            command: "bun",
            args: [
                "run",
                "${APP_DATA_DIR}/node_modules/<pkg>/dist/index.js",
            ],
            env: {},
        },
    },

    host: "127.0.0.1",
    port: 9090,
}

كل مفتاح داخل mcpServers كيعرّف خدمة MCP. بالنسبة لملف تنفيذي أصلي، عيّن command لمسار الملف التنفيذي. وبالنسبة لخدمة مبنية على حزمة، استعمل Bun كأمر ومرّر مسار السكريبت المثبّت عبر args. تقدر تزيد متغيرات البيئة الخاصة بالخدمة داخل env.

البوابة كتدعم إدماج متغيرات البيئة فالمسارات. المتغيرات كتضم ${APP_DATA_DIR} و${XDG_DATA_HOME} و${HOME} و%USERPROFILE%. الإدماج كيخلّي الإعدادات أسهل فإعادة الاستعمال بين الحواسيب بلا ما تكتب كل مسار مطلق بشكل ثابت.

خلي معرّف الخدمة ثابت. مثلاً، خدمة سميتها codebase_memory كتتعرض تحت مسار URL المطابق اللي كيتستعمل ملي كتجيب وثيقة OpenAPI ديالها.

تدبير إضافات MCP الخارجية

حزم MCP الخاصة بالأعمال ما خاصهاش تتركّب داخل مستودع البوابة. ثبّتها ودبّرها فمجلد بيانات XDG ديال البوابة بدلاً من ذلك:

cd "$XDG_DATA_HOME/mcp-gateway"
bun add <mcp-package-name>

باش تحدّث حزمة مثبّتة، شغّل:

cd "$XDG_DATA_HOME/mcp-gateway"
bun update <pkg>

من بعد التثبيت، أشر لنقطة الدخول ديال الحزمة من config.json5 باستعمال ${APP_DATA_DIR}، كيفما مبين فمثال stdio ديال السكريبت. بهاد الطريقة كتبقى اعتماديات الـgateway مفصولة على اعتماديات إضافات MCP.

الاستعمال الأساسي

1. ثبّت اعتماديات الـgateway ولا بنِ الملف التنفيذي الأصلي.

2. أنشئ $XDG_CONFIG_HOME/mcp-gateway/config.json5.

3. زِد خدمة ولا كثر تحت mcpServers.

4. شغّل الـgateway بـ bun run dev ولا طلّق الملف التنفيذي المجمّع.

5. جيب وثيقة OpenAPI ديال الخدمة المكوّنة وسجّلها عند العميل الخارجي ديالك.

بالنسبة لخدمة سميتها codebase_memory، النمط الموثّق ديال رابط OpenAPI هو:

http://<gateway-host>:8444/codebase_memory/openapi.json

فهاد المثال، 8444 هو البورت اللي كيمكن الولوج ليه من الخارج. يقدر يكون بورت ديال reverse proxy وماشي البورت الداخلي ديال الـgateway، بحال 9090 فمثال الإعدادات.

الدمج مع Open WebUI

يقدر reverse proxy بحال Caddy ولا Nginx يعرّض الـgateway على الـhost والبورت والبروتوكول الخارجيين اللي بغيتي. كوّن الـproxy باش يصيفط headers المناسبة ديال X-Forwarded-*. Open MCP Gateway كيقرا هاد headers ملي كيولّد وثيقة OpenAPI، وكيضمن أن servers.url كيشير للعنوان العمومي وماشي للـlistener الداخلي.

1. شغّل Open MCP Gateway من ورا reverse proxy.

2. حلّ لوحة إدارة Open WebUI.

3. مشي لقسم Functions ولا Tools ولا OpenAPI.

4. سجّل رابط وثيقة OpenAPI ديال كل خدمة MCP مكوّنة:

   http://<gateway-host>:8444/codebase_memory/openapi.json

5. سمح لـOpen WebUI يحمّل المواصفات. من بعد، تقدر تستعمل أدوات خدمة MCP كأدوات أصلية عبر عمليات OpenAPI المتولّدة.

حيت معرّفات العمليات كتحافظ على السميات الأصلية ديال أدوات MCP، كيشفو العملاء معرّفات واضحة للأدوات بلا لواحق ولا سوابق كيولّدها الـgateway.

الاختبار ومراقبة السجلات

شغّل أمر الاختبار ديال المشروع من بعد أي تغيير فالـgateway ولا فالإعدادات ديالو:

bun run test

فـWindows، المستودع كيوفّر حتى سكريبت اختبار ديال PowerShell:

.\ps1_scripts\test-gateway.ps1

اختبارات النهاية للنهاية كتشمل التحقق من الصحة، وMCP handshake، وتطابق أصل الـproxy.

فالأنظمة الشبيهة بـUnix، تبّع سجل الـgateway المستمر بهاد الأمر:

tail -f "$XDG_STATE_HOME/mcp-gateway/logs/gateway.log"

هاد الشي مفيد ملي كتقلب على مشاكل إقلاع العملية، ولا مسارات تنفيذية غير صحيحة، ولا فشل فـMCP handshake، ولا مشاكل فإعدادات reverse proxy.

نصائح متقدمة

استعمل مسارات قابلة للنقل

فضّل المسارات المدموجة بحال ${HOME} و${APP_DATA_DIR} على المسارات المطلقة المرتابطة بجهاز معيّن. فـWindows، تقدر تستعمل %USERPROFILE% ملي يكون مناسب. هاد الشي كيسهّل مشاركة الإعدادات بين الأنظمة.

خلّي الإضافات برا نسخة المصدر

ثبّت حزم MCP الخارجية فـ$XDG_DATA_HOME/mcp-gateway. بهاد الطريقة كيبقى شجر المصدر نقي، وكيقدرو الـgateway والإضافات العملية ديالو يترقّاو كل واحد بوحدو.

فرّق بين العناوين الداخلية والخارجية

ربط الـgateway بـ127.0.0.1 كيخلي الـlistener الداخلي محلي. ومن بعد يقدر reverse proxy يوفّر نقطة النهاية الخارجية ديال TLS. تأكد باللي الـheaders المحوّلة كتوصف الـscheme والـhost والبورت العموميين، باش وثائق OpenAPI المتولّدة تعلن على الرابط الصحيح.

استافد من التحديثات الفورية

مجموعة الجلسات blue-green كبدّل جلسات الخدمات، وكتحمي الانتقال باستعمال AsyncMutex. هاد التصميم كيسمح بتحديثات الإعدادات بلا ما يقطع الطلبات اللي راه خدامة. وإعادة التحميل الفورية والإصلاح الذاتي لدورة الحياة كينقصو حتى هما الحاجة للتدبير اليدوي للعمليات.

جمّع النشر

استعمل bun run build ملي ما خاصش الخادم الهدف يكون فيه Bun ولا اعتماديات المشروع منصّبة. نشّر الملف التنفيذي المتولّد مع إعدادات XDG المطلوبة وأي ملفات تنفيذية ولا حزم MCP كتتدار بشكل منفصل.

الخلاصة

Open MCP Gateway كيوفّر جسر موحّد من خدمات MCP المحلية لمسارات OpenAPI 3.1.0 صارمة. بدمج دعم عدة وسائل نقل، وإعدادات محمولة مبنية على XDG، وتدبير الإضافات الخارجية، والوعي بالـreverse proxy، والبنيات المستقلة، كيوفّر طريقة عملية باش تولّي أدوات MCP المحلية متاحة لـOpen WebUI ولعملاء آخرين كيدعمو OpenAPI.