Open MCP Gateway yordamida mahalliy MCP xizmatlari uchun OpenAPI shlyuzini yarating

Open MCP Gateway nima?

Open MCP Gateway, qisqacha OMG, mahalliy joylashtirilgan Model Context Protocol xizmatlarini OpenAPI 3.1.0 standartiga mos HTTP REST yo‘llari orqali taqdim etuvchi yuqori unumdor gateway hisoblanadi. U Open WebUI ekotizimi uchun Bun 1.4 va TypeScript yordamida yaratilgan. Biroq bu hamjamiyat loyihasi bo‘lib, Open WebUI jamoasi bilan bog‘liq emas.

Gateway tashqi mijoz va bir yoki bir nechta MCP xizmati o‘rtasida joylashadi. Open WebUI kabi mijoz gateway bilan HTTP yoki HTTPS orqali aloqa qiladi, gateway esa asosiy MCP transportlarini boshqaradi va ularning vositalarini OpenAPI bilan mos interfeysga aylantiradi.

OMG native binary stdio xizmatlarini, Node yoki Bun skriptlariga asoslangan stdio quvurlarini, shuningdek SSE yoki HTTP tarmoq transportlarini qo‘llab-quvvatlaydi. Bu turli bajarilish va aloqa modellaridan foydalanadigan MCP xizmatlari uchun yagona HTTP interfeysini taqdim etish imkonini beradi.

Asosiy imkoniyatlar

• Qat’iy OpenAPI 3.1.0 chiqishi: Vosita kiritish sxemalari requestBody.content['application/json'].schema ostida joylashtiriladi. Yaratilgan operationId qiymatlari tool_*_post kabi nomlar qo‘shish o‘rniga original MCP vosita nomlarini saqlab qoladi.
• Bir nechta MCP transportlari: Native binary stdio, skript stdio, SSE va HTTP xizmatlarini bitta gateway orqali boshqarish mumkin.
• Blue-green sessiyalar havzasi: Xizmat sessiyalari AsyncMutex ortida issiq almashtiriladi, bu esa jarayonda bo‘lgan so‘rovlarni to‘xtatmasdan konfiguratsiyani yangilash imkonini beradi.
• Hayotiy siklni boshqarish: Gateway protokolni o‘rash, hayotiy siklni o‘z-o‘zini tiklash va boshqariladigan xizmatlarni issiq qayta yuklash imkoniyatlarini taqdim etadi.
• Platformalararo XDG tuzilmasi: Konfiguratsiya, ilova ma’lumotlari, bajarilish holati va kesh fayllari manba repozitoriysidan tashqarida saqlanadi.
• Mustaqil yig‘ilmalar: Bun gateway’ni bajarilish muhitiga bog‘liq bo‘lmagan native bajariladigan faylga kompilyatsiya qilishi mumkin.
• Reverse-proxy qo‘llab-quvvatlovi: Gateway X-Forwarded-* sarlavhalarini o‘qiydi, shuning uchun yaratilgan OpenAPI servers.url mijozlar ko‘radigan tashqi manzilni aks ettiradi.

Talablar

Loyihani manba kodidan ishga tushirish uchun Bun 1.4 yoki undan keyingi versiyasi kerak. Shuningdek, ro‘yxatdan o‘tkazish uchun kamida bitta MCP xizmati bo‘lishi lozim. Bu mahalliy native bajariladigan fayl, Bun orqali ishga tushiriladigan JavaScript yoki TypeScript paketi yoxud SSE yoki HTTP orqali mavjud MCP xizmati bo‘lishi mumkin.

Gateway’ni o‘rnatish va ishga tushirish

Manba kodidan ishga tushirish

Repozitoriyni klonlang yoki yuklab oling, uning katalogiga kiring, bog‘liqliklarini o‘rnating va ishlab chiqish buyrug‘ini ishga tushiring:

bun install
bun run dev

Ishlab chiqish jarayoni gateway konfiguratsiyasini repozitoriyning o‘zidan emas, platformaning XDG konfiguratsiya katalogidan o‘qiydi.

Mustaqil bajariladigan fayl yaratish

Native bajariladigan fayl yaratish uchun quyidagini ishga tushiring:

bun run build

Natija Unix’ga o‘xshash tizimlarda build/mcp-gateway yoki Windows’da build/mcp-gateway.exe manziliga yoziladi. Joylashtirilganda kompilyatsiya qilingan binary alohida Bun bajarilish muhitini talab qilmaydi.

XDG katalog tuzilmasini tushunish

