Maintenance Due

Créateurs d'agents

Personal Agent Protocol sur Maintenance Due

Un agent personnel peut atteindre le tableau des échéances et le carnet d'entretien d'un propriétaire avec Personal Agent Protocol v0.1. Le propriétaire se connecte sur notre page et choisit lecture ou modification. Maintenance Due est gratuit, et le calcul des échéances n'appelle aucun modèle.

Cette page s'adresse à ceux qui créent des agents personnels. Si vous voulez seulement que Muse tienne la vidange de la camionnette à jour, copiez le prompt sur for-your-agent. La spécification se trouve sur personalagentprotocol.org.

Découverte

GET https://maintenancedue.com/.well-known/poppy.json indique l'organisation (maintenancedue.com), l'émetteur https://maintenancedue.com, Direct Sign-In avec poppy:read et poppy:write, et deux API : le serveur MCP à https://maintenancedue.com/mcp et la description OpenAPI à https://maintenancedue.com/openapi.json pour le REST sous /api/v1. Les métadonnées de l'émetteur à /.well-known/oauth-authorization-server listent maintenancedue.com dans poppy_domains et donnent les endpoints de jeton, d'autorisation et de révocation sous /oauth/.

Sessions et connexion

  1. Publiez votre client. Votre client_id est une URL https qui sert votre document de métadonnées client, avec jwks_uri et redirect_uris sur le même domaine. Chaque requête de jeton porte une assertion client private_key_jwt signée avec une clé de ce jwks_uri.
  2. Démarrez une Session. POST /oauth/token avec grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, une assertion dont iss est votre client_id, sub le User ID et aud https://maintenancedue.com/oauth/token en une seule chaîne, plus une preuve DPoP. Vous recevez un Session Token non connecté (token_type DPoP, une heure) et un session_id. Envoyez session_id avec une nouvelle assertion pour le renouveler.
  3. Envoyez le propriétaire sur notre page. Ouvrez /oauth/authorize avec response_type=code, votre client_id et votre redirect_uri, scope=poppy:read poppy:write (ou seulement poppy:read), un state et un code_challenge PKCE S256. Le propriétaire voit votre nom et votre domaine, choisit View only ou View and change, puis crée un atelier gratuit ou se connecte avec un jeton de membre qu'il possède déjà. La redirection renvoie code, state et iss. Vérifiez que iss vaut https://maintenancedue.com.
  4. Échangez le code. POST /oauth/token avec grant_type=authorization_code, le code, redirect_uri, code_verifier et votre session_id, plus votre assertion client et une preuve DPoP. La réponse contient l'Account Token dans refresh_token (pat_…, 30 jours), un Session Token connecté et le scope accordé. Le propriétaire peut choisir la lecture quand vous demandiez la modification, alors lisez scope.
  5. Démarrez connecté plus tard. POST /oauth/token avec grant_type=refresh_token et l'Account Token, avec ou sans session_id. Ajoutez scope=poppy:read pour un jeton en lecture seule le temps d'une consultation. L'Account Token ne tourne pas, donc des Sessions parallèles peuvent le partager.
  6. Déconnectez-vous. POST /oauth/revoke avec l'Account Token et votre assertion client. Chaque Session connectée avec lui est déconnectée à son prochain appel et se renouvelle non connectée.

Appeler le tableau

Le REST prend DPoP : Authorization: DPoP <token> plus une nouvelle preuve DPoP avec htm, htu et ath à chaque appel à /api/v1. MCP prend Bearer : renouvelez sans preuve DPoP et avec resource=https://maintenancedue.com/mcp, puis envoyez Authorization: Bearer <token> à /mcp. Un Session Token Bearer ne fonctionne que sur /mcp, et un jeton DPoP y est refusé. Les outils MCP, leurs schémas et l'en-tête MCP-Protocol-Version 2025-06-18 sont ceux qu'utilise ChatGPT.

Lire ou modifier

poppy:read ouvre chaque GET sur /api/v1 et chaque outil MCP marqué readOnlyHint, comme get_due, get_history et list_assets. poppy:write ouvre toutes les autres méthodes REST et tous les autres outils MCP, comme append_event, append_reading, create_service et set_rule, plus events/subscribe. Un scope manquant donne 403 avec error="insufficient_scope" et le scope requis dans WWW-Authenticate. Un jeton non connecté sur un appel de compte donne 403 sign_in_required. Un jeton expiré, ou émis avant la déconnexion, donne 401 invalid_token. Inviter, retirer ou quitter des membres de l'org reste réservé au jeton propre du membre.

Les connexions ChatGPT faites par /oauth/authorize avec le scope mcp, et les jetons de membre Muse existants, continuent de fonctionner comme avant. Les noms de champ sont sur skill.md, le contrat REST sur openapi.json et l'index des agents sur llms.txt.