@foundation0/api 1.1.1 → 1.1.3

package/mcp/server.ts

@@ -1,522 +1,2535 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
-import * as agentsApi from '../agents.ts'
-import * as projectsApi from '../projects.ts'
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+	CallToolRequestSchema,
+	ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import * as agentsApi from "../agents.ts";
+import * as netApi from "../net.ts";
+import * as projectsApi from "../projects.ts";
+import fs from "node:fs";
+import path from "node:path";
 
-type ApiMethod = (...args: unknown[]) => unknown
+type ApiMethod = (...args: unknown[]) => unknown;
 type ToolInvocationPayload = {
-  args?: unknown[]
-  options?: Record<string, unknown>
-  [key: string]: unknown
-}
+	args?: unknown[];
+	options?: Record<string, unknown>;
+	[key: string]: unknown;
+};
 type BatchToolCall = {
-  tool: string
-  args?: unknown[]
-  options?: Record<string, unknown>
-  [key: string]: unknown
-}
+	tool: string;
+	args?: unknown[];
+	options?: Record<string, unknown>;
+	[key: string]: unknown;
+};
 type BatchToolCallPayload = {
-  calls: BatchToolCall[]
-  continueOnError: boolean
-}
+	calls: BatchToolCall[];
+	continueOnError: boolean;
+	maxConcurrency: number;
+};
 type BatchResult = {
-  index: number
-  tool: string
-  isError: boolean
-  data: unknown
-}
+	index: number;
+	tool: string;
+	isError: boolean;
+	data: unknown;
+};
 type ToolDefinition = {
-  name: string
-  method: ApiMethod
-  path: string[]
-}
+	name: string;
+	method: ApiMethod;
+	path: string[];
+};
 
-type ToolNamespace = Record<string, unknown>
+type ToolNamespace = Record<string, unknown>;
 
 type ApiEndpoint = {
-  agents: ToolNamespace
-  projects: ToolNamespace
-}
+	agents: ToolNamespace;
+	net: ToolNamespace;
+	projects: ToolNamespace;
+	mcp: ToolNamespace;
+};
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
-const normalizePayload = (payload: unknown): { args: string[]; options: Record<string, unknown> } => {
-  if (!isRecord(payload)) {
-    return {
-      args: [],
-      options: {},
-    }
-  }
-
-  const explicitArgs = Array.isArray(payload.args) ? payload.args : undefined
-  const explicitOptions = isRecord(payload.options) ? payload.options : undefined
-
-  const args = explicitArgs ? explicitArgs.map((entry) => String(entry)) : []
-  const options: Record<string, unknown> = explicitOptions ? { ...explicitOptions } : {}
-
-  for (const [key, value] of Object.entries(payload)) {
-    if (key === 'args' || key === 'options') {
-      continue
-    }
-
-    if (value !== undefined) {
-      options[key] = value
-    }
-  }
-
-  return {
-    args,
-    options,
-  }
-}
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+const parseBooleanish = (value: unknown): boolean | null => {
+	if (value === true || value === false) return value;
+	if (value === 1 || value === 0) return Boolean(value);
+	if (typeof value !== "string") return null;
+	const normalized = value.trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(normalized)) return true;
+	if (["0", "false", "no", "off"].includes(normalized)) return false;
+	return null;
+};
+
+const parsePositiveInteger = (value: unknown): number | null => {
+	const numeric =
+		typeof value === "string" && value.trim() !== ""
+			? Number(value)
+			: typeof value === "number"
+				? value
+				: NaN;
+
+	if (!Number.isInteger(numeric) || numeric <= 0) return null;
+	return numeric;
+};
+
+const safeJsonStringify = (value: unknown): string => {
+	try {
+		return JSON.stringify(
+			value,
+			(_key, v) => (typeof v === "bigint" ? v.toString() : v),
+			2,
+		);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return JSON.stringify(
+			{
+				ok: false,
+				error: { message, note: "Failed to JSON stringify tool result." },
+			},
+			null,
+			2,
+		);
+	}
+};
+
+type ToolEnvelope =
+	| { ok: true; result: unknown }
+	| { ok: false; error: { message: string; details?: unknown } };
+
+const toolOk = (result: unknown) => ({
+	isError: false,
+	content: [
+		{
+			type: "text",
+			text: safeJsonStringify({ ok: true, result } satisfies ToolEnvelope),
+		},
+	],
+});
+
+const toolErr = (message: string, details?: unknown) => ({
+	isError: true,
+	content: [
+		{
+			type: "text",
+			text: safeJsonStringify({
+				ok: false,
+				error: { message, details },
+			} satisfies ToolEnvelope),
+		},
+	],
+});
+
+const isDir = (candidate: string): boolean => {
+	try {
+		return fs.statSync(candidate).isDirectory();
+	} catch {
+		return false;
+	}
+};
+
+const looksLikeRepoRoot = (candidate: string): boolean =>
+	isDir(path.join(candidate, "projects")) && isDir(path.join(candidate, "api"));
+
+const normalizeProcessRoot = (raw: string): string => {
+	const resolved = path.resolve(raw);
+	if (looksLikeRepoRoot(resolved)) return resolved;
+
+	// Common mistake: passing a project root like ".../projects/adl" as processRoot.
+	// Try to find the containing repo root by walking up a few levels.
+	let current = resolved;
+	for (let depth = 0; depth < 8; depth += 1) {
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		if (looksLikeRepoRoot(parent)) return parent;
+		current = parent;
+	}
+
+	const parts = resolved.split(path.sep).filter((part) => part.length > 0);
+	const projectsIndex = parts.lastIndexOf("projects");
+	if (projectsIndex >= 0) {
+		const candidate = parts.slice(0, projectsIndex).join(path.sep);
+		if (candidate && looksLikeRepoRoot(candidate)) return candidate;
+	}
+
+	return resolved;
+};
+
+const normalizeProcessRootOption = (
+	options: Record<string, unknown>,
+): Record<string, unknown> => {
+	const raw = options.processRoot;
+	if (typeof raw !== "string" || raw.trim().length === 0) return options;
+	const normalized = normalizeProcessRoot(raw.trim());
+	if (normalized === raw) return options;
+	return { ...options, processRoot: normalized };
+};
+
+type NormalizedToolPayload = {
+	args: unknown[];
+	options: Record<string, unknown>;
+};
+
+const parseStringish = (value: unknown): string | null => {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+};
+
+const parseStringArrayish = (value: unknown): string[] => {
+	if (Array.isArray(value)) {
+		return value
+			.map((entry) => String(entry))
+			.map((entry) => entry.trim())
+			.filter((entry) => entry.length > 0);
+	}
+	const asString = parseStringish(value);
+	return asString ? [asString] : [];
+};
+
+const popOption = (options: Record<string, unknown>, key: string): unknown => {
+	const value = options[key];
+	delete options[key];
+	return value;
+};
+
+const popStringOption = (
+	options: Record<string, unknown>,
+	...keys: string[]
+): string | null => {
+	for (const key of keys) {
+		const value = options[key];
+		const parsed = parseStringish(value);
+		if (parsed) {
+			delete options[key];
+			return parsed;
+		}
+	}
+	return null;
+};
+
+const popStringArrayOption = (
+	options: Record<string, unknown>,
+	...keys: string[]
+): string[] => {
+	for (const key of keys) {
+		const value = options[key];
+		const parsed = parseStringArrayish(value);
+		if (parsed.length > 0) {
+			delete options[key];
+			return parsed;
+		}
+	}
+	return [];
+};
+
+const popBooleanOption = (
+	options: Record<string, unknown>,
+	...keys: string[]
+): boolean | null => {
+	for (const key of keys) {
+		const value = options[key];
+		const parsed = parseBooleanish(value);
+		if (parsed !== null) {
+			delete options[key];
+			return parsed;
+		}
+	}
+	return null;
+};
+
+const popIntegerOption = (
+	options: Record<string, unknown>,
+	...keys: string[]
+): number | null => {
+	for (const key of keys) {
+		const value = options[key];
+		const parsed = parsePositiveInteger(value);
+		if (parsed !== null) {
+			delete options[key];
+			return parsed;
+		}
+	}
+	return null;
+};
+
+const normalizePayload = (payload: unknown): NormalizedToolPayload => {
+	if (!isRecord(payload)) {
+		return {
+			args: [],
+			options: {},
+		};
+	}
+
+	const explicitArgs = Array.isArray(payload.args) ? payload.args : undefined;
+	const explicitOptions = isRecord(payload.options)
+		? payload.options
+		: undefined;
+
+	const args = explicitArgs ? [...explicitArgs] : [];
+	const options: Record<string, unknown> = explicitOptions
+		? { ...explicitOptions }
+		: {};
+
+	for (const [key, value] of Object.entries(payload)) {
+		if (key === "args" || key === "options") {
+			continue;
+		}
+
+		if (value !== undefined) {
+			options[key] = value;
+		}
+	}
+
+	return {
+		args,
+		options: normalizeProcessRootOption(options),
+	};
+};
+
+const coercePayloadForTool = (
+	toolName: string,
+	input: NormalizedToolPayload,
+): NormalizedToolPayload => {
+	const args = [...input.args];
+	const options: Record<string, unknown> = { ...input.options };
+
+	const ensureArg0 = (value: unknown) => {
+		if (args.length > 0) return;
+		if (value !== undefined) {
+			args.push(value);
+		}
+	};
+
+	const ensureArgs = (...values: Array<unknown>) => {
+		while (args.length < values.length) {
+			const next = values[args.length];
+			if (next === undefined || next === null) break;
+			args.push(next);
+		}
+	};
+
+	const coerceProjectName = (): void => {
+		if (
+			args.length > 0 &&
+			typeof args[0] === "string" &&
+			args[0].trim().length > 0
+		)
+			return;
+		const name = popStringOption(options, "projectName", "project");
+		if (name) {
+			if (args.length === 0) args.push(name);
+			else args[0] = name;
+		}
+	};
+
+	const coerceProjectSearch = (): void => {
+		coerceProjectName();
+
+		// If caller already provided [projectName, pattern, ...], keep it.
+		if (args.length >= 2) return;
+
+		const pattern = popStringOption(options, "pattern", "query", "q") ?? null;
+		const paths = popStringArrayOption(options, "paths");
+		const globs = popStringArrayOption(options, "globs");
+		const ref = popStringOption(options, "ref");
+		const source = popStringOption(options, "source");
+
+		if (source) options.source = source;
+		if (ref) options.ref = ref;
+
+		const refresh = popBooleanOption(options, "refresh");
+		if (refresh !== null) options.refresh = refresh;
+		const cacheDir = popStringOption(options, "cacheDir");
+		if (cacheDir) options.cacheDir = cacheDir;
+
+		const owner = popStringOption(options, "owner");
+		if (owner) options.owner = owner;
+		const repo = popStringOption(options, "repo");
+		if (repo) options.repo = repo;
+
+		if (!pattern) return;
+
+		const rgArgs: string[] = [];
+		const addFlag = (key: string, flag: string) => {
+			const raw = popBooleanOption(options, key);
+			if (raw === true) rgArgs.push(flag);
+		};
+
+		addFlag("ignoreCase", "--ignore-case");
+		addFlag("caseSensitive", "--case-sensitive");
+		addFlag("smartCase", "--smart-case");
+		addFlag("fixedStrings", "--fixed-strings");
+		addFlag("wordRegexp", "--word-regexp");
+		addFlag("includeHidden", "--hidden");
+		addFlag("filesWithMatches", "--files-with-matches");
+		addFlag("filesWithoutMatch", "--files-without-match");
+		addFlag("countOnly", "--count");
+		addFlag("onlyMatching", "--only-matching");
+
+		const maxCount = popIntegerOption(options, "maxCount");
+		if (maxCount !== null) {
+			rgArgs.push("--max-count", String(maxCount));
+		}
+
+		for (const glob of globs) {
+			rgArgs.push("--glob", glob);
+		}
+
+		rgArgs.push(pattern, ...(paths.length > 0 ? paths : ["."]));
+
+		if (args.length === 0) {
+			// Can't build without projectName; leave for underlying error.
+			return;
+		}
+
+		if (args.length === 1) {
+			args.push(...rgArgs);
+		}
+	};
+
+	switch (toolName) {
+		case "projects.listProjects": {
+			// No positional args. processRoot is handled via options.processRoot + buildProcessRootOnly.
+			break;
+		}
+		case "projects.resolveProjectRoot":
+		case "projects.listProjectDocs":
+		case "projects.fetchGitTasks":
+		case "projects.createGitIssue": {
+			coerceProjectName();
+			break;
+		}
+		case "projects.readProjectDoc": {
+			coerceProjectName();
+			if (args.length >= 2) break;
+			const requestPath = popStringOption(
+				options,
+				"requestPath",
+				"path",
+				"docPath",
+			);
+			if (requestPath) {
+				ensureArgs(args[0] ?? undefined, requestPath);
+			}
+			break;
+		}
+		case "projects.searchDocs":
+		case "projects.searchSpecs": {
+			coerceProjectSearch();
+			break;
+		}
+		case "projects.parseProjectTargetSpec": {
+			if (args.length >= 1) break;
+			const spec = popStringOption(options, "spec", "target");
+			if (spec) {
+				args.push(spec);
+			}
+			break;
+		}
+		case "projects.resolveProjectTargetFile": {
+			if (args.length >= 2) break;
+			const targetDir = popStringOption(options, "targetDir", "dir");
+			const spec = options.spec;
+			if (targetDir) {
+				if (spec !== undefined) {
+					delete options.spec;
+				}
+				if (args.length === 0) args.push(targetDir);
+				if (args.length === 1 && spec !== undefined) args.push(spec);
+			}
+
+			const latest = popBooleanOption(options, "latest");
+			if (latest !== null) {
+				options.latest = latest;
+			}
+			break;
+		}
+		case "projects.resolveImplementationPlan": {
+			if (args.length >= 1) break;
+			const projectRoot = popStringOption(options, "projectRoot");
+			const inputFile = popStringOption(options, "inputFile");
+			const requireActive = popBooleanOption(options, "requireActive");
+			if (projectRoot) {
+				args.push(projectRoot);
+				if (inputFile) args.push(inputFile);
+			}
+			if (requireActive !== null) {
+				options.requireActive = requireActive;
+			}
+			break;
+		}
+		case "projects.readGitTask":
+		case "projects.writeGitTask": {
+			coerceProjectName();
+			if (args.length >= 2) break;
+			const taskRef = popStringOption(
+				options,
+				"taskRef",
+				"ref",
+				"issue",
+				"issueNumber",
+				"taskId",
+			);
+			if (taskRef && args.length >= 1) {
+				ensureArgs(args[0], taskRef);
+			}
+			break;
+		}
+		default:
+			break;
+	}
+
+	return { args, options: normalizeProcessRootOption(options) };
+};
 
 const normalizeBatchToolCall = (
-  call: unknown,
-  index: number,
+	call: unknown,
+	index: number,
 ): { tool: string; payload: ToolInvocationPayload } => {
-  if (!isRecord(call)) {
-    throw new Error(`Invalid batch call at index ${index}: expected object`)
-  }
-
-  const tool = typeof call.tool === 'string' ? call.tool.trim() : ''
-  if (!tool) {
-    throw new Error(`Invalid batch call at index ${index}: missing "tool"`)
-  }
-
-  const args = Array.isArray(call.args) ? call.args : []
-  const { options, ...extras } = call
-  const normalized: ToolInvocationPayload = {
-    args,
-    options: isRecord(options) ? options : {},
-  }
-
-  for (const [key, value] of Object.entries(extras)) {
-    if (value !== undefined) {
-      normalized.options[key] = value
-    }
-  }
-
-  return {
-    tool,
-    payload: normalized,
-  }
-}
+	if (!isRecord(call)) {
+		throw new Error(`Invalid batch call at index ${index}: expected object`);
+	}
+
+	const tool = typeof call.tool === "string" ? call.tool.trim() : "";
+	if (!tool) {
+		throw new Error(`Invalid batch call at index ${index}: missing "tool"`);
+	}
+
+	const args = Array.isArray(call.args) ? call.args : [];
+	const { options, ...extras } = call;
+	const normalized: ToolInvocationPayload = {
+		args,
+		options: isRecord(options) ? options : {},
+	};
+
+	for (const [key, value] of Object.entries(extras)) {
+		if (key === "tool" || key === "args" || key === "options") {
+			continue;
+		}
+		if (value !== undefined) {
+			normalized.options[key] = value;
+		}
+	}
+
+	return {
+		tool,
+		payload: normalized,
+	};
+};
 
 const normalizeBatchPayload = (payload: unknown): BatchToolCallPayload => {
-  if (!isRecord(payload)) {
-    throw new Error('Batch tool call requires an object payload')
-  }
-
-  if (!Array.isArray(payload.calls)) {
-    throw new Error('Batch tool call requires a "calls" array')
-  }
-
-  const calls = payload.calls.map((call, index) => normalizeBatchToolCall(call, index))
-
-  return {
-    calls: calls.map(({ tool, payload }) => ({
-      tool,
-      ...payload,
-    })),
-    continueOnError: Boolean(payload.continueOnError),
-  }
-}
+	if (!isRecord(payload)) {
+		throw new Error("Batch tool call requires an object payload");
+	}
 
