Jenga Lango la OpenAPI kwa Huduma za Ndani za MCP ukitumia Open MCP Gateway

Open MCP Gateway ni Nini?

Open MCP Gateway, kwa kifupi OMG, ni gateway yenye utendaji wa juu inayowasilisha huduma za Model Context Protocol zilizowekwa ndani ya kifaa kupitia njia za HTTP REST zinazofuata OpenAPI 3.1.0. Imeundwa kwa Bun 1.4 na TypeScript kwa ajili ya mfumo wa Open WebUI, ingawa ni mradi wa jamii na hauhusiani rasmi na timu ya Open WebUI.

Gateway hii hukaa kati ya mteja wa nje na huduma moja au zaidi za MCP. Mteja kama Open WebUI huwasiliana na gateway kupitia HTTP au HTTPS, huku gateway ikisimamia usafirishaji wa MCP wa msingi na kubadilisha zana zake kuwa kiolesura kinachooana na OpenAPI.

OMG inasaidia huduma za asili za stdio za binary, mabomba ya stdio yanayotumia skripti za Node au Bun, pamoja na usafirishaji wa mtandao wa SSE au HTTP. Hii huwezesha kutoa kiolesura thabiti cha HTTP kwa huduma za MCP zinazotumia miundo tofauti ya utekelezaji na mawasiliano.

Vipengele Muhimu

• Matokeo madhubuti ya OpenAPI 3.1.0: Mifumo ya ingizo ya zana huwekwa chini ya requestBody.content['application/json'].schema. Thamani zinazozalishwa za operationId huhifadhi majina ya awali ya zana za MCP badala ya kuongeza majina kama tool_*_post.
• Usafirishaji mwingi wa MCP: Huduma za stdio za binary za asili, stdio za skripti, SSE na HTTP zinaweza kusimamiwa kupitia gateway moja.
• Pool ya vipindi ya blue-green: Vipindi vya huduma hubadilishwa moja kwa moja nyuma ya AsyncMutex, hivyo kuruhusu masasisho ya usanidi bila kukatiza maombi ambayo tayari yanaendelea.
• Usimamizi wa mzunguko wa maisha: Gateway hutoa ufungaji wa itifaki, kujirekebisha kwa mzunguko wa maisha, na upakiaji upya wa moja kwa moja kwa huduma zinazosimamiwa.
• Muundo wa XDG wa majukwaa mbalimbali: Faili za usanidi, data ya programu, hali ya wakati wa utekelezaji na akiba huwekwa nje ya hazina ya chanzo.
• Miundo inayojitegemea: Bun inaweza kukusanya gateway kuwa faili la asili linaloweza kutekelezwa bila utegemezi wa wakati wa utekelezaji.
• Usaidizi wa reverse proxy: Gateway husoma vichwa vya X-Forwarded-* ili servers.url ya OpenAPI inayozalishwa iakisi anwani ya nje inayoonekana na wateja.

Mahitaji ya Awali

Kuendesha mradi kutoka kwenye chanzo kunahitaji Bun 1.4 au toleo jipya zaidi. Pia unahitaji angalau huduma moja ya MCP ya kusajili. Huduma hiyo inaweza kuwa faili la asili linaloweza kutekelezwa ndani ya kifaa, kifurushi cha JavaScript au TypeScript kinachoanzishwa kupitia Bun, au huduma ya MCP inayopatikana kupitia SSE au HTTP.

Sakinisha na Uendeshe Gateway

Endesha kutoka kwenye chanzo

Clone au pakua hazina, ingia kwenye saraka yake, sakinisha vitegemezi vyake, kisha uanze amri ya uendelezaji:

bun install
bun run dev

Mchakato wa uendelezaji husoma usanidi wa gateway kutoka kwenye saraka ya usanidi ya XDG ya jukwaa badala ya hazina yenyewe.

Unda faili la asili linaloweza kutekelezwa

Ili kuunda faili la asili linaloweza kutekelezwa, endesha:

bun run build

Matokeo huandikwa kwenye build/mcp-gateway kwenye mifumo inayofanana na Unix au build/mcp-gateway.exe kwenye Windows. Faili la binary lililokusanywa halihitaji wakati tofauti wa utekelezaji wa Bun linapotumwa.

