Kontrakty platformy (mcp-contracts 7.0.0)

mcp-contracts to maszynowo czytelna postać interfejsów między komponentami platformy: OpenAPI 3.1, JSON Schema 2020-12, schemat Cedar, klucze testowe, wektory testowe i atrapy. Bieżąca wersja: 7.0.0. To biblioteka dla autorów komponentów platformy i serwerów MCP, nie coś, co się uruchamia. Kontrakty są zamrożone: zmianę zgłasza się w CONTRACT_CHANGES.md w repozytorium i zatwierdza człowiek.

Kontrakty

Id	Co opisuje	Plik
C1	Token klienta AI w bramce (OAuth, token dostawcy tożsamości)	test-vectors/gateway-authentication/, test-vectors/oauth-metadata/
C2	Wewnętrzny JWT, który bramka wysyła do serwerów i brokera	schemas/internal-jwt.schema.json, test-vectors/jwt/
C3	Nagłówki poświadczenia X-MCP-Credential i X-MCP-Credential-Type	openapi/mcp-server.v1.yaml, test-vectors/credential-type-header/
C4	API brokera poświadczeń	openapi/credential-broker.v1.yaml
C5	API administracyjne bramki (serwery, polityki, zatwierdzenia)	openapi/gateway-admin.v1.yaml
C6	Manifest serwera: narzędzia, ryzyko, typy zasobów, polityki	schemas/server-manifest.schema.json, test-vectors/manifests/, test-vectors/definition-hash/
C7	Model Cedar, polityki i dane polityk wysyłane przez bramkę	cedar/mcp.cedarschema, cedar/platform/, cedar/examples/
C8	Zdarzenie audytu	schemas/audit-event.schema.json, test-vectors/audit-events/
C9	Nazwy grup (mcp-<system>-read i dalsze)	schemas/common.schema.json#/$defs/GroupName
C10	Błędy narzędzi	schemas/tool-error.schema.json, test-vectors/tool-errors/
C11	Potwierdzanie wywołań destrukcyjnych kodem jednorazowym	test-vectors/confirmation-binding/, test-vectors/totp/
C12	API BFF portalu	openapi/portal-bff.v1.yaml
C13	Port do systemu zarządzania dostępem (IGA)	opisany w README repozytorium

Interfejs, którym serwer łączy się z bramką, to C14, openapi/mcp-server.v1.yaml: GET /.well-known/mcp-manifest, POST /.well-known/mcp-policy-data i publiczny zestaw kluczy bramki GET /.well-known/mcp-jwks.json.

Autora serwera dotyczą głównie C2, C3, C6, C7, C10 i C14. Implementuje je starter; schematy czytaj, gdy piszesz własnego klienta, atrapę lub test.

Pobierz artefakty

Maven Central, grupa pl.aiwcorpo.mcp. Nie trzeba wpisu repozytorium ani danych logowania.

Współrzędne	Zawartość
pl.aiwcorpo.mcp:mcp-contracts:7.0.0	OpenAPI, schematy i pliki Cedar jako zasoby classpath pod mcp-contracts/
pl.aiwcorpo.mcp:mcp-contracts:7.0.0:test-vectors	Wektory testowe i klucze testowe. Tylko zakres test
pl.aiwcorpo.mcp:mcp-cedar-entities:7.0.0	Budowniczy encji Cedar i walidacja fragmentów polityk
pl.aiwcorpo.mcp:mcp-manifest:7.0.0	definitionHash i reguły manifestu
@aiwcorpo/mcp-contracts@7.0.0 (npm)	Te same pliki oraz typy TypeScript i handlery MSW

<dependency>
  <groupId>pl.aiwcorpo.mcp</groupId>
  <artifactId>mcp-contracts</artifactId>
  <version>7.0.0</version>
</dependency>
<dependency>
  <groupId>pl.aiwcorpo.mcp</groupId>
  <artifactId>mcp-contracts</artifactId>
  <version>7.0.0</version>
  <classifier>test-vectors</classifier>
  <scope>test</scope>
</dependency>

npm install --save-dev @aiwcorpo/mcp-contracts@7.0.0

Serwer napisany ze starterem dostaje kontrakty przez BOM startera, więc sam ich nie deklaruje. Plik z classpath odczytasz przez getResource("/mcp-contracts/schemas/internal-jwt.schema.json"). Pakiet npm eksportuje @aiwcorpo/mcp-contracts/msw, .../types/portal-bff, .../openapi/*, .../schemas/* i .../test-vectors/*.

Wektory testowe

test-vectors/ zawiera dane wejściowe i oczekiwany wynik każdej reguły, której nie wyrazi schemat. Odbiorca przechodzi test, gdy dla każdego pliku daje ten sam wynik i powód. Grupy przydatne autorowi serwera:

Katalog	Co testuje
jwt/	Każdy przypadek przyjęcia i odrzucenia wewnętrznego JWT
manifests/, definition-hash/	Poprawność manifestu i hash, który przypina bramka
tool-errors/	Poprawne i niepoprawne błędy C10
credential-type-header/	Typ poświadczenia w nagłówku wobec konfiguracji serwera
policy-decisions/, entity-builder/	Żądania Cedar i ich decyzje

Prywatne klucze testowe w test-vectors/keys/ są publiczne z założenia i oznaczone NOT-FOR-PRODUCTION. Serwery odrzucają je poza profilami dev i devstack. mcp-platform-test ze startera podpisuje nimi tokeny, więc większość serwerów nie sięga po wektory bezpośrednio.

Wersje

Wersja dotyczy naraz jarów, pakietu npm i taga git. Od 2.0.0 numeracja jest zgodna z SemVer: usunięte pole lub zaostrzona walidacja to wersja główna. Wydanie 7.0.0 zamieniło systemy, serwery i typy zasobów ze stałych list w dane czasu działania, dlatego nowy system nie wymaga zmiany w kontraktach. Zmiany w poszczególnych wydaniach są w CHANGELOG.md repozytorium.