-const collectTools = (api: ToolNamespace, namespace: string[], path: string[] = []): ToolDefinition[] => {
-  const tools: ToolDefinition[] = []
-  const currentPath = [...path, ...namespace]
+	if (!Array.isArray(payload.calls)) {
+		throw new Error('Batch tool call requires a "calls" array');
+	}
 
-  for (const [segment, value] of Object.entries(api)) {
-    if (typeof value !== 'function') {
-      continue
-    }
+	const calls = payload.calls.map((call, index) =>
+		normalizeBatchToolCall(call, index),
+	);
+	const continueOnError = (() => {
+		if (payload.continueOnError === undefined) return false;
+		const parsed = parseBooleanish(payload.continueOnError);
+		if (parsed === null) {
+			throw new Error(
+				'"continueOnError" must be a boolean or boolean-like string (true/false, 1/0).',
+			);
+		}
+		return parsed;
+	})();
+	const maxConcurrency = (() => {
+		if (payload.maxConcurrency === undefined) return 8;
+		const parsed = parsePositiveInteger(payload.maxConcurrency);
+		if (!parsed) {
+			throw new Error('"maxConcurrency" must be a positive integer.');
+		}
+		return parsed;
+	})();
 
-    tools.push({
-      name: [...currentPath, segment].join('.'),
-      method: value as ApiMethod,
-      path: [...currentPath, segment],
-    })
-  }
+	return {
+		calls: calls.map(({ tool, payload }) => ({
+			tool,
+			...payload,
+		})),
+		continueOnError,
+		maxConcurrency,
+	};
+};
 
-  return tools
-}
+const collectTools = (
+	api: ToolNamespace,
+	namespace: string[],
+	path: string[] = [],
+): ToolDefinition[] => {
+	const tools: ToolDefinition[] = [];
+	const currentPath = [...path, ...namespace];
+
+	for (const [segment, value] of Object.entries(api)) {
+		if (typeof value !== "function") {
+			continue;
+		}
+
+		tools.push({
+			name: [...currentPath, segment].join("."),
+			method: value as ApiMethod,
+			path: [...currentPath, segment],
+		});
+	}
+
+	return tools;
+};
 
 const buildToolName = (tool: ToolDefinition, prefix?: string): string =>
-  prefix ? `${prefix}.${tool.name}` : tool.name
-
-const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?: string) => {
-  const toolEntries = tools.map((tool) => ({
-    name: buildToolName(tool, prefix),
-    description: `Call API method ${tool.path.join('.')}`,
-    inputSchema: {
-      type: 'object',
-      additionalProperties: true,
-      properties: {
-        args: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Positional arguments',
-        },
-        options: {
-          type: 'object',
-          additionalProperties: true,
-          description: 'Named options',
-        },
-      },
-    },
-  }))
-
-  const batchTool = {
-    name: batchToolName,
-    description:
-      'Preferred mode for client calls: execute multiple MCP tool calls in one request with parallel execution.',
-    inputSchema: {
-      type: 'object',
-      additionalProperties: true,
-      properties: {
-        calls: {
-          type: 'array',
-          minItems: 1,
-          items: {
-            type: 'object',
-            additionalProperties: true,
-            properties: {
-              tool: {
-                type: 'string',
-                description: 'Full MCP tool name to execute',
-              },
-              args: {
-                type: 'array',
-                items: { type: 'string' },
-                description: 'Positional args for the tool',
-              },
-              options: {
-                type: 'object',
-                additionalProperties: true,
-                description: 'Tool invocation options',
-              },
-            },
-            required: ['tool'],
-          },
-          description: 'List of tool calls to execute',
-        },
-        continueOnError: {
-          type: 'boolean',
-          description: 'Whether to continue when a call in the batch fails',
-          default: false,
-        },
-      },
-      required: ['calls'],
-    },
-  }
-
-  return [...toolEntries, batchTool]
-}
+	prefix ? `${prefix}.${tool.name}` : tool.name;
 
-type ToolInvoker = (args: string[], options: Record<string, unknown>) => unknown[]
+type ToolAccess = "read" | "write" | "admin";
+type ToolMeta = {
+	access: ToolAccess;
+	category?: string;
+	notes?: string;
+};
 
