@explyt/ai-agent 0.1.0-rc.1 → 0.1.3

package/node_modules/pi-subagents/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -2,11 +2,21 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { findConfiguredProjectRoot } from "../../agents/agents.ts";
 import { getAgentDir, getProjectConfigDir } from "../../shared/utils.ts";
+import { isMcpServerDefinition, loadAgentPluginMcpServers, loadPackageMcpServers, type McpServerDefinition } from "./mcp-config-sources.ts";
+import {
+	normalizeMcpDirectToolSelectors,
+	parseMcpDirectToolSelectors,
+	planMcpDirectToolGrant,
+} from "./mcp-direct-tool-grant.ts";
+import type { McpToolPrefix, ResolvedMcpDirectToolSelection } from "./mcp-direct-tool-grant.ts";
+
+export { formatUnresolvedMcpDirectToolSelectors } from "./mcp-direct-tool-grant.ts";
+export type { ResolvedMcpDirectToolSelection } from "./mcp-direct-tool-grant.ts";
 
 const CACHE_VERSION = 1;
 const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
-const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 const GENERIC_GLOBAL_CONFIG_PATH = path.join(os.homedir(), ".config", "mcp", "mcp.json");
 const IMPORT_PATHS = {
 	cursor: [path.join(os.homedir(), ".cursor", "mcp.json")],
@@ -21,33 +31,41 @@ const IMPORT_PATHS = {
 	vscode: [".vscode/mcp.json"],
 } as const;
 
-type ToolPrefix = "server" | "none" | "short";
 type ImportKind = keyof typeof IMPORT_PATHS;
 
-interface ServerEntry {
-	command?: string;
-	args?: string[];
-	socket?: string;
-	env?: Record<string, string>;
-	cwd?: string;
-	url?: string;
-	headers?: Record<string, string>;
-	auth?: "oauth" | "bearer" | false;
-	bearerToken?: string;
-	bearerTokenEnv?: string;
-	exposeResources?: boolean;
-	includeTools?: string[];
-	excludeTools?: string[];
-	protocolVersion?: string;
-	directTools?: boolean | string[];
-}
-
-interface McpConfig {
+type ServerEntry = McpServerDefinition;
+
+export interface McpConfig {
 	mcpServers: Record<string, ServerEntry>;
 	imports?: ImportKind[];
 	settings?: {
-		toolPrefix?: ToolPrefix;
+		toolPrefix?: McpToolPrefix;
 		directTools?: boolean;
+		agentPluginPaths?: unknown;
+	};
+}
+
+export const MCP_RUNTIME_SNAPSHOT_EVENT = "pi-mcp-adapter:runtime-snapshot:v1" as const;
+export const MCP_RUNTIME_SNAPSHOT_VERSION = 1 as const;
+
+export interface McpRuntimeServerSnapshot {
+	readonly name: string;
+	readonly definition: ServerEntry;
+	readonly runtime: true;
+	readonly persisted: false;
+}
+
+interface McpRuntimeSnapshotRequest {
+	version: typeof MCP_RUNTIME_SNAPSHOT_VERSION;
+	name: string;
+	result?:
+		| { ok: true; snapshot: McpRuntimeServerSnapshot }
+		| { ok: false; error: Error };
+}
+
+export interface McpRuntimeSnapshotHost {
+	events: {
+		emit(event: string, request: McpRuntimeSnapshotRequest): void;
 	};
 }
 
@@ -72,19 +90,59 @@ interface MetadataCache {
 	servers: Record<string, ServerCacheEntry>;
 }
 
-export interface ResolvedMcpDirectToolSelection { name: string; selector: string }
-
-export function resolveMcpDirectToolSelections(mcpDirectTools: string[] | undefined, cwd = process.cwd()): ResolvedMcpDirectToolSelection[] {
-	if (!mcpDirectTools?.length) return [];
-
-	try {
-		const config = loadMcpConfig(cwd);
-		const cache = loadMetadataCache();
-		if (!cache) return [];
-		return resolveDirectToolSelections(config, cache, getToolPrefix(config.settings?.toolPrefix), mcpDirectTools);
-	} catch {
-		return [];
+export interface McpDirectToolResolution {
+	selections: ResolvedMcpDirectToolSelection[];
+	unresolvedSelectors: string[];
+	/** Normal loaded config plus the selected runtime server definitions. */
+	mcpConfig?: McpConfig;
+	runtimeServerNames?: string[];
+}
+
+export function resolveMcpDirectToolResolution(
+	mcpDirectTools: string[] | undefined,
+	cwd = process.cwd(),
+	runtimeSnapshotHost?: McpRuntimeSnapshotHost,
+	configOverride?: McpConfig,
+): McpDirectToolResolution {
+	const selectors = normalizeMcpDirectToolSelectors(mcpDirectTools);
+	if (selectors.length === 0) return { selections: [], unresolvedSelectors: [] };
+
+	const config = configOverride ?? loadMcpConfig(cwd);
+	const { servers: selectedServers, tools: selectedTools } = parseMcpDirectToolSelectors(selectors);
+	const runtimeSelectionServers = new Set([...selectedServers, ...selectedTools.keys()]);
+	const runtimeServers = resolveRuntimeMcpServers(config, runtimeSelectionServers, runtimeSnapshotHost);
+	const resolvedConfig = Object.keys(runtimeServers).length > 0
+		? mergeConfigs(config, { mcpServers: runtimeServers })
+		: config;
+	validateSelectedServerDefinitions(resolvedConfig, selectors);
+	const cache = loadMetadataCache();
+	if (!cache) return { selections: [], unresolvedSelectors: selectors };
+	const validMetadata: Record<string, ServerCacheEntry> = {};
+	for (const [serverName, definition] of Object.entries(resolvedConfig.mcpServers)) {
+		const serverCache = cache.servers[serverName];
+		if (isServerCacheValid(serverCache, definition)) validMetadata[serverName] = serverCache;
 	}
+	const grant = planMcpDirectToolGrant({
+		selectors,
+		servers: resolvedConfig.mcpServers,
+		metadata: validMetadata,
+		toolPrefix: resolvedConfig.settings?.toolPrefix,
+	});
+	return {
+		selections: grant.selections,
+		unresolvedSelectors: grant.unresolvedSelectors,
+		...(Object.keys(runtimeServers).length > 0
+			? { mcpConfig: resolvedConfig, runtimeServerNames: Object.keys(runtimeServers) }
+			: {}),
+	};
+}
+
+export function resolveMcpDirectToolSelections(
+	mcpDirectTools: string[] | undefined,
+	cwd = process.cwd(),
+	runtimeSnapshotHost?: McpRuntimeSnapshotHost,
+): ResolvedMcpDirectToolSelection[] {
+	return resolveMcpDirectToolResolution(mcpDirectTools, cwd, runtimeSnapshotHost).selections;
 }
 
 function loadMetadataCache(): MetadataCache | null {
@@ -96,28 +154,116 @@ function loadMetadataCache(): MetadataCache | null {
 		return null;
 	}
 
-	if (!parsed || typeof parsed !== "object") return null;
-	const raw = parsed as Record<string, unknown>;
-	if (raw.version !== CACHE_VERSION || !raw.servers || typeof raw.servers !== "object" || Array.isArray(raw.servers)) {
-		return null;
+	if (!isRecord(parsed) || parsed.version !== CACHE_VERSION || !isRecord(parsed.servers)) return null;
+	const servers: Record<string, ServerCacheEntry> = {};
+	for (const [name, value] of Object.entries(parsed.servers)) {
+		const entry = parseServerCacheEntry(value);
+		if (entry) servers[name] = entry;
 	}
-	return raw as unknown as MetadataCache;
+	return { version: CACHE_VERSION, servers };
+}
+
+function parseServerCacheEntry(value: unknown): ServerCacheEntry | undefined {
+	if (!isRecord(value)) return undefined;
+	if (value.configHash !== undefined && typeof value.configHash !== "string") return undefined;
+	if (value.cachedAt !== undefined && (typeof value.cachedAt !== "number" || !Number.isFinite(value.cachedAt))) return undefined;
+	if (value.tools !== undefined && !Array.isArray(value.tools)) return undefined;
+	if (value.resources !== undefined && !Array.isArray(value.resources)) return undefined;
+	const tools = value.tools?.map(parseCachedTool);
+	const resources = value.resources?.map(parseCachedResource);
+	if (tools && !tools.every((entry): entry is CachedTool => entry !== undefined)) return undefined;
+	if (resources && !resources.every((entry): entry is CachedResource => entry !== undefined)) return undefined;
+	return {
+		...(value.configHash !== undefined ? { configHash: value.configHash } : {}),
+		...(value.cachedAt !== undefined ? { cachedAt: value.cachedAt } : {}),
+		...(tools ? { tools } : {}),
+		...(resources ? { resources } : {}),
+	};
+}
+
+function parseCachedTool(value: unknown): CachedTool | undefined {
+	if (!isRecord(value) || (value.name !== undefined && typeof value.name !== "string")) return undefined;
+	return value.name === undefined ? {} : { name: value.name };
+}
+
+function parseCachedResource(value: unknown): CachedResource | undefined {
+	if (!isRecord(value)) return undefined;
+	if (value.uri !== undefined && typeof value.uri !== "string") return undefined;
+	if (value.name !== undefined && typeof value.name !== "string") return undefined;
+	return {
+		...(value.uri !== undefined ? { uri: value.uri } : {}),
+		...(value.name !== undefined ? { name: value.name } : {}),
+	};
+}
+
+function resolveRuntimeMcpServers(
+	config: McpConfig,
+	selectedServers: ReadonlySet<string>,
+	runtimeSnapshotHost: McpRuntimeSnapshotHost | undefined,
+): Record<string, ServerEntry> {
+	if (!runtimeSnapshotHost) return {};
+	const runtimeServers: Record<string, ServerEntry> = {};
+	for (const serverName of selectedServers) {
+		if (Object.hasOwn(config.mcpServers, serverName)) continue;
+		try {
+			const snapshot = getRuntimeMcpServerSnapshot(runtimeSnapshotHost, serverName);
+			runtimeServers[serverName] = snapshot.definition;
+		} catch {
+			// Missing, disposed, or shadowed runtime servers remain unresolved below.
+		}
+	}
+	return runtimeServers;
+}
+
+function getRuntimeMcpServerSnapshot(
+	host: McpRuntimeSnapshotHost,
+	name: string,
+): McpRuntimeServerSnapshot {
+	const request: McpRuntimeSnapshotRequest = {
+		version: MCP_RUNTIME_SNAPSHOT_VERSION,
+		name,
+	};
+	host.events.emit(MCP_RUNTIME_SNAPSHOT_EVENT, request);
+	if (!request.result) throw new Error("pi-mcp-adapter is not installed for this Pi instance");
+	if (!request.result.ok) throw request.result.error;
+	const snapshot = request.result.snapshot;
+	if (
+		!snapshot ||
+		snapshot.name !== name ||
+		snapshot.runtime !== true ||
+		snapshot.persisted !== false ||
+		!isMcpServerDefinition(snapshot.definition)
+	) {
+		throw new Error(`Invalid MCP runtime snapshot for server "${name}"`);
+	}
+	return snapshot;
 }
 
 function loadMcpConfig(cwd: string): McpConfig {
+	const resolvedCwd = path.resolve(cwd);
+	const projectRoot = findConfiguredProjectRoot(resolvedCwd) ?? resolvedCwd;
 	let config: McpConfig = { mcpServers: {} };
-	for (const sourcePath of getConfigPaths(cwd)) {
+	for (const sourcePath of getConfigPaths(projectRoot)) {
 		const loaded = readConfig(sourcePath);
 		if (!loaded) continue;
-		config = mergeConfigs(config, expandImports(loaded, cwd));
+		config = mergeConfigs(config, expandImports(loaded, projectRoot));
 	}
-	return config;
+
+	const packageServers = loadPackageMcpServers(projectRoot);
+	const pluginServers = loadAgentPluginMcpServers(config.settings?.agentPluginPaths, projectRoot);
+	const packageOnlyServers = Object.fromEntries(
+		Object.entries(packageServers).filter(([name]) => !Object.hasOwn(pluginServers, name)),
+	);
+	return mergeConfigs(
+		{ mcpServers: packageOnlyServers },
+		mergeConfigs({ mcpServers: pluginServers }, config),
+	);
 }
 
-function getConfigPaths(cwd: string): string[] {
+function getConfigPaths(projectRoot: string): string[] {
 	const piGlobalPath = path.join(getAgentDir(), "mcp.json");
-	const projectPath = path.resolve(cwd, ".mcp.json");
-	const projectPiPath = path.resolve(getProjectConfigDir(cwd), "mcp.json");
+	const projectPath = path.resolve(projectRoot, ".mcp.json");
+	const projectPiPath = path.resolve(getProjectConfigDir(projectRoot), "mcp.json");
 	const sources: string[] = [];
 	if (GENERIC_GLOBAL_CONFIG_PATH !== piGlobalPath) sources.push(GENERIC_GLOBAL_CONFIG_PATH);
 	sources.push(piGlobalPath);
@@ -137,18 +283,33 @@ function readConfig(configPath: string): McpConfig | null {
 }
 
 function validateConfig(raw: unknown): McpConfig {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { mcpServers: {} };
-	const obj = raw as Record<string, unknown>;
+	if (!isRecord(raw)) return { mcpServers: {} };
+	const obj = raw;
 	const servers = obj.mcpServers ?? obj["mcp-servers"] ?? {};
 	return {
-		mcpServers: servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {},
+		mcpServers: parseServerEntries(servers),
 		imports: Array.isArray(obj.imports) ? obj.imports.filter((value): value is ImportKind => isImportKind(value)) : undefined,
-		settings: obj.settings && typeof obj.settings === "object" && !Array.isArray(obj.settings)
-			? obj.settings as McpConfig["settings"]
-			: undefined,
+		settings: parseSettings(obj.settings),
 	};
 }
 
+function parseServerEntries(value: unknown): Record<string, ServerEntry> {
+	if (!isRecord(value)) return {};
+	return Object.fromEntries(Object.entries(value).filter((entry): entry is [string, ServerEntry] => isMcpServerDefinition(entry[1])));
+}
+
+function parseSettings(value: unknown): McpConfig["settings"] | undefined {
+	if (!isRecord(value)) return undefined;
+	const toolPrefix = value.toolPrefix === "server" || value.toolPrefix === "short" || value.toolPrefix === "none" ? value.toolPrefix : undefined;
+	const directTools = typeof value.directTools === "boolean" ? value.directTools : undefined;
+	const settings: NonNullable<McpConfig["settings"]> = {
+		...(toolPrefix ? { toolPrefix } : {}),
+		...(directTools !== undefined ? { directTools } : {}),
+		...(value.agentPluginPaths !== undefined ? { agentPluginPaths: value.agentPluginPaths } : {}),
+	};
+	return Object.keys(settings).length ? settings : undefined;
+}
+
 function mergeConfigs(base: McpConfig, next: McpConfig): McpConfig {
 	const imports = [...(base.imports ?? []), ...(next.imports ?? [])];
 	return {
@@ -192,76 +353,24 @@ function resolveImportPath(importKind: ImportKind, cwd: string): string | null {
 }
 
 function extractServers(config: unknown, kind: ImportKind): Record<string, ServerEntry> {
-	if (!config || typeof config !== "object" || Array.isArray(config)) return {};
-	const obj = config as Record<string, unknown>;
+	if (!isRecord(config)) return {};
+	const obj = config;
 	const servers = kind === "cursor" || kind === "windsurf" || kind === "vscode"
 		? obj.mcpServers ?? obj["mcp-servers"]
 		: obj.mcpServers;
-	return servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {};
-}
-
-function resolveDirectToolSelections(config: McpConfig, cache: MetadataCache, prefix: ToolPrefix, envOverride: string[]): ResolvedMcpDirectToolSelection[] {
-	const names: ResolvedMcpDirectToolSelection[] = [];
-	const seenNames = new Set<string>();
-	const { servers: selectedServers, tools: selectedTools } = parseSelections(envOverride);
-
-	for (const [serverName, definition] of Object.entries(config.mcpServers)) {
-		const serverCache = cache.servers[serverName];
-		if (!isServerCacheValid(serverCache, definition)) continue;
-
-		const toolFilter = selectedServers.has(serverName)
-			? true
-			: selectedTools.get(serverName);
-		if (!toolFilter) continue;
-
-		for (const tool of Array.isArray(serverCache.tools) ? serverCache.tools : []) {
-			if (typeof tool?.name !== "string" || !tool.name) continue;
-			if (toolFilter !== true && !toolFilter.has(tool.name)) continue;
-			if (isToolExcluded(tool.name, serverName, prefix, definition.excludeTools)) continue;
-			const prefixedName = formatToolName(tool.name, serverName, prefix);
-			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
-			seenNames.add(prefixedName);
-			names.push({ name: prefixedName, selector: `${serverName}/${tool.name}` });
-		}
-
-		if (definition.exposeResources === false) continue;
-		for (const resource of Array.isArray(serverCache.resources) ? serverCache.resources : []) {
-			if (typeof resource?.name !== "string" || !resource.name || typeof resource.uri !== "string" || !resource.uri) continue;
-			const baseName = `get_${resourceNameToToolName(resource.name)}`;
-			if (toolFilter !== true && !toolFilter.has(baseName)) continue;
-			if (isToolExcluded(baseName, serverName, prefix, definition.excludeTools)) continue;
-			const prefixedName = formatToolName(baseName, serverName, prefix);
-			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
-			seenNames.add(prefixedName);
-			names.push({ name: prefixedName, selector: `${serverName}/${baseName}` });
-		}
-	}
-
-	return names;
+	return parseServerEntries(servers);
 }
 
 export function resolveMcpDirectToolNames(mcpDirectTools: string[] | undefined, cwd = process.cwd()): string[] {
 	return resolveMcpDirectToolSelections(mcpDirectTools, cwd).map((selection) => selection.name);
 }
 
-function parseSelections(selections: string[]): { servers: Set<string>; tools: Map<string, Set<string>> } {
-	const servers = new Set<string>();
-	const tools = new Map<string, Set<string>>();
-	for (let item of selections) {
-		item = item.replace(/\/+$/, "");
-		if (item.includes("/")) {
-			const [server, tool] = item.split("/", 2);
-			if (server && tool) {
-				if (!tools.has(server)) tools.set(server, new Set());
-				tools.get(server)!.add(tool);
-			} else if (server) {
-				servers.add(server);
-			}
-		} else if (item) {
-			servers.add(item);
-		}
+function validateSelectedServerDefinitions(config: McpConfig, selectors: string[]): void {
+	const { servers, tools } = parseMcpDirectToolSelectors(selectors);
+	for (const serverName of new Set([...servers, ...tools.keys()])) {
+		const definition = config.mcpServers[serverName];
+		if (definition) computeMcpServerHash(definition);
 	}
-	return { servers, tools };
 }
 
 function isServerCacheValid(entry: ServerCacheEntry | undefined, definition: ServerEntry): entry is ServerCacheEntry {
@@ -279,6 +388,14 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 		cwd: resolveConfigPath(definition.cwd),
 		url: resolveServerUrl(definition),
 		headers: interpolateEnvRecord(definition.headers),
+		requestHeadersCommand: definition.requestHeadersCommand
+			? {
+				command: interpolateEnvVars(definition.requestHeadersCommand.command),
+				args: definition.requestHeadersCommand.args?.map(interpolateEnvVars),
+				env: interpolateEnvRecord(definition.requestHeadersCommand.env),
+				timeoutMs: definition.requestHeadersCommand.timeoutMs,
+			}
+			: undefined,
 		auth: definition.auth,
 		bearerToken: resolveBearerToken(definition),
 		bearerTokenEnv: definition.bearerTokenEnv,
@@ -290,52 +407,12 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 	return createHash("sha256").update(stableStringify(identity)).digest("hex");
 }
 
-function getToolPrefix(value: unknown): ToolPrefix {
-	return value === "none" || value === "short" || value === "server" ? value : "server";
-}
-
 function isImportKind(value: unknown): value is ImportKind {
 	return typeof value === "string" && Object.hasOwn(IMPORT_PATHS, value);
 }
 
-function getServerPrefix(serverName: string, mode: ToolPrefix): string {
-	if (mode === "none") return "";
-	if (mode === "short") {
-		const short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
-		return short || "mcp";
-	}
-	return serverName.replace(/-/g, "_");
-}
-
-function formatToolName(toolName: string, serverName: string, prefix: ToolPrefix): string {
-	const serverPrefix = getServerPrefix(serverName, prefix);
-	return serverPrefix ? `${serverPrefix}_${toolName}` : toolName;
-}
-
-function isToolExcluded(toolName: string, serverName: string, prefix: ToolPrefix, excludeTools: unknown): boolean {
-	if (!Array.isArray(excludeTools) || excludeTools.length === 0) return false;
-	const candidates = new Set([
-		normalizeToolName(toolName),
-		normalizeToolName(formatToolName(toolName, serverName, prefix)),
-		normalizeToolName(formatToolName(toolName, serverName, "server")),
-		normalizeToolName(formatToolName(toolName, serverName, "short")),
-	]);
-	return excludeTools.some((excluded) => typeof excluded === "string" && candidates.has(normalizeToolName(excluded)));
-}
-
-function normalizeToolName(value: string): string {
-	return value.replace(/-/g, "_");
-}
-
-function resourceNameToToolName(name: string): string {
-	let result = name
-		.replace(/[^a-zA-Z0-9]/g, "_")
-		.replace(/_+/g, "_")
-		.replace(/^_+/, "")
-		.replace(/_+$/, "")
-		.toLowerCase();
-	if (!result || /^\d/.test(result)) result = `resource${result ? `_${result}` : ""}`;
-	return result;
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
 function interpolateEnvRecord(values: Record<string, string> | undefined): Record<string, string> | undefined {

package/node_modules/pi-subagents/src/runs/shared/mcp-direct-tool-grant.ts

@@ -0,0 +1,194 @@
+const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
+
+export type McpToolPrefix = "server" | "none" | "short";
+
+export interface McpGrantServerFacts {
+	readonly exposeResources?: boolean;
+	readonly includeTools?: readonly unknown[];
+	readonly excludeTools?: readonly unknown[];
+}
+
+export interface McpGrantToolMetadata {
+	readonly name?: string;
+}
+
+export interface McpGrantResourceMetadata {
+	readonly name?: string;
+	readonly uri?: string;
+}
+
+export interface McpGrantServerMetadata {
+	readonly tools?: readonly McpGrantToolMetadata[];
+	readonly resources?: readonly McpGrantResourceMetadata[];
+}
+
+export interface McpDirectToolGrantInput {
+	readonly selectors?: readonly string[];
+	readonly servers: Readonly<Record<string, McpGrantServerFacts>>;
+	/** Cache entries already validated by the source-loading adapter. */
+	readonly metadata: Readonly<Record<string, McpGrantServerMetadata>>;
+	readonly toolPrefix?: unknown;
+}
+
+export interface ResolvedMcpDirectToolSelection {
+	name: string;
+	selector: string;
+}
+
+export interface McpDirectToolGrant {
+	selections: ResolvedMcpDirectToolSelection[];
+	unresolvedSelectors: string[];
+}
+
+export function normalizeMcpDirectToolSelectors(selectors: readonly string[] | undefined): string[] {
+	return [...new Set((selectors ?? []).map((selector) => selector.replace(/\/+$/, "")).filter(Boolean))];
+}
+
+export function parseMcpDirectToolSelectors(selectors: readonly string[]): {
+	servers: Set<string>;
+	tools: Map<string, Set<string>>;
+} {
+	const servers = new Set<string>();
+	const tools = new Map<string, Set<string>>();
+	for (const item of selectors) {
+		if (item.includes("/")) {
+			const [server, tool] = item.split("/", 2);
+			if (server && tool) {
+				if (!tools.has(server)) tools.set(server, new Set());
+				tools.get(server)!.add(tool);
+			} else if (server) {
+				servers.add(server);
+			}
+		} else if (item) {
+			servers.add(item);
+		}
+	}
+	return { servers, tools };
+}
+
+export function planMcpDirectToolGrant(input: McpDirectToolGrantInput): McpDirectToolGrant {
+	const selectors = normalizeMcpDirectToolSelectors(input.selectors);
+	if (selectors.length === 0) return { selections: [], unresolvedSelectors: [] };
+
+	const { servers: selectedServers, tools: selectedTools } = parseMcpDirectToolSelectors(selectors);
+	const selections: ResolvedMcpDirectToolSelection[] = [];
+	const seenNames = new Set<string>();
+	const prefix = normalizeMcpToolPrefix(input.toolPrefix);
+
+	for (const [serverName, server] of Object.entries(input.servers)) {
+		const metadata = input.metadata[serverName];
+		if (!metadata) continue;
+
+		const toolFilter: true | ReadonlySet<string> | undefined = selectedServers.has(serverName)
+			? true
+			: selectedTools.get(serverName);
+		if (!toolFilter) continue;
+
+		for (const tool of Array.isArray(metadata.tools) ? metadata.tools : []) {
+			if (typeof tool?.name !== "string" || !tool.name) continue;
+			if (toolFilter !== true && !toolFilter.has(tool.name)) continue;
+			if (!isToolAllowed(tool.name, serverName, prefix, server.includeTools, server.excludeTools)) continue;
+			const name = formatToolName(tool.name, serverName, prefix);
+			if (BUILTIN_TOOL_NAMES.has(name) || seenNames.has(name)) continue;
+			seenNames.add(name);
+			selections.push({ name, selector: `${serverName}/${tool.name}` });
+		}
+
+		if (server.exposeResources === false) continue;
+		for (const resource of Array.isArray(metadata.resources) ? metadata.resources : []) {
+			if (typeof resource?.name !== "string" || !resource.name || typeof resource.uri !== "string" || !resource.uri) continue;
+			const baseName = `get_${resourceNameToToolName(resource.name)}`;
+			if (toolFilter !== true && !toolFilter.has(baseName)) continue;
+			if (!isToolAllowed(baseName, serverName, prefix, server.includeTools, server.excludeTools)) continue;
+			const name = formatToolName(baseName, serverName, prefix);
+			if (BUILTIN_TOOL_NAMES.has(name) || seenNames.has(name)) continue;
+			seenNames.add(name);
+			selections.push({ name, selector: `${serverName}/${baseName}` });
+		}
+	}
+
+	const unresolvedSelectors = selectors.filter((selector) =>
+		selector.includes("/")
+			? !selections.some((selection) => selection.selector === selector)
+			: !selections.some((selection) => selection.selector.startsWith(`${selector}/`)),
+	);
+	return { selections, unresolvedSelectors };
+}
+
+export function normalizeMcpToolPrefix(value: unknown): McpToolPrefix {
+	return value === "none" || value === "short" || value === "server" ? value : "server";
+}
+
+export function formatUnresolvedMcpDirectToolSelectors(selectors: readonly string[]): string {
+	return `Unresolved MCP direct-tool selectors: ${selectors.join(", ")}. Direct MCP tools require a matching configured server and fresh metadata cache; runtime-registered servers require a host/pi-mcp-adapter handoff before child launch.`;
+}
+
+function getServerPrefix(serverName: string, mode: McpToolPrefix): string {
+	if (mode === "none") return "";
+	if (mode === "short") return serverName.replace(/-?mcp$/i, "") || "mcp";
+	return serverName;
+}
+
+function formatToolName(toolName: string, serverName: string, prefix: McpToolPrefix): string {
+	const serverPrefix = getServerPrefix(serverName, prefix);
+	return serverPrefix ? `${serverPrefix}_${toolName}` : toolName;
+}
+
+function isToolAllowed(
+	toolName: string,
+	serverName: string,
+	prefix: McpToolPrefix,
+	includeTools: readonly unknown[] | undefined,
+	excludeTools: readonly unknown[] | undefined,
+): boolean {
+	const candidates = toolNameCandidates(toolName, serverName, prefix);
+	return (!Array.isArray(includeTools) || includeTools.length === 0 || matchesToolPatterns(candidates, includeTools))
+		&& !matchesToolPatterns(candidates, excludeTools);
+}
+
+function toolNameCandidates(toolName: string, serverName: string, prefix: McpToolPrefix): Set<string> {
+	return new Set([
+		toolName,
+		`mcp_${toolName}`,
+		formatToolName(toolName, serverName, prefix),
+		formatToolName(toolName, serverName, "server"),
+		formatToolName(toolName, serverName, "short"),
+		formatToolName(toolName, serverName, "none"),
+	]);
+}
+
+function matchesToolPatterns(candidates: ReadonlySet<string>, patterns: readonly unknown[] | undefined): boolean {
+	if (!Array.isArray(patterns) || patterns.length === 0) return false;
+	for (const pattern of patterns) {
+		if (typeof pattern !== "string") continue;
+		const normalizedPattern = normalizeToolName(pattern);
+		const matcher = normalizedPattern.includes("*") || normalizedPattern.includes("?")
+			? globToRegExp(normalizedPattern)
+			: undefined;
+		for (const candidate of candidates) {
+			const normalizedCandidate = normalizeToolName(candidate);
+			if (matcher ? matcher.test(normalizedCandidate) : normalizedCandidate === normalizedPattern) return true;
+		}
+	}
+	return false;
+}
+
+function globToRegExp(pattern: string): RegExp {
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+	return new RegExp(`^${escaped}$`);
+}
+
+function normalizeToolName(value: string): string {
+	return value.replace(/-/g, "_");
+}
+
+function resourceNameToToolName(name: string): string {
+	let result = name
+		.replace(/[^a-zA-Z0-9]/g, "_")
+		.replace(/_+/g, "_")
+		.replace(/^_+/, "")
+		.replace(/_+$/, "")
+		.toLowerCase();
+	if (!result || /^\d/.test(result)) result = `resource${result ? `_${result}` : ""}`;
+	return result;
+}