Percher

Manage an app's collaborators (owner-only). action='list' lists collaborators + pending invites; each row's `id` is the shareId. action='invite' invites by email — role 'viewer' (read-only: analytics, deploys list, crash reports) or 'admin' (deploy + env, domains, KV, logs, PocketBase ops). An invite is PENDING until the recipient accepts; it grants no access until then, expires after 30 days, and is rate-limited to 20/h. action='set_role' changes a collaborator's role (idempotent). action='revoke' removes a collaborator or a pending invite — the recipient's next request 404s with no caching window. shareId comes from action='list'.

Put a running app to sleep. The container stops; its routes, domains, env vars and data stay exactly as they are, and the next visitor wakes it automatically (a few seconds of cold start). Use this when a deploy, wake or scale-up was refused because the account's plan allowance is in use — the refusal names which apps are holding it, and sleeping one hands its RAM and CPU back immediately. Reversible — the next request to the app's URL brings it back, no tool call needed. Not a fix for a disk refusal: a sleeping app keeps its disk. Idempotent; an app that is already asleep returns alreadySleeping=true. Returns { status, alreadySleeping, message }.

Supabase → PocketBase migration helper for Lovable / Bolt / v0 imports. Read-only against Percher — the Supabase personal access token (sbp_..., generate at https://supabase.com/dashboard/account/tokens) stays on the user's machine and is sent directly to api.supabase.com, never routed through Percher. action='inspect' introspects the source Supabase project and reports tables (user schemas only), authUsersCount, storageBuckets, and warnings up front (composite PKs, array columns, RLS policies, storage buckets needing separate migration, auth-user hash incompatibility). No file writes. Returns { status, projectRef, tables[], authUsersCount, storageBuckets[], warnings[], recovery, summary }. action='migrate_schema' runs the same introspection AND writes a migration PREVIEW to ./migration-preview/ (or outputDir): pb_schema.json (PocketBase collection-shape), MIGRATION_NOTES.md, and pb_migrate.js — a ready-to-run data-import script that copies rows from Supabase into PocketBase (reads credentials from env vars; auth users still need a password reset since bcrypt hashes don't carry over). A preview only — nothing lands in PocketBase until you run pb_migrate.js. Run action='inspect' first. Returns { status, projectRef, outputDir, filesWritten[], preview, recovery, summary }. action='rewrite_client' converts the project's Supabase SDK calls to the PocketBase SDK across every source file (auth + CRUD rewritten), plus swaps the package.json dependency and stubs .env keys — but ONLY when nothing Supabase remains (a hybrid project that still has storage/rpc/realtime/edge/un-mapped-auth calls keeps both SDKs + both env sets, which is correct; the report says so). `flags[]` lists locations still needing a human (file + line, no inline markers — also written to migration-preview/REWRITE_NOTES.md, which now starts with the same checklist as action='status'), in two kinds: kind='manual_review' was rewritten but its semantics differ (e.g. onAuthStateChange event shape, filter e…

App ownership transfer, sender side (owner-only, app-scoped). action='initiate' offers the app to another account's email; the recipient must explicitly accept for ownership to flip (offer expires after 7 days). Rate-limited to 5/h; only one pending transfer per app — TRANSFER_ALREADY_PENDING (409) otherwise. action='cancel' cancels a pending offer (transferId; only while pending). action='list' shows the app's transfer history. On accept the app moves entirely — the previous owner loses access and any connected GitHub/Forgejo webhook is disconnected (the new owner reconnects their own). action defaults to 'initiate'.

Incoming ownership transfers, recipient side (account-wide, resolved from your email). action='incoming' lists pending, unexpired offers; transferId comes from there. action='accept' makes you the owner — atomic (all checks + the ownership flip run in one transaction; if you were already an admin collaborator, that row is dropped so you become owner, not both). Failures: APP_LIMIT_REACHED (your plan won't fit one more app), APP_ADMIN_SUSPENDED, TRANSFER_EXPIRED (after 7 days), TRANSFER_NOT_PENDING (already accepted/declined/cancelled). action='decline' rejects a pending offer.

Unsuspend an app that's been auto-suspended after a failure loop. Use only AFTER fixing the underlying cause — calling unsuspend without resolving the build/runtime failure puts the app into a 1-hour cooldown where 3 more failures (instead of the standard 8) will auto-suspend it again. Returns { ok, app, flipped, summary }; flipped=false means the app was already active.

List deployment history for an app

Only use when `recovery.nextAction = 'wait_auth'` — i.e. percher_publish returned `status: 'auth_pending'` because the MCP session has no token. Pre-fetched device-code is in flight; this tool short-polls the exchange and, once a token lands, runs the original publish for the FIRST time (the auth_pending percher_publish call did NOT pack a tarball — that work is preserved entirely for the resume here, so the whole flow packs exactly one bundle). Inputs: - `deviceCode` — opaque string from `recovery.args.deviceCode` on the auth_pending response. Pass verbatim. - `publishArgs` — original `percher_publish` input flags from `recovery.args.publishArgs`. Pass verbatim. - `pollIntervalSec` — server-requested poll interval from `recovery.args.pollIntervalSec`. Pass verbatim when present; defaults to 5. Returns one of two shapes: - On success: the same `PublishResult` shape as percher_publish (status='live'/'queued'/'failed'/etc., recovery, url, deployId, ...). Follow `recovery.nextAction` exactly, same as a fresh percher_publish response. - On failure: `{ status: 'auth_failed', reason: 'expired'|'error', detail, recovery }`. `recovery.nextAction = 'open_login'` — call percher_publish again to start a fresh auth flow with a new device-code (do NOT call this tool again with the old code; it's dead). Polls at the server-requested interval (default ~5s, clamped to 1-30s) with a 2-minute total budget. Don't shorten the polling interval client-side — Percher's exchange endpoint enforces it server-side.

Only use when `recovery.nextAction = 'wait_deploy'` (e.g. percher_publish returned status='queued', or percher_doctor pointed here), or when you already have a deployId and need to know whether the deploy is live yet. Never starts a new deploy — for that use percher_publish. Short-polls a single deploy and returns within `timeoutSeconds` (default 30, max 720). The default keeps each call short so the agent can resume; the bumped max equals the platform's full publish poll budget for callers that want to ride a single build to completion. Returns one of five statuses; in every case follow `result.recovery.nextAction` literally: - `live` → deploy is up; surface result.url to the user. recovery.nextAction='none'. - `failed` → terminal failure; result.error + result.recovery describe what to do. After FUTURE12 Phase 4 ambiguous build failures (generic build_failed, missing_dependency, runtime_crash, oom_killed without file-located problems) emit recovery.nextAction='run_doctor' as the primary action — call percher_doctor with recovery.args (carries `mode='deploy'` + `deployId`) and follow doctor's recovery recursively. Direct-action recoveries still emit when publish/wait already knows the answer: `set_env_vars` (missing_env with extracted keys), `fix_problems` (build problems with file/line), `retry` (infra_unavailable), `fix_config` (config_invalid), `ask_user` (quota_exceeded / unknown). `inspect_build_log` only appears when doctor explicitly hands off after classification yielded nothing. - `replaced` → terminal-but-not-failed: this row was superseded. Resolver looked at the latest deploy and the recovery field tells you what to do next: `nextAction: 'none'` with `result.url` set means the app is currently live at that URL via a newer deploy; `nextAction: 'wait_deploy'` means a newer deploy is still in flight (call percher_wait_for_deploy with the args); `nextAction: 'run_doctor'` or `nextAction: 'ask_user'` means resolution was ambiguous (no other deploys,…

Your account's single outbound event webhook (account-level — one URL receives every event for every app you own: deploy.failed, deploy.succeeded, app.crashed, app.unhealthy, app.recovered, domain.expiring, security.finding). There is no per-app routing and no event filter — surface that honestly before saving. Use when the user says 'set up a webhook', 'notify my CI when a deploy succeeds', 'send deploy events to <url>', or after percher_publish when the user wants async deploy notifications instead of polling percher_wait_for_deploy. action='add' sets or replaces the URL. Each delivery is signed HMAC-SHA256 with a per-account secret; `result.signingSecret` carries that secret and is shown EXACTLY ONCE (null when the URL was unchanged and the existing secret was kept) — relay it verbatim, tell the user to store it on their receiver, and if the transcript could be archived recommend rotating via the dashboard after testing. The URL must be a public HTTPS endpoint — private IPs, localhost, link-local and metadata endpoints are rejected (SSRF guard). action='list' returns the current URL + whether a secret is set (never the secret itself). action='remove' clears the URL and stored secret (idempotent).

Show the signed-in user