fix: Align OAuth MCP annotations with tool behavior
Summary
Make OAuth MCP annotations describe actual tool behavior rather than defaulting every tool to open-world or inferring destructiveness from a few names.
- Require explicit read-only, destructive and open-world policy values and propagate Context operation values through full OAuth registration.
- Fill all required hints on limited OAuth tools and mark profile overwrites as destructive.
- Correct hidden-effect cases: pack reads can settle expired jobs/refund credits; export changes its timestamp; sends and public uploads have irreversible effects; catalog upserts replace metadata; paid analysis/site work changes credits. Chat compaction only computes an unsaved summary and is read-only.
- Add side-effect notices and regression coverage using real SDK discovery. All 91 full-mode registered tools, including the app-only sidebar, have explicit boolean hints. Limited business tools are checked individually.
- Document exact booleans, behavioral reasons and pinned source references for all 91 full-mode and 7 limited-mode registrations in the inventory. Correct stale pack/compaction labels in the existing qualification map.
This changes metadata and descriptions, not handlers, schemas, authorization, scopes or business behavior.
Tests
- Full repository suite on the final runtime changes: 1,460 files / 9,322 tests passed, 15 files / 45 tests skipped.
- OAuth suite: 52 files / 313 tests passed, 2 files / 5 tests skipped, after the normal extension build.
- Final strengthened SDK-discovery and limited-annotation tests: 2 files / 6 tests passed. These were strengthened after the full-suite run, then rerun on this branch.
pnpm typecheck:mcp-oauthand final direct OAuth TypeScript check passed.- Additional local checks on the exact published tree passed:
pnpm exec tsc --noEmit --project tsconfig.build.json,pnpm typecheck:response-contracts, andpnpm typecheck:release-format. pnpm lint:check, changed TypeScript formatting andgit diff --checkpassed.- New regressions were observed failing before their fixes. An independent source review found no material annotation issue.
Draft / release limitations
This is ready for code review, not an assertion that the deployed plugin is qualified for approval.
- The reviewed API baseline is
b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21. Database behavior was traced through all relevant migration definitions atebdb549d0b719a95ee7105bb9146c077841411e6; deployed database state is not verified. - Before release, compare authenticated
tools/listfrom the exact intended review endpoint in full and limited OAuth modes against the inventory. Confirm the pack-settlement migration behavior. - The separate API-key/Privy standard catalog includes additional tools and is not fully repaired by this patch. If that catalog is submitted, it needs its own audit.
- No live writes, paid generation, messages, publication, deletion or database mutations were used as test probes. Environment-gated tests remain skipped. No production build/deployment or plugin resubmission was performed.
- Existing cost/approval/retry limitations remain. Annotation hints are not authorization enforcement. The existing broad
search_webpreference language and role/message-array research input also deserve a separate submission-metadata/data-minimization review.
Deployment guard
vercel.json disables automatic deployment only for this exact branch, fix/mcp-oauth-behavior-annotations, using Vercel's branch-specific setting. Existing cron settings and every other branch's deployment behavior are unchanged. The exact guard and preservation of all prior config were checked locally. GitHub CI remains enabled. Do not remove the guard, merge, deploy or resubmit without the separate release decision.
Parallel PRs
No existing annotation-repair PR was found before starting publication. Two open PRs touch adjacent code:
- #1237 changes the Context operation type import; retain that extraction if it lands first.
- #1008 adds Context source withdrawal and optional annotation/notice metadata. Reconcile it with these required booleans, retain withdrawal's destructive flag and notice, and classify its open-world behavior explicitly. Update discovery expectations if it changes catalog membership.
Coordinator disposition: this source candidate is superseded by merged #1252, which preserves its history and adds the qualified review/composition fixes. Closing this PR avoids competing source candidates; its branch/history remain preserved. Owning-epic authenticated/native/provider/database and business acceptance remain open as separately recorded; source merge does not close those gates.