Personal Agent Protocol di Maintenance Due

Halaman ini untuk orang yang membuat agen pribadi. Jika Anda hanya ingin Muse menjaga jadwal oli van, salin prompt di for-your-agent. Spesifikasinya ada di personalagentprotocol.org.

Penemuan

GET https://maintenancedue.com/.well-known/poppy.json menyebut organisasi (maintenancedue.com), penerbit https://maintenancedue.com, Direct Sign-In dengan poppy:read dan poppy:write, serta dua API: server MCP di https://maintenancedue.com/mcp dan deskripsi OpenAPI di https://maintenancedue.com/openapi.json untuk REST di bawah /api/v1. Metadata penerbit di /.well-known/oauth-authorization-server mencantumkan maintenancedue.com di poppy_domains dan memberi endpoint token, otorisasi, dan pencabutan di bawah /oauth/.

Session dan masuk

1. Terbitkan klien Anda. client_id Anda adalah URL https yang menyajikan dokumen metadata klien, dengan jwks_uri dan redirect_uris di domain yang sama. Setiap permintaan token membawa asersi klien private_key_jwt yang ditandatangani dengan kunci dari jwks_uri itu.
2. Mulai Session. POST /oauth/token dengan grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, asersi dengan iss berisi client_id Anda, sub berisi User ID, dan aud berisi https://maintenancedue.com/oauth/token sebagai satu string, ditambah bukti DPoP. Anda menerima Session Token belum masuk (token_type DPoP, satu jam) dan session_id. Kirim session_id dengan asersi baru untuk memperbaruinya.
3. Arahkan pemilik ke halaman kami. Buka /oauth/authorize dengan response_type=code, client_id dan redirect_uri Anda, scope=poppy:read poppy:write (atau hanya poppy:read), sebuah state, dan code_challenge PKCE S256. Pemilik melihat nama dan domain Anda, memilih View only atau View and change, lalu membuat bengkel gratis atau masuk dengan token anggota yang sudah dimilikinya. Pengalihan mengembalikan code, state, dan iss. Pastikan iss adalah https://maintenancedue.com.
4. Tukar kodenya. POST /oauth/token dengan grant_type=authorization_code, code, redirect_uri, code_verifier, dan session_id Anda, ditambah asersi klien dan bukti DPoP. Respons berisi Account Token di refresh_token (pat_…, 30 hari), Session Token yang sudah masuk, dan scope yang diberikan. Pemilik bisa memilih lihat saat Anda meminta ubah, jadi baca scope.
5. Mulai dalam keadaan masuk di lain waktu. POST /oauth/token dengan grant_type=refresh_token dan Account Token, dengan atau tanpa session_id. Tambahkan scope=poppy:read untuk token baca saja saat sekadar mencari data. Account Token tidak dirotasi, sehingga beberapa Session paralel bisa berbagi.
6. Keluar. POST /oauth/revoke dengan Account Token dan asersi klien Anda. Setiap Session yang masuk dengannya keluar pada panggilan berikutnya dan diperbarui dalam keadaan belum masuk.

Memanggil papan

REST memakai DPoP: Authorization: DPoP <token> ditambah bukti DPoP baru dengan htm, htu, dan ath di setiap panggilan ke /api/v1. MCP memakai Bearer: perbarui tanpa bukti DPoP dan dengan resource=https://maintenancedue.com/mcp, lalu kirim Authorization: Bearer <token> ke /mcp. Session Token Bearer hanya berlaku di /mcp, dan token DPoP ditolak di sana. Alat MCP, skemanya, dan header MCP-Protocol-Version 2025-06-18 sama dengan yang dipakai ChatGPT.

Lihat atau ubah

poppy:read membuka setiap GET di /api/v1 dan setiap alat MCP bertanda readOnlyHint, seperti get_due, get_history, dan list_assets. poppy:write membuka semua metode REST dan alat MCP lainnya, seperti append_event, append_reading, create_service, dan set_rule, ditambah events/subscribe. Scope yang kurang menghasilkan 403 dengan error="insufficient_scope" dan scope yang dibutuhkan di WWW-Authenticate. Token belum masuk pada panggilan akun menghasilkan 403 sign_in_required. Token kedaluwarsa, atau yang terbit sebelum keluar, menghasilkan 401 invalid_token. Mengundang, menghapus, atau keluar dari keanggotaan org tetap memakai token milik anggota itu sendiri.

Koneksi ChatGPT yang dibuat lewat /oauth/authorize dengan scope mcp, dan token anggota Muse yang sudah ada, tetap bekerja seperti sebelumnya. Nama field ada di skill.md, kontrak REST di openapi.json, dan indeks agen di llms.txt.