Protokolltest

Der Protokolltest-Dienst ist ein öffentlicher Testpartner für das OpenBot App Protocol. Er veröffentlicht erfundene Apps, die jede Art des Verbindens und Anmeldens abdecken. Nutze ihn, um einen Host, einen Client oder OpenBot selbst zu testen.

Der Dienst liegt im Ordner protocol-test des Repositorys. Sein Paketname ist @openbot-build/protocol-test. Er nutzt MCP 2026-07-28, Streamable HTTP über HTTPS und MCP Apps 2026-01-26. Die Beispiele nutzen https://protocol-test.example.com als seinen Origin.

Ein laufender Dienst liefert unter /guide auch eine vollständige Anleitung als reinen Text aus.

Szenarien

App-ID	MCP-Pfad	Zugangsdaten
`anonymous`	`/mcp/anonymous`	Keine
`api-key`	`/mcp/api-key`	`X-API-Key: protocol-test-api-key`
`bearer`	`/mcp/bearer`	`Authorization: Bearer protocol-test-bearer-token`
`basic`	`/mcp/basic`	`Authorization: Basic cHJvdG9jb2wtdGVzdDpwcm90b2NvbC10ZXN0LXBhc3N3b3Jk`
`oauth-cimd`	`/mcp/oauth-cimd`	Client ID Metadata Document und öffentliches PKCE
`oauth-dcr`	`/mcp/oauth-dcr`	Dynamische Client-Registrierung, öffentliches oder vertrauliches PKCE
`oauth-preregistered`	`/mcp/oauth-preregistered`	Ein registrierter öffentlicher oder vertraulicher Client mit PKCE
`oauth-client-credentials`	`/mcp/oauth-client-credentials`	Ein vertraulicher Maschinen-Client

Jede App hat eine Seite unter /apps/<id>, einen Catalog unter /apps/<id>/catalog.json und eine Card unter /apps/<id>/server-card.json. Der Haupt-Catalog unter /.well-known/ai-catalog.json führt sie alle auf. /scenarios.json führt jedes Szenario und jede Fixture als JSON auf. /healthz und /readyz melden den Status.

Um es in OpenBot auszuprobieren, verbinde protocol-test.example.com so, wie es unter Apps beschrieben ist.

Lebensdauer der Daten

Daten	Hält
Workspace	30 Minuten
Access Token	5 Minuten
Refresh Grant	1 Stunde
Autorisierungs-Code	1 Minute
Zustimmungs-Anfrage	10 Minuten

Jedes Szenario hat seine eigenen Workspaces. In OAuth-Szenarien hat auch jedes Konto seine eigenen. Andere Szenarien teilen Daten. Wähle also eine Workspace-ID, die sonst niemand nutzt.

Öffentliche Test-Zugangsdaten

Client-ID	Authentifizierung	Callbacks
`https://protocol-test.example.com/clients/public.json`	`none`, CIMD	`https://protocol-test.example.com/callback`
`protocol-test-public`	`none`	Öffentliches `/callback`, `http://127.0.0.1:8765/callback`, `http://localhost:8765/callback`
`protocol-test-confidential-basic`	`client_secret_basic`	Öffentliches `/callback`
`protocol-test-confidential-post`	`client_secret_post`	Öffentliches `/callback`

Beide vertraulichen Clients nutzen das Geheimnis protocol-test-client-secret. Für andere Callbacks nutze dein eigenes öffentliches CIMD-Dokument oder die dynamische Registrierung unter /oauth/dcr/register.

Auf der Anmeldeseite kannst du den Zugriff als Alice oder Bob erlauben oder ablehnen.

Scope	Erlaubt
`test:read`	Erkennung und Lesen.
`test:write`	Zusätzlich `write_note` und `delete_note`. Frage nach beiden.

OAuth-Abläufe

Jeder Modus (cimd, dcr, preregistered, client-credentials) hat seinen eigenen Issuer unter /oauth/<mode>. Die Issuer-Metadaten liegen unter /.well-known/oauth-authorization-server/oauth/<mode>. Die Protected Resource Metadata liegen unter /.well-known/oauth-protected-resource/mcp/oauth-<mode>.

Für eine Anmeldung im Browser öffne /oauth/<mode>/authorize mit response_type=code, client_id, der genauen redirect_uri, resource, scope, state und einer S256-code_challenge. Tausche dann den Code einmal unter /oauth/<mode>/token mit dem PKCE-Verifier ein. Jede Anfrage muss die genaue resource senden, zum Beispiel https://protocol-test.example.com/mcp/oauth-cimd.

Ein Maschinen-Token holen:

curl https://protocol-test.example.com/oauth/client-credentials/token \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id=protocol-test-confidential-post \
  --data-urlencode client_secret=protocol-test-client-secret \
  --data-urlencode resource=https://protocol-test.example.com/mcp/oauth-client-credentials \
  --data-urlencode scope='test:read test:write'

Ein Token nur zum Lesen versteckt die Schreib-Werkzeuge. Ein Schreibvorgang ohne test:write bekommt 403. Ein falsches, abgelaufenes, widerrufenes Token oder ein Token für die falsche Ressource bekommt 401. Ein Refresh fügt nie Scopes hinzu. /oauth/<mode>/revoke widerruft alle Tokens des Grants.

Was du testen kannst

Werkzeuge. echo, add, identity, content_samples, read_workspace, write_note (mit einem idempotencyKey), delete_note (mit einer expectedRevision), ui_read_workspace (nur für die App), test_error, wait und notify.
Nachfragen. request_form, request_url, request_sampling und request_roots nehmen { "text": "..." } und bitten den Client um mehr Eingaben.
Ressourcen. protocol-test://about, protocol-test://binary, protocol-test://workspace/<workspace> und 110 Fixtures zum Blättern.
Prompt. summarize_workspace, mit Vervollständigung.
Ansicht. ui://protocol-test/workspace.html, eine MCP-Apps-Ansicht eines Workspaces.

Fixtures für Erkennung und Indizierung

Jede Fixture (Testvorlage) hat eine Card unter /fixtures/<id>/server-card.json.

ID	Was du sehen solltest
`noindex`	Eine aufgeführte Card mit `X-Robots-Tag: noindex`
`robots-denied`	Eine aufgeführte Card, die `/robots.txt` sperrt
`unlisted`	Eine gültige Card, die kein Catalog aufführt
`withdrawn`	410 Gone
`malformed`	Fehlerhaftes JSON
`incompatible`	Nur eine nicht unterstützte Protokollversion und Übertragungsart
`redirect`	Eine Weiterleitung zur anonymen Card
`unavailable`	503 mit `Retry-After`

Lokal starten

Im Hauptordner des Repositorys:

devenv shell -- pnpm --filter @openbot-build/protocol build
devenv shell -- pnpm --filter @openbot-build/protocol-test build
devenv shell -- pnpm --filter @openbot-build/protocol-test test
PROTOCOL_TEST_PUBLIC_ORIGIN=https://protocol-test.example.com \
  devenv shell -- pnpm --filter @openbot-build/protocol-test start

Der Dienst spricht standardmäßig HTTP. Er erwartet einen TLS-Proxy davor. Wenn du HTTPS direkt auf deinem Computer anbieten willst, setze den Origin auf https://localhost:7445, den Port auf 7445 und beide TLS-Pfade. Sorge dann dafür, dass dein Host dem Zertifikat vertraut.

Mit Docker starten

Das Ziel protocol-test in deploy/docker/Dockerfile erzeugt das Image. Baue es und starte es:

devenv shell -- docker buildx bake -f deploy/docker/docker-bake.hcl --load protocol-test
devenv shell -- docker run -d --name protocol-test -p 127.0.0.1:3001:3001 \
  -e PROTOCOL_TEST_PUBLIC_ORIGIN=https://protocol-test.example.com \
  openbot-protocol-test:local

Der Dienst hört nur auf 127.0.0.1:3001. Setze einen TLS-Proxy davor, der Streaming unterstützt. deploy/docker/protocol-test.nginx.conf ist ein Beispiel. deploy/docker/compose.production.yaml startet das Image openbot-protocol-test genauso, ohne Datenbank. Starte nur eine Kopie, denn alle Daten liegen in einem Prozess.

Konfiguration

Variable	Standard	Zweck
`PROTOCOL_TEST_PUBLIC_ORIGIN`	Pflicht	Der genaue öffentliche HTTPS-Origin, ohne Pfad.
`PROTOCOL_TEST_HOST`	`0.0.0.0`	Die Adresse, auf der der Dienst hört.
`PROTOCOL_TEST_PORT`	`3001`	Der Port, auf dem der Dienst hört.
`PROTOCOL_TEST_ALLOWED_ORIGINS`	Der öffentliche Origin	Browser-Origins, die ihn aufrufen dürfen, durch Kommas getrennt.
`PROTOCOL_TEST_TLS_KEY`, `PROTOCOL_TEST_TLS_CERT`	Nicht gesetzt	Dateipfade. Setze beide, um HTTPS direkt anzubieten.

Server-Clients senden keinen Header Origin. Darum funktionieren sie immer. Ein Browser-Client funktioniert nur, wenn sein genauer Origin in PROTOCOL_TEST_ALLOWED_ORIGINS steht.