Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 151 additions & 0 deletions docs/mcp-oauth-annotations.md

Large diffs are not rendered by default.

8 changes: 5 additions & 3 deletions docs/mcp-oauth-tool-qualification.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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) |
Expand Down Expand Up @@ -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) |
Expand Down
46 changes: 44 additions & 2 deletions lib/mcp/oauth/__tests__/fullOAuthCatalog.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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);
Expand All @@ -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)
Expand All @@ -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<string, [boolean, boolean, boolean]> = {
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");
Expand All @@ -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");
Expand Down
19 changes: 17 additions & 2 deletions lib/mcp/oauth/__tests__/registerOAuthTools.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ function fixture() {
const tools = new Map<
string,
{
annotations?: Record<string, unknown>;
schema: { parse: (args: unknown) => unknown };
call: (args: unknown, extra: unknown) => Promise<{ isError?: boolean }>;
}
Expand All @@ -32,10 +33,13 @@ function fixture() {
{
registerTool: (
name: string,
config: { inputSchema: { parse: (args: unknown) => unknown } },
config: {
annotations?: Record<string, unknown>;
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,
Expand Down Expand Up @@ -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,
});
}
});
15 changes: 14 additions & 1 deletion lib/mcp/oauth/catalogCaseToolOperations.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,36 @@ 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: {
name: "read_catalog_case",
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: {
name: "list_catalog_cases",
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;
}
>;
Loading
Loading