-const buildOptionsOnly = (args: string[], options: Record<string, unknown>): unknown[] => {
-  const invocationArgs: unknown[] = [...args]
-  if (Object.keys(options).length > 0) {
-    invocationArgs.push(options)
-  }
-  return invocationArgs
-}
+const TOOL_META: Record<string, ToolMeta> = {};
 
-const buildOptionsThenProcessRoot = (args: string[], options: Record<string, unknown>): unknown[] => {
-  const invocationArgs: unknown[] = [...args]
-  const remaining = { ...options }
-  const processRoot = remaining.processRoot
-  if (typeof processRoot === 'string') {
-    delete remaining.processRoot
-  }
-
-  if (Object.keys(remaining).length > 0) {
-    invocationArgs.push(remaining)
-  }
-  if (typeof processRoot === 'string') {
-    invocationArgs.push(processRoot)
-  }
-
-  return invocationArgs
-}
+const TOOL_REQUIRED_ARGS: Record<string, string[]> = {
+	"agents.createAgent": ["<agent-name>"],
+	"agents.setActive": ["<agent-name>", "</file-path>"],
+	"agents.loadAgent": ["<agent-name>"],
+	"agents.loadAgentPrompt": ["<agent-name>"],
+	"agents.runAgent": ["<agent-name>"],
+	"projects.resolveProjectRoot": ["<project-name>"],
+	"projects.listProjectDocs": ["<project-name>"],
+	"projects.readProjectDoc": ["<project-name>", "</doc-path>"],
+	"projects.searchDocs": ["<project-name>", "<pattern>", "[path...]"],
+	"projects.searchSpecs": ["<project-name>", "<pattern>", "[path...]"],
+	"projects.generateSpec": ["<project-name>"],
+	"projects.setActive": ["<project-name>", "</file-path>"],
+	"projects.fetchGitTasks": ["<project-name>"],
+	"projects.createGitIssue": ["<project-name>"],
+	"projects.readGitTask": ["<project-name>", "<issue-number|task-id>"],
+	"projects.writeGitTask": ["<project-name>", "<issue-number|task-id>"],
+};
 
-const buildProcessRootThenOptions = (args: string[], options: Record<string, unknown>): unknown[] => {
-  const invocationArgs: unknown[] = [...args]
-  const remaining = { ...options }
-  const processRoot = remaining.processRoot
-  if (typeof processRoot === 'string') {
-    delete remaining.processRoot
-  }
-
-  if (typeof processRoot === 'string') {
-    invocationArgs.push(processRoot)
-  }
-  if (Object.keys(remaining).length > 0) {
-    invocationArgs.push(remaining)
-  }
-
-  return invocationArgs
-}
+const TOOL_DEFAULT_OPTIONS: Record<string, Record<string, unknown>> = {
+	"projects.searchDocs": { source: "auto" },
+	"projects.searchSpecs": { source: "auto" },
+};
 
