Personal Agent Protocol в Maintenance Due

Эта страница для тех, кто создаёт личных агентов. Если вам нужно только, чтобы Muse следил за заменой масла в фургоне, скопируйте промпт на for-your-agent. Спецификация лежит на personalagentprotocol.org.

Обнаружение

GET https://maintenancedue.com/.well-known/poppy.json называет организацию (maintenancedue.com), издателя https://maintenancedue.com, Direct Sign-In с poppy:read и poppy:write и два API: MCP-сервер по адресу https://maintenancedue.com/mcp и описание OpenAPI по адресу https://maintenancedue.com/openapi.json для REST под /api/v1. Метаданные издателя на /.well-known/oauth-authorization-server перечисляют maintenancedue.com в poppy_domains и дают эндпоинты токенов, авторизации и отзыва под /oauth/.

Session и вход

1. Опубликуйте клиента. Ваш client_id это https URL, который отдаёт документ метаданных клиента, где jwks_uri и redirect_uris на том же домене. Каждый запрос токена несёт клиентское утверждение private_key_jwt, подписанное ключом из этого jwks_uri.
2. Начните Session. POST /oauth/token с grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, утверждением, где iss это ваш client_id, sub это User ID, а aud это https://maintenancedue.com/oauth/token одной строкой, плюс доказательство DPoP. Вы получите Session Token без входа (token_type DPoP, один час) и session_id. Отправьте session_id со свежим утверждением, чтобы продлить его.
3. Отправьте владельца на нашу страницу. Откройте /oauth/authorize с response_type=code, вашими client_id и redirect_uri, scope=poppy:read poppy:write (или только poppy:read), state и code_challenge PKCE S256. Владелец видит ваше имя и домен, выбирает View only или View and change, затем создаёт бесплатную мастерскую или входит с токеном участника, который у него уже есть. Перенаправление возвращает code, state и iss. Проверьте, что iss равен https://maintenancedue.com.
4. Обменяйте код. POST /oauth/token с grant_type=authorization_code, code, redirect_uri, code_verifier и вашим session_id, плюс клиентское утверждение и доказательство DPoP. В ответе Account Token в refresh_token (pat_…, 30 дней), Session Token со входом и выданный scope. Владелец может выбрать просмотр, даже если вы просили изменение, поэтому читайте scope.
5. Позже начинайте уже со входом. POST /oauth/token с grant_type=refresh_token и Account Token, с session_id или без. Добавьте scope=poppy:read, чтобы получить токен только для чтения на время поиска. Account Token не ротируется, поэтому параллельные Session могут делить его.
6. Выйдите. POST /oauth/revoke с Account Token и вашим клиентским утверждением. Каждая Session, вошедшая с ним, теряет вход при следующем вызове и продлевается без входа.

Вызов доски

REST принимает DPoP: Authorization: DPoP <token> плюс свежее доказательство DPoP с htm, htu и ath на каждом вызове /api/v1. MCP принимает Bearer: продлите без доказательства DPoP и с resource=https://maintenancedue.com/mcp, затем отправьте Authorization: Bearer <token> на /mcp. Bearer Session Token работает только на /mcp, а токен DPoP там отклоняется. Инструменты MCP, их схемы и заголовок MCP-Protocol-Version 2025-06-18 те же, что использует ChatGPT.

Просмотр или изменение

poppy:read открывает каждый GET на /api/v1 и каждый инструмент MCP с пометкой readOnlyHint, например get_due, get_history и list_assets. poppy:write открывает все остальные методы REST и инструменты MCP, например append_event, append_reading, create_service и set_rule, а также events/subscribe. Нехватка scope даёт 403 с error="insufficient_scope" и нужным scope в WWW-Authenticate. Токен без входа на вызове аккаунта даёт 403 sign_in_required. Просроченный токен или выданный до выхода даёт 401 invalid_token. Приглашение, удаление участников и выход из org остаются за собственным токеном участника.

Подключения ChatGPT через /oauth/authorize со scope mcp и существующие токены участников Muse работают как прежде. Имена полей на skill.md, контракт REST на openapi.json, индекс агентов на llms.txt.