Multiplayer agent harness for work.
Serve a large MCP tool catalog as one searchable tool (#2562)
Regan Belleb6c483814ad
diff --git a/src/api/routes/admin/mcp-servers.ts b/src/api/routes/admin/mcp-servers.tsindex 526042473..180f41175 100644--- a/src/api/routes/admin/mcp-servers.ts+++ b/src/api/routes/admin/mcp-servers.ts@@ -87,15 +87,23 @@ export async function putMcpServer(ctx: ApiCtx): Promise<void> {if (!AUTH_MODES.includes(auth)) {return sendJson(ctx.res, 400, { error: "bad_request", message: `auth must be one of ${AUTH_MODES.join(", ")}` });}- const approval = b.approval ?? (await ctx.deps.mcpServers.get(id))?.approval ?? "annotations";+ const existing = await ctx.deps.mcpServers.get(id);+ const approval = b.approval ?? existing?.approval ?? "annotations";if (!APPROVAL_POLICIES.includes(approval)) {return sendJson(ctx.res, 400, {error: "bad_request",message: `approval must be one of ${APPROVAL_POLICIES.join(", ")}`,});}- const existing = await ctx.deps.mcpServers.get(id);const oauthUser = auth === "oauth-user";+ const catalog = (b.catalog ?? existing?.catalog) === true;+ const attestActor = (b.attestActor ?? existing?.attestActor) === true;+ if ((catalog || attestActor) && oauthUser) {+ return sendJson(ctx.res, 400, {+ error: "bad_request",+ message: "catalog and attestActor are not available with oauth-user auth",+ });+ }if (oauthUser && PROVIDERS[id]) {return sendJson(ctx.res, 400, { error: "bad_request", message: `id ${id} is reserved by a built-in connector` });}@@ -103,6 +111,16 @@ export async function putMcpServer(ctx: ApiCtx): Promise<void> {if (credentialScope !== "shared" && credentialScope !== "per-user") {return sendJson(ctx.res, 400, { error: "bad_request", message: "credentialScope must be shared or per-user" });}+ if (+ attestActor &&+ (!catalog || credentialScope !== "shared" || (auth !== "bearer" && auth !== "client-credentials"))+ ) {+ return sendJson(ctx.res, 400, {+ error: "bad_request",+ message:+ "attestActor requires catalog, shared credentials, and bearer or client-credentials auth, so only QM can assert the person",+ });+ }const credentialHost = b.credentialHost ?? existing?.credentialHost ?? (oauthUser ? parsed.hostname : undefined);if (oauthUser &&@@ -181,6 +199,8 @@ export async function putMcpServer(ctx: ApiCtx): Promise<void> {}: {}),...(approval === "annotations" ? {} : { approval }),+ ...(catalog ? { catalog } : {}),+ ...(attestActor ? { attestActor } : {}),readOnly: b.readOnly !== false,enabled: b.enabled !== false,updatedAt: Date.now(),@@ -206,7 +226,7 @@ export async function putMcpServer(ctx: ApiCtx): Promise<void> {let toolNames: string[] | undefined;if (b.validate !== false && !oauthUser && ctx.deps.mcpToolService) {try {- toolNames = await ctx.deps.mcpToolService.probe(server);+ toolNames = await ctx.deps.mcpToolService.probe(server, authorized.id);} catch (e) {return sendJson(ctx.res, 400, {error: "unreachable",diff --git a/src/harness/agent-tools.ts b/src/harness/agent-tools.tsindex 1b262ea7e..56f2f610b 100644--- a/src/harness/agent-tools.ts+++ b/src/harness/agent-tools.ts@@ -139,6 +139,7 @@ export interface ToolContextRef {goalRecentWork?: () => string;screenToolResult?: (input: ToolResultScreenInput) => Promise<ToolResultScreen>;toolApprovalGate?: (tool: string, callKey?: string) => boolean;+ approvedToolCalls?: Map<string, string>;}function text(s: string) {@@ -4231,7 +4232,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):});const mcpDefs = opts?.mcpTools ?? [];- const mcpTools = mcpDefs+ const mcpCandidates = mcpDefs.filter((d) => !opts?.readOnly || d.readOnly).map((d) => ({...defineTool({@@ -4247,7 +4248,11 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):if (!tc) return text("[error] no active tool context");await recordCall(callId, { tool: d.name, mcpServer: d.serverId, args: params });try {- const out = await tc.callMcpTool(d.name, (params ?? {}) as Record<string, unknown>);+ const out = await tc.callMcpTool(+ d.name,+ (params ?? {}) as Record<string, unknown>,+ ref.approvedToolCalls?.get(callId),+ );return recordExternalResult(callId,{ tool: d.name, mcpServer: d.serverId },@@ -4264,7 +4269,13 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):}},}),- needsApproval: d.needsApproval === true,+ needsApproval: d.catalog+ ? async (params: unknown) => {+ const tc = ref.current;+ if (!tc) return true;+ return tc.mcpToolNeedsApproval(d.name, (isObj(params) ? params : {}) as Record<string, unknown>);+ }+ : d.needsApproval === true,}));const clientTools = [...(opts?.clientTools ?? [])]@@ -4442,9 +4453,15 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):resourceTool("goal", { create: createGoal, get: getGoal, update: updateGoal }),runtime,context,- ...mcpTools,...clientTools,];+ const nativeNames = new Set(tools.map((t) => t.name));+ const mcpTools = mcpCandidates.filter((t) => {+ if (!nativeNames.has(t.name)) return true;+ console.warn(`[mcp] ${t.name} is hidden because a built-in tool has the same name`);+ return false;+ });+ tools.push(...mcpTools);const operationFields: Record<string, Record<string, string[]>> = {sandbox: {status: ["sandbox_id"],@@ -4708,7 +4725,14 @@ function withToolApprovalGate(true,);}- return (inner as (callId: string, params: unknown) => unknown)(callId, params);+ if (!callKey) return (inner as (callId: string, params: unknown) => unknown)(callId, params);+ const approved = (ref.approvedToolCalls ??= new Map());+ approved.set(callId, callKey);+ try {+ return await (inner as (callId: string, params: unknown) => unknown)(callId, params);+ } finally {+ approved.delete(callId);+ }},} as ToolDefinition;}diff --git a/src/mcp/mcp-client.ts b/src/mcp/mcp-client.tsindex 3f0f9ad2c..5f5dccc5b 100644--- a/src/mcp/mcp-client.ts+++ b/src/mcp/mcp-client.ts@@ -27,8 +27,8 @@ export type McpAuth =| { mode: "client-credentials"; clientId: string; clientSecret: string };export interface McpClient {- listTools(): Promise<McpRemoteTool[]>;- callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;+ listTools(opts?: { headers?: Record<string, string>; maxTools?: number }): Promise<McpRemoteTool[]>;+ callTool(name: string, args: Record<string, unknown>, headers?: Record<string, string>): Promise<CallToolResult>;}export function createMcpClient(opts: { url: string; auth: McpAuth }): McpClient {@@ -44,10 +44,15 @@ export function createMcpClient(opts: { url: string; auth: McpAuth }): McpClient}): undefined;- async function session<T>(op: string, work: (client: Client) => Promise<T>): Promise<T> {+ async function session<T>(+ op: string,+ work: (client: Client) => Promise<T>,+ extraHeaders: Record<string, string> = {},+ ): Promise<T> {+ const headers = { ...extraHeaders, ...(auth.mode === "bearer" ? { authorization: `Bearer ${auth.token}` } : {}) };const transport = new StreamableHTTPClientTransport(endpoint, {...(authProvider ? { authProvider } : {}),- ...(auth.mode === "bearer" ? { requestInit: { headers: { authorization: `Bearer ${auth.token}` } } } : {}),+ ...(Object.keys(headers).length ? { requestInit: { headers } } : {}),fetch: (url, init) => fetch(url, { ...init, redirect: "error" }),});const client = new Client({ name: "qm", version: "1.0.0" });@@ -64,26 +69,32 @@ export function createMcpClient(opts: { url: string; auth: McpAuth }): McpClient}return {- listTools: () =>- session("tools/list", async (client) => {- const tools: McpRemoteTool[] = [];- let cursor: string | undefined;- do {- const page = await client.listTools(cursor === undefined ? undefined : { cursor });- for (const t of page.tools)- tools.push({- name: t.name,- description: t.description ?? "",- inputSchema: t.inputSchema,- ...(t.annotations ? { annotations: t.annotations } : {}),- });- cursor = page.nextCursor;- } while (cursor && tools.length < MAX_TOOLS);- return tools.slice(0, MAX_TOOLS);- }),- async callTool(name, args) {- const result = (await session("tools/call", (client) =>- client.callTool({ name, arguments: args }, undefined, { timeout: CALL_TIMEOUT_MS }),+ listTools: (opts) =>+ session(+ "tools/list",+ async (client) => {+ const tools: McpRemoteTool[] = [];+ let cursor: string | undefined;+ do {+ const page = await client.listTools(cursor === undefined ? undefined : { cursor });+ for (const t of page.tools)+ tools.push({+ name: t.name,+ description: t.description ?? "",+ inputSchema: t.inputSchema,+ ...(t.annotations ? { annotations: t.annotations } : {}),+ });+ cursor = page.nextCursor;+ } while (cursor && tools.length < (opts?.maxTools ?? MAX_TOOLS));+ return tools.slice(0, opts?.maxTools ?? MAX_TOOLS);+ },+ opts?.headers,+ ),+ async callTool(name, args, headers) {+ const result = (await session(+ "tools/call",+ (client) => client.callTool({ name, arguments: args }, undefined, { timeout: CALL_TIMEOUT_MS }),+ headers,)) as CallToolResult;if (result.isError) throw new Error(`mcp tool ${name} error: ${mcpResultText(result) || "(no detail)"}`);return result;diff --git a/src/mcp/mcp-server-store.ts b/src/mcp/mcp-server-store.tsindex cc4ebe089..9fce9291c 100644--- a/src/mcp/mcp-server-store.ts+++ b/src/mcp/mcp-server-store.ts@@ -32,6 +32,8 @@ export interface McpServer {annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean };}>;approval?: McpApprovalPolicy;+ catalog?: boolean;+ attestActor?: boolean;readOnly: boolean;enabled: boolean;updatedAt: number;diff --git a/src/mcp/mcp-tool-service.ts b/src/mcp/mcp-tool-service.tsindex 7eda3c4ce..fa1736aea 100644--- a/src/mcp/mcp-tool-service.ts+++ b/src/mcp/mcp-tool-service.ts@@ -10,11 +10,17 @@ import type { ConnectorTokenStore } from "../credentials/keychain.ts";import type { AuditLog } from "../audit/audit-log.ts";import { errMessage, reportFailureAs } from "../util/errors.ts";import { setPublicOAuthClients, type PublicOAuthClient } from "../connectors/oauth.ts";+import { LRUCache } from "lru-cache";+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";import { createMcpClient, mcpResultText, type McpAuth, type McpClient } from "./mcp-client.ts";import type { McpServer, McpServerStore } from "./mcp-server-store.ts";const REFRESH_INTERVAL_MS = 5 * 60_000;-const MAX_RESULT_CHARS = 60_000;+const CATALOG_TTL_MS = 60_000;+const CATALOG_CACHE_MAX = 1_000;+const CATALOG_MAX_TOOLS = 5_000;+const CATALOG_SEARCH_LIMIT = 50;+const CATALOG_OPERATIONS = ["search", "describe", "invoke"];const DROPPED_OPTIONAL_PARAMS = ["intent", "locale"];function modelInputSchema(schema: Record<string, unknown>): Record<string, unknown> {@@ -66,6 +72,7 @@ export interface McpToolDescriptor {readOnly: boolean;needsApproval: boolean;signIn?: true;+ catalog?: true;}export interface McpToolService {@@ -73,16 +80,82 @@ export interface McpToolService {toolDefs(): McpToolDescriptor[];toolDefsFor(principalId?: string): Promise<McpToolDescriptor[]>;/** Call a namespaced tool. Returns the tool's text output (clamped). */- call(name: string, args: Record<string, unknown>, principalId?: string): Promise<string>;+ call(name: string, args: Record<string, unknown>, principalId?: string, approval?: string): Promise<string>;+ needsApproval(name: string, args: Record<string, unknown>, principalId?: string): Promise<boolean>;/** Force a registry re-read + tools/list refresh (admin save path, tests). */refresh(): Promise<void>;/** Probe a server config without persisting it. Returns its tool names. */- probe(server: McpServer): Promise<string[]>;+ probe(server: McpServer, principalId?: string): Promise<string[]>;close(): void;}class SignInRequired extends Error {}+type RemoteTool = NonNullable<McpServer["tools"]>[number];++function catalogDescriptor(server: McpServer): McpToolDescriptor {+ return {+ name: server.id,+ serverId: server.id,+ remoteName: "",+ catalog: true,+ description: `${server.name}: a catalog of tools behind one interface. Search for a tool, describe it to see its parameters, then invoke it. Tools marked "needs approval" pause until the person approves that exact call.`,+ inputSchema: {+ type: "object",+ properties: {+ operation: {+ type: "string",+ enum: CATALOG_OPERATIONS,+ description: "search finds tools; describe shows one tool's parameters; invoke runs one tool.",+ },+ query: {+ type: "string",+ description: "search: words to match in tool names and descriptions; omit to list every tool.",+ },+ tool: { type: "string", description: "describe and invoke: a tool name from search." },+ arguments: {+ type: "object",+ description: "invoke: the tool's arguments, matching its parameters from describe.",+ },+ },+ required: ["operation"],+ },+ readOnly: server.readOnly,+ needsApproval: false,+ };+}++function resultText(result: CallToolResult): string {+ return mcpResultText(result) || JSON.stringify(result.structuredContent ?? "") || "";+}++function callResource(def: McpToolDescriptor, args: Record<string, unknown>): string {+ if (!def.catalog) return `${def.serverId}/${def.remoteName}`;+ return `${def.serverId}/${typeof args.tool === "string" ? args.tool : String(args.operation)}`;+}++function headersFor(server: McpServer, principalId: string | undefined, approval?: string): Record<string, string> {+ if (!server.attestActor || server.credentialScope === "per-user") return {};+ if (!principalId) throw new Error(`MCP server ${server.id} needs a signed-in person`);+ return { "x-qm-actor": principalId, ...(approval ? { "x-qm-approval": approval } : {}) };+}++function catalogSearch(server: McpServer, tools: RemoteTool[], query: string): string {+ const words = query.toLowerCase().split(/\s+/).filter(Boolean);+ const hits = tools.filter((t) => {+ const text = `${t.name} ${t.description}`.toLowerCase();+ return words.every((w) => text.includes(w));+ });+ if (!hits.length) return `No ${server.name} tools match "${query}".`;+ const lines = hits.slice(0, CATALOG_SEARCH_LIMIT).map((t) => {+ const summary = (t.description.split("\n")[0] ?? "").slice(0, 200);+ return `- ${t.name}${mcpToolNeedsApproval(server, t.annotations) ? " (needs approval)" : ""}: ${summary}`;+ });+ if (hits.length > CATALOG_SEARCH_LIMIT)+ lines.push(`…and ${hits.length - CATALOG_SEARCH_LIMIT} more; narrow the query.`);+ return lines.join("\n");+}+function authOf(server: McpServer): McpAuth {if (server.auth === "bearer") return { mode: "bearer", token: server.bearerToken ?? "" };if (server.auth === "client-credentials")@@ -102,6 +175,7 @@ export function createMcpToolService(opts: {const clients = new Map<string, { client: McpClient; server: McpServer }>();let snapshot: McpToolDescriptor[] = [];let perUserServers = new Map<string, McpServer>();+ const catalogs = new LRUCache<string, Promise<RemoteTool[]>>({ max: CATALOG_CACHE_MAX, ttl: CATALOG_TTL_MS });function signInMessage(server: McpServer): string {const url = opts.signInUrl?.(server.id);@@ -148,7 +222,63 @@ export function createMcpToolService(opts: {return createMcpClient({ url: server.url, auth: { mode: "bearer", token } });}+ async function catalogTools(server: McpServer, principalId?: string): Promise<RemoteTool[]> {+ const client = await callerClient(server, principalId);+ const perPerson = server.attestActor || server.credentialScope === "per-user";+ const key = `${server.id}\0${server.updatedAt}\0${perPerson ? (principalId ?? "") : ""}`;+ const cached = catalogs.get(key);+ if (cached) return cached;+ const listing = client.listTools({ headers: headersFor(server, principalId), maxTools: CATALOG_MAX_TOOLS });+ catalogs.set(key, listing);+ listing.catch(() => {+ if (catalogs.peek(key) === listing) catalogs.delete(key);+ });+ return listing;+ }++ async function catalogEntry(server: McpServer, principalId: string | undefined, name: unknown): Promise<RemoteTool> {+ if (typeof name !== "string" || !name) throw new Error("tool is required");+ const entry = (await catalogTools(server, principalId)).find((t) => t.name === name);+ if (!entry) throw new Error(`Unknown ${server.name} tool: ${name}. Search for it first.`);+ return entry;+ }++ async function callCatalog(+ server: McpServer,+ args: Record<string, unknown>,+ principalId: string | undefined,+ approval: string | undefined,+ ): Promise<string> {+ if (args.operation === "search") {+ const query = typeof args.query === "string" ? args.query : "";+ return catalogSearch(server, await catalogTools(server, principalId), query);+ }+ const entry = await catalogEntry(server, principalId, args.tool);+ if (args.operation === "describe") {+ return JSON.stringify({+ name: entry.name,+ description: entry.description,+ needsApproval: mcpToolNeedsApproval(server, entry.annotations),+ parameters: modelInputSchema(entry.inputSchema),+ });+ }+ if (args.operation !== "invoke") throw new Error(`operation must be one of ${CATALOG_OPERATIONS.join(", ")}`);+ const input = args.arguments ?? {};+ if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("arguments must be an object");+ if (mcpToolNeedsApproval(server, entry.annotations) && !approval)+ throw new Error(`${entry.name} needs the person's approval; call it again so they get an approval card.`);+ const client = await callerClient(server, principalId);+ const result = await client.callTool(+ entry.name,+ input as Record<string, unknown>,+ headersFor(server, principalId, approval),+ );+ record("call", `${server.id}/${entry.name}`, approval ? "ok approved" : "ok", principalId);+ return resultText(result);+ }+async function refresh(): Promise<void> {+ catalogs.clear();const all = await opts.servers.list();setPublicOAuthClients(mcpPublicOAuthClients(all));const servers = all.filter((s) => s.enabled);@@ -157,6 +287,10 @@ export function createMcpToolService(opts: {for (const server of servers) {try {let tools: NonNullable<McpServer["tools"]>;+ if (server.catalog) {+ next.push(catalogDescriptor(server));+ continue;+ }if (server.auth === "oauth-user") {nextPerUser.set(server.id, server);next.push({@@ -171,7 +305,7 @@ export function createMcpToolService(opts: {});tools = server.tools ?? [];if (!tools.length) continue;- } else tools = await clientFor(server).listTools();+ } else tools = await clientFor(server).listTools({ headers: headersFor(server, undefined) });for (const tool of tools) {next.push({name: `${server.id}_${tool.name}`.replace(/[^a-zA-Z0-9_-]/g, "_"),@@ -227,12 +361,27 @@ export function createMcpToolService(opts: {return {toolDefs: () => snapshot,toolDefsFor,- async call(name, args, principalId) {+ async needsApproval(name, args, principalId) {+ const def = snapshot.find((t) => t.name === name);+ if (!def) throw new Error(`unknown MCP tool: ${name}`);+ if (!def.catalog) return def.needsApproval;+ if (args.operation !== "invoke") return false;+ try {+ const server = await opts.servers.get(def.serverId);+ if (!server || !server.enabled) throw new Error(`MCP server ${def.serverId} is not available`);+ return mcpToolNeedsApproval(server, (await catalogEntry(server, principalId, args.tool)).annotations);+ } catch (e) {+ record("call", callResource(def, args), `approval check error: ${errMessage(e)}`, principalId);+ throw e;+ }+ },+ async call(name, args, principalId, approval) {const def = snapshot.find((t) => t.name === name);if (!def) throw new Error(`unknown MCP tool: ${name}`);const server = await opts.servers.get(def.serverId);if (!server || !server.enabled) throw new Error(`MCP server ${def.serverId} is not available`);try {+ if (def.catalog) return await callCatalog(server, args, principalId, approval);const client = await callerClient(server, principalId);if (def.signIn) {const tools = await client.listTools();@@ -242,22 +391,24 @@ export function createMcpToolService(opts: {record("call", `${def.serverId}/sign_in`, `ok tools=${tools.length}`, principalId);return `Signed in to ${server.name}. Tools now available: ${tools.map((t) => `${server.id}_${t.name}`).join(", ")}`;}- const result = await client.callTool(def.remoteName, args);- record("call", `${def.serverId}/${def.remoteName}`, "ok", principalId);- const text = mcpResultText(result) || JSON.stringify(result.structuredContent ?? "") || "";- return text.length > MAX_RESULT_CHARS ? `${text.slice(0, MAX_RESULT_CHARS)}\n[truncated]` : text;+ const result = await client.callTool(def.remoteName, args, headersFor(server, principalId, approval));+ record("call", `${def.serverId}/${def.remoteName}`, approval ? "ok approved" : "ok", principalId);+ return resultText(result);} catch (e) {if (e instanceof SignInRequired) {- record("call", `${def.serverId}/${def.remoteName}`, "sign-in required", principalId);+ record("call", callResource(def, args), "sign-in required", principalId);return e.message;}- record("call", `${def.serverId}/${def.remoteName}`, `error: ${errMessage(e)}`, principalId);+ record("call", callResource(def, args), `error: ${errMessage(e)}`, principalId);throw e;}},refresh,- async probe(server) {- const tools = await createMcpClient({ url: server.url, auth: authOf(server) }).listTools();+ async probe(server, principalId) {+ const tools = await createMcpClient({ url: server.url, auth: authOf(server) }).listTools({+ headers: headersFor(server, principalId),+ ...(server.catalog ? { maxTools: CATALOG_MAX_TOOLS } : {}),+ });return tools.map((t) => t.name);},close() {diff --git a/src/tools/primitives.ts b/src/tools/primitives.tsindex c77785b8b..dfae5ffb9 100644--- a/src/tools/primitives.ts+++ b/src/tools/primitives.ts@@ -247,7 +247,8 @@ export interface ToolContext extends SurfaceToolDeps {memoryDelete(ids: string[]): Promise<true | null>;history(q: string, limit?: number): Promise<string[]>;historyOpen(seq: number): Promise<string | null>;- callMcpTool(name: string, args: Record<string, unknown>): Promise<string>;+ callMcpTool(name: string, args: Record<string, unknown>, approval?: string): Promise<string>;+ mcpToolNeedsApproval(name: string, args: Record<string, unknown>): Promise<boolean>;awaitClientResult(callId: string,timeoutMs: number,@@ -1239,9 +1240,14 @@ export function createToolContext(deps: ToolContextDeps): ToolContext {return deps.sessionHistory.open(seq);},- async callMcpTool(name: string, args: Record<string, unknown>): Promise<string> {+ async callMcpTool(name: string, args: Record<string, unknown>, approval?: string): Promise<string> {if (!deps.mcp) throw new Error("no MCP connectors are configured");- return deps.mcp.call(name, args, deps.createdBy);+ return deps.mcp.call(name, args, deps.createdBy, approval);+ },++ async mcpToolNeedsApproval(name: string, args: Record<string, unknown>): Promise<boolean> {+ if (!deps.mcp) throw new Error("no MCP connectors are configured");+ return deps.mcp.needsApproval(name, args, deps.createdBy);},async awaitClientResult(callId, timeoutMs, signal, toolName) {diff --git a/test/agent-tools.test.ts b/test/agent-tools.test.tsindex 23953c900..d45489f18 100644--- a/test/agent-tools.test.ts+++ b/test/agent-tools.test.ts@@ -359,6 +359,9 @@ function fakeToolContext(sink?: { lastExecOpts?: Parameters<ToolContext["executeasync callMcpTool() {return "";},+ async mcpToolNeedsApproval() {+ return false;+ },async awaitClientResult() {return "timeout" as const;},@@ -4491,6 +4494,105 @@ test("an MCP tool that needs approval is not called until its exact arguments ar);});+function catalogTools(ref: ToolContextRef, name = "records") {+ return createAgentTools(ref, {+ mcpTools: [+ {+ name,+ serverId: name,+ remoteName: "",+ catalog: true,+ description: "Catalog",+ inputSchema: { type: "object", properties: {} },+ readOnly: false,+ needsApproval: false,+ },+ ],+ });+}++test("a catalog tool asks per call and forwards the approval only on the approved call", async () => {+ const calls: Array<[Record<string, unknown>, string | undefined]> = [];+ const approved = new Set<string>();+ const ref: ToolContextRef = {+ current: {+ ...fakeToolContext(),+ mcpToolNeedsApproval: async (_name, args) => args.operation === "invoke" && args.tool === "send-message",+ callMcpTool: async (_name, args, approval) => {+ calls.push([args, approval]);+ return "ok";+ },+ },+ pendingApprovals: [],+ scopeLabel: "personal:U1",+ toolApprovalGate: (_tool, callKey) => !callKey || approved.has(callKey),+ };+ const catalog = catalogTools(ref).find((t) => t.name === "records")!;+ const send = { operation: "invoke", tool: "send-message", arguments: { to: "x" } };+ await call(catalog, { operation: "invoke", tool: "find", arguments: {} });+ await call(catalog, send);+ assert.deepEqual(calls, [[{ operation: "invoke", tool: "find", arguments: {} }, undefined]]);+ const card = ref.pendingApprovals!.at(-1)!;+ assert.equal(card.command, 'records {"arguments":{"to":"x"},"operation":"invoke","tool":"send-message"}');+ approved.add(card.approvalKey!);+ ref.pausedOnApproval = false;+ await call(catalog, send);+ assert.deepEqual(calls.at(-1), [send, card.approvalKey]);+ approved.clear();+ ref.pausedOnApproval = false;+ await call(catalog, send);+ assert.equal(calls.length, 2, "the next identical call needs its own approval");+ assert.equal(ref.pendingApprovals!.length, 2);+});++test("a failing approval check returns its error to the model and offers no card", async () => {+ let ran = false;+ const ref: ToolContextRef = {+ current: {+ ...fakeToolContext(),+ mcpToolNeedsApproval: async () => {+ throw new Error("Unknown Records tool: nope. Search for it first.");+ },+ callMcpTool: async () => {+ ran = true;+ return "ok";+ },+ },+ pendingApprovals: [],+ toolApprovalGate: () => true,+ };+ const catalog = catalogTools(ref).find((t) => t.name === "records")!;+ assert.match(+ textOut(await call(catalog, { operation: "invoke", tool: "nope" })),+ /could not check whether this call needs approval: Unknown Records tool: nope/,+ );+ assert.equal(ran, false);+ assert.deepEqual(ref.pendingApprovals, []);+});++test("a catalog named like a native tool never replaces it or widens read-only turns", () => {+ const ref: ToolContextRef = { current: fakeToolContext() };+ const files = catalogTools(ref, "files").filter((t) => t.name === "files");+ assert.equal(files.length, 1);+ assert.doesNotMatch(files[0]!.description, /^Catalog/);+ const readOnly = createAgentTools(ref, {+ readOnly: true,+ mcpTools: [+ {+ name: "files",+ serverId: "files",+ remoteName: "",+ catalog: true,+ description: "Catalog",+ inputSchema: { type: "object", properties: {} },+ readOnly: true,+ needsApproval: false,+ },+ ],+ });+ assert.ok(!readOnly.some((t) => t.name === "files"));+});+test("a tool that needs approval fails closed without an approval gate", async () => {let called = false;const ref: ToolContextRef = {diff --git a/test/mcp-admin.test.ts b/test/mcp-admin.test.tsindex 6682800a7..c5c1c7a09 100644--- a/test/mcp-admin.test.ts+++ b/test/mcp-admin.test.ts@@ -94,6 +94,32 @@ test("MCP admin validates and preserves credential scope, without returning secrassert.equal((await store.get("crm"))?.approval, "all", "an update that omits the policy keeps it");assert.equal((await put({ approval: "annotations" })).status, 200);assert.equal((await store.get("crm"))?.approval, undefined);+ assert.equal((await put({ attestActor: true })).status, 400);+ assert.equal(+ (await put({ catalog: true, attestActor: true })).status,+ 400,+ "an unauthenticated upstream cannot trust the actor",+ );+ assert.equal(+ (+ await put({+ catalog: true,+ attestActor: true,+ auth: "bearer",+ bearerToken: "t",+ credentialScope: "per-user",+ credentialHost: "accounts.example.com",+ })+ ).status,+ 400,+ "a per-person token could otherwise assert someone else",+ );+ assert.equal(+ (await put({ catalog: true, attestActor: true, auth: "bearer", bearerToken: "t", credentialScope: "shared" }))+ .status,+ 200,+ );+ assert.deepEqual([(await store.get("crm"))?.catalog, (await store.get("crm"))?.attestActor], [true, true]);});test("production wiring never uses operator fallback tokens for per-user MCP calls", async (t) => {diff --git a/test/mcp-connectors.test.ts b/test/mcp-connectors.test.tsindex b71a4de49..e3a9f3e44 100644--- a/test/mcp-connectors.test.ts+++ b/test/mcp-connectors.test.ts@@ -175,6 +175,86 @@ test("destructive annotations mark MCP tools for approval unless the server overservice.close();});+test("a catalog server is one tool that searches, describes, and invokes as the attested person", async (t) => {+ const mcp = await startMcpTestServer(t, {+ tools: [+ { name: "find-record", description: "Find a record by name", inputSchema: { type: "object" } },+ {+ name: "send-message",+ description: "Send a message to a contact\nLong detail",+ inputSchema: { type: "object", properties: { to: { type: "string" } } },+ annotations: { destructiveHint: true },+ },+ ],+ call: (name, args) => ({ content: [{ type: "text", text: `${name} ${JSON.stringify(args)}` }] }),+ });+ const store = createMcpServerStore(createMemoryMap<McpServer>());+ const service = createMcpToolService({ servers: store, refreshIntervalMs: 3600_000 });+ await store.put(server({ id: "records", name: "Records", url: mcp.url, catalog: true, attestActor: true }));+ await service.refresh();+ assert.deepEqual(+ service.toolDefs().map((d) => [d.name, d.catalog]),+ [["records", true]],+ );+ assert.equal(mcp.requests.filter((r) => r.rpc === "tools/list").length, 0, "a catalog is listed per person on use");+ assert.equal(+ await service.call("records", { operation: "search", query: "message" }, "[email protected]"),+ "- send-message (needs approval): Send a message to a contact",+ );+ assert.match(+ await service.call("records", { operation: "describe", tool: "send-message" }, "[email protected]"),+ /"needsApproval":true/,+ );+ assert.equal(+ await service.needsApproval("records", { operation: "invoke", tool: "send-message" }, "[email protected]"),+ true,+ );+ assert.equal(+ await service.needsApproval("records", { operation: "invoke", tool: "find-record" }, "[email protected]"),+ false,+ );+ assert.equal(await service.needsApproval("records", { operation: "search" }, "[email protected]"), false);+ await assert.rejects(+ service.needsApproval("records", { operation: "invoke", tool: "send_message" }, "[email protected]"),+ /Unknown Records tool: send_message\. Search for it first/,+ );+ await assert.rejects(+ service.call("records", { operation: "invoke", tool: "send-message", arguments: { to: "x" } }, "[email protected]"),+ /needs the person's approval/,+ "an approval-requiring tool never goes out without an approval",+ );+ assert.equal(+ await service.call(+ "records",+ { operation: "invoke", tool: "send-message", arguments: { to: "x" } },+ "[email protected]",+ "tool-call:abc",+ ),+ 'send-message {"to":"x"}',+ );+ assert.deepEqual(+ mcp.requests.filter((r) => r.rpc === "tools/call").map((r) => [r.actor, r.approval]),+ [["[email protected]", "tool-call:abc"]],+ );+ assert.equal(mcp.requests.filter((r) => r.rpc === "tools/list").length, 1, "the catalog is cached per person");+ await service.call("records", { operation: "search" }, "[email protected]");+ assert.equal(mcp.requests.filter((r) => r.rpc === "tools/list").length, 2, "each person gets their own catalog");+ assert.ok(mcp.requests.every((r) => r.actor === "[email protected]" || r.actor === "[email protected]"));+ await assert.rejects(service.call("records", { operation: "search" }), /needs a signed-in person/);+ await service.refresh();+ const lists = mcp.requests.filter((r) => r.rpc === "tools/list").length;+ await Promise.all([+ service.call("records", { operation: "search" }, "[email protected]"),+ service.call("records", { operation: "search" }, "[email protected]"),+ ]);+ assert.equal(+ mcp.requests.filter((r) => r.rpc === "tools/list").length,+ lists + 1,+ "refresh drops the cache and parallel lookups share one listing",+ );+ service.close();+});+test("disabled server's tools disappear and calls fail", async (t) => {const mcp = await startMcpTestServer(t);const store = createMcpServerStore(createMemoryMap<McpServer>());diff --git a/test/support/mcp-test-server.ts b/test/support/mcp-test-server.tsindex 14360deba..af7e53fa4 100644--- a/test/support/mcp-test-server.ts+++ b/test/support/mcp-test-server.ts@@ -17,6 +17,8 @@ interface McpRequest {path: string;rpc?: string;authorization?: string;+ actor?: string;+ approval?: string;}export interface McpTestServer {@@ -123,6 +125,8 @@ export async function startMcpTestServer(path,...(parsed?.method ? { rpc: parsed.method } : {}),...(authorization ? { authorization } : {}),+ ...(typeof req.headers["x-qm-actor"] === "string" ? { actor: req.headers["x-qm-actor"] } : {}),+ ...(typeof req.headers["x-qm-approval"] === "string" ? { approval: req.headers["x-qm-approval"] } : {}),});if (!authorized(authorization)) {return json(res, 401, { error: "unauthorized" }, { "www-authenticate": 'Bearer error="invalid_token"' });