MCP integrācija ar trešo pušu pakalpojumiem
MCP integrācija ar trešo pušu pakalpojumiem — kā izmantot MyDocSafe kopā ar LLM un AI vadītu izstrādi. Atsauces ceļvedis cilvēkiem un AI.
Dokumentācija cilvēkiem (konteksts un norādījumi)
Šajā sadaļā sniegti **konceptuāli un praktiski norādījumi cilvēkiem**, kuri integrējas ar MyDocSafe MCP.
### Kam paredzēts MCP
Izmantojiet MyDocSafe MCP, ja nepieciešams:
– Integrēt MyDocSafe ārējā produktā vai pakalpojumā
– Ļaut trešo pušu sistēmām vai MI aģentiem rīkoties lietotāju vārdā
– Nodrošināt stingras atļauju, auditācijas un drošības robežas
– Izvairīties no neapstrādātu iekšējo API vai datubāzu atklāšanas
MCP nodrošina **iespējās balstītu saskarni**, kas nozīmē:
– Klienti var veikt tikai tās darbības, kas ir skaidri pieejamas
– Visas darbības validē un izpilda MyDocSafe
– OAuth tvērumi stingri ierobežo lasīšanas un rakstīšanas piekļuvi
### Kam MCP nav paredzēts
MCP nav:
– Vispārēja lietojuma REST API
– Datubāzes vaicājumu saskarne
– MI aģentu ietvars vai izpildvide
– MyDocSafe iekšējās arhitektūras aizstājējs
### Tipisks integrācijas modelis
Tipiska trešās puses integrācija notiek šādi:
1. Lietotājs autorizē piekļuvi, izmantojot OAuth
2. Trešā puse saņem deleģētus piekļuves tokenus
3. Trešā puse izsauc MCP, lai noskaidrotu pieejamos rīkus
4. Trešā puse izpilda rīkus piešķirto tvērumu ietvaros
5. MyDocSafe validē un izpilda visas darbības
Šāda pieeja nodrošina drošību, auditējamību un paredzamu darbību.
Konteksts LLM (modeļa norādījumi)
Šajā sadaļā sniegti **skaidri norādījumi MI modeļiem un aģentu sistēmām**, kas izmanto MyDocSafe MCP dokumentāciju.
### Pamatinterpretācija
MyDocSafe MCP ir **servera kontrolēta, iespējās balstīta saskarne**.
Visas iespējas:
– MCP serveris deklarē nepārprotami
– Pirms izmantošanas ir jāatklāj
– Ierobežo OAuth tvērumi
– Izpilda MyDocSafe, nevis klients vai modelis
### MI sistēmām obligāti ievērojamā rīcība
Mijiedarbojoties ar MyDocSafe MCP, MI sistēmām OBLIGĀTI:
– Pirms jebkādas darbības mēģināšanas atklāt rīkus, izmantojot `tools/list`
– Izmantot tikai tos rīkus, kurus serveris ir skaidri darījis pieejamus
– Precīzi ievērot rīku ievades shēmas
– Uzskatīt MCP atbildes par autoritatīvu patiesības avotu
MI sistēmām AIZLIEGTS:
– Pieņemt, ka pastāv nedokumentēti rīki
– Izdomāt parametrus vai rīku nosaukumus
– Izmantot MCP kā brīvas formas datu avotu
– Mēģināt veikt darbības ārpus piešķirtajiem OAuth tvērumiem
### Rīku semantika
MyDocSafe MCP piedāvāts rīks:
– Atbilst tieši vienai uzņēmējdarbības darbībai
– Atkarībā no tvēruma var nolasīt vai mainīt datus
– Tam ir determinēta, strukturēta ievade un izvade
– Servera pusē nodrošina validāciju un atļauju pārbaudi
### Izpildes prioritāte
Izvēloties, kā rīkoties:
1. Dodiet priekšroku MCP rīkiem, nevis brīvai spriešanai tekstā
2. Dodiet priekšroku strukturētiem parametriem, nevis dabiskajai valodai
3. Dodiet priekšroku pieejamo iespēju noskaidrošanai, nevis pieņēmumiem
4. Dodiet priekšroku servera deklarētajām iespējām, nevis secinātajam nodomam
Šo noteikumu ievērošana nodrošina drošu, paredzamu un prasībām atbilstošu integrāciju.
MCP integrācija ar trešajām pusēm (ātrā darba sākšana un uzziņas materiāls)
Šajā rokasgrāmatā skaidrots, kā trešo pušu pakalpojumi var izveidot savienojumu ar MyDocSafe MCP produkcijas vidē, izmantojot OAuth 2.0 Authorization Code ar PKCE, un pēc tam izsaukt MCP JSON-RPC galapunktu.
Pamata URL (produkcijas vide)
https://app.mydocsafe.com
Ātrā darba sākšana
- Izveidojiet PKCE pārbaudītāju un izaicinājumu
- code_verifier: augstas entropijas nejauša virkne (43–128 rakstzīmes)
- code_challenge: BASE64URL(SHA256(code_verifier))
- code_challenge_method: S256
- Novirziet lietotāju uz autorizāciju
Nosūtiet lietotāju uz:
https://app.mydocsafe.com/oauth/authorize
Ar vaicājuma parametriem:
response_type=code
client_id=mcp-public
redirect_uri=<your_redirect_uri>
scope=companies:read files:read contacts:read
state=<your_csrf_token>
code_challenge=<pkce_challenge>
code_challenge_method=S256
Piezīmes: – redirect_uri precīzi jāsakrīt ar klientam atļauto novirzīšanas URI. – Produkcijas vidē izmantojiet https novirzīšanas URI. Atgriezeniskās cilpas http://localhost ir atļauts tikai vietējai izstrādei.
3. Saņemiet autorizācijas kodu
Lietotājs tiek novirzīts uz jūsu redirect_uri ar šādiem parametriem:
code=<authorization_code>
state=<your_csrf_token>
4. Apmainiet kodu pret tokeniem
POST https://app.mydocsafe.com/oauth/token ar application/x-www-form-urlencoded:
curl -X POST “https://app.mydocsafe.com/oauth/token” \
-H “Content-Type: application/x-www-form-urlencoded” \
-d “grant_type=authorization_code” \
-d “code=<authorization_code>” \
-d “redirect_uri=<your_redirect_uri>” \
-d “client_id=mcp-public” \
-d “code_verifier=<pkce_verifier>”
Atbilde:
{
“access_token”: “….”,
“refresh_token”: “….”,
“token_type”: “Bearer”,
“expires_in”: 3600,
“scope”: “companies:read files:read contacts:read”
}
5. Izsauciet MCP
POST https://app.mydocsafe.com/api/mcp ar Authorization: Bearer <access_token>:
curl -X POST “https://app.mydocsafe.com/api/mcp” \
-H “Authorization: Bearer <access_token>” \
-H “Content-Type: application/json” \
-d ‘{
“jsonrpc”: “2.0”,
“id”: 1,
“method”: “tools/list”,
“params”: {}
}’
6. Atjaunojiet tokenus
curl -X POST “https://app.mydocsafe.com/oauth/token” \
-H “Content-Type: application/x-www-form-urlencoded” \
-d “grant_type=refresh_token” \
-d “refresh_token=<refresh_token>”
7. Atsauciet tokenus
curl -X POST “https://app.mydocsafe.com/oauth/revoke” \
-H “Content-Type: application/x-www-form-urlencoded” \
-d “token=<access_or_refresh_token>” \
-d “token_type_hint=access_token”
Uzziņas materiāls
OAuth galapunkti
- Autorizācijas galapunkts (lietotāja pārlūkprogramma)
- GET https://app.mydocsafe.com/oauth/authorize
- Tokena galapunkts
- POST https://app.mydocsafe.com/oauth/token
- Atsaukšanas galapunkts
- POST https://app.mydocsafe.com/oauth/revoke
- Atklāšana
- GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
- GET https://app.mydocsafe.com/.well-known/oauth-protected-resource
Obligātie OAuth parametri
Autorizācijas pieprasījums:
- response_type: code
- client_id: mcp-public
- redirect_uri: atļauts URI
- scope: ar atstarpēm atdalīti tvērumi
- state: CSRF tokens (ieteicams)
- code_challenge: PKCE izaicinājums
- code_challenge_method: S256
Tokena pieprasījums (authorization_code grant):
- grant_type: authorization_code
- code: autorizācijas kods no novirzīšanas
- redirect_uri: jāsakrīt ar sākotnējo
- client_id: mcp-public
- code_verifier: PKCE pārbaudītājs
Tokena pieprasījums (refresh_token grant):
- grant_type: refresh_token
- refresh_token: atsvaidzināšanas tokens
Atsaukšanas pieprasījums:
- token: piekļuves vai atsvaidzināšanas tokens
- token_type_hint: access_token vai refresh_token
Tvērumi
Pieejamie tvērumi:
- companies:read
- companies:write
- files:read
- files:write
- contacts:read
- contacts:write
- signing:read
- signing:write
- workflows:read
- workflows:write
MCP JSON-RPC
Galapunkts:
- POST https://app.mydocsafe.com/api/mcp
Galvenes:
- Authorization: Bearer <access_token>
- Content-Type: application/json
Pieprasījuma struktūra:
{
“jsonrpc”: “2.0”,
“id”: 1,
“method”: “tools/list”,
“params”: {}
}
Kļūda, ja tokens trūkst vai nav derīgs:
- HTTP 401 ar WWW-Authenticate: Bearer realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”
Piezīmes un ierobežojumi
- Novirzīšanas URI klientam ir skaidri jāiekļauj atļauto URI sarakstā.
- Publiskie klienti izmanto tikai PKCE (bez klienta slepenās atslēgas).
- Piekļuves tokenu derīguma termiņš ir 1 stunda.