Jinsi ya Kujitegemea Kuendesha Seva ya Didit MCP

Mambo muhimu ya kuzingatia

• Seva ya Didit Model Context Protocol (MCP) ni chanzo huria chini ya leseni ya MIT. Unaweza kuijenga kutoka hazina ya umma ya GitHub na kuiendesha na Docker, Node.js, au usafirishaji wa stdio usio na kichwa.
• Kujitegemea kuendesha hubadilisha mahali mchakato wa MCP unapoendeshwa, sio jinsi unavyofikia Didit. Kila hali inathibitisha kama mtumiaji wa Didit na tokeni ya kufikia ya Bearer. Hakuna hali ya ufunguo wa API ya programu kwa zana za MCP.
• Katalogi kamili inayojiendesha ina zana 121. Kituo cha Open Authorization (OAuth) kinachoendeshwa kwa makusudi kinafichua 115. Mifano katika chanzo cha sasa ni pamoja na didit_context_get, didit_session_create, na didit_transaction_screen_wallet.
• Sehemu ya kuingilia ya HTTP haina hali na inakubali trafiki ya MCP kupitia maombi ya POST. Seva mpya na usafirishaji huundwa kwa kila ombi, kwa hivyo kipakiaji hakihitaji umiliki wa kikao.
• Tumia /healthz kwa ukaguzi wa kontena na kipakiaji. Sanidi URI ya rasilimali ya umma, asili ya idhini, hali ya uthibitishaji wa tokeni, na siri kwa uwazi kabla ya kufichua huduma.

Kituo cha mwisho kinachoendeshwa ni rahisi, lakini sio chaguo sahihi la uendeshaji kwa kila timu. Biashara inaweza kuhitaji kuweka muunganiko ndani ya mipaka yake ya mtandao, kudhibiti picha ya wakati wa kuendeshwa, kuelekeza trafiki kupitia safu ya faragha ya kutoka, au kutumia sera zake za uchunguzi na usimamizi wa mabadiliko. Hazina ya Didit MCP inasaidia mtindo huo wa upelekaji bila kuunda uso tofauti wa bidhaa.

Mwongozo huu unazingatia tu uendeshaji wa seva. Kwa katalogi na tabia ya zana, tumia rejeleo la zana za Didit MCP. Kwa usanidi wa mteja dhidi ya kituo cha mwisho kinachosimamiwa, tumia mwongozo wa usakinishaji wa Claude. Marejeleo kamili ya kiufundi yapo katika muhtasari wa MCP na nyaraka za uthibitishaji.

Chagua sehemu ya kuingilia ya HTTP au stdio

Hazina inajenga katalogi moja ya zana inayoshirikiwa na sehemu mbili za kuingilia. dist/http.js inaendesha seva ya rasilimali ya Express juu ya HTTP isiyo na hali. Ni chaguo sahihi kwa huduma inayoshirikiwa inayofikiwa na wateja kadhaa wa MCP, kontena, au watumiaji. dist/index.js inaendesha juu ya stdio na inakusudiwa kwa mchakato wa ndani usio na kichwa uliozinduliwa na mteja mmoja.

Sehemu zote mbili za kuingilia huita mantiki sawa ya usambazaji, na toleo la 5 linafichua zana za MCP tu—sio rasilimali au vidokezo vya MCP. Zote zinathibitisha maombi ya chini kama mtumiaji wa Didit. Tofauti ni jinsi kitambulisho hicho cha mtumiaji kinavyofikia mchakato: sehemu ya kuingilia ya HTTP inapokea na kuthibitisha tokeni ya Bearer ya OAuth ya mpigaji; sehemu ya kuingilia ya stdio inasoma tokeni ya Bearer ya mtumiaji kutoka DIDIT_ACCESS_TOKEN.

Kujitegemea kuendesha haimaanishi bila kitambulisho: MCP bado inafanya kazi kama mtumiaji wa Didit, na Didit inatumia jukumu na ruhusa za shirika la mtumiaji huyo kwa kila simu ya zana.

Jenga na endesha na Docker

Hazina inajumuisha Dockerfile ya hatua nyingi kulingana na Node 20. Hatua ya ujenzi husakinisha tegemeo za maendeleo, huunganisha TypeScript, na hupunguza vifurushi vya maendeleo. Hatua ya uzalishaji inaendeshwa kama mtumiaji asiye na mizizi node na inajumuisha ukaguzi wa afya ya kontena.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env

docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp

Kabla ya kuanza kontena, badilisha chaguo-msingi zilizowekwa zinazotambulisha upelekaji wako. Angalau, weka MCP_RESOURCE_URI kwa asili ya umma ambayo wateja wanafikia seva hii ya rasilimali, kisha toa vitambulisho vya mteja wa OAuth vinavyohitajika kwa uchunguzi wa tokeni. Weka siri katika meneja wa siri wa jukwaa lako la kontena badala ya kuweka faili ya .env iliyojaa.

MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=replace-with-client-id
MCP_OAUTH_CLIENT_SECRET=replace-with-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