-const buildProcessRootOnly = (args: string[], options: Record<string, unknown>): unknown[] => {
-  const invocationArgs: unknown[] = [...args]
-  const processRoot = options.processRoot
-  if (typeof processRoot === 'string') {
-    invocationArgs.push(processRoot)
-  }
-  return invocationArgs
-}
+const TOOL_USAGE_HINTS: Record<string, string> = {
+	"projects.searchDocs":
+		" Usage: args=[projectName, pattern, ...paths]. Options include source/local cache controls.",
+	"projects.searchSpecs":
+		" Usage: args=[projectName, pattern, ...paths]. Options include source/local cache controls.",
+	"projects.setActive":
+		" Usage: args=[projectName, /file-path]. Use options.latest=true to auto-pick latest version.",
+	"agents.setActive":
+		" Usage: args=[agentName, /file-path]. Use options.latest=true to auto-pick latest version.",
+};
+
+const NET_CURL_SCHEMA = {
+	type: "object",
+	additionalProperties: true,
+	properties: {
+		args: {
+			type: "array",
+			items: { type: "string" },
+			description:
+				'Curl-style CLI arguments (recommended when you already know curl). Excludes the leading "curl". Example: { "args": ["-L", "https://example.com"] }',
+		},
+		url: {
+			description:
+				'Structured mode: URL to fetch (string or array). Example: { "url": "https://example.com", "method": "GET" }',
+			anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+		urls: {
+			type: "array",
+			items: { type: "string" },
+			description:
+				"Structured mode: multiple URLs to fetch (like passing multiple URLs to curl).",
+		},
+		method: {
+			type: "string",
+			description:
+				"Structured mode: HTTP method (GET/POST/PUT/PATCH/DELETE/HEAD).",
+		},
+		headers: {
+			type: "object",
+			additionalProperties: { type: "string" },
+			description: "Structured mode: request headers.",
+		},
+		body: {
+			type: "string",
+			description: "Structured mode: raw request body (maps to --data-raw).",
+		},
+		data: {
+			description: "Structured mode: request body data (maps to -d).",
+			anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+		json: {
+			description:
+				"Structured mode: JSON payload (maps to --json). Can be object/array/string.",
+		},
+		form: {
+			type: "object",
+			additionalProperties: { type: "string" },
+			description:
+				"Structured mode: multipart form fields (maps to -F key=value).",
+		},
+		followRedirects: {
+			type: "boolean",
+			description: "Structured mode: follow redirects (maps to -L).",
+		},
+		includeHeaders: {
+			type: "boolean",
+			description: "Structured mode: include response headers (maps to -i).",
+		},
+		head: {
+			type: "boolean",
+			description: "Structured mode: HEAD request (maps to -I).",
+		},
+		user: {
+			type: "string",
+			description:
+				'Structured mode: basic auth in "user:pass" form (maps to -u).',
+		},
+		output: {
+			type: "string",
+			description: "Structured mode: write response to file (maps to -o).",
+		},
+		remoteName: {
+			type: "boolean",
+			description:
+				"Structured mode: write response to remote filename (maps to -O).",
+		},
+		fail: {
+			type: "boolean",
+			description:
+				"Structured mode: fail on HTTP >= 400 and suppress body (maps to -f).",
+		},
+		silent: {
+			type: "boolean",
+			description: "Structured mode: silent (maps to -s).",
+		},
+		showError: {
+			type: "boolean",
+			description:
+				"Structured mode: show errors even when silent (maps to -S).",
+		},
+		verbose: {
+			type: "boolean",
+			description: "Structured mode: verbose (maps to -v).",
+		},
+		writeOut: {
+			type: "string",
+			description: "Structured mode: write-out template (maps to -w).",
+		},
+		maxRedirects: {
+			type: "integer",
+			minimum: 0,
+			description: "Structured mode: max redirects (maps to --max-redirs).",
+		},
+		maxTimeSeconds: {
+			type: "number",
+			minimum: 0,
+			description: "Structured mode: max time in seconds (maps to --max-time).",
+		},
+		get: {
+			type: "boolean",
+			description: "Structured mode: send data as query params (maps to -G).",
+		},
+		timeoutMs: {
+			type: "integer",
+			minimum: 1,
+			description: "Optional timeout in milliseconds.",
+		},
+		cwd: {
+			type: "string",
+			description: "Optional working directory for the curl process.",
+		},
+		stdin: {
+			description: "Optional stdin content for @- (string or byte array).",
+			anyOf: [
+				{ type: "string" },
+				{ type: "array", items: { type: "integer", minimum: 0, maximum: 255 } },
+			],
+		},
+		env: {
+			type: "object",
+			additionalProperties: { type: "string" },
+			description:
+				"Optional environment variable overrides for the curl process.",
+		},
+		options: {
+			type: "object",
+			additionalProperties: true,
+			description:
+				"Legacy tool options bag. Prefer top-level keys instead of nesting under options.",
+		},
+	},
+	required: [],
+} as const;
+
+const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
+	"net.curl": NET_CURL_SCHEMA,
+	net_curl: NET_CURL_SCHEMA,
+	"projects.usage": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			args: {
+				type: "array",
+				description: "Unused. This tool takes no arguments.",
+				minItems: 0,
+				maxItems: 0,
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Unused.",
+				additionalProperties: true,
+			},
+			processRoot: {
+				type: "string",
+				description: "Unused.",
+			},
+		},
+	},
+	"projects.listProjects": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			processRoot: {
+				type: "string",
+				description:
+					'Repo root containing /projects and /agents. If you have a project root like ".../projects/adl", omit this or pass its parent.',
+			},
+		},
+		required: [],
+	},
+	"projects.resolveProjectRoot": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: 'Project name under /projects (e.g. "adl").',
+			},
+			processRoot: {
+				type: "string",
+				description:
+					"Repo root containing /projects and /agents. If omitted, uses server cwd.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (projectName).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy named options.",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName"],
+	},
+	"projects.listProjectDocs": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: 'Project name under /projects (e.g. "adl").',
+			},
+			processRoot: {
+				type: "string",
+				description: "Repo root containing /projects and /agents.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (projectName).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy named options.",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName"],
+	},
+	"projects.readProjectDoc": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: 'Project name under /projects (e.g. "adl").',
+			},
+			requestPath: {
+				type: "string",
+				description:
+					'Doc path under docs/, starting with "docs/..." (or a bare filename in catalog).',
+			},
+			processRoot: {
+				type: "string",
+				description: "Repo root containing /projects and /agents.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (projectName, requestPath).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy named options.",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName", "requestPath"],
+	},
+	"projects.searchDocs": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: 'Project name under /projects (e.g. "adl").',
+			},
+			pattern: {
+				type: "string",
+				description: "Search pattern (like rg PATTERN).",
+			},
+			query: { type: "string", description: "Alias of pattern." },
+			q: { type: "string", description: "Alias of pattern." },
+			paths: {
+				type: "array",
+				items: { type: "string" },
+				description: 'Paths inside docs/ to search. Defaults to [\".\"].',
+			},
+			globs: {
+				type: "array",
+				items: { type: "string" },
+				description: "Glob filters (like rg --glob).",
+			},
+			ignoreCase: { type: "boolean" },
+			caseSensitive: { type: "boolean" },
+			smartCase: { type: "boolean" },
+			fixedStrings: { type: "boolean" },
+			wordRegexp: { type: "boolean" },
+			maxCount: { type: "integer", minimum: 1 },
+			includeHidden: { type: "boolean" },
+			filesWithMatches: { type: "boolean" },
+			filesWithoutMatch: { type: "boolean" },
+			countOnly: { type: "boolean" },
+			onlyMatching: { type: "boolean" },
+			ref: {
+				type: "string",
+				description: "Optional git ref for remote search.",
+			},
+			source: {
+				type: "string",
+				enum: ["local", "gitea", "auto"],
+				description: "local=filesystem, gitea=remote, auto=local-first.",
+			},
+			refresh: {
+				type: "boolean",
+				description: "Refresh cached search corpus.",
+			},
+			cacheDir: {
+				type: "string",
+				description: "Optional override cache directory.",
+			},
+			owner: {
+				type: "string",
+				description: "Remote owner override for gitea mode.",
+			},
+			repo: {
+				type: "string",
+				description: "Remote repo override for gitea mode.",
+			},
+			processRoot: {
+				type: "string",
+				description: "Repo root containing /projects and /agents.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy rg-like args (projectName, PATTERN, [PATH...]).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy named options.",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName"],
+	},
+	"projects.searchSpecs": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: 'Project name under /projects (e.g. "adl").',
+			},
+			pattern: {
+				type: "string",
+				description: "Search pattern (like rg PATTERN).",
+			},
+			query: { type: "string", description: "Alias of pattern." },
+			q: { type: "string", description: "Alias of pattern." },
+			paths: {
+				type: "array",
+				items: { type: "string" },
+				description: 'Paths inside spec/ to search. Defaults to [\".\"].',
+			},
+			globs: {
+				type: "array",
+				items: { type: "string" },
+				description: "Glob filters (like rg --glob).",
+			},
+			ignoreCase: { type: "boolean" },
+			caseSensitive: { type: "boolean" },
+			smartCase: { type: "boolean" },
+			fixedStrings: { type: "boolean" },
+			wordRegexp: { type: "boolean" },
+			maxCount: { type: "integer", minimum: 1 },
+			includeHidden: { type: "boolean" },
+			filesWithMatches: { type: "boolean" },
+			filesWithoutMatch: { type: "boolean" },
+			countOnly: { type: "boolean" },
+			onlyMatching: { type: "boolean" },
+			ref: {
+				type: "string",
+				description: "Optional git ref for remote search.",
+			},
+			source: {
+				type: "string",
+				enum: ["local", "gitea", "auto"],
+				description: "local=filesystem, gitea=remote, auto=local-first.",
+			},
+			refresh: {
+				type: "boolean",
+				description: "Refresh cached search corpus.",
+			},
+			cacheDir: {
+				type: "string",
+				description: "Optional override cache directory.",
+			},
+			owner: {
+				type: "string",
+				description: "Remote owner override for gitea mode.",
+			},
+			repo: {
+				type: "string",
+				description: "Remote repo override for gitea mode.",
+			},
+			processRoot: {
+				type: "string",
+				description: "Repo root containing /projects and /agents.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy rg-like args (projectName, PATTERN, [PATH...]).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy named options.",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName"],
+	},
+	"projects.parseProjectTargetSpec": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			spec: {
+				type: "string",
+				description:
+					'Target spec string like \"/implementation-plan.v0.0.1\" or \"spec/README.md\".',
+			},
+			target: { type: "string", description: "Alias of spec." },
+			args: {
+				type: "array",
+				description: "Legacy positional args (spec).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy named options.",
+				additionalProperties: true,
+			},
+		},
+		anyOf: [{ required: ["spec"] }, { required: ["target"] }],
+	},
+	"projects.resolveProjectTargetFile": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			targetDir: { type: "string", description: "Directory to scan." },
+			spec: {
+				type: "object",
+				description: "Output of projects.parseProjectTargetSpec().",
+				additionalProperties: true,
+			},
+			latest: {
+				type: "boolean",
+				description:
+					"If true and no version given, select latest versioned file.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (targetDir, spec).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy named options (e.g. {latest:true}).",
+				additionalProperties: true,
+			},
+		},
+		required: ["targetDir", "spec"],
+	},
+	"projects.resolveImplementationPlan": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectRoot: {
+				type: "string",
+				description: "Absolute project directory (e.g. C:/.../projects/adl).",
+			},
+			inputFile: {
+				type: "string",
+				description: "Optional file within docs/ (or absolute) to select plan.",
+			},
+			requireActive: {
+				type: "boolean",
+				description: "If true, require implementation-plan.active.* to exist.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (projectRoot, inputFile?).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy named options (e.g. {requireActive:true}).",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectRoot"],
+	},
+	"projects.fetchGitTasks": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: "Project name under /projects.",
+			},
+			owner: { type: "string", description: "Remote owner override." },
+			repo: { type: "string", description: "Remote repo override." },
+			state: {
+				type: "string",
+				enum: ["open", "closed", "all"],
+				description: "Issue state filter.",
+			},
+			taskOnly: {
+				type: "boolean",
+				description: "If true, only return issues with TASK-* IDs.",
+			},
+			processRoot: {
+				type: "string",
+				description: "Repo root containing /projects.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (projectName).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy options (owner/repo/state/taskOnly).",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName"],
+	},
+	"projects.readGitTask": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: "Project name under /projects.",
+			},
+			taskRef: {
+				type: "string",
+				description:
+					'Issue number (e.g. \"123\") or task ID (e.g. \"TASK-001\").',
+			},
+			owner: { type: "string", description: "Remote owner override." },
+			repo: { type: "string", description: "Remote repo override." },
+			state: {
+				type: "string",
+				enum: ["open", "closed", "all"],
+				description: "Search scope.",
+			},
+			taskOnly: {
+				type: "boolean",
+				description: "If true, restrict to issues with TASK-* payloads.",
+			},
+			processRoot: {
+				type: "string",
+				description: "Repo root containing /projects.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (projectName, taskRef).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy options.",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName", "taskRef"],
+	},
+	"projects.writeGitTask": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: "Project name under /projects.",
+			},
+			taskRef: {
+				type: "string",
+				description:
+					'Issue number (e.g. \"123\") or task ID (e.g. \"TASK-001\").',
+			},
+			owner: { type: "string", description: "Remote owner override." },
+			repo: { type: "string", description: "Remote repo override." },
+			createIfMissing: {
+				type: "boolean",
+				description: "Create issue if taskRef is TASK-* and not found.",
+			},
+			title: { type: "string", description: "Issue title override." },
+			body: { type: "string", description: "Issue body override." },
+			labels: {
+				type: "array",
+				items: { type: "string" },
+				description: "Labels to set.",
+			},
+			state: {
+				type: "string",
+				enum: ["open", "closed"],
+				description: "Issue state.",
+			},
+			taskDependencies: {
+				type: "array",
+				items: { type: "string" },
+				description: "TASK-* dependencies.",
+			},
+			taskSignature: {
+				type: "string",
+				description: "Optional task signature.",
+			},
+			processRoot: {
+				type: "string",
+				description: "Repo root containing /projects.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (projectName, taskRef).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy options.",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName", "taskRef"],
+	},
+	"projects.createGitIssue": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: "Project name under /projects.",
+			},
+			owner: { type: "string", description: "Remote owner override." },
+			repo: { type: "string", description: "Remote repo override." },
+			title: { type: "string", description: "Issue title." },
+			body: { type: "string", description: "Issue body." },
+			labels: {
+				type: "array",
+				items: { type: "string" },
+				description: "Labels to set.",
+			},
+			processRoot: {
+				type: "string",
+				description: "Repo root containing /projects.",
+			},
+			args: {
+				type: "array",
+				description: "Legacy positional args (projectName).",
+				items: {},
+			},
+			options: {
+				type: "object",
+				description: "Legacy options.",
+				additionalProperties: true,
+			},
+		},
+		required: ["projectName", "title"],
+	},
+	"mcp.search": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			projectName: {
+				type: "string",
+				description: 'Project name under /projects (e.g. "adl").',
+			},
+			section: {
+				type: "string",
+				enum: ["spec", "docs"],
+				description: "Search target section.",
+			},
+			pattern: {
+				type: "string",
+				description: "Search pattern (like rg PATTERN).",
+			},
+			query: { type: "string", description: "Alias of pattern." },
+			q: { type: "string", description: "Alias of pattern." },
+			paths: {
+				type: "array",
+				items: { type: "string" },
+				description: "Paths to search within the section.",
+			},
+			globs: {
+				type: "array",
+				items: { type: "string" },
+				description: "Glob filters (like rg --glob).",
+			},
+			ignoreCase: { type: "boolean" },
+			caseSensitive: { type: "boolean" },
+			smartCase: { type: "boolean" },
+			fixedStrings: { type: "boolean" },
+			wordRegexp: { type: "boolean" },
+			maxCount: { type: "integer", minimum: 1 },
+			includeHidden: { type: "boolean" },
+			filesWithMatches: { type: "boolean" },
+			filesWithoutMatch: { type: "boolean" },
+			countOnly: { type: "boolean" },
+			onlyMatching: { type: "boolean" },
+			ref: {
+				type: "string",
+				description: "Optional git ref for remote search.",
+			},
+			source: {
+				type: "string",
+				enum: ["local", "gitea", "auto"],
+				description: "local=filesystem, gitea=remote, auto=local-first.",
+			},
+			refresh: {
+				type: "boolean",
+				description: "Refresh cached search corpus.",
+			},
+			cacheDir: {
+				type: "string",
+				description: "Optional override cache directory.",
+			},
+			processRoot: {
+				type: "string",
+				description:
+					"Repo root containing /projects. If you pass a project root, it will be normalized.",
+			},
+		},
+		$comment: safeJsonStringify({
+			example: {
+				projectName: "adl",
+				section: "spec",
+				pattern: "REQ-",
+				paths: ["."],
+				source: "auto",
+			},
+		}),
+	},
+};
+
+const buildArgsSchemaFromPlaceholders = (
+	placeholders: string[],
+): Record<string, unknown> => ({
+	type: "array",
+	description: "Positional arguments",
+	minItems: placeholders.length,
+	prefixItems: placeholders.map((placeholder) => ({
+		type: "string",
+		title: placeholder,
+		description: placeholder,
+	})),
+	items: {},
+});
+
+const TOOL_ARGS_SCHEMA_OVERRIDES: Record<string, Record<string, unknown>> = {
+	"projects.listProjects": {
+		type: "array",
+		description: "No positional arguments. Use options.processRoot if needed.",
+		minItems: 0,
+		maxItems: 0,
+		items: {},
+	},
+	"projects.usage": {
+		type: "array",
+		description: "No positional arguments.",
+		minItems: 0,
+		maxItems: 0,
+		items: {},
+	},
+	"agents.usage": {
+		type: "array",
+		description: "No positional arguments.",
+		minItems: 0,
+		maxItems: 0,
+		items: {},
+	},
+	"projects.searchDocs": {
+		type: "array",
+		description: "rg-like: projectName, pattern, then optional paths.",
+		minItems: 2,
+		prefixItems: [
+			{ type: "string", title: "projectName" },
+			{ type: "string", title: "pattern" },
+		],
+		items: { type: "string", title: "path" },
+	},
+	"projects.searchSpecs": {
+		type: "array",
+		description: "rg-like: projectName, pattern, then optional paths.",
+		minItems: 2,
+		prefixItems: [
+			{ type: "string", title: "projectName" },
+			{ type: "string", title: "pattern" },
+		],
+		items: { type: "string", title: "path" },
+	},
+	"projects.resolveProjectTargetFile": {
+		type: "array",
+		description: "Low-level helper: resolve versioned file in a directory.",
+		minItems: 2,
+		prefixItems: [
+			{
+				type: "string",
+				title: "targetDir",
+				description: "Directory to scan (absolute or relative to cwd).",
+			},
+			{
+				type: "object",
+				title: "spec",
+				description: "Output of projects.parseProjectTargetSpec().",
+				additionalProperties: true,
+			},
+		],
+		items: {},
+	},
+	"agents.resolveTargetFile": {
+		type: "array",
+		description: "Low-level helper: resolve versioned file in a directory.",
+		minItems: 2,
+		prefixItems: [
+			{ type: "string", title: "targetDir" },
+			{
+				type: "object",
+				title: "spec",
+				description: "Output of agents.parseTargetSpec().",
+				additionalProperties: true,
+			},
+		],
+		items: {},
+	},
+	"projects.resolveImplementationPlan": {
+		type: "array",
+		description:
+			"Low-level helper: resolve docs implementation plan path for a given projectRoot.",
+		minItems: 1,
+		prefixItems: [
+			{
+				type: "string",
+				title: "projectRoot",
+				description:
+					"Absolute path to a project folder (e.g. .../projects/adl).",
+			},
+			{
+				type: "string",
+				title: "inputFile",
+				description: "Optional path within docs/ (or absolute) to pick a plan.",
+			},
+		],
+		items: {},
+	},
+};
+
+const toolArgsSchema = (toolName: string): Record<string, unknown> => {
+	const override = TOOL_ARGS_SCHEMA_OVERRIDES[toolName];
+	if (override) return override;
+
+	const requiredArgs = TOOL_REQUIRED_ARGS[toolName];
+	if (requiredArgs && requiredArgs.length > 0) {
+		return buildArgsSchemaFromPlaceholders(requiredArgs);
+	}
+
+	return {
+		type: "array",
+		items: {},
+		description: "Positional arguments",
+	};
+};
+
+const getInvocationPlanName = (toolName: string): string => {
+	const plan = toolInvocationPlans[toolName];
+	if (!plan) return "default";
+	if (plan === buildOptionsOnly) return "optionsOnly";
+	if (plan === buildOptionsThenProcessRoot) return "optionsThenProcessRoot";
+	if (plan === buildProcessRootThenOptions) return "processRootThenOptions";
+	if (plan === buildProcessRootOnly) return "processRootOnly";
+	return "custom";
+};
+
+const buildInvocationExample = (toolName: string): Record<string, unknown> => {
+	const requiredArgs = TOOL_REQUIRED_ARGS[toolName];
+	const plan = getInvocationPlanName(toolName);
+	const defaultOptions = TOOL_DEFAULT_OPTIONS[toolName] ?? {};
+
+	const example: Record<string, unknown> = {};
+	if (requiredArgs && requiredArgs.length > 0) {
+		example.args = [...requiredArgs];
+	} else if (plan !== "processRootOnly") {
+		example.args = ["<arg0>"];
+	}
+
+	if (plan === "processRootOnly") {
+		example.options = { processRoot: "<repo-root>", ...defaultOptions };
+		return example;
+	}
+
+	if (plan === "optionsThenProcessRoot" || plan === "processRootThenOptions") {
+		example.options = { processRoot: "<repo-root>", ...defaultOptions };
+		return example;
+	}
+
+	if (plan === "optionsOnly") {
+		example.options =
+			Object.keys(defaultOptions).length > 0
+				? { ...defaultOptions }
+				: { example: true };
+		return example;
+	}
+
+	example.options =
+		Object.keys(defaultOptions).length > 0
+			? { ...defaultOptions }
+			: { example: true };
+	return example;
+};
+
+const defaultToolInputSchema = (toolName: string) => ({
+	type: "object",
+	additionalProperties: true,
+	properties: {
+		args: {
+			...toolArgsSchema(toolName),
+		},
+		options: {
+			type: "object",
+			additionalProperties: true,
+			description: "Named options",
+		},
+		processRoot: {
+			type: "string",
+			description:
+				'Repo root containing /projects and /agents. If you have a project root like ".../projects/adl", omit this or pass its parent.',
+		},
+	},
+	$comment: safeJsonStringify({
+		note: "Preferred: pass args as JSON-native values. Avoid stringifying objects.",
+		invocationPlan: getInvocationPlanName(toolName),
+		example: buildInvocationExample(toolName),
+	}),
+});
+
+const buildToolList = (
+	tools: ToolDefinition[],
+	batchToolName: string,
+	prefix: string | undefined,
+	exposeUnprefixedAliases: boolean,
+) => {
+	const toolEntries = tools.flatMap((tool) => {
+		const canonicalName = buildToolName(tool, prefix);
+		const schema =
+			TOOL_INPUT_SCHEMA_OVERRIDES[tool.name] ??
+			defaultToolInputSchema(tool.name);
+		const base = {
+			// Some UIs only show tool descriptions. Make the fastest path be "copy schema, fill values".
+			description: safeJsonStringify(schema),
+			inputSchema: schema,
+		};
+
+		const entries: Array<{
+			name: string;
+			description: string;
+			inputSchema: unknown;
+		}> = [
+			{
+				name: canonicalName,
+				...base,
+			},
+		];
+
+		if (prefix && exposeUnprefixedAliases) {
+			entries.push({
+				name: tool.name,
+				description: safeJsonStringify(schema),
+				inputSchema: base.inputSchema,
+			});
+		}
+
+		return entries;
+	});
+
+	const batchTool = {
+		name: batchToolName,
+		description: "",
+		inputSchema: {
+			type: "object",
+			additionalProperties: true,
+			properties: {
+				calls: {
+					type: "array",
+					minItems: 1,
+					items: {
+						type: "object",
+						additionalProperties: true,
+						properties: {
+							tool: {
+								type: "string",
+								description: "Full MCP tool name to execute",
+							},
+							args: {
+								type: "array",
+								items: {},
+								description: "Positional args for the tool",
+							},
+							options: {
+								type: "object",
+								additionalProperties: true,
+								description: "Tool invocation options",
+							},
+						},
+						required: ["tool"],
+					},
+					description: "List of tool calls to execute",
+				},
+				continueOnError: {
+					type: "boolean",
+					description: "Whether to continue when a call in the batch fails",
+					default: false,
+				},
+				maxConcurrency: {
+					type: "integer",
+					minimum: 1,
+					description:
+						"Max number of calls to execute concurrently when continueOnError=true.",
+					default: 8,
+				},
+			},
+			required: ["calls"],
+		},
+	};
+
+	(batchTool as any).description = safeJsonStringify(batchTool.inputSchema);
+
+	const out = [...toolEntries, batchTool];
+	if (prefix && exposeUnprefixedAliases) {
+		out.push({
+			...batchTool,
+			name: "batch",
+			description: safeJsonStringify(batchTool.inputSchema),
+		});
+	}
+
+	return out;
+};
+
+type ToolInvoker = (
+	args: unknown[],
+	options: Record<string, unknown>,
+) => unknown[];
+
+const buildOptionsOnly = (
+	args: unknown[],
+	options: Record<string, unknown>,
+): unknown[] => {
+	const invocationArgs: unknown[] = [...args];
+	if (Object.keys(options).length > 0) {
+		invocationArgs.push(options);
+	}
+	return invocationArgs;
+};
+
+const buildOptionsThenProcessRoot = (
+	args: unknown[],
+	options: Record<string, unknown>,
+): unknown[] => {
+	const invocationArgs: unknown[] = [...args];
+	const remaining = { ...options };
+	const processRoot = remaining.processRoot;
+	if (typeof processRoot === "string") {
+		delete remaining.processRoot;
+	}
+
+	if (Object.keys(remaining).length > 0) {
+		invocationArgs.push(remaining);
+	} else if (typeof processRoot === "string") {
+		// Preserve positional slot for signatures like fn(projectName, options?, processRoot?).
+		invocationArgs.push({});
+	}
+	if (typeof processRoot === "string") {
+		invocationArgs.push(processRoot);
+	}
+
+	return invocationArgs;
+};
+
+const buildProcessRootThenOptions = (
+	args: unknown[],
+	options: Record<string, unknown>,
+): unknown[] => {
+	const invocationArgs: unknown[] = [...args];
+	const remaining = { ...options };
+	const processRoot = remaining.processRoot;
+	if (typeof processRoot === "string") {
+		delete remaining.processRoot;
+	}
+
+	if (typeof processRoot === "string") {
+		invocationArgs.push(processRoot);
+	}
+	if (Object.keys(remaining).length > 0) {
+		invocationArgs.push(remaining);
+	}
+
+	return invocationArgs;
+};
+
+const buildProcessRootOnly = (
+	args: unknown[],
+	options: Record<string, unknown>,
+): unknown[] => {
+	const invocationArgs: unknown[] = [...args];
+	const processRoot = options.processRoot;
+	if (typeof processRoot === "string") {
+		invocationArgs.push(processRoot);
+	}
+	return invocationArgs;
+};
 
 const toolInvocationPlans: Record<string, ToolInvoker> = {
-  'agents.setActive': buildProcessRootThenOptions,
-  'agents.resolveAgentsRootFrom': buildProcessRootOnly,
-  'projects.setActive': buildProcessRootThenOptions,
-  'projects.generateSpec': buildOptionsThenProcessRoot,
-  'projects.syncTasks': buildOptionsThenProcessRoot,
-  'projects.clearIssues': buildOptionsThenProcessRoot,
-  'projects.fetchGitTasks': buildOptionsThenProcessRoot,
-  'projects.readGitTask': buildOptionsThenProcessRoot,
-  'projects.writeGitTask': buildOptionsThenProcessRoot,
-  'agents.resolveTargetFile': buildOptionsOnly,
-  'projects.resolveProjectTargetFile': buildOptionsOnly,
-  'agents.loadAgent': buildProcessRootOnly,
-  'agents.main': buildProcessRootOnly,
-  'agents.resolveAgentsRoot': buildProcessRootOnly,
-  'agents.resolveAgentsRootFrom': buildProcessRootOnly,
-  'agents.listAgents': buildProcessRootOnly,
-  'projects.resolveProjectRoot': buildProcessRootOnly,
-  'projects.listProjects': buildProcessRootOnly,
-  'projects.listProjectDocs': buildProcessRootOnly,
-  'projects.readProjectDoc': buildProcessRootOnly,
-  'projects.main': buildProcessRootOnly,
-}
+	"agents.setActive": buildProcessRootThenOptions,
+	"agents.resolveAgentsRootFrom": buildProcessRootOnly,
+	"projects.setActive": buildProcessRootThenOptions,
+	"projects.generateSpec": buildOptionsThenProcessRoot,
+	"projects.syncTasks": buildOptionsThenProcessRoot,
+	"projects.clearIssues": buildOptionsThenProcessRoot,
+	"projects.fetchGitTasks": buildOptionsThenProcessRoot,
+	"projects.createGitIssue": buildOptionsThenProcessRoot,
+	"projects.readGitTask": buildOptionsThenProcessRoot,
+	"projects.writeGitTask": buildOptionsThenProcessRoot,
+	"agents.resolveTargetFile": buildOptionsOnly,
+	"projects.resolveProjectTargetFile": buildOptionsOnly,
+	"agents.loadAgent": buildProcessRootOnly,
+	"agents.loadAgentPrompt": buildProcessRootOnly,
+	"projects.resolveImplementationPlan": (args, options) => {
+		const invocationArgs: unknown[] = [...args];
+		const remaining = { ...options };
+		const processRoot = remaining.processRoot;
+		if (typeof processRoot === "string") {
+			delete remaining.processRoot;
+		}
 
-const invokeTool = async (tool: ToolDefinition, payload: unknown): Promise<unknown> => {
-  const { args, options } = normalizePayload(payload)
-  const invoke = toolInvocationPlans[tool.name] ?? ((rawArgs, rawOptions) => {
-    const invocationArgs = [...rawArgs]
-    if (Object.keys(rawOptions).length > 0) {
-      invocationArgs.push(rawOptions)
-    }
-    return invocationArgs
-  })
-  const invocationArgs = invoke(args, options)
-
-  return Promise.resolve(tool.method(...invocationArgs))
-}
+		// This tool is a low-level helper: projects.resolveImplementationPlan(projectRoot, inputFile?, options?)
+		// If the caller provides options but no inputFile, preserve the positional slot.
+		if (Object.keys(remaining).length > 0) {
+			if (invocationArgs.length === 1) {
+				invocationArgs.push(undefined);
+			}
+			invocationArgs.push(remaining);
+		}
+
+		// Intentionally do NOT append processRoot: projectRoot is the first positional argument.
+		return invocationArgs;
+	},
+	"agents.main": buildProcessRootOnly,
+	"agents.resolveAgentsRoot": buildProcessRootOnly,
+	"agents.listAgents": buildProcessRootOnly,
+	"projects.resolveProjectRoot": buildProcessRootOnly,
+	"projects.listProjects": buildProcessRootOnly,
+	"projects.listProjectDocs": buildProcessRootOnly,
+	"projects.readProjectDoc": buildProcessRootOnly,
+	"projects.main": buildProcessRootOnly,
+};
+
+const invokeTool = async (
+	tool: ToolDefinition,
+	payload: unknown,
+): Promise<unknown> => {
+	const normalized = normalizePayload(payload);
+	const { args, options } = coercePayloadForTool(tool.name, normalized);
+	const invoke =
+		toolInvocationPlans[tool.name] ??
+		((rawArgs, rawOptions) => {
+			const invocationArgs = [...rawArgs];
+			if (Object.keys(rawOptions).length > 0) {
+				invocationArgs.push(rawOptions);
+			}
+			return invocationArgs;
+		});
+	const invocationArgs = invoke(args, options);
+
+	return Promise.resolve(tool.method(...invocationArgs));
+};
 
 export interface ExampleMcpServerOptions {
-  serverName?: string
-  serverVersion?: string
-  toolsPrefix?: string
-  allowedRootEndpoints?: string[]
-  disableWrite?: boolean
-  enableIssues?: boolean
-  admin?: boolean
+	serverName?: string;
+	serverVersion?: string;
+	toolsPrefix?: string;
+	allowedRootEndpoints?: string[];
+	disableWrite?: boolean;
+	enableIssues?: boolean;
+	admin?: boolean;
+	exposeUnprefixedToolAliases?: boolean;
 }
 
 export type ExampleMcpServerInstance = {
-  api: ApiEndpoint
-  tools: ToolDefinition[]
-  server: Server
-  run: () => Promise<Server>
-}
+	api: ApiEndpoint;
+	tools: ToolDefinition[];
+	server: Server;
+	run: () => Promise<Server>;
+};
 
