diff --git a/docs/mcp-oauth-annotations.md b/docs/mcp-oauth-annotations.md new file mode 100644 index 000000000..043b00822 --- /dev/null +++ b/docs/mcp-oauth-annotations.md @@ -0,0 +1,151 @@ +# OAuth MCP annotation behavior inventory + +Source baseline: API `b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21`, November 9, 2026. This inventory documents the proposed explicit annotations, not the deployed endpoint or a release approval. Handler behavior, schemas, authentication and scopes are unchanged. + +The full OAuth registry contains 89 business tools and two workflow UI entrypoints (91 registered, 90 model-visible). The limited registry contains five business tools and the same two UI entrypoints (7 registered, 6 model-visible). The sidebar entrypoint is app-only. Two legacy deep-research aliases remain in internal policy but are excluded from the full registry. The separate API-key/Privy standard registry has additional tools and is not fully remediated here. + +## Classification rules + +The [OpenAI plugin guidelines](https://developers.openai.com/plugins/plugin-guidelines#correct-annotation) require explicit `readOnlyHint`, `destructiveHint` and `openWorldHint` booleans. These classifications follow business behavior, not names or HTTP verbs: + +- `readOnlyHint=true`: retrieval or computation without saving, sending, starting jobs or otherwise changing business state. +- `destructiveHint=true`: an operation can replace/delete/cancel existing state, irreversibly send or publicly disclose information, or change charged/held account credits. Purely additive private writes remain false. +- `openWorldHint=true`: public/open-ended entities, arbitrary fetched URLs, public disclosure or arbitrary destinations. Network use alone does not make a fixed-provider, private-workspace operation open-world. +- Authentication, rate-limit counters and operational telemetry are distinguished from the business action. These hints do not establish idempotency, cost ceilings or an approval record. + +A tool with multiple paths uses the more consequential classification supported by any path. + +## Database-backed effects + +Database source snapshot: `ebdb549d0b719a95ee7105bb9146c077841411e6`. All migration definitions of the relevant functions were searched; these are repository observations, not verification of deployed migrations. + +- [Release pack command](https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261020150000_release_pack_jobs.sql#L49-L166) settles expired running jobs even on `read`, changes asset/job state and refunds held credits. Therefore `get_release_pack` is a write with destructive effects. Export also updates `exported_at`; prepare and estimate can replace pack state. Generate/retry use private snapshots, while estimate and asset upload can fetch arbitrary URLs. +- [Release review receipts](https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261008160000_context_release_cases.sql#L131-L152) are immutable/idempotent inserts, not replacements. +- [Brief snapshots](https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261010010000_context_company_assessment.sql#L31-L66) remain immutable/idempotent inserts in the later company-assessment definition. + +## Full OAuth inventory + +Columns `R`, `D` and `O` mean `readOnlyHint`, `destructiveHint` and `openWorldHint`, respectively. Source links are pinned to the inspected behavior baseline; policies in this branch supply the corrected metadata. + +| Tool | R | D | O | Behavioral justification | Source | +| --- | --- | --- | --- | --- | --- | +| `analyze_music` | false | true | true | Fetches an arbitrary supplied audio URL or attachment, performs analysis, and deducts account credits after successful model calls. That credit transaction makes it destructive even though it returns an analysis. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/flamingo/processAnalyzeMusicRequest.ts) | +| `compact_chats` | true | false | false | Selects authorized saved messages and computes a summary with a tool-free model. Returns text without saving the summary, compacting storage or deleting source messages. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/chats/compactChat.ts) | +| `compile_music_context_brief` | true | false | false | Compile a creative direction, playlist pitch or company onboarding (company_onboarding) brief from selected saved context without saving a snapshot. Company onboarding is a bounded assessment with evidence gaps, not confirmation of company facts, rights or workspace authority. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `contact_team` | false | true | false | Immediately sends a Telegram message to Recoup’s configured support destination. The send is irreversible, but the recipient is fixed, not an arbitrary address. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/contact/contactTeam.ts) | +| `create_knowledge_base` | false | true | true | Uploads submitted text to public media storage, creating public-by-URL exposure rather than a private scratch note. New writes are public even though old Arweave references remain readable. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/artist/createKnowledgeBase.ts) | +| `create_new_artist` | false | false | false | Adds a new workspace/artist record and ownership link; does not replace a previous artist or publish content. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/artists/createArtistInDb.ts) | +| `create_release_player` | false | true | true | Adds a player, but enabled=true also publishes it. Classifies the entire accepted schema, including that irreversible public-disclosure path. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/players/processPlayerOperation.ts) | +| `create_site` | false | false | true | Adds a private draft and fetches a public Spotify release from its URL. No previous draft is overwritten or published. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `create_task` | false | false | false | Creates an account-owned scheduled action and its Trigger schedule. This is stateful scheduled work, not a read, but creates rather than replaces a schedule; this tool itself does not execute arbitrary destinations. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/tasks/createTask.ts) | +| `delete_site` | false | true | true | Publishes/replaces public snapshot, removes public access, or deletes the site and associated records. Each action can remove/overwrite existing state or disclose content publicly. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `delete_task` | false | true | false | Deletes the saved task and cancels its schedule; limited to account-owned task resources. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/tasks/deleteTask.ts) | +| `edit_image` | false | true | true | Creates a new image and uploads it to public media storage, also attempting to create a moment. Public disclosure can have irreversible effects; edit retains the original but still publishes the new result. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/image/uploadImageAndCreateMoment.ts) | +| `estimate_release_pack` | false | true | true | Fetches arbitrary supplied source media into private storage, replaces quote and planned assets, and persists the estimate. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/content/packs/processPackOperation.ts ; https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261020150000_release_pack_jobs.sql) | +| `expand_music_context_catalog` | false | false | false | Save context subjects for a page of catalog recordings. Creates retained context/receipt data without replacing existing records or publishing it. Submitted names/URLs remain saved assertions; this action does not dereference them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `export_release_pack` | false | true | false | Overwrites exported_at on the saved job; may also auto-settle an expired running job and refund held credits. Returns private authorized download links, not publication. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/content/packs/processPackOperation.ts ; https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261020150000_release_pack_jobs.sql) | +| `generate_image` | false | true | true | Creates a new image and uploads it to public media storage, also attempting to create a moment. Public disclosure can have irreversible effects; edit retains the original but still publishes the new result. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/image/uploadImageAndCreateMoment.ts) | +| `generate_release_pack` | false | true | false | Commits approved paid generation/credit holds and updates saved job/assets. Inputs and outputs are private account-owned snapshots; fixed generation providers alone do not make the operation open-world. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/content/packs/processPackOperation.ts) | +| `generate_site` | false | true | true | Collects public context, runs charged generation, and replaces the saved site draft. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `generate_sora_2_video` | false | false | false | Creates a new provider video-generation job; no source replacement or public publishing path is exposed here. The OAuth result is an account-bound job locator. Provider compute alone is not a separate customer-credit debit in this handler. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/video/generateVideo.ts) | +| `generate_txt_file` | false | true | true | Uploads submitted text to public media storage, creating public-by-URL exposure rather than a private scratch note. New writes are public even though old Arweave references remain readable. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/files/generateAndStoreTxtFile.ts) | +| `get_artist_socials` | true | false | false | Reads already-saved artist/social associations; does not collect new public profiles or change them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/artist/getArtistSocials.ts) | +| `get_chats` | true | false | false | Reads authorized saved chat summaries; no persistence; bounded account resources. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/chats/registerGetChatsTool.ts) | +| `get_daily_email_status` | true | false | false | Reads the connected account’s saved daily-email preference; no messages sent or preference change. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/pulse/registerGetPulsesTool.ts) | +| `get_local_time` | true | false | false | Computes local clock/date output without saving data or addressing outside entities. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/registerGetLocalTimeTool.ts) | +| `get_release_pack` | false | true | false | A nominal read can settle an expired running job: changes asset/job status, clears holds and refunds wallet credits. Not read-only; bounded private pack. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/content/packs/processPackOperation.ts ; https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261020150000_release_pack_jobs.sql) | +| `get_release_player` | true | false | false | Reads authorized saved player configuration, private fan records or reported activity. Returning an existing share URL does not publish or change it. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/players/processPlayerOperation.ts) | +| `get_release_player_activity` | true | false | false | Reads authorized saved player configuration, private fan records or reported activity. Returning an existing share URL does not publish or change it. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/players/processPlayerOperation.ts) | +| `get_release_player_fans` | true | false | false | Reads authorized saved player configuration, private fan records or reported activity. Returning an existing share URL does not publish or change it. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/players/processPlayerOperation.ts) | +| `get_site` | true | false | false | Reads saved site state, private signups or a generation status within authorized workspace; does not publish, generate or alter a draft. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `get_site_generation` | true | false | false | Reads saved site state, private signups or a generation status within authorized workspace; does not publish, generate or alter a draft. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `get_site_signups` | true | false | false | Reads saved site state, private signups or a generation status within authorized workspace; does not publish, generate or alter a draft. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `get_spotify_album` | true | false | true | Retrieves/searches Spotify’s public catalog, including arbitrary public artists, albums and tracks; no saved business-state changes. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/spotify/registerGetSpotifyAlbumTool.ts) | +| `get_spotify_artist_albums` | true | false | true | Retrieves/searches Spotify’s public catalog, including arbitrary public artists, albums and tracks; no saved business-state changes. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/spotify/registerGetSpotifyArtistAlbumsTool.ts) | +| `get_spotify_artist_top_tracks` | true | false | true | Retrieves/searches Spotify’s public catalog, including arbitrary public artists, albums and tracks; no saved business-state changes. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/spotify/registerGetSpotifyArtistTopTracksTool.ts) | +| `get_spotify_search` | true | false | true | Retrieves/searches Spotify’s public catalog, including arbitrary public artists, albums and tracks; no saved business-state changes. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/spotify/registerGetSpotifySearchTool.ts) | +| `get_task_run_status` | true | false | false | Reads only a caller-owned provider run through the ownership-aware OAuth adapter; no new work. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/oauth/executeFullOAuthTool.ts) | +| `get_tasks` | true | false | false | Selects existing account-owned schedules without changing the schedule or starting a task. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/tasks/registerGetTasksTool.ts) | +| `get_workspace_player_fans` | true | false | false | Reads authorized saved player configuration, private fan records or reported activity. Returning an existing share URL does not publish or change it. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/players/processPlayerOperation.ts) | +| `get_youtube_revenue` | true | false | false | Queries existing analytics for the connected, authorized YouTube account; no change to video/channel/revenue state. External hosting does not make this open-world. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/youtube/registerGetYouTubeRevenueTool.ts) | +| `import_artist_context` | false | false | false | Create a context request from an artist you can access. Creates retained context/receipt data without replacing existing records or publishing it. Submitted names/URLs remain saved assertions; this action does not dereference them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `import_catalog_context` | false | false | false | Create a context request from a catalog you can access. Creates retained context/receipt data without replacing existing records or publishing it. Submitted names/URLs remain saved assertions; this action does not dereference them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `import_music_campaign_brief` | false | false | false | Save a structured music campaign brief as context. Creates retained context/receipt data without replacing existing records or publishing it. Submitted names/URLs remain saved assertions; this action does not dereference them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `import_music_company_context` | false | false | false | Create a context request from a submitted music company name. A name is not verified identity. Creates retained context/receipt data without replacing existing records or publishing it. Submitted names/URLs remain saved assertions; this action does not dereference them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `import_music_release_context` | false | false | false | Create a context request from a Spotify release URL. Creates retained context/receipt data without replacing existing records or publishing it. Submitted names/URLs remain saved assertions; this action does not dereference them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `import_music_supporting_text` | false | false | false | Save specifically selected supporting music material as context. Supply only material the account asked to save, never conversation history. Creates retained context/receipt data without replacing existing records or publishing it. Submitted names/URLs remain saved assertions; this action does not dereference them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `import_song_context` | false | false | true | Collect and save music context for a Spotify track URL and selected research topics. Starts collection and adds saved provider observations; no overwrite, publication or customer charge found. It queries public Spotify entities. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `import_songwriter_context` | false | false | false | Create a context request from a submitted songwriter name. A name is not verified identity. Creates retained context/receipt data without replacing existing records or publishing it. Submitted names/URLs remain saved assertions; this action does not dereference them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `insert_catalog_songs` | false | true | true | Fetches public Spotify metadata and upserts existing song rows by ISRC before adding catalog links, so it can overwrite prior song metadata. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/songs/processSongsInput.ts) | +| `list_artists` | true | false | false | Reads the authenticated account’s accessible artists; no business-state mutation; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/artists/getArtists.ts) | +| `list_music_context_catalog_members` | true | false | false | Read a page of saved catalog recordings. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `list_music_context_executions` | true | false | false | List research executions for a saved music context request. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `list_music_context_release_tracks` | true | false | false | Read a page of saved release track slots. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `list_music_release_cases` | true | false | false | List saved release cases and their review status. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `list_release_player` | true | false | false | Reads authorized saved player configuration, private fan records or reported activity. Returning an existing share URL does not publish or change it. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/players/processPlayerOperation.ts) | +| `list_sites` | true | false | false | Reads saved site state, private signups or a generation status within authorized workspace; does not publish, generate or alter a draft. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `open_recoup_workflows` | true | false | false | Returns the static Recoup workflow-library UI; no account change, job creation or external entity lookup. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/extension/registerRecoupExtension.ts) | +| `open_recoup_workflows_sidebar` | true | false | false | App-only sidebar entrypoint for the same static workflow UI; no business-state mutation or outside entity lookup. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/extension/registerRecoupExtension.ts) | +| `plan_music_catalog_research` | true | false | false | Preview research modules for a page of saved catalog recordings without running them. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `plan_music_context_research` | true | false | false | Preview research modules for saved music context without running them. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `prepare_release_pack` | false | true | false | May revise an existing saved pack: deletes pending assets and replaces brief, quote and context; private account-owned pack. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/content/packs/processPackOperation.ts ; https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261020150000_release_pack_jobs.sql) | +| `propose_site_concepts` | false | true | true | Collects public release/artist context and incurs nonrefundable generation credit usage. Does not itself overwrite the site draft. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/production/generateProductionObject.ts) | +| `publish_site` | false | true | true | Publishes/replaces public snapshot, removes public access, or deletes the site and associated records. Each action can remove/overwrite existing state or disclose content publicly. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `read_music_context` | true | false | false | Read the status and results of a saved music context request. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `read_music_context_brief` | true | false | false | Read a previously saved music brief. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `read_music_context_execution` | true | false | false | Read the status and results of a saved research execution. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `read_music_release_case` | true | false | false | Read a saved release case and its evidence. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `read_music_release_case_review` | true | false | false | Read a saved release case review. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `read_music_release_track_observations` | true | false | false | Read saved release track observations and evidence. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `record_music_release_case_review` | false | false | false | Inserts a new review receipt. Reused idempotency key returns the existing identical receipt or rejects different inputs. Does not overwrite prior review decisions; private saved case. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts ; https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261008160000_context_release_cases.sql#L131-L152) | +| `retrieve_sora_2_video` | true | false | false | Reads a completed/existing provider job or its bytes using an account-bound signed video locator; no upload or new generation. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/oauth/executeFullOAuthTool.ts) | +| `retrieve_sora_2_video_content` | true | false | false | Reads a completed/existing provider job or its bytes using an account-bound signed video locator; no upload or new generation. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/oauth/executeFullOAuthTool.ts) | +| `retry_release_pack` | false | true | false | Commits approved paid generation/credit holds and updates saved job/assets. Inputs and outputs are private account-owned snapshots; fixed generation providers alone do not make the operation open-world. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/content/packs/processPackOperation.ts) | +| `review_music_release_track_identities` | true | false | false | Read the identity review for saved release tracks. Does not approve rights. Retrieves or computes from saved authorized context without saving, queuing collection, or altering records; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `save_music_context_brief` | false | false | false | Compiles and inserts an immutable private brief snapshot. An existing matching idempotency key returns the prior snapshot; differing content rejects. No overwrite/publication. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts ; https://github.com/recoupable/database/blob/ebdb549d0b719a95ee7105bb9146c077841411e6/supabase/migrations/20261010010000_context_company_assessment.sql#L31-L66) | +| `search_google_images` | true | false | true | Retrieves or computes research from open-ended public web sources; no saved artifact or stateful job in the inspected handler. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/search/registerSearchGoogleImagesTool.ts) | +| `search_web` | true | false | true | Retrieves or computes research from open-ended public web sources; no saved artifact or stateful job in the inspected handler. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/search/registerSearchWebTool.ts) | +| `select_catalog_songs` | true | false | false | Reads bounded catalogs and saved catalog-song records the account can access; no collection or mutation. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/catalogs/registerGetCatalogSongsTool.ts) | +| `select_catalogs` | true | false | false | Reads bounded catalogs and saved catalog-song records the account can access; no collection or mutation. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/catalogs/registerGetCatalogsTool.ts) | +| `send_email` | false | true | true | Immediately sends email through Resend to supplied permitted recipients; irreversible outbound communication and open-ended destinations. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/registerSendEmailTool.ts) | +| `set_daily_email_status` | false | true | false | Overwrites the connected account’s email preference, including disabling/cancelling future daily updates. Does not immediately send an email. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/pulse/registerUpdatePulseTool.ts) | +| `transcribe_audio` | false | false | true | Fetches arbitrary audio URL, transcribes, and adds original-audio and transcript files using fresh timestamped names. No overwrite/public-publication or customer-credit debit was found in this path. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/transcribe/processAudioTranscription.ts) | +| `unpublish_site` | false | true | true | Publishes/replaces public snapshot, removes public access, or deletes the site and associated records. Each action can remove/overwrite existing state or disclose content publicly. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/sites/processSiteOperation.ts) | +| `update_account_info` | false | true | false | Overwrites existing artist profile fields/knowledge references in the authorized account, without fetching the supplied image/link. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/artist/updateArtistProfile.ts) | +| `update_artist_socials` | false | true | false | Deletes existing associations for changed platforms and inserts their replacements, with saved social-row upserts. Does not fetch or post to the social sites. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/artist/updateArtistSocials.ts) | +| `update_release_player` | false | true | true | Replaces saved player configuration and can publish/unpublish; invalidates active listening sessions. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/players/processPlayerOperation.ts) | +| `update_task` | false | true | false | Replaces existing task fields and may reschedule, disable or replace its Trigger schedule within the account. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/tasks/updateTask.ts) | +| `upload_release_pack_asset` | false | false | true | Imports supplied HTTPS/file bytes to a fresh UUID object in private storage; additive, no overwrite. Arbitrary input URLs make it open-world. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/content/packs/uploadPackAsset.ts) | +| `upload_site_asset` | false | true | true | Uploads a fresh UUID object to public site-assets storage and returns a public URL. Additive object creation still discloses the content publicly. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/supabase/storage/uploadSiteAsset.ts) | +| `verify_music_release` | false | false | true | Start provider verification for a saved release context request. Starts collection and adds saved provider observations; no overwrite, publication or customer charge found. It queries public Spotify entities. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `verify_music_release_tracks` | false | false | true | Start provider verification of saved release tracks and save resulting observations. Starts collection and adds saved provider observations; no overwrite, publication or customer charge found. It queries public Spotify entities. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/context/processContextOperation.ts) | +| `web_deep_research` | true | false | true | Retrieves or computes research from open-ended public web sources; no saved artifact or stateful job in the inspected handler. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/tools/registerWebDeepResearchTool.ts) | + +## Limited OAuth inventory + +| Tool | R | D | O | Behavioral justification | Source | +| --- | --- | --- | --- | --- | --- | +| `list_artists` | true | false | false | Reads the authenticated account’s accessible artists; no business-state mutation; bounded private workspace. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/oauth/createOAuthToolServices.ts) | +| `create_new_artist` | false | false | false | Adds a new workspace/artist record and ownership link; does not replace a previous artist or publish content. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/oauth/createOAuthToolServices.ts) | +| `update_account_info` | false | true | false | Overwrites existing artist profile fields/knowledge references in the authorized account, without fetching the supplied image/link. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/oauth/createOAuthToolServices.ts) | +| `get_artist_socials` | true | false | false | Reads already-saved artist/social associations; does not collect new public profiles or change them. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/oauth/createOAuthToolServices.ts) | +| `get_chats` | true | false | false | Reads authorized saved chat summaries; no persistence; bounded account resources. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/oauth/createOAuthToolServices.ts) | +| `open_recoup_workflows` | true | false | false | Returns the static Recoup workflow-library UI; no account change, job creation or external entity lookup. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/extension/registerRecoupExtension.ts) | +| `open_recoup_workflows_sidebar` | true | false | false | App-only sidebar entrypoint for the same static workflow UI; no business-state mutation or outside entity lookup. | [source](https://github.com/recoupable/api/blob/b371f5ed2f2cda150de6156d5a3d6b0c5f7afb21/lib/mcp/extension/registerRecoupExtension.ts) | + +## Validation and limits + +- Regression tests first reproduced blanket open-world annotations, missing limited-mode booleans, and the incorrect pack-read classification. +- Full repository suite on the final runtime changes: 1,460 files and 9,322 tests passed; 15 files and 45 tests skipped. +- OAuth suite: 52 files and 313 tests passed; two files and five tests skipped. A fresh checkout first needed the normal extension build; the suite passed after that step. +- The final test-only strengthening includes both workflow UI entrypoints in actual SDK discovery: two focused files and six tests passed. Every full-mode tool has all three explicit booleans; semantic assertions independently cover key classifications. Limited-mode tests cover all five business tools. +- `pnpm lint:check`, `pnpm typecheck:mcp-oauth`, changed-file formatting and `git diff --check` passed. +- No live sends, paid generation, publication, deletion or database writes were used as test probes. Environment-gated integration/database tests remain skipped. A production build, deployed migration state and authenticated production `tools/list` were not verified. + +Before any release or resubmission, compare authenticated `tools/list` from the exact review endpoint in both OAuth modes with this inventory, including the app-only sidebar. Confirm deployed database behavior, especially pack settlement. If the review endpoint exposes the API-key/Privy standard registry, audit that separate catalog too. + +Existing cost, approval and replay limitations in [the delegated-tool qualification map](mcp-oauth-tool-qualification.md) remain open. These annotations neither enforce authorization nor claim that every operation is safe to retry. + +## Draft branch deployment guard + +`vercel.json` disables automatic deployments only for `fix/mcp-oauth-behavior-annotations`, using Vercel's documented [branch-specific deployment control](https://vercel.com/docs/project-configuration/git-configuration#git.deploymentEnabled). All other branches retain their existing behavior. This lets review and GitHub CI proceed without creating a preview deployment. Removing the guard or deploying the branch requires a separate release decision. diff --git a/docs/mcp-oauth-tool-qualification.md b/docs/mcp-oauth-tool-qualification.md index 05db897fe..428852356 100644 --- a/docs/mcp-oauth-tool-qualification.md +++ b/docs/mcp-oauth-tool-qualification.md @@ -2,6 +2,8 @@ Source baseline: API `57c7f1ea5dc9b2d3d6ef26b202735b70c6db1909`, October 26, 2026. This is a source-bound qualification map for [Mono #212](https://github.com/recoupable/mono/issues/212), not a grant of new authority or a claim that every operation is safe to retry. It enumerates every public operation derived from the existing full-scope policy and delegated Context action map, including aliases. It does not add a fixed-count discovery test. +Annotation refresh, November 9, 2026: the [current three-hint inventory](mcp-oauth-annotations.md) supersedes annotation labels and catalog membership in this historical map. Pack read/export and chat-compaction labels below have been corrected from traced behavior. The cost, authorization and retry qualifications remain source-bound; this does not requalify production behavior. + ## Common execution boundary Every row inherits [registerFullOAuthTools](../lib/mcp/oauth/registerFullOAuthTools.ts): reverify the token at call time; require current `mcp:tools`, matching account, client and grant; strict-parse exposed arguments; reject caller `account_id`; bind any internal owner field and Context action on the server. [prepareFullOAuthTool](../lib/mcp/oauth/prepareFullOAuthTool.ts) consumes the shared rate budget, then checks applicable task, artist, organization, catalog, room and recipient references before the business callback. [executeFullOAuthTool](../lib/mcp/oauth/executeFullOAuthTool.ts) adds task-run and Sora locator boundaries. These are sequential checks, not a transaction or a guarantee against authorization changes during an in-flight call. @@ -15,12 +17,12 @@ Each source link identifies the registration callback or shared domain/executor | Public operation | Annotation | Effect and gate | Cost/approval | Recipient/destination | Retry qualification | Source | | --- | --- | --- | --- | --- | --- | --- | | `prepare_release_pack` | W | Save/revise pack brief; no generation | No spend per manifest | Private pack workspace | Domain command/revision semantics; no new guarantee here | [source](../lib/mcp/tools/packs/index.ts) | -| `get_release_pack` | RO | Read saved pack/export private download links | No generation per manifest | Private download recipient; no publish | Repeat read; external billing/retry behavior remains unqualified | [source](../lib/mcp/tools/packs/index.ts) | +| `get_release_pack` | W | Read pack; expired running jobs can settle and refund held credits | No new generation; settlement can change credits | Private download recipient; no publish | Settlement mutates job/assets; not a pure repeatable read | [source](../lib/mcp/tools/packs/index.ts) | | `estimate_release_pack` | W | Save complete quote; may import source assets; optional targeted retry quote | Quote only per manifest; no spend | Private pack workspace | Revision/quote-bound; re-estimate before paid retry | [source](../lib/mcp/tools/packs/index.ts) | | `generate_release_pack` | W | Generate after current quote/revision/budget checks | Explicit quote + approved maximum + credit gate | Private outputs; never publish | Accepted command/provider receipt behavior belongs to Packs qualification | [source](../lib/content/packs/processPackOperation.ts) | | `retry_release_pack` | W | Resume uncertain accepted receipt or approve targeted failed-asset retry | Fresh targeted quote for new paid retry; receipt-backed resume | Private outputs; never publish | Missing/ambiguous receipt rejected; RPC/provider guarantees remain Packs-owned | [source](../lib/content/packs/processPackOperation.ts) | | `upload_release_pack_asset` | W | Selected file import/private signed transfer/finalize | Storage/network cost not qualified | Private workspace object | Transfer/finalize contract; no automatic generation | [source](../lib/mcp/tools/packs/index.ts) | -| `export_release_pack` | RO | Read pack then issue export domain command; return private links/manifest | No generation per manifest | Private download recipient; no publish | Export marking/RPC replay behavior not qualified | [source](../lib/content/packs/processPackOperation.ts) | +| `export_release_pack` | W | Read/settle pack then update export timestamp; return private links/manifest | No generation per manifest | Private download recipient; no publish | Export marking/RPC replay behavior not qualified | [source](../lib/content/packs/processPackOperation.ts) | | `list_artists` | RO | Read accessible artists | Unknown: no per-call quote/ceiling established at this boundary | No outbound recipient; authenticated response only | Repeat read; external billing/retry behavior remains unqualified | [source](../lib/mcp/oauth/registerFullOAuthTools.ts) | | `get_artist_socials` | RO | Read stored artist socials; artist gate when ID supplied | Unknown: no per-call quote/ceiling established at this boundary | No outbound recipient; authenticated response only | Repeat read; external billing/retry behavior remains unqualified | [source](../lib/mcp/tools/artistSocials/registerGetArtistSocialsTool.ts) | | `artist_deep_research` | RO | Read stored artist socials; artist gate when ID supplied | Unknown: no per-call quote/ceiling established at this boundary | No outbound recipient; authenticated response only | Repeat read; external billing/retry behavior remains unqualified | [source](../lib/mcp/tools/registerArtistDeepResearchTool.ts) | @@ -61,7 +63,7 @@ Each source link identifies the registration callback or shared domain/executor | `update_task` | W | Exact delegated task owner before shared update domain | Unknown: no per-call quote/ceiling established at this boundary | Future task effects not qualified | Unknown: no wrapper idempotency/accepted-work guarantee | [source](../lib/mcp/tools/tasks/registerUpdateTaskTool.ts) | | `delete_task` | W | Exact delegated owner before shared domain; Trigger schedule and DB delete | Unknown: no per-call quote/ceiling established at this boundary | Trigger scheduler + database; no email | Parallel deletions are not atomic; retry after partial failure unqualified | [source](../lib/mcp/tools/tasks/registerDeleteTaskTool.ts) | | `insert_catalog_songs` | W | Authorize every catalog in batch before insertion | Unknown: no per-call quote/ceiling established at this boundary | No outbound recipient; authenticated response only | Unknown: no wrapper idempotency/accepted-work guarantee | [source](../lib/mcp/tools/catalogs/registerInsertCatalogSongsTool.ts) | -| `compact_chats` | W | Authorize every room owner before compaction | AI compaction possible; quote/ceiling unknown | No outbound recipient; authenticated response only | Unknown: no wrapper idempotency/accepted-work guarantee | [source](../lib/mcp/tools/chats/registerCompactChatsTool.ts) | +| `compact_chats` | RO | Authorize every room owner; return unsaved computed summary | AI compaction possible; quote/ceiling unknown | No outbound recipient; authenticated response only | No chat state saved/replaced; recomputation may differ | [source](../lib/mcp/tools/chats/registerCompactChatsTool.ts) | | `generate_image` | W | Image model then public media storage/moment | Provider generation; quote/ceiling unknown | Public media; no exact publication approval token at wrapper | Unknown: no wrapper idempotency/accepted-work guarantee | [source](../lib/mcp/tools/images/registerGenerateImageTool.ts) | | `edit_image` | W | Image model then public media storage/moment | Provider generation; quote/ceiling unknown | Public media; no exact publication approval token at wrapper | Unknown: no wrapper idempotency/accepted-work guarantee | [source](../lib/mcp/tools/images/registerEditImageTool.ts) | | `generate_sora_2_video` | W | Validate locator config before provider generation; sign returned ID | Paid provider operation; no wrapper budget approval token | OpenAI provider; returned ID account-bound | Do not resubmit ambiguous generation; retrieval locator is not idempotency | [source](../lib/mcp/oauth/executeFullOAuthTool.ts) | diff --git a/lib/mcp/oauth/__tests__/fullOAuthCatalog.test.ts b/lib/mcp/oauth/__tests__/fullOAuthCatalog.test.ts index 47cb0f187..3155b12ab 100644 --- a/lib/mcp/oauth/__tests__/fullOAuthCatalog.test.ts +++ b/lib/mcp/oauth/__tests__/fullOAuthCatalog.test.ts @@ -5,6 +5,7 @@ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; import { registerFullOAuthTools } from "../registerFullOAuthTools"; import { contextToolOperations } from "../contextToolOperations"; import { fullOAuthToolPolicy } from "../fullOAuthToolPolicy"; +import { registerRecoupExtension } from "../../extension/registerRecoupExtension"; vi.mock("@/lib/supabase/serverClient", () => ({ default: {} })); vi.hoisted(() => { process.env.PRIVY_PROJECT_SECRET = "test"; @@ -33,6 +34,7 @@ it("discovers the entire delegated catalog over the real MCP SDK", async () => { ).toEqual([...standardOnlyContextActions].sort()); const server = new McpServer({ name: "recoup-test", version: "1" }); registerFullOAuthTools(server, vi.fn(), { prepare: vi.fn(), listArtists: vi.fn() }); + registerRecoupExtension(server); const client = new Client({ name: "test", version: "1" }); const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); await server.connect(serverTransport); @@ -50,6 +52,8 @@ it("discovers the entire delegated catalog over the real MCP SDK", async () => { "spotify_deep_research", ].includes(name), ), + "open_recoup_workflows", + "open_recoup_workflows_sidebar", "get_daily_email_status", "set_daily_email_status", ...Object.entries(contextToolOperations) @@ -58,7 +62,41 @@ it("discovers the entire delegated catalog over the real MCP SDK", async () => { ].sort(), ); for (const tool of tools) expect(tool.inputSchema.properties).not.toHaveProperty("account_id"); - expect(tools).toHaveLength(89); + expect(tools).toHaveLength(91); + for (const tool of tools) { + for (const hint of ["readOnlyHint", "destructiveHint", "openWorldHint"] as const) + expect(typeof tool.annotations?.[hint], `${tool.name}.${hint}`).toBe("boolean"); + } + const expectedAnnotations: Record = { + list_artists: [true, false, false], + get_tasks: [true, false, false], + get_youtube_revenue: [true, false, false], + search_web: [true, false, true], + send_email: [false, true, true], + contact_team: [false, true, false], + compact_chats: [true, false, false], + generate_image: [false, true, true], + edit_image: [false, true, true], + analyze_music: [false, true, true], + insert_catalog_songs: [false, true, true], + read_music_context: [true, false, false], + save_music_context_brief: [false, false, false], + upload_site_asset: [false, true, true], + generate_site: [false, true, true], + get_site: [true, false, false], + get_release_player: [true, false, false], + get_release_pack: [false, true, false], + export_release_pack: [false, true, false], + }; + for (const [name, [readOnlyHint, destructiveHint, openWorldHint]] of Object.entries( + expectedAnnotations, + )) { + expect(tools.find(tool => tool.name === name)?.annotations, name).toMatchObject({ + readOnlyHint, + destructiveHint, + openWorldHint, + }); + } expect(tools.map(tool => tool.name)).toContain("get_artist_socials"); expect(tools.map(tool => tool.name)).not.toContain("artist_deep_research"); expect(tools.map(tool => tool.name)).not.toContain("spotify_deep_research"); @@ -70,7 +108,11 @@ it("discovers the entire delegated catalog over the real MCP SDK", async () => { const tool = tools.find(tool => tool.name === operation.name)!; expect(Object.keys(tool.inputSchema.properties ?? {}).length).toBeGreaterThan(0); expect(tool.inputSchema.properties).not.toHaveProperty("action"); - expect(tool.annotations?.readOnlyHint).toBe(operation.readOnly); + expect(tool.annotations).toMatchObject({ + readOnlyHint: operation.readOnly, + destructiveHint: operation.destructive, + openWorldHint: operation.openWorld, + }); } const artist = tools.find(tool => tool.name === "create_new_artist")!; expect(artist.inputSchema.properties).not.toHaveProperty("active_conversation_id"); diff --git a/lib/mcp/oauth/__tests__/registerOAuthTools.test.ts b/lib/mcp/oauth/__tests__/registerOAuthTools.test.ts index 6e1f38eec..8c67fc367 100644 --- a/lib/mcp/oauth/__tests__/registerOAuthTools.test.ts +++ b/lib/mcp/oauth/__tests__/registerOAuthTools.test.ts @@ -24,6 +24,7 @@ function fixture() { const tools = new Map< string, { + annotations?: Record; schema: { parse: (args: unknown) => unknown }; call: (args: unknown, extra: unknown) => Promise<{ isError?: boolean }>; } @@ -32,10 +33,13 @@ function fixture() { { registerTool: ( name: string, - config: { inputSchema: { parse: (args: unknown) => unknown } }, + config: { + annotations?: Record; + inputSchema: { parse: (args: unknown) => unknown }; + }, call: (args: unknown, extra: unknown) => Promise<{ isError?: boolean }>, ) => { - tools.set(name, { schema: config.inputSchema, call }); + tools.set(name, { schema: config.inputSchema, annotations: config.annotations, call }); }, } as unknown as McpServer, services, @@ -86,3 +90,14 @@ it("rejects profile updates with no changed fields", () => { .schema.parse({ artistId: "00000000-0000-4000-8000-000000000001" }), ).toThrow(); }); + +it("sets explicit behavior-based annotations for every limited tool", () => { + const { tools } = fixture(); + for (const [name, tool] of tools) { + expect(tool.annotations).toEqual({ + readOnlyHint: !["create_new_artist", "update_account_info"].includes(name), + destructiveHint: name === "update_account_info", + openWorldHint: false, + }); + } +}); diff --git a/lib/mcp/oauth/catalogCaseToolOperations.ts b/lib/mcp/oauth/catalogCaseToolOperations.ts index d196bc567..26450ed2c 100644 --- a/lib/mcp/oauth/catalogCaseToolOperations.ts +++ b/lib/mcp/oauth/catalogCaseToolOperations.ts @@ -7,6 +7,8 @@ export const catalogCaseToolOperations = { description: "Save a bounded portable catalog case as a customer assertion. Requires last read revision and an idempotency key. Does not verify rights, authorize provider operations, register music or collect royalties. History is server-maintained; omit local history.", readOnly: false, + destructive: true, + openWorld: false, delegated: false, }, read_catalog_case: { @@ -14,6 +16,8 @@ export const catalogCaseToolOperations = { description: "Read the current or specified catalog case revision under current workspace access. Withdrawn Context evidence and dependent records are withheld. A partial snapshot cannot be saved without explicit reassembly.", readOnly: true, + destructive: false, + openWorld: false, delegated: false, }, list_catalog_cases: { @@ -21,9 +25,18 @@ export const catalogCaseToolOperations = { description: "List a bounded page of catalog cases in the selected workspace. Follow next_id as after_id while has_more is true. No artist or request ID is required.", readOnly: true, + destructive: false, + openWorld: false, delegated: false, }, } satisfies Record< CatalogCaseOperation["action"], - { name: string; description: string; readOnly: boolean; delegated: false } + { + name: string; + description: string; + readOnly: boolean; + destructive: boolean; + openWorld: boolean; + delegated: false; + } >; diff --git a/lib/mcp/oauth/contextToolOperations.ts b/lib/mcp/oauth/contextToolOperations.ts index 8eed566cc..cea2bd8f0 100644 --- a/lib/mcp/oauth/contextToolOperations.ts +++ b/lib/mcp/oauth/contextToolOperations.ts @@ -12,147 +12,208 @@ export const contextToolOperations = { name: "list_music_release_cases", description: "List saved release cases and their review status.", readOnly: true, + destructive: false, + openWorld: false, }, read_release_case: { name: "read_music_release_case", description: "Read a saved release case and its evidence.", readOnly: true, + destructive: false, + openWorld: false, }, read_release_case_review: { name: "read_music_release_case_review", description: "Read a saved release case review.", readOnly: true, + destructive: false, + openWorld: false, }, review_release_case: { name: "record_music_release_case_review", description: "Save a release case review decision and optional note. This does not approve rights or distribution.", readOnly: false, + destructive: false, + openWorld: false, }, save_brief: { name: "save_music_context_brief", description: "Compile and save a creative direction, playlist pitch or company onboarding (company_onboarding) brief from selected saved context. Company onboarding is a bounded assessment with evidence gaps, not confirmation of company facts, rights or workspace authority.", readOnly: false, + destructive: false, + openWorld: false, }, read_brief: { name: "read_music_context_brief", description: "Read a previously saved music brief.", readOnly: true, + destructive: false, + openWorld: false, }, plan: { name: "plan_music_context_research", description: "Preview research modules for saved music context without running them.", readOnly: true, + destructive: false, + openWorld: false, }, list_executions: { name: "list_music_context_executions", description: "List research executions for a saved music context request.", readOnly: true, + destructive: false, + openWorld: false, }, list_catalog_members: { name: "list_music_context_catalog_members", description: "Read a page of saved catalog recordings.", readOnly: true, + destructive: false, + openWorld: false, }, list_release_tracks: { name: "list_music_context_release_tracks", description: "Read a page of saved release track slots.", readOnly: true, + destructive: false, + openWorld: false, }, read_release_track_observations: { name: "read_music_release_track_observations", description: "Read saved release track observations and evidence.", readOnly: true, + destructive: false, + openWorld: false, }, review_release_track_identities: { name: "review_music_release_track_identities", description: "Read the identity review for saved release tracks. Does not approve rights.", readOnly: true, + destructive: false, + openWorld: false, }, verify_release_tracks: { name: "verify_music_release_tracks", description: "Start provider verification of saved release tracks and save resulting observations.", readOnly: false, + destructive: false, + openWorld: true, }, expand_catalog_members: { name: "expand_music_context_catalog", description: "Save context subjects for a page of catalog recordings.", readOnly: false, + destructive: false, + openWorld: false, }, plan_catalog_members: { name: "plan_music_catalog_research", description: "Preview research modules for a page of saved catalog recordings without running them.", readOnly: true, + destructive: false, + openWorld: false, }, read_execution: { name: "read_music_context_execution", description: "Read the status and results of a saved research execution.", readOnly: true, + destructive: false, + openWorld: false, }, ingest_catalog: { name: "import_catalog_context", description: "Create a context request from a catalog you can access.", readOnly: false, + destructive: false, + openWorld: false, }, ingest_artist: { name: "import_artist_context", description: "Create a context request from an artist you can access.", readOnly: false, + destructive: false, + openWorld: false, }, ingest_songwriter_name: { name: "import_songwriter_context", description: "Create a context request from a submitted songwriter name. A name is not verified identity.", readOnly: false, + destructive: false, + openWorld: false, }, ingest_company_name: { name: "import_music_company_context", description: "Create a context request from a submitted music company name. A name is not verified identity.", readOnly: false, + destructive: false, + openWorld: false, }, ingest_campaign_brief: { name: "import_music_campaign_brief", description: "Save a structured music campaign brief as context.", readOnly: false, + destructive: false, + openWorld: false, }, ingest_supporting_text: { name: "import_music_supporting_text", description: "Save specifically selected supporting music material as context. Supply only material the account asked to save, never conversation history.", readOnly: false, + destructive: false, + openWorld: false, }, ingest_release: { name: "import_music_release_context", description: "Create a context request from a Spotify release URL.", readOnly: false, + destructive: false, + openWorld: false, }, verify_release: { name: "verify_music_release", description: "Start provider verification for a saved release context request.", readOnly: false, + destructive: false, + openWorld: true, }, ingest: { name: "import_song_context", description: "Collect and save music context for a Spotify track URL and selected research topics.", readOnly: false, + destructive: false, + openWorld: true, }, read: { name: "read_music_context", description: "Read the status and results of a saved music context request.", readOnly: true, + destructive: false, + openWorld: false, }, brief: { name: "compile_music_context_brief", description: "Compile a creative direction, playlist pitch or company onboarding (company_onboarding) brief from selected saved context without saving a snapshot. Company onboarding is a bounded assessment with evidence gaps, not confirmation of company facts, rights or workspace authority.", readOnly: true, + destructive: false, + openWorld: false, }, } satisfies Record< Action, - { name: string; description: string; readOnly: boolean; delegated?: false } + { + name: string; + description: string; + readOnly: boolean; + destructive: boolean; + openWorld: boolean; + delegated?: false; + } >; diff --git a/lib/mcp/oauth/evidenceToolOperations.ts b/lib/mcp/oauth/evidenceToolOperations.ts index a0fe56a65..c541df515 100644 --- a/lib/mcp/oauth/evidenceToolOperations.ts +++ b/lib/mcp/oauth/evidenceToolOperations.ts @@ -7,6 +7,8 @@ export const evidenceToolOperations = { description: "Associate an exact retained source version with existing authorized artist, professional or Context request/subject records. Relevance only; does not confirm identities, rights or mandates. Reuse the same key on retries.", readOnly: false, + destructive: false, + openWorld: false, delegated: false, }, read_evidence_attachment: { @@ -14,6 +16,8 @@ export const evidenceToolOperations = { description: "Read an evidence association receipt under current workspace, source and target access. Withdrawn or inaccessible evidence is withheld.", readOnly: true, + destructive: false, + openWorld: false, delegated: false, }, list_evidence_attachments: { @@ -21,9 +25,18 @@ export const evidenceToolOperations = { description: "List a bounded page of associations for an exact source version. Pass the returned next_id as after_id while has_more is true, including empty pages with withheld receipts.", readOnly: true, + destructive: false, + openWorld: false, delegated: false, }, } satisfies Record< EvidenceAttachmentOperation["action"], - { name: string; description: string; readOnly: boolean; delegated: false } + { + name: string; + description: string; + readOnly: boolean; + destructive: boolean; + openWorld: boolean; + delegated: false; + } >; diff --git a/lib/mcp/oauth/fullOAuthToolPolicy.ts b/lib/mcp/oauth/fullOAuthToolPolicy.ts index 0d0a7f692..d5e8d1d64 100644 --- a/lib/mcp/oauth/fullOAuthToolPolicy.ts +++ b/lib/mcp/oauth/fullOAuthToolPolicy.ts @@ -1,130 +1,207 @@ interface ToolPolicy { readOnly: boolean; - destructive?: boolean; + destructive: boolean; + openWorld: boolean; notice?: string; } /** Explicit inventory: a newly registered tool cannot silently become delegated authority. */ export const fullOAuthToolPolicy: Record = { - prepare_release_pack: { readOnly: false, destructive: false }, - get_release_pack: { readOnly: true }, - estimate_release_pack: { readOnly: false, destructive: false }, + prepare_release_pack: { readOnly: false, destructive: true, openWorld: false }, + get_release_pack: { + readOnly: false, + destructive: true, + openWorld: false, + notice: + "Reading an expired running pack settles its unfinished work, updates job and asset status, and refunds held credits.", + }, + estimate_release_pack: { readOnly: false, destructive: true, openWorld: true }, generate_release_pack: { readOnly: false, - destructive: false, + destructive: true, + openWorld: false, notice: "Requires explicit approval of the complete current quote and budget. Never publishes.", }, retry_release_pack: { readOnly: false, - destructive: false, + destructive: true, + openWorld: false, notice: "Paid retries require a fresh approved targeted quote; accepted work resumes without duplicate submission.", }, - upload_release_pack_asset: { readOnly: false, destructive: false }, - export_release_pack: { readOnly: true }, - list_artists: { readOnly: true }, - get_artist_socials: { readOnly: true }, - artist_deep_research: { readOnly: true }, - spotify_deep_research: { readOnly: true }, - get_spotify_album: { readOnly: true }, - get_spotify_artist_albums: { readOnly: true }, - get_spotify_artist_top_tracks: { readOnly: true }, - get_spotify_search: { readOnly: true }, - get_local_time: { readOnly: true }, - get_chats: { readOnly: true }, - get_pulses: { readOnly: true }, - get_tasks: { readOnly: true }, + upload_release_pack_asset: { readOnly: false, destructive: false, openWorld: true }, + export_release_pack: { + readOnly: false, + destructive: true, + openWorld: false, + notice: + "Updates the saved export timestamp. An expired running pack may also settle unfinished work and refund held credits.", + }, + list_artists: { readOnly: true, destructive: false, openWorld: false }, + get_artist_socials: { readOnly: true, destructive: false, openWorld: false }, + artist_deep_research: { readOnly: true, destructive: false, openWorld: false }, + spotify_deep_research: { readOnly: true, destructive: false, openWorld: false }, + get_spotify_album: { readOnly: true, destructive: false, openWorld: true }, + get_spotify_artist_albums: { readOnly: true, destructive: false, openWorld: true }, + get_spotify_artist_top_tracks: { readOnly: true, destructive: false, openWorld: true }, + get_spotify_search: { readOnly: true, destructive: false, openWorld: true }, + get_local_time: { readOnly: true, destructive: false, openWorld: false }, + get_chats: { readOnly: true, destructive: false, openWorld: false }, + get_pulses: { readOnly: true, destructive: false, openWorld: false }, + get_tasks: { readOnly: true, destructive: false, openWorld: false }, get_task_run_status: { readOnly: true, + destructive: false, + openWorld: false, notice: "Only caller-owned runs with verifiable ownership can be read.", }, - select_catalogs: { readOnly: true }, - select_catalog_songs: { readOnly: true }, - get_youtube_revenue: { readOnly: true }, - search_google_images: { readOnly: true }, - search_web: { readOnly: true }, - web_deep_research: { readOnly: true }, + select_catalogs: { readOnly: true, destructive: false, openWorld: false }, + select_catalog_songs: { readOnly: true, destructive: false, openWorld: false }, + get_youtube_revenue: { readOnly: true, destructive: false, openWorld: false }, + search_google_images: { readOnly: true, destructive: false, openWorld: true }, + search_web: { readOnly: true, destructive: false, openWorld: true }, + web_deep_research: { readOnly: true, destructive: false, openWorld: true }, retrieve_sora_2_video: { readOnly: true, + destructive: false, + openWorld: false, notice: "Pass the account-bound video_id returned by this OAuth connection's generate_sora_2_video call.", }, retrieve_sora_2_video_content: { readOnly: true, + destructive: false, + openWorld: false, notice: "Pass the account-bound video_id returned by generate_sora_2_video.", }, - list_release_player: { readOnly: true }, - get_release_player: { readOnly: true }, + list_release_player: { readOnly: true, destructive: false, openWorld: false }, + get_release_player: { readOnly: true, destructive: false, openWorld: false }, get_release_player_activity: { readOnly: true, + destructive: false, + openWorld: false, notice: "Private reported browser listening; never DSP stream totals.", }, get_release_player_fans: { readOnly: true, + destructive: false, + openWorld: false, notice: "Private artist/workspace fan profiles. Sign-in is not marketing consent.", }, get_workspace_player_fans: { readOnly: true, + destructive: false, + openWorld: false, notice: "Private workspace fan contacts with artist relationships. Sign-in is not marketing consent.", }, create_release_player: { readOnly: false, destructive: true, + openWorld: true, notice: "Disabled by default. Setting enabled=true publishes; requires explicit account authorization.", }, update_release_player: { readOnly: false, destructive: true, + openWorld: true, notice: "Enabling publishes. Require explicit account authorization and current revision.", }, - list_sites: { readOnly: true }, - get_site: { readOnly: true }, - get_site_signups: { readOnly: true }, - get_site_generation: { readOnly: true }, - create_new_artist: { readOnly: false, destructive: false }, - update_account_info: { readOnly: false }, - update_artist_socials: { readOnly: false }, - update_pulse: { readOnly: false }, - create_task: { readOnly: false, destructive: false }, - update_task: { readOnly: false }, - delete_task: { readOnly: false }, - insert_catalog_songs: { readOnly: false, destructive: false }, - compact_chats: { readOnly: false }, + list_sites: { readOnly: true, destructive: false, openWorld: false }, + get_site: { readOnly: true, destructive: false, openWorld: false }, + get_site_signups: { readOnly: true, destructive: false, openWorld: false }, + get_site_generation: { readOnly: true, destructive: false, openWorld: false }, + create_new_artist: { readOnly: false, destructive: false, openWorld: false }, + update_account_info: { readOnly: false, destructive: true, openWorld: false }, + update_artist_socials: { readOnly: false, destructive: true, openWorld: false }, + update_pulse: { readOnly: false, destructive: true, openWorld: false }, + create_task: { readOnly: false, destructive: false, openWorld: false }, + update_task: { readOnly: false, destructive: true, openWorld: false }, + delete_task: { readOnly: false, destructive: true, openWorld: false }, + insert_catalog_songs: { + readOnly: false, + destructive: true, + openWorld: true, + notice: + "May enrich songs using public Spotify data and overwrite existing shared song metadata for matching ISRCs.", + }, + compact_chats: { + readOnly: true, + destructive: false, + openWorld: false, + notice: "Returns a summary without saving it or replacing the source conversation.", + }, // Context operations are classified individually in contextToolOperations.ts. - generate_image: { readOnly: false, destructive: false }, - edit_image: { readOnly: false, destructive: false }, - generate_sora_2_video: { readOnly: false, destructive: false }, - analyze_music: { readOnly: false, destructive: false }, - transcribe_audio: { readOnly: false, destructive: false }, + generate_image: { + readOnly: false, + destructive: true, + openWorld: true, + notice: + "Generates a new image and uploads it to public media storage; use only when public storage is authorized.", + }, + edit_image: { + readOnly: false, + destructive: true, + openWorld: true, + notice: + "Creates a new edited image and uploads it to public media storage; the source image is retained. Use only when public storage is authorized.", + }, + generate_sora_2_video: { readOnly: false, destructive: false, openWorld: false }, + analyze_music: { + readOnly: false, + destructive: true, + openWorld: true, + notice: "Successful analysis deducts Recoup credits from the connected account.", + }, + transcribe_audio: { readOnly: false, destructive: false, openWorld: true }, create_knowledge_base: { readOnly: false, destructive: true, + openWorld: true, notice: "Publishes text to public media storage. Use only for content explicitly approved for public publication; never confidential material.", }, generate_txt_file: { readOnly: false, destructive: true, + openWorld: true, notice: "Publishes text to public media storage. Use only for content explicitly approved for public publication; never confidential material.", }, contact_team: { readOnly: false, - destructive: false, + destructive: true, + openWorld: false, notice: "Sends a message to Recoup support. Requires an explicit request to contact support.", }, send_email: { readOnly: false, - destructive: false, + destructive: true, + openWorld: true, notice: "Sends email immediately. Confirm exact recipients and content with the account before calling. Existing recipient restrictions apply.", }, - upload_site_asset: { readOnly: false, destructive: false }, - create_site: { readOnly: false, destructive: false }, - propose_site_concepts: { readOnly: false, destructive: false }, - generate_site: { readOnly: false, destructive: false }, - publish_site: { readOnly: false }, - unpublish_site: { readOnly: false }, - delete_site: { readOnly: false }, + upload_site_asset: { + readOnly: false, + destructive: true, + openWorld: true, + notice: + "Uploads bytes to public site asset storage. Anyone with the returned URL can access them.", + }, + create_site: { readOnly: false, destructive: false, openWorld: true }, + propose_site_concepts: { + readOnly: false, + destructive: true, + openWorld: true, + notice: "Collects public release context and incurs generation credit usage.", + }, + generate_site: { + readOnly: false, + destructive: true, + openWorld: true, + notice: "Runs generation and replaces the saved draft; generation incurs credit usage.", + }, + publish_site: { readOnly: false, destructive: true, openWorld: true }, + unpublish_site: { readOnly: false, destructive: true, openWorld: true }, + delete_site: { readOnly: false, destructive: true, openWorld: true }, }; diff --git a/lib/mcp/oauth/registerFullOAuthTools.ts b/lib/mcp/oauth/registerFullOAuthTools.ts index 909f2e870..4b7f96c9e 100644 --- a/lib/mcp/oauth/registerFullOAuthTools.ts +++ b/lib/mcp/oauth/registerFullOAuthTools.ts @@ -34,7 +34,13 @@ export function registerFullOAuthTools( name: string, config: { description?: string; inputSchema: z.ZodType; annotations?: Record }, handler: (args: Args, extra: Extra) => Promise, - operation?: { name: string; action: string; readOnly: boolean }, + operation?: { + name: string; + action: string; + readOnly: boolean; + destructive: boolean; + openWorld: boolean; + }, ) => { // Credentials never belong in model-visible output. Professional roster tools // remain excluded until their delegated organization-grant audit is complete. @@ -77,7 +83,12 @@ export function registerFullOAuthTools( return; } const policy = operation - ? { readOnly: operation.readOnly, destructive: false, notice: "" } + ? { + readOnly: operation.readOnly, + destructive: operation.destructive, + openWorld: operation.openWorld, + notice: "", + } : fullOAuthToolPolicy[name]; if (!policy) throw new Error(`Missing delegated policy for ${name}`); const originalObject = @@ -138,8 +149,8 @@ export function registerFullOAuthTools( annotations: { ...config.annotations, readOnlyHint: policy.readOnly, - destructiveHint: policy.destructive ?? !policy.readOnly, - openWorldHint: true, + destructiveHint: policy.destructive, + openWorldHint: policy.openWorld, }, }, async (raw, extra) => { diff --git a/lib/mcp/oauth/registerOAuthTools.ts b/lib/mcp/oauth/registerOAuthTools.ts index c5ff48b60..d3c493278 100644 --- a/lib/mcp/oauth/registerOAuthTools.ts +++ b/lib/mcp/oauth/registerOAuthTools.ts @@ -52,7 +52,7 @@ export function registerOAuthTools( { description: "List artists in your personal Recoup account.", inputSchema: z.object({}).strict(), - annotations: { readOnlyHint: true }, + annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, }, (_args, extra) => run(extra, "list_artists", id => services.listArtists(id)), ); @@ -84,7 +84,7 @@ export function registerOAuthTools( value.instruction !== undefined, "Provide at least one profile field to update", ), - annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, + annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, }, ({ artistId, ...updates }, extra) => run(extra, "update_account_info", id => services.updateArtist(id, artistId, updates)), @@ -94,7 +94,7 @@ export function registerOAuthTools( { description: "Read social profiles for an artist in your personal Recoup account.", inputSchema: z.object({ artist_account_id: z.string().uuid() }).strict(), - annotations: { readOnlyHint: true }, + annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, }, (args, extra) => run(extra, "get_artist_socials", id => services.getSocials(id, args.artist_account_id)), @@ -104,7 +104,7 @@ export function registerOAuthTools( { description: "List your own Recoup chat conversations.", inputSchema: z.object({}).strict(), - annotations: { readOnlyHint: true }, + annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, }, (_args, extra) => run(extra, "get_chats", id => services.getChats(id)), ); diff --git a/vercel.json b/vercel.json index 074ffea96..2eb362d32 100644 --- a/vercel.json +++ b/vercel.json @@ -21,5 +21,10 @@ "path": "/api/internal/missed-report-check", "schedule": "17 * * * *" } - ] + ], + "git": { + "deploymentEnabled": { + "fix/mcp-oauth-behavior-annotations": false + } + } }