Skip to content

armgit / qm

Public Imported from GitHub
0

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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["execute
async 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.ts
index 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 secr
assert.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.ts
index 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 over
service.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" } },
+ "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.ts
index 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"' });