Open MCP Gateway fayllarni maqsadiga ko‘ra ajratadi. Bu yaratilgan ma’lumotlar, o‘rnatilgan plaginlar, jurnallar va keshlar manba daraxtini ifloslantirishining oldini oladi.

• Konfiguratsiya: XDG_CONFIG_HOME asosiy mcp-gateway/config.json5 faylini o‘z ichiga oladi.
• Ma’lumotlar: XDG_DATA_HOME tashqi MCP plaginlar repozitoriysi va uning package.json faylini o‘z ichiga oladi.
• Holat: XDG_STATE_HOME bajarilish holati va doimiy jurnallarni saqlaydi.
• Kesh: XDG_CACHE_HOME spetsifikatsiya hujjatlarining keshlangan nusxalari va vaqtinchalik bajarilish ma’lumotlarini saqlaydi.

Asosiy konfiguratsiya yo‘li:

$XDG_CONFIG_HOME/mcp-gateway/config.json5

Fayl JSON5 formatidan foydalanadi, shuning uchun izohlar va oxirgi vergullardan foydalanish mumkin.

MCP xizmatlarini sozlash

Zarur bo‘lsa, konfiguratsiya katalogini yarating, so‘ng config.json5 faylini qo‘shing. Quyidagi misolda bitta native MCP bajariladigan fayli va bitta paketga asoslangan MCP xizmati ro‘yxatdan o‘tkaziladi:

