Yakha Isango le-OpenAPI Lezinsizakalo ze-MCP Zasendaweni usebenzisa i-Open MCP Gateway

Yini i-Open MCP Gateway?

i-Open MCP Gateway, efushaniswa ngokuthi OMG, iyi-gateway esebenza kahle kakhulu eveza izinsiza ze-Model Context Protocol ezisetshenziswe endaweni ngama-route e-HTTP REST ahambisana ne-OpenAPI 3.1.0. Yakhiwe nge-Bun 1.4 ne-TypeScript ukuze isetshenziswe ku-ecosystem ye-Open WebUI, nakuba iwumsebenzi womphakathi futhi ingahlangene nethimba le-Open WebUI.

I-gateway iphakathi kweklayenti langaphandle nesevisi eyodwa noma eziningi ze-MCP. Iklayenti elifana ne-Open WebUI lixhumana ne-gateway nge-HTTP noma i-HTTPS, kanti i-gateway ilawula ama-transport e-MCP angaphansi futhi iguqule amathuluzi awo abe yi-interface ehambisana ne-OpenAPI.

I-OMG isekela izinsiza zomdabu ze-binary stdio, amapayipi e-stdio asebenzisa izikripthi ze-Node noma i-Bun, kanye nama-transport enethiwekhi e-SSE noma e-HTTP. Lokhu kwenza kube nokwenzeka ukuhlinzeka nge-interface ye-HTTP engaguquki yezinsiza ze-MCP ezisebenzisa amamodeli ahlukene okusebenza nokuxhumana.

Izici Eziyinhloko

• Okukhiphayo okuqinile kwe-OpenAPI 3.1.0: Ama-schema okufaka amathuluzi afakwa ngaphansi kwe-requestBody.content['application/json'].schema. Amanani akhiqiziwe e-operationId agcina amagama amathuluzi e-MCP okuqala esikhundleni sokwengeza amagama afana ne-tool_*_post.
• Ama-transport e-MCP amaningi: Izinsiza zomdabu ze-binary stdio, i-script stdio, i-SSE, ne-HTTP zingalawulwa nge-gateway eyodwa.
• Ichibi leseshini ye-blue-green: Amaseshini ezinsiza ashintshaniswa ngokushesha ngaphansi kwe-AsyncMutex, okuvumela ukubuyekezwa kokucushwa ngaphandle kokuphazamisa izicelo eseziqhubeka.
• Ukuphathwa komjikelezo wokuphila: I-gateway ihlinzeka ngokusongelwa kwephrothokholi, ukuzilungisa komjikelezo wokuphila, kanye nokulayisha kabusha okusheshayo kwezinsiza ezilawulwayo.
• Isakhiwo se-XDG esisebenza ezinkundleni eziningi: Amafayela okucushwa, idatha yohlelo, isimo sesikhathi sokusebenza, nama-cache agcinwa ngaphandle kwe-source repository.
• Ukwakhiwa okuzimele: I-Bun ingahlanganisa i-gateway ibe yi-executable yomdabu engenazo izidingo zesikhathi sokusebenza.
• Ukusekelwa kwe-reverse proxy: I-gateway ifunda ama-header e-X-Forwarded-* ukuze i-OpenAPI servers.url ekhiqiziwe ibonise ikheli langaphandle elibonwa amaklayenti.

Izidingo Zokuqala

Ukuqhuba iphrojekthi kusuka ku-source kudinga i-Bun 1.4 noma eyakamuva. Udinga futhi okungenani insizakalo eyodwa ye-MCP ozoyibhalisa. Leyo nsizakalo ingaba yi-executable yomdabu yasendaweni, iphakheji ye-JavaScript noma i-TypeScript eqaliswa nge-Bun, noma insizakalo ye-MCP etholakala nge-SSE noma i-HTTP.

Faka Futhi Uqalise I-Gateway

Qalisa kusuka ku-source

Clone noma landa i-repository, ngena ku-directory yayo, faka ama-dependency ayo, bese uqala umyalo wokuthuthukisa:

bun install
bun run dev

Inqubo yokuthuthukisa ifunda ukucushwa kwe-gateway ku-directory yokucushwa ye-XDG yesikhulumi esikhundleni se-repository uqobo.

Yakha i-executable ezimele

Ukuze wakhe i-executable yomdabu, sebenzisa:

bun run build

Okukhiphayo kubhalwa ku-build/mcp-gateway ezinhlelweni ezifana ne-Unix noma ku-build/mcp-gateway.exe ku-Windows. I-binary ehlanganisiwe ayidingi i-Bun runtime ehlukile uma isetshenziswa.

Qonda Isakhiwo Sama-Directory e-XDG