-const READ_ONLY_TOOL_NAMES = new Set([
-  'agents.usage',
-  'agents.resolveAgentsRoot',
-  'agents.resolveAgentsRootFrom',
-  'agents.listAgents',
-  'agents.parseTargetSpec',
-  'agents.resolveTargetFile',
-  'agents.loadAgent',
-  'agents.loadAgentPrompt',
-  'projects.usage',
-  'projects.resolveProjectRoot',
-  'projects.listProjects',
-  'projects.listProjectDocs',
-  'projects.readProjectDoc',
-  'projects.resolveImplementationPlan',
-  'projects.fetchGitTasks',
-  'projects.readGitTask',
-  'projects.parseProjectTargetSpec',
-  'projects.resolveProjectTargetFile',
-])
-
-const isWriteCapableTool = (toolName: string): boolean => !READ_ONLY_TOOL_NAMES.has(toolName)
-const ISSUE_TOOL_NAMES = new Set([
-  'projects.fetchGitTasks',
-  'projects.readGitTask',
-  'projects.writeGitTask',
-  'projects.syncTasks',
-  'projects.clearIssues',
-])
-const isIssueTool = (toolName: string): boolean => ISSUE_TOOL_NAMES.has(toolName)
-const ADMIN_TOOL_NAMES = new Set([
-  'projects.syncTasks',
-  'projects.clearIssues',
-])
-const isAdminTool = (toolName: string): boolean => ADMIN_TOOL_NAMES.has(toolName)
-
-export const createExampleMcpServer = (options: ExampleMcpServerOptions = {}): ExampleMcpServerInstance => {
-  const api: ApiEndpoint = {
-    agents: agentsApi,
-    projects: projectsApi,
-  }
-
-  const allRoots = Object.keys(api) as Array<keyof ApiEndpoint>
-  const selectedRoots = (() => {
-    if (!options.allowedRootEndpoints || options.allowedRootEndpoints.length === 0) {
-      return allRoots
-    }
-
-    const normalized = options.allowedRootEndpoints
-      .map((value) => value.trim())
-      .filter((value) => value.length > 0)
-
-    const unknown = normalized.filter((value) => !allRoots.includes(value as keyof ApiEndpoint))
-    if (unknown.length > 0) {
-      throw new Error(`Unknown root endpoints: ${unknown.join(', ')}. Allowed: ${allRoots.join(', ')}`)
-    }
-
-    return [...new Set(normalized)] as Array<keyof ApiEndpoint>
-  })()
-
-  const selectedTools = selectedRoots.flatMap((root) => collectTools(api[root], [root]))
-  const adminFilteredTools = Boolean(options.admin)
-    ? selectedTools
-    : selectedTools.filter((tool) => !isAdminTool(tool.name))
-  const tools = options.disableWrite
-    ? adminFilteredTools.filter((tool) => !isWriteCapableTool(tool.name) || (Boolean(options.enableIssues) && isIssueTool(tool.name)))
-    : adminFilteredTools
-  const prefix = options.toolsPrefix
-  const batchToolName = prefix ? `${prefix}.batch` : 'batch'
-
-  const server = new Server(
-    {
-      name: options.serverName ?? 'example-api',
-      version: options.serverVersion ?? '1.0.0',
-    },
-    {
-      capabilities: {
-        tools: {},
-      },
-    },
-  )
-
-  const toolByName = new Map<string, ToolDefinition>(tools.map((tool) => [buildToolName(tool, prefix), tool]))
-
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: buildToolList(tools, batchToolName, prefix),
-  }))
-
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const requestedName = request.params.name
-
-    if (requestedName === batchToolName) {
-      try {
-        const { calls, continueOnError } = normalizeBatchPayload(request.params.arguments)
-        const executions = calls.map(({ tool, args = [], options = {} }, index) => ({ tool, args, options, index }))
-        const results = await Promise.all(
-          executions.map(async ({ tool, args, options, index }) => {
-            const toolDefinition = toolByName.get(tool)
-            if (!toolDefinition) {
-              return {
-                index,
-                tool,
-                isError: true,
-                data: `Unknown tool: ${tool}`,
-              } as BatchResult
-            }
-
-            try {
-              const data = await invokeTool(toolDefinition, { args, options })
-              return {
-                index,
-                tool,
-                isError: false,
-                data,
-              } as BatchResult
-            } catch (error) {
-              if (continueOnError) {
-                return {
-                  index,
-                  tool,
-                  isError: true,
-                  data: error instanceof Error ? error.message : String(error),
-                } as BatchResult
-              }
-              throw error
-            }
-          }),
-        )
-
-        return {
-          isError: results.some((result) => result.isError),
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(results, null, 2),
-            },
-          ],
-        }
-      } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: 'text',
-              text: error instanceof Error ? error.message : String(error),
-            },
-          ],
-        }
-      }
-    }
-
-    const tool = toolByName.get(requestedName)
-
-    if (!tool) {
-      throw new Error(`Unknown tool: ${requestedName}`)
-    }
-
-    try {
-      const data = await invokeTool(tool, request.params.arguments)
-      return {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify(data, null, 2),
-          },
-        ],
-      }
-    } catch (error) {
-      return {
-        isError: true,
-        content: [
-          {
-            type: 'text',
-            text: error instanceof Error ? error.message : String(error),
-          },
-        ],
-      }
-    }
-  })
-
-  const run = async (): Promise<Server> => {
-    await server.connect(new StdioServerTransport())
-    return server
-  }
-
-  return { api, tools, server, run }
-}
+const READ_ONLY_TOOL_NAMES = new Set<string>([
+	"agents.usage",
+	"agents.resolveAgentsRoot",
+	"agents.resolveAgentsRootFrom",
+	"agents.listAgents",
+	"agents.parseTargetSpec",
+	"agents.resolveTargetFile",
+	"agents.loadAgent",
+	"agents.loadAgentPrompt",
+	"net.curl",
+	"net_curl",
+	"projects.usage",
+	"projects.resolveProjectRoot",
+	"projects.listProjects",
+	"projects.listProjectDocs",
+	"projects.readProjectDoc",
+	"projects.searchDocs",
+	"projects.searchSpecs",
+	"projects.resolveImplementationPlan",
+	"projects.fetchGitTasks",
+	"projects.readGitTask",
+	"projects.parseProjectTargetSpec",
+	"projects.resolveProjectTargetFile",
+	"mcp.usage",
+	"mcp.listTools",
+	"mcp.describeTool",
+	"mcp.search",
+]);
 