Elewa Muundo wa Saraka za XDG

Open MCP Gateway hutenganisha faili kulingana na madhumuni. Hii huzuia data inayozalishwa, programu-jalizi zilizosakinishwa, kumbukumbu na akiba kuchafua mti wa chanzo.

• Usanidi: XDG_CONFIG_HOME huwa na faili kuu la mcp-gateway/config.json5.
• Data: XDG_DATA_HOME huwa na hazina ya nje ya programu-jalizi za MCP pamoja na package.json yake.
• Hali: XDG_STATE_HOME huhifadhi hali ya wakati wa utekelezaji na kumbukumbu zinazoendelea.
• Akiba: XDG_CACHE_HOME huhifadhi hati za vipimo zilizowekwa akiba na data ya muda ya wakati wa utekelezaji.

Njia kuu ya usanidi ni:

$XDG_CONFIG_HOME/mcp-gateway/config.json5

Faili hili hutumia JSON5, hivyo maoni na koma za mwisho zinaungwa mkono.

Sanidi Huduma za MCP

Unda saraka ya usanidi ikiwa ni lazima, kisha ongeza config.json5. Mfano ufuatao husajili faili moja la asili la MCP linaloweza kutekelezwa na huduma moja ya MCP inayotumia kifurushi:

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

Kila ufunguo ndani ya mcpServers hutambulisha huduma ya MCP. Kwa binary ya asili, weka command kwenye njia ya faili linaloweza kutekelezwa. Kwa huduma inayotumia kifurushi, tumia Bun kama amri na pitisha njia ya skripti iliyosakinishwa kupitia args. Vigezo vya mazingira maalum kwa huduma vinaweza kuongezwa kwenye env.

Gateway inasaidia uingizaji wa vigezo vya mazingira kwenye njia. Vigezo vinajumuisha ${APP_DATA_DIR}, ${XDG_DATA_HOME}, ${HOME} na %USERPROFILE%. Uingizaji huu hurahisisha kutumia tena usanidi kwenye kompyuta mbalimbali bila kuweka kwa lazima kila njia kamili.

Weka kitambulishi cha huduma kiwe thabiti. Kwa mfano, huduma inayoitwa codebase_memory huwasilishwa chini ya njia ya URL inayolingana inayotumika wakati wa kupata hati yake ya OpenAPI.

Simamia Programu-jalizi za Nje za MCP

Vifurushi vya MCP vinavyohusiana na biashara havipaswi kusakinishwa kwenye hazina ya gateway. Visakinishe na visimamie kwenye saraka ya data ya XDG ya gateway badala yake:

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

Ili kusasisha kifurushi kilichosakinishwa, endesha:

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

Baada ya usakinishaji, rejelea sehemu ya kuanzia ya kifurushi kutoka config.json5 ukitumia ${APP_DATA_DIR}, kama ilivyoonyeshwa kwenye mfano wa stdio wa hati. Hii huweka vitegemezi vya gateway tofauti na vitegemezi vya viendelezi vya MCP.

Matumizi ya Msingi

1. Sakinisha vitegemezi vya gateway au tengeneza programu asilia inayoweza kutekelezwa.

2. Unda $XDG_CONFIG_HOME/mcp-gateway/config.json5.

3. Ongeza huduma moja au zaidi chini ya mcpServers.

4. Anzisha gateway kwa bun run dev au endesha programu iliyotengenezwa.

5. Pata hati ya OpenAPI ya huduma iliyosanidiwa na uisajili kwa mteja wako wa nje.

Kwa huduma inayoitwa codebase_memory, muundo wa URL ya OpenAPI ulioandikwa ni:

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

Katika mfano huu, 8444 ni mlango unaoweza kufikiwa kwa nje. Huenda ukawa mlango wa reverse proxy badala ya mlango wa ndani wa gateway, kama vile 9090 katika mfano wa usanidi.

Unganisha na Open WebUI

Reverse proxy kama Caddy au Nginx inaweza kufichua gateway kupitia hosti, mlango na itifaki ya nje unayotaka. Sanidi proxy itume vichwa vinavyofaa vya X-Forwarded-*. Open MCP Gateway husoma vichwa hivi inapotengeneza hati ya OpenAPI, na hivyo kuhakikisha kuwa servers.url inaelekeza kwenye anwani ya umma badala ya kisikilizaji cha ndani.