i-Open MCP Gateway ihlukanisa amafayela ngokwenhloso. Lokhu kuvimbela idatha ekhiqiziwe, ama-plugin afakiwe, ama-log, nama-cache ekungcoliseni i-source tree.

• Ukucushwa: XDG_CONFIG_HOME iqukethe ifayela eliyinhloko elithi mcp-gateway/config.json5.
• Idatha: XDG_DATA_HOME iqukethe i-external MCP plugin repository kanye ne-package.json yayo.
• Isimo: XDG_STATE_HOME igcina isimo sesikhathi sokusebenza nama-log aqhubekayo.
• I-Cache: XDG_CACHE_HOME igcina amadokhumenti e-specification agciniwe kanye nedatha yesikhashana yesikhathi sokusebenza.

Indlela eyinhloko yokucushwa ithi:

$XDG_CONFIG_HOME/mcp-gateway/config.json5

Ifayela lisebenzisa i-JSON5, ngakho amazwana namakhoma okugcina kuyasekelwa.

Hlela Izinsiza ze-MCP

Dala i-directory yokucushwa uma kudingeka, bese wengeza i-config.json5. Isibonelo esilandelayo sibhalisa i-executable eyodwa yomdabu ye-MCP kanye nesevisi eyodwa ye-MCP esekelwe kuphakheji:

{
    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,
}

Ukhiye ngamunye ongaphakathi kwe-mcpServers ukhomba insizakalo ye-MCP. Ku-binary yomdabu, setha i-command ibe yindlela ye-executable. Ensizakalweni esekelwe kuphakheji, sebenzisa i-Bun njengomyalo bese udlulisa indlela yeskripthi efakiwe nge-args. Okuguquguqukayo kwemvelo okuqondene nesevisi kungangezwa ku-env.

I-gateway isekela ukufakwa kwamaguquguquki emvelo ezindleleni. Amaguquguquki afaka i-${APP_DATA_DIR}, i-${XDG_DATA_HOME}, i-${HOME}, kanye ne-%USERPROFILE%. Lokhu kufakwa kwenza ukucushwa kube lula ukukusebenzisa kabusha kumakhompyutha ahlukene ngaphandle kokubhala ngokuqondile yonke indlela ephelele.

Gcina isihlonzi sesevisi singashintshi. Isibonelo, isevisi ebizwa ngokuthi codebase_memory ivezwa ngaphansi kwendlela ye-URL ehambisanayo esetshenziswa lapho kutholwa idokhumenti yayo ye-OpenAPI.

Phatha Ama-Plugin Angaphandle e-MCP

Amaphakheji e-MCP aqondene nezidingo zebhizinisi akufanele afakwe ku-gateway repository. Wafake futhi uwagcine ku-XDG data directory ye-gateway esikhundleni salokho:

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

Ukuze uthuthukise iphakheji efakiwe, sebenzisa:

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

Ngemva kokufakwa, bhekisa endaweni yokuqala yephakheji kusuka ku-config.json5 usebenzisa i-${APP_DATA_DIR}, njengoba kuboniswe esibonelweni se-script stdio. Lokhu kugcina okuncike ku-gateway kuhlukene nokuncika kwezandiso ze-MCP.

Ukusetshenziswa Okuyisisekelo

1. Faka okuncike ku-gateway noma wakhe ifayela elisebenzisekayo le-native.

2. Dala i-$XDG_CONFIG_HOME/mcp-gateway/config.json5.

3. Engeza isevisi eyodwa noma eziningi ngaphansi kwe-mcpServers.

4. Qalisa i-gateway nge-bun run dev noma uqalise ifayela elisebenzisekayo elihlanganisiwe.

5. Thola idokhumenti ye-OpenAPI yesevisi ehleliwe bese uyibhalisa neklayenti lakho langaphandle.

Ngenkonzo ebizwa ngokuthi codebase_memory, iphethini ye-URL ye-OpenAPI ebhaliwe ithi:

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

Kulesi sibonelo, i-8444 iyiphothi efinyeleleka ngaphandle. Ingaba yiphothi ye-reverse proxy esikhundleni sephothi yangaphakathi ye-gateway, efana ne-9090 esibonelweni sokumiswa.

Hlanganisa ne-Open WebUI

I-reverse proxy efana ne-Caddy noma i-Nginx ingadalula i-gateway nge-host, iphothe, nephrothokholi yangaphandle oyifunayo. Lungiselela i-proxy ukuthi ithumele ama-header afanele e-X-Forwarded-*. I-Open MCP Gateway ifunda lawa ma-header lapho ikhiqiza idokhumenti ye-OpenAPI, iqinisekise ukuthi i-servers.url ikhomba ekhelini lomphakathi esikhundleni somlaleli wangaphakathi.