-export const runExampleMcpServer = async (options: ExampleMcpServerOptions = {}): Promise<Server> => {
-  const instance = createExampleMcpServer(options)
-  return instance.run()
-}
+const isWriteCapableTool = (toolName: string): boolean =>
+	!READ_ONLY_TOOL_NAMES.has(toolName);
+const ISSUE_TOOL_NAMES = new Set<string>([
+	"projects.fetchGitTasks",
+	"projects.createGitIssue",
+	"projects.readGitTask",
+	"projects.writeGitTask",
+	"projects.syncTasks",
+	"projects.clearIssues",
+]);
+const isIssueTool = (toolName: string): boolean =>
+	ISSUE_TOOL_NAMES.has(toolName);
+const ADMIN_TOOL_NAMES = new Set<string>([
+	"projects.syncTasks",
+	"projects.clearIssues",
+	"agents.runAgent",
+	"agents.main",
+	"projects.main",
+]);
+const isAdminTool = (toolName: string): boolean =>
+	ADMIN_TOOL_NAMES.has(toolName);
+
+const getToolAccess = (toolName: string): ToolAccess => {
+	if (isAdminTool(toolName)) return "admin";
+	return isWriteCapableTool(toolName) ? "write" : "read";
+};
+
+const buildToolMeta = (tools: ToolDefinition[]): void => {
+	for (const tool of tools) {
+		TOOL_META[tool.name] = {
+			access: getToolAccess(tool.name),
+			category: tool.path[0],
+			notes: isAdminTool(tool.name) ? " Admin-only." : undefined,
+		};
+	}
+};
+
+const escapeRegExp = (value: string): string =>
+	value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const OPENAI_SAFE_TOOL_ALIASES: Record<string, string> = {
+	"net.curl": "net_curl",
+};
+
+const applyToolAliases = (tools: ToolDefinition[]): ToolDefinition[] => {
+	const existing = new Set(tools.map((tool) => tool.name));
+	const out: ToolDefinition[] = [...tools];
+
+	for (const tool of tools) {
+		const aliasName = OPENAI_SAFE_TOOL_ALIASES[tool.name];
+		if (!aliasName) continue;
+		if (existing.has(aliasName)) continue;
+		existing.add(aliasName);
+		out.push({
+			...tool,
+			name: aliasName,
+		});
+	}
+
+	return out;
+};
+
+const runWithConcurrency = async <T>(
+	tasks: Array<() => Promise<T>>,
+	maxConcurrency: number,
+): Promise<T[]> => {
+	const results: T[] = new Array(tasks.length);
+	let nextIndex = 0;
+
+	const worker = async (): Promise<void> => {
+		while (true) {
+			const index = nextIndex;
+			nextIndex += 1;
+			if (index >= tasks.length) return;
+			results[index] = await tasks[index]();
+		}
+	};
+
+	const concurrency = Math.max(1, Math.min(maxConcurrency, tasks.length));
+	await Promise.all(Array.from({ length: concurrency }, () => worker()));
+	return results;
+};
+
+export const createExampleMcpServer = (
+	options: ExampleMcpServerOptions = {},
+): ExampleMcpServerInstance => {
+	let toolCatalog: unknown[] = [];
+
+	const parseString = (value: unknown): string | null => {
+		if (typeof value !== "string") return null;
+		const trimmed = value.trim();
+		return trimmed.length > 0 ? trimmed : null;
+	};
+
+	const parseBoolean = (value: unknown): boolean =>
+		value === true || value === 1 || value === "1" || value === "true";
+
+	const parseStringArray = (value: unknown): string[] => {
+		if (Array.isArray(value)) {
+			return value
+				.map((entry) => String(entry))
+				.map((entry) => entry.trim())
+				.filter((entry) => entry.length > 0);
+		}
+		const asString = parseString(value);
+		return asString ? [asString] : [];
+	};
+
+	const ensureProjectName = (
+		projectName: string | null,
+		processRoot: string,
+	): string => {
+		if (projectName) return projectName;
+		const projects = projectsApi.listProjects(processRoot);
+		if (projects.length === 1) return projects[0];
+		throw new Error(
+			`projectName is required. Available projects: ${projects.join(", ")}`,
+		);
+	};
+
+	const mcpApi = {
+		usage: () =>
+			[
+				"F0 MCP helper tools:",
+				"- mcp.listTools: returns tool catalog with access + invocation hints",
+				"- mcp.describeTool: describe one tool by name (prefixed or unprefixed)",
+				"- mcp.search: LLM-friendly search over project docs/spec (local-first)",
+				"",
+				'Tip: Prefer mcp.search for "search spec/docs" requests.',
+			].join("\n"),
+		listTools: () => ({ tools: toolCatalog }),
+		describeTool: (toolName: string) => {
+			const normalized = typeof toolName === "string" ? toolName.trim() : "";
+			if (!normalized) {
+				throw new Error("toolName is required.");
+			}
+
+			const matches = toolCatalog.filter(
+				(entry) =>
+					isRecord(entry) &&
+					(entry.name === normalized ||
+						(entry as any).unprefixedName === normalized),
+			) as Array<Record<string, unknown>>;
+
+			if (matches.length === 0) {
+				const needle = normalized.toLowerCase();
+				const candidates = toolCatalog
+					.filter(isRecord)
+					.map((entry) => String((entry as any).name ?? ""))
+					.filter((name) => name.length > 0);
+				const suggestions = candidates
+					.filter(
+						(name) =>
+							name.toLowerCase().includes(needle) ||
+							needle.includes(name.toLowerCase()),
+					)
+					.slice(0, 8);
+				const hint =
+					suggestions.length > 0
+						? ` Did you mean: ${suggestions.join(", ")}?`
+						: "";
+				throw new Error(`Unknown tool: ${normalized}.${hint}`);
+			}
+
+			const canonical = matches.find(
+				(entry) => (entry as any).kind === "canonical",
+			);
+			return canonical ?? matches[0];
+		},
+		search: async (input: unknown) => {
+			const payload = isRecord(input) ? input : {};
+			const processRoot = (() => {
+				const raw = parseString(payload.processRoot);
+				return raw ? normalizeProcessRoot(raw) : process.cwd();
+			})();
+
+			const sectionRaw = parseString(payload.section)?.toLowerCase();
+			const section = sectionRaw === "docs" ? "docs" : "spec";
+
+			const pattern =
+				parseString(payload.pattern) ??
+				parseString(payload.query) ??
+				parseString(payload.q);
+			if (!pattern) {
+				throw new Error("pattern is required (or query/q).");
+			}
+
+			const rgArgs: string[] = [];
+			if (parseBoolean(payload.ignoreCase)) rgArgs.push("--ignore-case");
+			if (parseBoolean(payload.caseSensitive)) rgArgs.push("--case-sensitive");
+			if (parseBoolean(payload.smartCase)) rgArgs.push("--smart-case");
+			if (parseBoolean(payload.fixedStrings)) rgArgs.push("--fixed-strings");
+			if (parseBoolean(payload.wordRegexp)) rgArgs.push("--word-regexp");
+			if (parseBoolean(payload.includeHidden)) rgArgs.push("--hidden");
+			if (parseBoolean(payload.filesWithMatches))
+				rgArgs.push("--files-with-matches");
+			if (parseBoolean(payload.filesWithoutMatch))
+				rgArgs.push("--files-without-match");
+			if (parseBoolean(payload.countOnly)) rgArgs.push("--count");
+			if (parseBoolean(payload.onlyMatching)) rgArgs.push("--only-matching");
+
+			const maxCount =
+				typeof payload.maxCount === "number"
+					? payload.maxCount
+					: Number(payload.maxCount);
+			if (Number.isFinite(maxCount) && maxCount > 0) {
+				rgArgs.push("--max-count", String(Math.floor(maxCount)));
+			}
+
+			for (const glob of parseStringArray(payload.globs)) {
+				rgArgs.push("--glob", glob);
+			}
+
+			rgArgs.push(pattern);
+			const paths = parseStringArray(payload.paths);
+			if (paths.length > 0) {
+				rgArgs.push(...paths);
+			}
+
+			const projectName = ensureProjectName(
+				parseString(payload.projectName),
+				processRoot,
+			);
+
+			const searchOptions: Record<string, unknown> = {
+				processRoot,
+			};
+
+			const source = parseString(payload.source)?.toLowerCase();
+			if (source) {
+				searchOptions.source = source;
+			}
+			const ref = parseString(payload.ref);
+			if (ref) {
+				searchOptions.ref = ref;
+			}
+			if (parseBoolean(payload.refresh)) {
+				searchOptions.refresh = true;
+			}
+			const cacheDir = parseString(payload.cacheDir);
+			if (cacheDir) {
+				searchOptions.cacheDir = cacheDir;
+			}
+
+			return section === "docs"
+				? await projectsApi.searchDocs(projectName, ...rgArgs, searchOptions)
+				: await projectsApi.searchSpecs(projectName, ...rgArgs, searchOptions);
+		},
+	} satisfies ToolNamespace;
+
+	const api: ApiEndpoint = {
+		agents: agentsApi,
+		net: netApi,
+		projects: projectsApi,
+		mcp: mcpApi,
+	};
+
+	const allRoots = Object.keys(api) as Array<keyof ApiEndpoint>;
+	const selectedRoots = (() => {
+		if (
+			!options.allowedRootEndpoints ||
+			options.allowedRootEndpoints.length === 0
+		) {
+			return allRoots;
+		}
+
+		const normalized = options.allowedRootEndpoints
+			.map((value) => value.trim())
+			.filter((value) => value.length > 0);
+
+		const unknown = normalized.filter(
+			(value) => !allRoots.includes(value as keyof ApiEndpoint),
+		);
+		if (unknown.length > 0) {
+			throw new Error(
+				`Unknown root endpoints: ${unknown.join(", ")}. Allowed: ${allRoots.join(", ")}`,
+			);
+		}
+
+		return [...new Set(normalized)] as Array<keyof ApiEndpoint>;
+	})();
+
+	const selectedTools = selectedRoots.flatMap((root) =>
+		collectTools(api[root], [root]),
+	);
+	const selectedToolsWithAliases = applyToolAliases(selectedTools);
+	buildToolMeta(selectedToolsWithAliases);
+	const adminFilteredTools = Boolean(options.admin)
+		? selectedToolsWithAliases
+		: selectedToolsWithAliases.filter((tool) => !isAdminTool(tool.name));
+	const tools = options.disableWrite
+		? adminFilteredTools.filter(
+				(tool) =>
+					!isWriteCapableTool(tool.name) ||
+					(Boolean(options.enableIssues) && isIssueTool(tool.name)),
+			)
+		: adminFilteredTools;
+	const prefix = options.toolsPrefix;
+	const exposeUnprefixedAliases = options.exposeUnprefixedToolAliases ?? true;
+	const batchToolName = prefix ? `${prefix}.batch` : "batch";
+
+	toolCatalog = tools.flatMap((tool) => {
+		const canonicalName = buildToolName(tool, prefix);
+		const schema =
+			TOOL_INPUT_SCHEMA_OVERRIDES[tool.name] ??
+			defaultToolInputSchema(tool.name);
+		const base = {
+			canonicalName,
+			unprefixedName: tool.name,
+			access: getToolAccess(tool.name),
+			category: TOOL_META[tool.name]?.category ?? tool.path[0],
+			invocationPlan: getInvocationPlanName(tool.name),
+			example: buildInvocationExample(tool.name),
+			description: safeJsonStringify(schema),
+			inputSchema: schema,
+		};
+
+		const out = [
+			{
+				name: canonicalName,
+				kind: "canonical" as const,
+				...base,
+			},
+		];
+
+		if (prefix && exposeUnprefixedAliases) {
+			out.push({
+				name: tool.name,
+				kind: "alias" as const,
+				aliasOf: canonicalName,
+				...base,
+			});
+		}
+
+		return out;
+	});
+
+	toolCatalog.push({
+		name: batchToolName,
+		kind: "canonical" as const,
+		canonicalName: batchToolName,
+		unprefixedName: "batch",
+		access: "write",
+		category: "mcp",
+		invocationPlan: "custom",
+		example: {
+			calls: [
+				{ tool: prefix ? `${prefix}.projects.usage` : "projects.usage" },
+				{
+					tool: prefix
+						? `${prefix}.projects.listProjects`
+						: "projects.listProjects",
+					options: { processRoot: "<repo-root>" },
+				},
+			],
+			continueOnError: true,
+			maxConcurrency: 4,
+		},
+		description: safeJsonStringify({
+			type: "object",
+			additionalProperties: true,
+			properties: {
+				calls: {
+					type: "array",
+					minItems: 1,
+					items: { type: "object", additionalProperties: true },
+				},
+				continueOnError: { type: "boolean", default: false },
+				maxConcurrency: { type: "integer", minimum: 1, default: 8 },
+			},
+			required: ["calls"],
+		}),
+		inputSchema: {
+			type: "object",
+			additionalProperties: true,
+			properties: {
+				calls: {
+					type: "array",
+					minItems: 1,
+					items: { type: "object", additionalProperties: true },
+				},
+				continueOnError: { type: "boolean", default: false },
+				maxConcurrency: { type: "integer", minimum: 1, default: 8 },
+			},
+			required: ["calls"],
+		},
+	});
+	if (prefix && exposeUnprefixedAliases) {
+		toolCatalog.push({
+			name: "batch",
+			kind: "alias" as const,
+			aliasOf: batchToolName,
+			canonicalName: batchToolName,
+			unprefixedName: "batch",
+			access: "write",
+			category: "mcp",
+			invocationPlan: "custom",
+			example: {
+				calls: [{ tool: batchToolName }],
+			},
+			description: safeJsonStringify({
+				type: "object",
+				additionalProperties: true,
+				properties: {
+					calls: {
+						type: "array",
+						minItems: 1,
+						items: { type: "object", additionalProperties: true },
+					},
+					continueOnError: { type: "boolean", default: false },
+					maxConcurrency: { type: "integer", minimum: 1, default: 8 },
+				},
+				required: ["calls"],
+			}),
+			inputSchema: {
+				type: "object",
+				additionalProperties: true,
+				properties: {
+					calls: {
+						type: "array",
+						minItems: 1,
+						items: { type: "object", additionalProperties: true },
+					},
+					continueOnError: { type: "boolean", default: false },
+					maxConcurrency: { type: "integer", minimum: 1, default: 8 },
+				},
+				required: ["calls"],
+			},
+		});
+	}
+
+	const server = new Server(
+		{
+			name: options.serverName ?? "example-api",
+			version: options.serverVersion ?? "1.0.0",
+		},
+		{
+			capabilities: {
+				tools: {},
+			},
+		},
+	);
+
+	const toolByName = new Map<string, ToolDefinition>(
+		tools.map((tool) => [buildToolName(tool, prefix), tool]),
+	);
+	const toolByUnprefixedName = new Map<string, ToolDefinition>(
+		prefix ? tools.map((tool) => [tool.name, tool]) : [],
+	);
+
+	const knownToolNames = (() => {
+		const names = new Set<string>();
+		for (const name of toolByName.keys()) names.add(name);
+		if (prefix && exposeUnprefixedAliases) {
+			for (const tool of tools) names.add(tool.name);
+			names.add("batch");
+		}
+		names.add(batchToolName);
+		return names;
+	})();
+
+	const suggestToolNames = (requested: string): string[] => {
+		const needle = requested.trim().toLowerCase();
+		if (!needle) return [];
+
+		const score = (candidate: string): number => {
+			const cand = candidate.toLowerCase();
+			if (cand === needle) return 0;
+			if (cand.includes(needle)) return 1;
+			if (needle.includes(cand)) return 2;
+			const needleLast = needle.split(".").pop() ?? needle;
+			const candLast = cand.split(".").pop() ?? cand;
+			if (needleLast && candLast === needleLast) return 3;
+			if (candLast.includes(needleLast)) return 4;
+			return 100;
+		};
+
+		return Array.from(knownToolNames)
+			.map((name) => ({ name, s: score(name) }))
+			.filter((entry) => entry.s < 100)
+			.sort((a, b) => a.s - b.s || a.name.localeCompare(b.name))
+			.slice(0, 8)
+			.map((entry) => entry.name);
+	};
+
+	const resolveTool = (name: string): ToolDefinition | null => {
+		const direct = toolByName.get(name);
+		if (direct) return direct;
+		if (prefix) {
+			const unprefixed = name.replace(
+				new RegExp(`^${escapeRegExp(prefix)}\\.`),
+				"",
+			);
+			return (
+				toolByUnprefixedName.get(unprefixed) ??
+				toolByName.get(`${prefix}.${unprefixed}`) ??
+				null
+			);
+		}
+		return null;
+	};
+
+	const enrichToolError = (
+		toolName: string,
+		message: string,
+	): { message: string; details?: unknown } => {
+		const details: Record<string, unknown> = {};
+		const unprefixedToolName = prefix
+			? toolName.replace(new RegExp(`^${escapeRegExp(prefix)}\\.`), "")
+			: toolName;
+
+		if (/Missing project name\./i.test(message)) {
+			details.hint =
+				"Provide projectName (recommended) or pass it as the first positional arg (args[0]).";
+			details.suggestion =
+				"Prefer mcp.search with { projectName, section, pattern }.";
+			details.example = {
+				tool: prefix ? `${prefix}.mcp.search` : "mcp.search",
+				arguments: {
+					projectName: "<project-name>",
+					section: "spec",
+					pattern: "<pattern>",
+				},
+			};
+		}
+
+		if (
+			/Project folder not found:/i.test(message) &&
+			/projects[\\/].+projects[\\/]/i.test(message)
+		) {
+			details.hint =
+				"You likely passed a project root as processRoot. processRoot should be the repo root containing /projects.";
+		}
+
+		if (/Missing search pattern\./i.test(message)) {
+			details.hint =
+				"Provide pattern/query (recommended) or a PATTERN as the first rg positional.";
+		}
+
+		if (Object.keys(details).length === 0) {
+			return { message };
+		}
+
+		details.tool = toolName;
+		details.inputSchema =
+			TOOL_INPUT_SCHEMA_OVERRIDES[unprefixedToolName] ??
+			defaultToolInputSchema(unprefixedToolName);
+		details.invocationExample = buildInvocationExample(unprefixedToolName);
+		return { message, details };
+	};
+
+	server.setRequestHandler(ListToolsRequestSchema, async () => ({
+		tools: buildToolList(tools, batchToolName, prefix, exposeUnprefixedAliases),
+	}));
+
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const requestedName = request.params.name;
+
+		const isBatchName =
+			requestedName === batchToolName || (prefix && requestedName === "batch");
+		if (isBatchName) {
+			try {
+				const { calls, continueOnError, maxConcurrency } =
+					normalizeBatchPayload(request.params.arguments);
+				const executions = calls.map(
+					({ tool, args = [], options = {} }, index) => ({
+						tool,
+						args,
+						options,
+						index,
+					}),
+				);
+
+				const runCall = async ({
+					tool,
+					args,
+					options,
+					index,
+				}: (typeof executions)[number]): Promise<BatchResult> => {
+					const toolDefinition = resolveTool(tool);
+					if (!toolDefinition) {
+						const message = `Unknown tool: ${tool}`;
+						if (!continueOnError) {
+							throw new Error(message);
+						}
+						const suggestions = suggestToolNames(tool);
+						return {
+							index,
+							tool,
+							isError: true,
+							data: { message, suggestions },
+						};
+					}
+
+					try {
+						const data = await invokeTool(toolDefinition, { args, options });
+						return { index, tool, isError: false, data };
+					} catch (error) {
+						const message =
+							error instanceof Error ? error.message : String(error);
+						if (!continueOnError) {
+							throw new Error(message);
+						}
+						const enriched = enrichToolError(tool, message);
+						return {
+							index,
+							tool,
+							isError: true,
+							data: { message: enriched.message, details: enriched.details },
+						};
+					}
+				};
+
+				const results = continueOnError
+					? await runWithConcurrency(
+							executions.map((execution) => () => runCall(execution)),
+							maxConcurrency,
+						)
+					: await (async () => {
+							const out: BatchResult[] = [];
+							for (const execution of executions) {
+								out.push(await runCall(execution));
+							}
+							return out;
+						})();
+
+				const ordered = [...results].sort((a, b) => a.index - b.index);
+				const hasErrors = ordered.some((result) => result.isError);
+				return hasErrors
+					? toolErr("One or more batch calls failed.", { results: ordered })
+					: toolOk({ results: ordered });
+			} catch (error) {
+				return toolErr(error instanceof Error ? error.message : String(error));
+			}
+		}
+
+		const tool = resolveTool(requestedName);
+
+		if (!tool) {
+			const suggestions = suggestToolNames(requestedName);
+			return toolErr(
+				`Unknown tool: ${requestedName}`,
+				suggestions.length > 0 ? { suggestions } : undefined,
+			);
+		}
+
+		try {
+			const data = await invokeTool(tool, request.params.arguments);
+			return toolOk(data);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			const enriched = enrichToolError(requestedName, message);
+			return toolErr(enriched.message, enriched.details);
+		}
+	});
+
+	const run = async (): Promise<Server> => {
+		await server.connect(new StdioServerTransport());
+		return server;
+	};
+
+	return { api, tools, server, run };
+};
+
+export const runExampleMcpServer = async (
+	options: ExampleMcpServerOptions = {},
+): Promise<Server> => {
+	const instance = createExampleMcpServer(options);
+	return instance.run();
+};
 
-export const normalizeToolCallNameForServer = (prefix: string | undefined, toolName: string): string =>
-  prefix ? toolName.replace(new RegExp(`^${prefix}\\.`), '') : toolName
+export const normalizeToolCallNameForServer = (
+	prefix: string | undefined,
+	toolName: string,
+): string =>
+	prefix
+		? toolName.replace(new RegExp(`^${escapeRegExp(prefix)}\\.`), "")
+		: toolName;