1. Anzisha Open MCP Gateway nyuma ya reverse proxy.

2. Fungua paneli ya usimamizi ya Open WebUI.

3. Nenda kwenye sehemu ya Functions, Tools au OpenAPI.

4. Sajili URL ya hati ya OpenAPI kwa kila huduma ya MCP iliyosanidiwa:

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

5. Ruhusu Open WebUI kupakia vipimo. Zana za huduma ya MCP zinaweza kisha kutumiwa kama zana asilia kupitia operesheni za OpenAPI zilizotengenezwa.

Kwa kuwa vitambulisho vya operesheni huhifadhi majina asilia ya zana za MCP, wateja huona vitambulisho safi vya zana bila viambishi tamati au awali vinavyotengenezwa na gateway.

Upimaji na Ufuatiliaji wa Kumbukumbu

Endesha amri ya majaribio ya mradi baada ya kubadilisha gateway au usanidi wake:

bun run test

Kwenye Windows, hazina pia hutoa hati ya majaribio ya PowerShell:

.\ps1_scripts\test-gateway.ps1

Uthibitishaji wa mwisho hadi mwisho unahusisha ukaguzi wa hali, salamu ya MCP na ulinganifu wa chanzo cha proxy.

Kwenye mifumo inayofanana na Unix, fuatilia kumbukumbu endelevu ya gateway kwa:

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

Hii ni muhimu unapochunguza matatizo ya kuanzisha mchakato, njia batili za programu inayoweza kutekelezwa, hitilafu za salamu ya MCP au matatizo ya usanidi wa reverse proxy.

Vidokezo vya Kina

Tumia njia zinazobebeka

Pendelea njia zinazoingiliana kama ${HOME} na ${APP_DATA_DIR} badala ya njia kamili zinazotegemea mashine mahususi. Kwenye Windows, %USERPROFILE% inaweza kutumiwa inapofaa. Hii hurahisisha kushiriki usanidi kati ya mifumo.

Weka programu-jalizi nje ya hazina ya chanzo

Sakinisha vifurushi vya nje vya MCP katika $XDG_DATA_HOME/mcp-gateway. Hii hudumisha mti safi wa chanzo na kuruhusu gateway pamoja na viendelezi vyake vya biashara kusasishwa kwa kujitegemea.

Tenganisha anwani za ndani na za nje

Kufunga gateway kwenye 127.0.0.1 huweka kisikilizaji cha ndani kuwa cha mashine hiyo pekee. Reverse proxy inaweza kisha kutoa mwisho wa TLS wa nje. Hakikisha vichwa vilivyopitishwa vinaeleza mpango, hosti na mlango wa umma ili hati za OpenAPI zinazotengenezwa zitangaze URL sahihi.

Tumia masasisho ya papo hapo

Hifadhi ya vipindi ya blue-green hubadilisha vipindi vya huduma huku ikilinda mpito kwa AsyncMutex. Muundo huu huruhusu masasisho ya usanidi bila kusitisha maombi ambayo tayari yanaendelea. Upakiaji upya wa papo hapo na kujirekebisha kwa mzunguko wa maisha hupunguza zaidi hitaji la usimamizi wa michakato kwa mkono.

Unda kwa ajili ya uwekaji

Tumia bun run build wakati seva lengwa haipaswi kuhitaji Bun au vitegemezi vya mradi vilivyosakinishwa. Weka programu iliyotengenezwa pamoja na usanidi unaohitajika wa XDG na programu au vifurushi vyovyote vya MCP vinavyosimamiwa kando.

Hitimisho

Open MCP Gateway hutoa daraja lililounganishwa kutoka huduma za ndani za MCP hadi njia madhubuti za OpenAPI 3.1.0. Kwa kuchanganya usaidizi wa usafirishaji wa aina nyingi, usanidi unaobebeka unaotegemea XDG, usimamizi wa programu-jalizi za nje, uelewa wa reverse proxy na miundo inayojitegemea, inatoa njia ya kiutendaji ya kufanya zana za ndani za MCP zipatikane kwa Open WebUI na wateja wengine wanaoweza kutumia OpenAPI.