Maintenance Due 上的 Personal Agent Protocol

本页面向开发个人智能体的人。如果你只想让 Muse 按时提醒货车换机油，请复制 for-your-agent 上的提示词。规范见 personalagentprotocol.org。

发现

GET https://maintenancedue.com/.well-known/poppy.json 给出组织（maintenancedue.com）、签发方 https://maintenancedue.com、支持 poppy:read 和 poppy:write 的 Direct Sign-In，以及两个 API：位于 https://maintenancedue.com/mcp 的 MCP 服务器，和位于 https://maintenancedue.com/openapi.json 的 OpenAPI 描述（REST 在 /api/v1 下）。签发方元数据 /.well-known/oauth-authorization-server 在 poppy_domains 中列出 maintenancedue.com，并给出 /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，以及 PKCE S256 的 code_challenge。车主会看到你的名称和域名，选择 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 证明。响应中 refresh_token 是 Account 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：每次调用 /api/v1 都发送 Authorization: DPoP <token>，并附上包含 htm、htu 和 ath 的新 DPoP 证明。MCP 使用 Bearer：续期时不带 DPoP 证明，并带上 resource=https://maintenancedue.com/mcp，然后向 /mcp 发送 Authorization: Bearer <token>。Bearer Session Token 只在 /mcp 上有效，DPoP 令牌在那里会被拒绝。MCP 工具、其模式以及 MCP-Protocol-Version 2025-06-18 响应头，与 ChatGPT 使用的完全相同。

查看或修改

poppy:read 可访问 /api/v1 上的所有 GET，以及所有标记了 readOnlyHint 的 MCP 工具，例如 get_due、get_history 和 list_assets。poppy:write 可访问其他所有 REST 方法和 MCP 工具，例如 append_event、append_reading、create_service 和 set_rule，以及 events/subscribe。缺少 scope 时返回 403，WWW-Authenticate 中带有 error="insufficient_scope" 和所需的 scope。未登录的令牌调用账户操作时返回 403 sign_in_required。过期的令牌，或在退出登录前签发的令牌，返回 401 invalid_token。邀请、移除或退出组织成员仍需成员自己的令牌。

通过 /oauth/authorize 以 mcp scope 建立的 ChatGPT 连接，以及已有的 Muse 成员令牌，都照常可用。字段名见 skill.md，REST 契约见 openapi.json，智能体索引见 llms.txt。