Personal Agent Protocol bei Maintenance Due

Diese Seite ist für Leute, die persönliche Agenten bauen. Wenn Muse nur den Ölwechsel des Transporters im Blick behalten soll, kopiere den Prompt auf for-your-agent. Die Spezifikation liegt auf personalagentprotocol.org.

Erkennung

GET https://maintenancedue.com/.well-known/poppy.json nennt die Organisation (maintenancedue.com), den Aussteller https://maintenancedue.com, Direct Sign-In mit poppy:read und poppy:write und zwei APIs: den MCP-Server unter https://maintenancedue.com/mcp und die OpenAPI-Beschreibung unter https://maintenancedue.com/openapi.json für REST unter /api/v1. Die Aussteller-Metadaten unter /.well-known/oauth-authorization-server führen maintenancedue.com in poppy_domains und nennen die Endpunkte für Token, Autorisierung und Widerruf unter /oauth/.

Sessions und Anmeldung

1. Veröffentliche deinen Client. Deine client_id ist eine https-URL, die dein Client-Metadatendokument liefert, mit jwks_uri und redirect_uris auf derselben Domain. Jede Token-Anfrage trägt eine private_key_jwt-Client-Assertion, signiert mit einem Schlüssel aus diesem jwks_uri.
2. Starte eine Session. POST /oauth/token mit grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, einer Assertion mit deiner client_id als iss, der User ID als sub und https://maintenancedue.com/oauth/token als einzelner Zeichenkette in aud, dazu ein DPoP-Nachweis. Du bekommst ein abgemeldetes Session Token (token_type DPoP, eine Stunde) und eine session_id. Sende session_id mit einer frischen Assertion, um es zu erneuern.
3. Schicke den Besitzer auf unsere Seite. Öffne /oauth/authorize mit response_type=code, deiner client_id und redirect_uri, scope=poppy:read poppy:write (oder nur poppy:read), einem state und einer PKCE-S256-code_challenge. Der Besitzer sieht deinen Namen und deine Domain, wählt View only oder View and change und legt dann eine kostenlose Werkstatt an oder meldet sich mit einem Mitglieds-Token an, das er schon hat. Die Weiterleitung bringt code, state und iss zurück. Prüfe, dass iss https://maintenancedue.com ist.
4. Tausche den Code ein. POST /oauth/token mit grant_type=authorization_code, dem code, redirect_uri, code_verifier und deiner session_id, dazu deine Client-Assertion und ein DPoP-Nachweis. Die Antwort enthält das Account Token in refresh_token (pat_…, 30 Tage), ein angemeldetes Session Token und den gewährten scope. Der Besitzer kann Lesen wählen, wenn du Ändern angefragt hast, also lies scope.
5. Später angemeldet starten. POST /oauth/token mit grant_type=refresh_token und dem Account Token, mit oder ohne session_id. Füge scope=poppy:read hinzu, um für eine Abfrage ein reines Lese-Token zu bekommen. Das Account Token wird nicht rotiert, parallele Sessions können es also teilen.
6. Abmelden. POST /oauth/revoke mit dem Account Token und deiner Client-Assertion. Jede damit angemeldete Session ist beim nächsten Aufruf abgemeldet und erneuert sich abgemeldet.

Die Tafel aufrufen

REST nimmt DPoP: Authorization: DPoP <token> plus ein frischer DPoP-Nachweis mit htm, htu und ath bei jedem Aufruf von /api/v1. MCP nimmt Bearer: erneuere ohne DPoP-Nachweis und mit resource=https://maintenancedue.com/mcp, dann sende Authorization: Bearer <token> an /mcp. Ein Bearer Session Token gilt nur auf /mcp, und ein DPoP-Token wird dort abgelehnt. Die MCP-Tools, ihre Schemas und der Header MCP-Protocol-Version 2025-06-18 sind dieselben, die ChatGPT nutzt.

Lesen oder ändern

poppy:read öffnet jedes GET auf /api/v1 und jedes MCP-Tool mit readOnlyHint, etwa get_due, get_history und list_assets. poppy:write öffnet alle anderen REST-Methoden und MCP-Tools, etwa append_event, append_reading, create_service und set_rule, dazu events/subscribe. Ein fehlender Scope ergibt 403 mit error="insufficient_scope" und dem nötigen Scope in WWW-Authenticate. Ein abgemeldetes Token bei einem Kontoaufruf ergibt 403 sign_in_required. Ein abgelaufenes Token, oder eines aus der Zeit vor der Abmeldung, ergibt 401 invalid_token. Mitglieder der Org einladen, entfernen oder die Org verlassen bleibt beim eigenen Token des Mitglieds.

ChatGPT-Verbindungen über /oauth/authorize mit dem Scope mcp und bestehende Muse-Mitglieds-Tokens funktionieren weiter wie bisher. Feldnamen stehen auf skill.md, der REST-Vertrag auf openapi.json und der Agentenindex auf llms.txt.