1. Qalisa i-Open MCP Gateway ngemuva kwe-reverse proxy.

2. Vula iphaneli yokuphatha ye-Open WebUI.

3. Yiya endaweni ye-Functions, Tools, noma ye-OpenAPI.

4. Bhalisa i-URL yedokhumenti ye-OpenAPI yesevisi ngayinye ye-MCP ehleliwe:

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

5. Vumela i-Open WebUI ukuthi ilayishe incazelo. Amathuluzi esevisi ye-MCP angasetshenziswa njengamathuluzi omdabu ngokusebenzisa imisebenzi ye-OpenAPI ekhiqiziwe.

Ngenxa yokuthi ama-ID emisebenzi agcina amagama amathuluzi okuqala e-MCP, amaklayenti abona izihlonzi zamathuluzi ezihlanzekile ezingenazo izijobelelo noma iziqalo ezikhiqizwe yi-gateway.

Ukuhlola Nokulandelela Amalogi

Qalisa umyalo wokuhlola wephrojekthi ngemva kokushintsha i-gateway noma ukumiswa kwayo:

bun run test

Kuma-Windows, indawo yokugcina inikeza neskripthi sokuhlola se-PowerShell:

.\ps1_scripts\test-gateway.ps1

Ukuqinisekiswa kokuphela kuya ekupheleni kuhlanganisa ukuhlolwa kwempilo, ukuxhawulana kwe-MCP, nokuhambisana kwemvelaphi ye-proxy.

Kumasistimu afana ne-Unix, landela ilogi eqhubekayo ye-gateway nge:

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

Lokhu kuyasiza lapho uhlonza izinkinga zokuqalisa inqubo, izindlela zamafayela asebenzisekayo ezingavumelekile, ukwehluleka kokuxhawulana kwe-MCP, noma izinkinga zokumiswa kwe-reverse proxy.

Izeluleko Ezithuthukile

Sebenzisa izindlela eziphathwayo

Khetha izindlela ezihunyushwayo ezifana ne-${HOME} kanye ne-${APP_DATA_DIR} esikhundleni sezindlela eziphelele eziqondene nomshini. Ku-Windows, i-%USERPROFILE% ingasetshenziswa lapho kufanele khona. Lokhu kwenza kube lula ukwabelana ngokumiswa phakathi kwezinhlelo ezahlukene.

Gcina ama-plugin ngaphandle kwe-source checkout

Faka amaphakheji angaphandle e-MCP ku-$XDG_DATA_HOME/mcp-gateway. Lokhu kugcina isihlahla somthombo sihlanzekile futhi kuvumela i-gateway nezandiso zayo zebhizinisi ukuthi zithuthukiswe ngokuzimela.

Hlukanisa amakheli angaphakathi nangaphandle

Ukubopha i-gateway ku-127.0.0.1 kugcina umlaleli wangaphakathi usemshinini wendawo. I-reverse proxy ingabe isinikeza indawo yangaphandle ye-TLS. Qinisekisa ukuthi ama-header adlulisiwe achaza i-scheme, i-host, nephothi yomphakathi ukuze amadokhumenti e-OpenAPI akhiqiziwe amemezele i-URL efanele.

Zuza ezibuyekezweni ezisheshayo

Ichibi leseshini ye-blue-green lishintshanisa amasessioni esevisi ngenkathi livikela ushintsho nge-AsyncMutex. Lo mklamo uvumela izibuyekezo zokumiswa ngaphandle kokuqeda izicelo esezisebenza. Ukulayisha kabusha ngokushesha nokuzilungisa komjikelezo wokuphila kunciphisa futhi isidingo sokuphathwa kwezinqubo ngesandla.

Hlanganisela ukuthunyelwa

Sebenzisa i-bun run build lapho iseva eqondiwe kungafanele idinge i-Bun noma okuncike kuphrojekthi okufakiwe. Thumela ifayela elisebenzisekayo elikhiqiziwe kanye nokumiswa okudingekayo kwe-XDG nanoma yimaphi ama-binary noma amaphakheji e-MCP aphathwa ngokuhlukile.

Isiphetho

I-Open MCP Gateway inikeza ibhuloho elihlanganisiwe elisuka kumasevisi e-MCP endawo liye emizileni eqinile ye-OpenAPI 3.1.0. Ngokuhlanganisa ukusekelwa kwezithuthi eziningi, ukumiswa okuphathekayo okusekelwe ku-XDG, ukuphathwa kwama-plugin angaphandle, ukuqaphela i-reverse proxy, nokwakhiwa okuzimele, inikeza indlela esebenzayo yokwenza amathuluzi e-MCP endawo atholakale ku-Open WebUI nakwamanye amaklayenti akwazi ukusebenzisa i-OpenAPI.