{
    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 ichidagi har bir kalit MCP xizmatini identifikatsiya qiladi. Native binary uchun command qiymatini bajariladigan fayl yo‘liga o‘rnating. Paketga asoslangan xizmat uchun buyruq sifatida Bun’dan foydalaning va o‘rnatilgan skript yo‘lini args orqali uzating. Xizmatga xos muhit o‘zgaruvchilarini env ga qo‘shish mumkin.

Gateway yo‘llarda muhit o‘zgaruvchilarini interpolatsiya qilishni qo‘llab-quvvatlaydi. O‘zgaruvchilar qatoriga ${APP_DATA_DIR}, ${XDG_DATA_HOME}, ${HOME} va %USERPROFILE% kiradi. Interpolatsiya har bir mutlaq yo‘lni qattiq kodlamasdan, konfiguratsiyani turli kompyuterlarda qayta ishlatishni osonlashtiradi.

Xizmat identifikatorini barqaror saqlang. Masalan, codebase_memory nomli xizmat uning OpenAPI hujjatini olishda ishlatiladigan mos URL yo‘li orqali taqdim etiladi.

Tashqi MCP plaginlarini boshqarish

Biznesga xos MCP paketlari gateway repozitoriysiga o‘rnatilmasligi kerak. Ularni gateway’ning XDG ma’lumotlar katalogiga o‘rnating va shu yerda boshqaring:

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

O‘rnatilgan paketni yangilash uchun quyidagini ishga tushiring:

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

O‘rnatilgandan so‘ng, skriptdagi stdio misolida ko‘rsatilganidek, ${APP_DATA_DIR} yordamida config.json5 faylida paketning kirish nuqtasiga murojaat qiling. Bu gateway bog‘liqliklarini MCP kengaytmalari bog‘liqliklaridan alohida saqlaydi.

Asosiy foydalanish

1. Gateway bog‘liqliklarini o‘rnating yoki native bajariladigan faylni yarating.

2. $XDG_CONFIG_HOME/mcp-gateway/config.json5 faylini yarating.

3. mcpServers ostida bir yoki bir nechta xizmat qo‘shing.

4. Gateway’ni bun run dev bilan ishga tushiring yoki kompilyatsiya qilingan bajariladigan faylni ishga tushiring.

5. Sozlangan xizmat uchun OpenAPI hujjatini oling va uni tashqi mijozingizda ro‘yxatdan o‘tkazing.

codebase_memory nomli xizmat uchun hujjatlashtirilgan OpenAPI URL andozasi quyidagicha:

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

Bu misolda 8444 tashqaridan foydalanish mumkin bo‘lgan portdir. U konfiguratsiya misolidagi 9090 kabi gateway’ning ichki porti emas, reverse-proxy porti bo‘lishi mumkin.

Open WebUI bilan integratsiya

Caddy yoki Nginx kabi reverse proxy gateway’ni kerakli tashqi host, port va protokol orqali ochib berishi mumkin. Proksini mos X-Forwarded-* sarlavhalarini yuboradigan qilib sozlang. Open MCP Gateway OpenAPI hujjatini yaratishda ushbu sarlavhalarni o‘qiydi va uning servers.url qiymati ichki tinglovchi manziliga emas, ommaviy manzilga yo‘naltirilishini ta’minlaydi.

1. Open MCP Gateway’ni reverse proxy ortida ishga tushiring.

2. Open WebUI ma’muriyat panelini oching.

3. Functions, Tools yoki OpenAPI bo‘limiga o‘ting.

4. Har bir sozlangan MCP xizmati uchun OpenAPI hujjati URL manzilini ro‘yxatdan o‘tkazing:

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

5. Open WebUI’ga spetsifikatsiyani yuklashga ruxsat bering. Shundan so‘ng MCP xizmati vositalaridan yaratilgan OpenAPI operatsiyalari orqali native vositalar sifatida foydalanish mumkin.

Operatsiya identifikatorlari asl MCP vositalari nomlarini saqlab qolgani sababli, mijozlar gateway tomonidan yaratilgan qo‘shimcha suffiks yoki prefikslarsiz, tartibli vosita identifikatorlarini ko‘radi.

Testlash va jurnat monitoringi

Gateway yoki uning konfiguratsiyasini o‘zgartirgandan so‘ng loyiha test buyrug‘ini ishga tushiring:

bun run test

Windows’da repository PowerShell test skriptini ham taqdim etadi:

.\ps1_scripts\test-gateway.ps1

End-to-end tekshiruvlar health check, MCP handshake va proksi manbasi mosligini qamrab oladi.

Unix’ga o‘xshash tizimlarda doimiy gateway jurnalini quyidagi buyruq bilan kuzating:

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

Bu jarayonni ishga tushirish muammolari, noto‘g‘ri bajariladigan fayl yo‘llari, MCP handshake xatolari yoki reverse-proxy konfiguratsiyasi muammolarini aniqlashda foydalidir.

Kengaytirilgan maslahatlar

Portativ yo‘llardan foydalaning

Muayyan kompyuterga bog‘langan mutlaq yo‘llar o‘rniga ${HOME} va ${APP_DATA_DIR} kabi interpolatsiya qilinadigan yo‘llardan foydalaning. Windows’da tegishli hollarda %USERPROFILE% dan foydalanish mumkin. Bu konfiguratsiyani turli tizimlar o‘rtasida ulashishni osonlashtiradi.

Plaginlarni manba nusxasidan tashqarida saqlang

Tashqi MCP paketlarini $XDG_DATA_HOME/mcp-gateway ichiga o‘rnating. Bu manba daraxtini toza saqlaydi va gateway hamda uning biznes kengaytmalarini mustaqil ravishda yangilash imkonini beradi.

Ichki va tashqi manzillarni ajrating

Gateway’ni 127.0.0.1 manziliga bog‘lash ichki tinglovchini lokal saqlaydi. Shundan so‘ng reverse proxy tashqi TLS endpointini taqdim etishi mumkin. Yaratilgan OpenAPI hujjatlari to‘g‘ri URL manzilini ko‘rsatishi uchun uzatiladigan sarlavhalar ommaviy sxema, host va portni tavsiflashiga ishonch hosil qiling.

Issiq yangilanishlardan foydalaning

Blue-green sessiyalar havzasi xizmat sessiyalarini almashtiradi va o‘tish jarayonini AsyncMutex yordamida himoya qiladi. Bu dizayn allaqachon ishlayotgan so‘rovlarni to‘xtatmasdan konfiguratsiyani yangilash imkonini beradi. Issiq qayta yuklash va hayotiy siklni o‘z-o‘zini tiklash imkoniyatlari jarayonlarni qo‘lda boshqarish ehtiyojini yanada kamaytiradi.

Joylashtirish uchun kompilyatsiya qiling

Maqsadli serverda Bun yoki loyiha bog‘liqliklarini o‘rnatish talab qilinmasligi kerak bo‘lsa, bun run build dan foydalaning. Yaratilgan bajariladigan faylni kerakli XDG konfiguratsiyasi hamda alohida boshqariladigan MCP binarlari yoki paketlari bilan birga joylashtiring.

Xulosa

Open MCP Gateway lokal MCP xizmatlaridan qat’iy OpenAPI 3.1.0 yo‘llariga yagona ko‘prikni taqdim etadi. U ko‘p transportli qo‘llab-quvvatlash, portativ XDG asosidagi konfiguratsiya, tashqi plaginlarni boshqarish, reverse-proxy xabardorligi va mustaqil build’larni birlashtirib, lokal MCP vositalarini Open WebUI hamda OpenAPI’ni qo‘llab-quvvatlaydigan boshqa mijozlarga taqdim etishning amaliy usulini taklif qiladi.