@foundation0/api 1.1.2 → 1.1.4

package/mcp/server.ts

@@ -1,1759 +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 fs from 'node:fs'
-import path from 'node:path'
-
-type ApiMethod = (...args: unknown[]) => unknown
+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 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
-  maxConcurrency: number
-}
+	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
-  mcp: 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)
+	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
-}
+	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)
+	const numeric =
+		typeof value === "string" && value.trim() !== ""
+			? Number(value)
+			: typeof value === "number"
+				? value
+				: NaN;
 
-  if (!Number.isInteger(numeric) || numeric <= 0) return null
-  return numeric
-}
+	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)
-  }
-}
+	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 } }
+	| { 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) }],
-})
+	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) }],
-})
+	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
-  }
-}
+	try {
+		return fs.statSync(candidate).isDirectory();
+	} catch {
+		return false;
+	}
+};
 
 const looksLikeRepoRoot = (candidate: string): boolean =>
-  isDir(path.join(candidate, 'projects')) && isDir(path.join(candidate, 'api'))
+	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 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
-}
+	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] : []
-}
+	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 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': {
-      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) }
-}
+	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 (key === 'tool' || key === 'args' || key === 'options') {
-      continue
-    }
-    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))
-  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
-  })()
-
-  return {
-    calls: calls.map(({ tool, payload }) => ({
-      tool,
-      ...payload,
-    })),
-    continueOnError,
-    maxConcurrency,
-  }
-}
-
-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
-}
+	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),
+	);
+	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;
+	})();
+
+	return {
+		calls: calls.map(({ tool, payload }) => ({
+			tool,
+			...payload,
+		})),
+		continueOnError,
+		maxConcurrency,
+	};
+};
+
+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
+	prefix ? `${prefix}.${tool.name}` : tool.name;
 
-type ToolAccess = 'read' | 'write' | 'admin'
+type ToolAccess = "read" | "write" | "admin";
 type ToolMeta = {
-  access: ToolAccess
-  category?: string
-  notes?: string
-}
+	access: ToolAccess;
+	category?: string;
+	notes?: string;
+};
 
-const TOOL_META: Record<string, ToolMeta> = {}
+const TOOL_META: Record<string, ToolMeta> = {};
 
 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.readGitTask': ['<project-name>', '<issue-number|task-id>'],
-  'projects.writeGitTask': ['<project-name>', '<issue-number|task-id>'],
-}
+	"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 TOOL_DEFAULT_OPTIONS: Record<string, Record<string, unknown>> = {
-  'projects.searchDocs': { source: 'auto' },
-  'projects.searchSpecs': { source: 'auto' },
-}
+	"projects.searchDocs": { source: "auto" },
+	"projects.searchSpecs": { source: "auto" },
+};
 
 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.',
-}
+	"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> = {
-  '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'],
-  },
-  '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: {},
-})
+	"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: {},
-  },
-}
+	"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 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 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 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),
-  }),
-})
+	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,
+	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)
-  }
-  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 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.loadAgentPrompt': buildProcessRootOnly,
-  'projects.resolveImplementationPlan': (args, options) => {
-    const invocationArgs: unknown[] = [...args]
-    const remaining = { ...options }
-    const processRoot = remaining.processRoot
-    if (typeof processRoot === 'string') {
-      delete remaining.processRoot
-    }
-
-    // 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))
-}
+	"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;
+		}
+
+		// 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
-  exposeUnprefixedToolAliases?: 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<string>([
-  '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.searchDocs',
-  'projects.searchSpecs',
-  'projects.resolveImplementationPlan',
-  'projects.fetchGitTasks',
-  'projects.readGitTask',
-  'projects.parseProjectTargetSpec',
-  'projects.resolveProjectTargetFile',
-  'mcp.usage',
-  'mcp.listTools',
-  'mcp.describeTool',
-  'mcp.search',
-])
-
-const isWriteCapableTool = (toolName: string): boolean => !READ_ONLY_TOOL_NAMES.has(toolName)
+	"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",
+]);
+
+const isWriteCapableTool = (toolName: string): boolean =>
+	!READ_ONLY_TOOL_NAMES.has(toolName);
 const ISSUE_TOOL_NAMES = new Set<string>([
-  'projects.fetchGitTasks',
-  'projects.readGitTask',
-  'projects.writeGitTask',
-  'projects.syncTasks',
-  'projects.clearIssues',
-])
-const isIssueTool = (toolName: string): boolean => ISSUE_TOOL_NAMES.has(toolName)
+	"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)
+	"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'
-}
+	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, '\\$&')
+	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,
+	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,
-    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]))
-  buildToolMeta(selectedTools)
-  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 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(`^${escapeRegExp(prefix)}\\.`), '') : toolName
+	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(`^${escapeRegExp(prefix)}\\.`), "")
+		: toolName;