Maliza Usalama wa Safu ya Usafiri (TLS) kwenye lango lako la kuingilia au kipakiaji, sambaza maombi ya MCP POST kwa bandari 3000, na uhifadhi kichwa cha Authorization. MCP_RESOURCE_URI inayoonekana nje lazima ifanane na kitambulisho cha rasilimali kinachotangazwa kwa wateja; usiache URI ya Didit inayosimamiwa mahali pake kwa asili tofauti ya umma.

Jenga na endesha moja kwa moja na Node.js

Ikiwa jukwaa lako tayari linasimamia wakati wa kuendeshwa wa Node, tumia sehemu sawa ya kuingilia ya HTTP bila kontena. Kifurushi ni cha faragha na hakijasambazwa kupitia npm, kwa hivyo cheza hazina badala ya kujaribu kutekeleza kifurushi kilichochapishwa.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js

Mchakato unasoma vigezo sawa vya mazingira kama kontena. Uendeshe chini ya msimamizi wako wa mchakato, ingiza siri kupitia mazingira ya upelekaji, na uelekeze tu vituo vya mwisho vinavyohitajika. Maombi ya MCP huenda kwa POST /mcp. Huduma inakataa kwa makusudi GET na DELETE kwenye njia hiyo kwa sababu haishiki vikao vya MCP au mitiririko inayoanzishwa na seva.

Node.js haipakii faili ya .env ya hazina kiotomatiki. Hamisha thamani katika ganda, ziingize kupitia meneja wa huduma, au tumia usaidizi wa faili ya mazingira ya jukwaa lako kabla ya kuanza dist/http.js. Pia kumbuka kuwa npm start inazindua sehemu ya kuingilia ya stdio; tumia node dist/http.js au npm run start:http kwa HTTP.

Endesha bila kichwa juu ya stdio

Kwa wakala wa ndani, kiendesha jengo, au mchakato wa mteja mmoja uliotengwa, tumia sehemu ya kuingilia ya stdio. Toa tokeni ya kufikia ya mtumiaji kupitia mazingira na ruhusu mteja wa MCP kumiliki mzunguko wa maisha wa mchakato.

DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js

Tokeni hii ni kitambulisho cha Bearer cha mtumiaji, sio kitambulisho cha programu. Ihifadhi kama siri, iweke mbali na historia ya ganda na magogo, na uibadilishe kulingana na sera yako ya kufikia. Ikiwa upelekaji mmoja unafanya kazi kila wakati katika shirika au programu moja, MCP_DEFAULT_ORG na MCP_DEFAULT_APP zinaweza kutoa wigo huo chaguomsingi. Vinginevyo, zana zinaweza kutatua wigo kutoka kwa hoja za wazi au muktadha wa ombi lililothibitishwa.

Bado hakuna hali ya ufunguo wa API ya programu katika stdio. HTTP inayojiendesha na stdio inayojiendesha zote huita vituo vya mwisho vya koni ya Didit vilivyo na wigo wa mtumiaji, kwa hivyo ufunguo wa programu hauwezi kuchukua nafasi ya tokeni ya Bearer ya mtumiaji.

Sanidi uso kamili wa mazingira

src/config.ts ya sasa inasaidia vigezo vifuatavyo. Upelekaji mwingi unapaswa kuweka API ya Didit ya uzalishaji na chaguo-msingi za idhini na kubatilisha tu kitambulisho cha rasilimali, usanidi wa uthibitishaji, na siri zinazohitajika kwa topolojia yao.

Vigezo vilivyoshirikiwa na stdio

• DIDIT_ACCESS_TOKEN: tokeni ya Bearer ya mtumiaji kwa hali ya stdio isiyo na kichwa; hakuna chaguo-msingi.
• DIDIT_API_BASE_URL: msingi wa API ya uthibitishaji; chaguo-msingi kwa https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: msingi wa API ya uthibitishaji; chaguo-msingi kwa https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG na MCP_DEFAULT_APP: chaguo-msingi za hiari za shirika na programu kwa upelekaji wa mpangaji mmoja.

Vigezo vya seva ya rasilimali ya HTTP

• MCP_PORT: bandari ya kusikiliza; chaguo-msingi kwa 3000.
• MCP_RESOURCE_URI: URI ya seva ya rasilimali ya umma; chaguo-msingi kwa https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: asili ya seva ya idhini; chaguo-msingi kwa https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: introspection kwa chaguo-msingi, au jwks wakati huduma ya idhini inatoa Tokeni za Wavuti za JSON (JWTs) zinazofaa kwa uthibitishaji wa saini ya ndani.
• MCP_OAUTH_CLIENT_ID na MCP_OAUTH_CLIENT_SECRET: hakuna chaguo-msingi; hutumiwa kama vitambulisho vya HTTP Basic kwa Ombi la Maoni (RFC) 7662 uchunguzi.
• MCP_OAUTH_INTROSPECT_URL: chaguo-msingi kwa https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: wigo wa ugunduzi uliotenganishwa na nafasi; chaguo-msingi kwa didit:management didit:verification.

Kubatilisha metadata ya idhini

