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
161 changes: 161 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 new generation; settlement can refund held credits | 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 @@ -64,7 +66,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
68 changes: 65 additions & 3 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,7 +34,10 @@ it("discovers the entire delegated catalog over the real MCP SDK", async () => {
.sort(),
).toEqual([...standardOnlyContextActions].sort());
const server = new McpServer({ name: "recoup-test", version: "1" });
registerFullOAuthTools(server, vi.fn(), { prepare: vi.fn(), listArtists: vi.fn() });
const verify = vi.fn();
const services = { prepare: vi.fn(), listArtists: vi.fn() };
registerFullOAuthTools(server, verify, services);
registerRecoupExtension(server);
const client = new Client({ name: "test", version: "1" });
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
await server.connect(serverTransport);
Expand All @@ -51,6 +55,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 @@ -59,7 +65,57 @@ 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(92);
expect(tools).toHaveLength(94);
expect(
tools.filter(
tool => !(tool._meta?.ui as { visibility?: string[] })?.visibility?.includes("app"),
),
).toHaveLength(93);
expect(verify).not.toHaveBeenCalled();
for (const service of Object.values(services)) expect(service).not.toHaveBeenCalled();
expect(contextToolOperations.prepare_catalog_audit).toMatchObject({
readOnly: true,
destructive: false,
openWorld: false,
delegated: false,
});
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_artist_posts: [true, false, false],
get_scraper_results: [true, false, true],
scrape_artist_socials: [false, true, true],
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 @@ -71,11 +127,17 @@ 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");
expect(JSON.stringify(artist)).not.toMatch(/system prompt|copy.*conversation/i);
expect(tools.map(tool => tool.name)).not.toContain("ingestion");
expect(tools.map(tool => tool.name)).not.toContain("prepare_catalog_audit");
expect(tools.map(tool => tool.name)).not.toContain("validate_application_registration");
expect(tools.map(tool => tool.name)).not.toContain("list_professional_roster");
expect(tools.map(tool => tool.name)).not.toContain("confirm_professional_roster");
Expand Down
56 changes: 56 additions & 0 deletions lib/mcp/oauth/__tests__/limitedOAuthCatalog.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
import { expect, it, vi } from "vitest";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { registerOAuthTools } from "../registerOAuthTools";
import { registerRecoupExtension } from "../../extension/registerRecoupExtension";

it("discovers all seven limited registrations without invoking business services", async () => {
const services = {
listArtists: vi.fn(),
createArtist: vi.fn(),
updateArtist: vi.fn(),
getSocials: vi.fn(),
getChats: vi.fn(),
};
const verify = vi.fn();
const server = new McpServer({ name: "recoup-limited-test", version: "1" });
registerOAuthTools(server, services, verify);
registerRecoupExtension(server);
const client = new Client({ name: "test", version: "1" });
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
await server.connect(serverTransport);
await client.connect(clientTransport);
try {
const { tools } = await client.listTools();
const expected: Record<string, [boolean, boolean, boolean]> = {
list_artists: [true, false, false],
create_new_artist: [false, false, false],
update_account_info: [false, true, false],
get_artist_socials: [true, false, false],
get_chats: [true, false, false],
open_recoup_workflows: [true, false, false],
open_recoup_workflows_sidebar: [true, false, false],
};
expect(tools.map(tool => tool.name).sort()).toEqual(Object.keys(expected).sort());
expect(tools).toHaveLength(7);
const modelVisibleTools = tools.filter(tool => tool.name !== "open_recoup_workflows_sidebar");
expect(modelVisibleTools).toHaveLength(6);
for (const tool of modelVisibleTools) {
expect(tool._meta?.ui ?? {}).not.toHaveProperty("visibility");
}
expect(
tools.find(tool => tool.name === "open_recoup_workflows_sidebar")?._meta?.ui,
).toMatchObject({ visibility: ["app"] });
for (const tool of tools) {
const [readOnlyHint, destructiveHint, openWorldHint] = expected[tool.name];
expect(tool.annotations).toMatchObject({ readOnlyHint, destructiveHint, openWorldHint });
expect(tool.inputSchema.properties).not.toHaveProperty("account_id");
}
expect(verify).not.toHaveBeenCalled();
for (const service of Object.values(services)) expect(service).not.toHaveBeenCalled();
} finally {
await client.close();
await server.close();
}
});
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", () => {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Custom agent: Enforce Clear Code Style and Maintainability Practices

This file is now 103 lines, over the 100-line cap in the code-style rules, and the new annotations test is what pushed it past the limit. Trim the added test or fixture lines so the file stays under 100 lines (at or below 99).

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At lib/mcp/oauth/__tests__/registerOAuthTools.test.ts, line 94:

<comment>This file is now 103 lines, over the 100-line cap in the code-style rules, and the new annotations test is what pushed it past the limit. Trim the added test or fixture lines so the file stays under 100 lines (at or below 99).</comment>

<file context>
@@ -86,3 +90,14 @@ it("rejects profile updates with no changed fields", () => {
   ).toThrow();
 });
+
+it("sets explicit behavior-based annotations for every limited tool", () => {
+  const { tools } = fixture();
+  for (const [name, tool] of tools) {
</file context>

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,
});
}
});
46 changes: 46 additions & 0 deletions lib/mcp/oauth/__tests__/standardCatalogAnnotations.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import { expect, it, vi } from "vitest";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { registerCatalogCaseTools } from "@/lib/mcp/tools/context/registerCatalogCaseTools";
import { handleContextToolOperation } from "@/lib/mcp/tools/context/handleContextToolOperation";
import { catalogCaseToolOperations } from "../catalogCaseToolOperations";

vi.mock("@/lib/mcp/tools/context/handleContextToolOperation", () => ({
handleContextToolOperation: vi.fn(),
}));

it("discovers standard catalog annotations without executing handlers or granting delegation", async () => {
const server = new McpServer({ name: "catalog-annotations-test", version: "1" });
registerCatalogCaseTools(server);
const client = new Client({ name: "test", version: "1" });
const [ct, st] = InMemoryTransport.createLinkedPair();
await server.connect(st);
await client.connect(ct);
try {
const { tools } = await client.listTools();
const expected: Record<string, [boolean, boolean, boolean]> = {
prepare_catalog_audit: [true, false, false],
save_catalog_case: [false, true, false],
read_catalog_case: [true, false, false],
list_catalog_cases: [true, false, false],
};
expect(tools.map(tool => tool.name).sort()).toEqual(Object.keys(expected).sort());
for (const tool of tools) {
const [readOnlyHint, destructiveHint, openWorldHint] = expected[tool.name];
expect(tool.annotations, tool.name).toMatchObject({
readOnlyHint,
destructiveHint,
openWorldHint,
});
expect(tool.inputSchema.properties).not.toHaveProperty("account_id");
}
for (const operation of Object.values(catalogCaseToolOperations)) {
expect(operation.delegated).toBe(false);
}
expect(handleContextToolOperation).not.toHaveBeenCalled();
} finally {
await client.close();
await server.close();
}
});
Loading
Loading