• DIDIT_AUTH_ISSUER: chaguo-msingi kwa MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: hati ya ugunduzi ya OpenID Connect (OIDC); chaguo-msingi kwa asili ya idhini pamoja na /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: kituo cha JSON Web Key Set (JWKS); chaguo-msingi kwa https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: chaguo-msingi kwa asili ya idhini pamoja na /authorize.
• DIDIT_OIDC_TOKEN_URL: chaguo-msingi kwa asili ya idhini pamoja na /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: chaguo-msingi kwa asili ya idhini pamoja na /api/auth/oauth-register.

Tumia introspection kwa tokeni za kufikia zisizo wazi. Seva inazituma kwa kituo cha uchunguzi kilichosanidiwa kwa kutumia MCP_OAUTH_CLIENT_ID na MCP_OAUTH_CLIENT_SECRET. Tumia jwks tu wakati huduma yako ya idhini imesanidiwa kutoa tokeni za kufikia za JWT zilizotiwa saini kwa mteja huyu; seva basi inathibitisha saini dhidi ya DIDIT_JWKS_URL. Kubadilisha hali ya uthibitishaji hakuundi mfumo tofauti wa kitambulisho: mkuu aliyethibitishwa anabaki kuwa mtumiaji wa Didit.

Wateja wa MCP wanaweza kutumia Usajili wa Mteja wa Nguvu (DCR) na Didit Business Console wakati wa mtiririko wao wa idhini. Usajili huo wa mteja umetenganishwa na MCP_OAUTH_CLIENT_ID na MCP_OAUTH_CLIENT_SECRET ya seva ya rasilimali, ambayo inathibitisha maombi ya uchunguzi. Toa vitambulisho hivyo vya upande wa seva kupitia chaneli inayofaa ya upelekaji wa Didit badala ya kudhani usajili wa mteja unaweza kuvibadilisha.

Ukaguzi wa afya na uenezaji usio na hali

Mchakato wa HTTP unafichua GET /healthz na unarudisha JSON iliyo na status, service, na version. Picha ya Docker tayari inaiangalia kila sekunde 30 baada ya kipindi cha kuanza cha sekunde 15. Unaweza kutumia kituo hicho hicho kwa utayari wa Kubernetes, kikundi cha lengo la Kipakiaji cha Programu, au uchunguzi wa nje wa muda wa kufanya kazi.

curl -fsS http://localhost:3000/healthz

Njia ya MCP haina hali kwa muundo. Kwa kila POST iliyothibitishwa, mchakato huunda seva mpya na usafirishaji wa HTTP unaoweza kutiririka na utengenezaji wa kikao umezimwa, hupeleka kitambulisho kilichothibitishwa cha mpigaji kupitia muktadha wa ombi kwa kila ombi, hukamilisha usambazaji, na kufunga usafirishaji. Hakuna kikao cha ndani ya kumbukumbu ambacho ombi la baadaye lazima lipate kwenye nakala hiyo hiyo.

Hapa, isiyo na hali inaelezea usafirishaji wa MCP na mzunguko wa maisha wa ombi. Vikao vya uthibitishaji, mtiririko wa kazi, kesi, na rekodi zingine za biashara bado zinaendelea katika huduma za juu za Didit.

Matokeo yake, nakala za usawa hazihitaji vikao vya kunata. Kila mfano wenye afya unaweza kushughulikia POST inayofuata, na upelekaji unaoendelea hauhitaji kumaliza kikao zaidi ya ushughulikiaji wa kawaida wa maombi yanayoendelea. Upangaji wa uwezo unapaswa kuzingatia wakati mmoja wa ombi, muda wa kusubiri wa API ya Didit ya chini, na sera yako ya kawaida ya muda wa kuisha na kujaribu tena.

Thibitisha kabla ya kufichua huduma

• Thibitisha /healthz inafanikiwa kutoka kwa njia sawa ya mtandao kama kipakiaji.
• Thibitisha maombi ya MCP yasiyothibitishwa yanapokea changamoto ya idhini badala ya matokeo ya zana.
• Kamilisha mtiririko wa OAuth 2.1 na Proof Key for Code Exchange (PKCE), kisha ita didit_context_get ili kuthibitisha mashirika na programu zinazotarajiwa zinaonekana.
• Kagua nyaraka za hali ya juu za MCP kabla ya kubadilisha vituo vya ugunduzi au uthibitishaji wa tokeni.
• Tumia ukurasa wa msanidi wa Didit MCP kwa uso unaosimamiwa unaoungwa mkono na viungo vya sasa.

Ikiwa kujitegemea kuendesha sio hitaji tena, kituo cha mwisho kinachosimamiwa huondoa uendeshaji wa wakati wa kuendeshwa na seva ya rasilimali ya OAuth iliyoelezwa hapo juu. Watumiaji wa Claude wanaweza kuiongeza na kiungo cha kina cha kiunganishi cha Didit. Iwe unaendesha mchakato au Didit inafanya, sheria kuu ni sawa: shughuli za MCP zinathibitisha kama mtumiaji wa Didit, kamwe kama ufunguo wa API ya programu.