@foundation0/api 1.1.1 → 1.1.2

package/mcp/server.ts

@@ -3,6 +3,8 @@ 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
 type ToolInvocationPayload = {
@@ -19,6 +21,7 @@ type BatchToolCall = {
 type BatchToolCallPayload = {
   calls: BatchToolCall[]
   continueOnError: boolean
+  maxConcurrency: number
 }
 type BatchResult = {
   index: number
@@ -37,12 +40,168 @@ type ToolNamespace = Record<string, unknown>
 type ApiEndpoint = {
   agents: ToolNamespace
   projects: ToolNamespace
+  mcp: ToolNamespace
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
 
-const normalizePayload = (payload: unknown): { args: string[]; options: Record<string, unknown> } => {
+const parseBooleanish = (value: unknown): boolean | null => {
+  if (value === true || value === false) return value
+  if (value === 1 || value === 0) return Boolean(value)
+  if (typeof value !== 'string') return null
+  const normalized = value.trim().toLowerCase()
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false
+  return null
+}
+
+const parsePositiveInteger = (value: unknown): number | null => {
+  const numeric = typeof value === 'string' && value.trim() !== ''
+    ? Number(value)
+    : (typeof value === 'number' ? value : NaN)
+
+  if (!Number.isInteger(numeric) || numeric <= 0) return null
+  return numeric
+}
+
+const safeJsonStringify = (value: unknown): string => {
+  try {
+    return JSON.stringify(value, (_key, v) => (typeof v === 'bigint' ? v.toString() : v), 2)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return JSON.stringify({ ok: false, error: { message, note: 'Failed to JSON stringify tool result.' } }, null, 2)
+  }
+}
+
+type ToolEnvelope =
+  | { ok: true; result: unknown }
+  | { ok: false; error: { message: string; details?: unknown } }
+
+const toolOk = (result: unknown) => ({
+  isError: false,
+  content: [{ type: 'text', text: safeJsonStringify({ ok: true, result } satisfies ToolEnvelope) }],
+})
+
+const toolErr = (message: string, details?: unknown) => ({
+  isError: true,
+  content: [{ type: 'text', text: safeJsonStringify({ ok: false, error: { message, details } } satisfies ToolEnvelope) }],
+})
+
+const isDir = (candidate: string): boolean => {
+  try {
+    return fs.statSync(candidate).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+const looksLikeRepoRoot = (candidate: string): boolean =>
+  isDir(path.join(candidate, 'projects')) && isDir(path.join(candidate, 'api'))
+
+const normalizeProcessRoot = (raw: string): string => {
+  const resolved = path.resolve(raw)
+  if (looksLikeRepoRoot(resolved)) return resolved
+
+  // Common mistake: passing a project root like ".../projects/adl" as processRoot.
+  // Try to find the containing repo root by walking up a few levels.
+  let current = resolved
+  for (let depth = 0; depth < 8; depth += 1) {
+    const parent = path.dirname(current)
+    if (parent === current) break
+    if (looksLikeRepoRoot(parent)) return parent
+    current = parent
+  }
+
+  const parts = resolved.split(path.sep).filter((part) => part.length > 0)
+  const projectsIndex = parts.lastIndexOf('projects')
+  if (projectsIndex >= 0) {
+    const candidate = parts.slice(0, projectsIndex).join(path.sep)
+    if (candidate && looksLikeRepoRoot(candidate)) return candidate
+  }
+
+  return resolved
+}
+
+const normalizeProcessRootOption = (options: Record<string, unknown>): Record<string, unknown> => {
+  const raw = options.processRoot
+  if (typeof raw !== 'string' || raw.trim().length === 0) return options
+  const normalized = normalizeProcessRoot(raw.trim())
+  if (normalized === raw) return options
+  return { ...options, processRoot: normalized }
+}
+
+type NormalizedToolPayload = { args: unknown[]; options: Record<string, unknown> }
+
+const parseStringish = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+const parseStringArrayish = (value: unknown): string[] => {
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry)).map((entry) => entry.trim()).filter((entry) => entry.length > 0)
+  }
+  const asString = parseStringish(value)
+  return asString ? [asString] : []
+}
+
+const popOption = (options: Record<string, unknown>, key: string): unknown => {
+  const value = options[key]
+  delete options[key]
+  return value
+}
+
+const popStringOption = (options: Record<string, unknown>, ...keys: string[]): string | null => {
+  for (const key of keys) {
+    const value = options[key]
+    const parsed = parseStringish(value)
+    if (parsed) {
+      delete options[key]
+      return parsed
+    }
+  }
+  return null
+}
+
+const popStringArrayOption = (options: Record<string, unknown>, ...keys: string[]): string[] => {
+  for (const key of keys) {
+    const value = options[key]
+    const parsed = parseStringArrayish(value)
+    if (parsed.length > 0) {
+      delete options[key]
+      return parsed
+    }
+  }
+  return []
+}
+
+const popBooleanOption = (options: Record<string, unknown>, ...keys: string[]): boolean | null => {
+  for (const key of keys) {
+    const value = options[key]
+    const parsed = parseBooleanish(value)
+    if (parsed !== null) {
+      delete options[key]
+      return parsed
+    }
+  }
+  return null
+}
+
+const popIntegerOption = (options: Record<string, unknown>, ...keys: string[]): number | null => {
+  for (const key of keys) {
+    const value = options[key]
+    const parsed = parsePositiveInteger(value)
+    if (parsed !== null) {
+      delete options[key]
+      return parsed
+    }
+  }
+  return null
+}
+
+const normalizePayload = (payload: unknown): NormalizedToolPayload => {
   if (!isRecord(payload)) {
     return {
       args: [],
@@ -53,7 +212,7 @@ const normalizePayload = (payload: unknown): { args: string[]; options: Record<s
   const explicitArgs = Array.isArray(payload.args) ? payload.args : undefined
   const explicitOptions = isRecord(payload.options) ? payload.options : undefined
 
-  const args = explicitArgs ? explicitArgs.map((entry) => String(entry)) : []
+  const args = explicitArgs ? [...explicitArgs] : []
   const options: Record<string, unknown> = explicitOptions ? { ...explicitOptions } : {}
 
   for (const [key, value] of Object.entries(payload)) {
@@ -68,10 +227,186 @@ const normalizePayload = (payload: unknown): { args: string[]; options: Record<s
 
   return {
     args,
-    options,
+    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) }
+}
+
 const normalizeBatchToolCall = (
   call: unknown,
   index: number,
@@ -93,6 +428,9 @@ const normalizeBatchToolCall = (
   }
 
   for (const [key, value] of Object.entries(extras)) {
+    if (key === 'tool' || key === 'args' || key === 'options') {
+      continue
+    }
     if (value !== undefined) {
       normalized.options[key] = value
     }
@@ -114,13 +452,30 @@ const normalizeBatchPayload = (payload: unknown): BatchToolCallPayload => {
   }
 
   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: Boolean(payload.continueOnError),
+    continueOnError,
+    maxConcurrency,
   }
 }
 
@@ -146,32 +501,526 @@ const collectTools = (api: ToolNamespace, namespace: string[], path: string[] =
 const buildToolName = (tool: ToolDefinition, prefix?: string): string =>
   prefix ? `${prefix}.${tool.name}` : tool.name
 
-const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?: string) => {
-  const toolEntries = tools.map((tool) => ({
-    name: buildToolName(tool, prefix),
-    description: `Call API method ${tool.path.join('.')}`,
-    inputSchema: {
+type ToolAccess = 'read' | 'write' | 'admin'
+type ToolMeta = {
+  access: ToolAccess
+  category?: string
+  notes?: string
+}
+
+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>'],
+}
+
+const TOOL_DEFAULT_OPTIONS: Record<string, Record<string, unknown>> = {
+  '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.',
+}
+
+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: {},
+})
+
+const TOOL_ARGS_SCHEMA_OVERRIDES: Record<string, Record<string, unknown>> = {
+  'projects.listProjects': {
+    type: 'array',
+    description: 'No positional arguments. Use options.processRoot if needed.',
+    minItems: 0,
+    maxItems: 0,
+    items: {},
+  },
+  'projects.usage': {
+    type: 'array',
+    description: 'No positional arguments.',
+    minItems: 0,
+    maxItems: 0,
+    items: {},
+  },
+  'agents.usage': {
+    type: 'array',
+    description: 'No positional arguments.',
+    minItems: 0,
+    maxItems: 0,
+    items: {},
+  },
+  'projects.searchDocs': {
+    type: 'array',
+    description: 'rg-like: projectName, pattern, then optional paths.',
+    minItems: 2,
+    prefixItems: [
+      { type: 'string', title: 'projectName' },
+      { type: 'string', title: 'pattern' },
+    ],
+    items: { type: 'string', title: 'path' },
+  },
+  'projects.searchSpecs': {
+    type: 'array',
+    description: 'rg-like: projectName, pattern, then optional paths.',
+    minItems: 2,
+    prefixItems: [
+      { type: 'string', title: 'projectName' },
+      { type: 'string', title: 'pattern' },
+    ],
+    items: { type: 'string', title: 'path' },
+  },
+  'projects.resolveProjectTargetFile': {
+    type: 'array',
+    description: 'Low-level helper: resolve versioned file in a directory.',
+    minItems: 2,
+    prefixItems: [
+      { type: 'string', title: 'targetDir', description: 'Directory to scan (absolute or relative to cwd).' },
+      {
+        type: 'object',
+        title: 'spec',
+        description: 'Output of projects.parseProjectTargetSpec().',
+        additionalProperties: true,
+      },
+    ],
+    items: {},
+  },
+  'agents.resolveTargetFile': {
+    type: 'array',
+    description: 'Low-level helper: resolve versioned file in a directory.',
+    minItems: 2,
+    prefixItems: [
+      { type: 'string', title: 'targetDir' },
+      {
+        type: 'object',
+        title: 'spec',
+        description: 'Output of agents.parseTargetSpec().',
+        additionalProperties: true,
+      },
+    ],
+    items: {},
+  },
+  'projects.resolveImplementationPlan': {
+    type: 'array',
+    description: 'Low-level helper: resolve docs implementation plan path for a given projectRoot.',
+    minItems: 1,
+    prefixItems: [
+      { type: 'string', title: 'projectRoot', description: 'Absolute path to a project folder (e.g. .../projects/adl).' },
+      { type: 'string', title: 'inputFile', description: 'Optional path within docs/ (or absolute) to pick a plan.' },
+    ],
+    items: {},
+  },
+}
+
+const toolArgsSchema = (toolName: string): Record<string, unknown> => {
+  const override = TOOL_ARGS_SCHEMA_OVERRIDES[toolName]
+  if (override) return override
+
+  const requiredArgs = TOOL_REQUIRED_ARGS[toolName]
+  if (requiredArgs && requiredArgs.length > 0) {
+    return buildArgsSchemaFromPlaceholders(requiredArgs)
+  }
+
+  return {
+    type: 'array',
+    items: {},
+    description: 'Positional arguments',
+  }
+}
+
+const getInvocationPlanName = (toolName: string): string => {
+  const plan = toolInvocationPlans[toolName]
+  if (!plan) return 'default'
+  if (plan === buildOptionsOnly) return 'optionsOnly'
+  if (plan === buildOptionsThenProcessRoot) return 'optionsThenProcessRoot'
+  if (plan === buildProcessRootThenOptions) return 'processRootThenOptions'
+  if (plan === buildProcessRootOnly) return 'processRootOnly'
+  return 'custom'
+}
+
+const buildInvocationExample = (toolName: string): Record<string, unknown> => {
+  const requiredArgs = TOOL_REQUIRED_ARGS[toolName]
+  const plan = getInvocationPlanName(toolName)
+  const defaultOptions = TOOL_DEFAULT_OPTIONS[toolName] ?? {}
+
+  const example: Record<string, unknown> = {}
+  if (requiredArgs && requiredArgs.length > 0) {
+    example.args = [...requiredArgs]
+  } else if (plan !== 'processRootOnly') {
+    example.args = ['<arg0>']
+  }
+
+  if (plan === 'processRootOnly') {
+    example.options = { processRoot: '<repo-root>', ...defaultOptions }
+    return example
+  }
+
+  if (plan === 'optionsThenProcessRoot' || plan === 'processRootThenOptions') {
+    example.options = { processRoot: '<repo-root>', ...defaultOptions }
+    return example
+  }
+
+  if (plan === 'optionsOnly') {
+    example.options = Object.keys(defaultOptions).length > 0 ? { ...defaultOptions } : { example: true }
+    return example
+  }
+
+  example.options = Object.keys(defaultOptions).length > 0 ? { ...defaultOptions } : { example: true }
+  return example
+}
+
+const defaultToolInputSchema = (toolName: string) => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    args: {
+      ...toolArgsSchema(toolName),
+    },
+    options: {
       type: 'object',
       additionalProperties: true,
-      properties: {
-        args: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Positional arguments',
-        },
-        options: {
-          type: 'object',
-          additionalProperties: true,
-          description: 'Named options',
-        },
-      },
+      description: 'Named options',
     },
-  }))
+    processRoot: {
+      type: 'string',
+      description:
+        'Repo root containing /projects and /agents. If you have a project root like ".../projects/adl", omit this or pass its parent.',
+    },
+  },
+  $comment: safeJsonStringify({
+    note: 'Preferred: pass args as JSON-native values. Avoid stringifying objects.',
+    invocationPlan: getInvocationPlanName(toolName),
+    example: buildInvocationExample(toolName),
+  }),
+})
+
+const buildToolList = (
+  tools: ToolDefinition[],
+  batchToolName: string,
+  prefix: string | undefined,
+  exposeUnprefixedAliases: boolean,
+) => {
+  const toolEntries = tools.flatMap((tool) => {
+    const canonicalName = buildToolName(tool, prefix)
+    const schema = TOOL_INPUT_SCHEMA_OVERRIDES[tool.name] ?? defaultToolInputSchema(tool.name)
+    const base = {
+      // Some UIs only show tool descriptions. Make the fastest path be "copy schema, fill values".
+      description: safeJsonStringify(schema),
+      inputSchema: schema,
+    }
+
+    const entries: Array<{ name: string; description: string; inputSchema: unknown }> = [
+      {
+        name: canonicalName,
+        ...base,
+      },
+    ]
+
+    if (prefix && exposeUnprefixedAliases) {
+      entries.push({
+        name: tool.name,
+        description: safeJsonStringify(schema),
+        inputSchema: base.inputSchema,
+      })
+    }
+
+    return entries
+  })
 
   const batchTool = {
     name: batchToolName,
-    description:
-      'Preferred mode for client calls: execute multiple MCP tool calls in one request with parallel execution.',
+    description: '',
     inputSchema: {
       type: 'object',
       additionalProperties: true,
@@ -189,7 +1038,7 @@ const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?:
               },
               args: {
                 type: 'array',
-                items: { type: 'string' },
+                items: {},
                 description: 'Positional args for the tool',
               },
               options: {
@@ -207,17 +1056,34 @@ const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?:
           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'],
     },
   }
 
-  return [...toolEntries, batchTool]
+  ;(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: string[], options: Record<string, unknown>) => unknown[]
+type ToolInvoker = (args: unknown[], options: Record<string, unknown>) => unknown[]
 
-const buildOptionsOnly = (args: string[], 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)
@@ -225,7 +1091,7 @@ const buildOptionsOnly = (args: string[], options: Record<string, unknown>): unk
   return invocationArgs
 }
 
-const buildOptionsThenProcessRoot = (args: string[], options: Record<string, unknown>): unknown[] => {
+const buildOptionsThenProcessRoot = (args: unknown[], options: Record<string, unknown>): unknown[] => {
   const invocationArgs: unknown[] = [...args]
   const remaining = { ...options }
   const processRoot = remaining.processRoot
@@ -243,7 +1109,7 @@ const buildOptionsThenProcessRoot = (args: string[], options: Record<string, unk
   return invocationArgs
 }
 
-const buildProcessRootThenOptions = (args: string[], options: Record<string, unknown>): unknown[] => {
+const buildProcessRootThenOptions = (args: unknown[], options: Record<string, unknown>): unknown[] => {
   const invocationArgs: unknown[] = [...args]
   const remaining = { ...options }
   const processRoot = remaining.processRoot
@@ -261,7 +1127,7 @@ const buildProcessRootThenOptions = (args: string[], options: Record<string, unk
   return invocationArgs
 }
 
-const buildProcessRootOnly = (args: string[], options: Record<string, unknown>): unknown[] => {
+const buildProcessRootOnly = (args: unknown[], options: Record<string, unknown>): unknown[] => {
   const invocationArgs: unknown[] = [...args]
   const processRoot = options.processRoot
   if (typeof processRoot === 'string') {
@@ -283,9 +1149,29 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
   '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.resolveAgentsRootFrom': buildProcessRootOnly,
   'agents.listAgents': buildProcessRootOnly,
   'projects.resolveProjectRoot': buildProcessRootOnly,
   'projects.listProjects': buildProcessRootOnly,
@@ -295,7 +1181,8 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
 }
 
 const invokeTool = async (tool: ToolDefinition, payload: unknown): Promise<unknown> => {
-  const { args, options } = normalizePayload(payload)
+  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) {
@@ -316,6 +1203,7 @@ export interface ExampleMcpServerOptions {
   disableWrite?: boolean
   enableIssues?: boolean
   admin?: boolean
+  exposeUnprefixedToolAliases?: boolean
 }
 
 export type ExampleMcpServerInstance = {
@@ -325,7 +1213,7 @@ export type ExampleMcpServerInstance = {
   run: () => Promise<Server>
 }
 
-const READ_ONLY_TOOL_NAMES = new Set([
+const READ_ONLY_TOOL_NAMES = new Set<string>([
   'agents.usage',
   'agents.resolveAgentsRoot',
   'agents.resolveAgentsRootFrom',
@@ -339,15 +1227,21 @@ const READ_ONLY_TOOL_NAMES = new Set([
   '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([
+const ISSUE_TOOL_NAMES = new Set<string>([
   'projects.fetchGitTasks',
   'projects.readGitTask',
   'projects.writeGitTask',
@@ -355,16 +1249,193 @@ const ISSUE_TOOL_NAMES = new Set([
   'projects.clearIssues',
 ])
 const isIssueTool = (toolName: string): boolean => ISSUE_TOOL_NAMES.has(toolName)
-const ADMIN_TOOL_NAMES = new Set([
+const ADMIN_TOOL_NAMES = new Set<string>([
   'projects.syncTasks',
   'projects.clearIssues',
+  'agents.runAgent',
+  'agents.main',
+  'projects.main',
 ])
 const isAdminTool = (toolName: string): boolean => ADMIN_TOOL_NAMES.has(toolName)
 
+const getToolAccess = (toolName: string): ToolAccess => {
+  if (isAdminTool(toolName)) return 'admin'
+  return isWriteCapableTool(toolName) ? 'write' : 'read'
+}
+
+const buildToolMeta = (tools: ToolDefinition[]): void => {
+  for (const tool of tools) {
+    TOOL_META[tool.name] = {
+      access: getToolAccess(tool.name),
+      category: tool.path[0],
+      notes: isAdminTool(tool.name) ? ' Admin-only.' : undefined,
+    }
+  }
+}
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const runWithConcurrency = async <T>(
+  tasks: Array<() => Promise<T>>,
+  maxConcurrency: number,
+): Promise<T[]> => {
+  const results: T[] = new Array(tasks.length)
+  let nextIndex = 0
+
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const index = nextIndex
+      nextIndex += 1
+      if (index >= tasks.length) return
+      results[index] = await tasks[index]()
+    }
+  }
+
+  const concurrency = Math.max(1, Math.min(maxConcurrency, tasks.length))
+  await Promise.all(Array.from({ length: concurrency }, () => worker()))
+  return results
+}
+
 export const createExampleMcpServer = (options: ExampleMcpServerOptions = {}): ExampleMcpServerInstance => {
+  let toolCatalog: unknown[] = []
+
+  const parseString = (value: unknown): string | null => {
+    if (typeof value !== 'string') return null
+    const trimmed = value.trim()
+    return trimmed.length > 0 ? trimmed : null
+  }
+
+  const parseBoolean = (value: unknown): boolean => value === true || value === 1 || value === '1' || value === 'true'
+
+  const parseStringArray = (value: unknown): string[] => {
+    if (Array.isArray(value)) {
+      return value.map((entry) => String(entry)).map((entry) => entry.trim()).filter((entry) => entry.length > 0)
+    }
+    const asString = parseString(value)
+    return asString ? [asString] : []
+  }
+
+  const ensureProjectName = (projectName: string | null, processRoot: string): string => {
+    if (projectName) return projectName
+    const projects = projectsApi.listProjects(processRoot)
+    if (projects.length === 1) return projects[0]
+    throw new Error(`projectName is required. Available projects: ${projects.join(', ')}`)
+  }
+
+  const mcpApi = {
+    usage: () =>
+      [
+        'F0 MCP helper tools:',
+        '- mcp.listTools: returns tool catalog with access + invocation hints',
+        '- mcp.describeTool: describe one tool by name (prefixed or unprefixed)',
+        '- mcp.search: LLM-friendly search over project docs/spec (local-first)',
+        '',
+        'Tip: Prefer mcp.search for "search spec/docs" requests.',
+      ].join('\n'),
+    listTools: () => ({ tools: toolCatalog }),
+    describeTool: (toolName: string) => {
+      const normalized = typeof toolName === 'string' ? toolName.trim() : ''
+      if (!normalized) {
+        throw new Error('toolName is required.')
+      }
+
+      const matches = toolCatalog.filter((entry) =>
+        isRecord(entry) && (entry.name === normalized || (entry as any).unprefixedName === normalized),
+      ) as Array<Record<string, unknown>>
+
+      if (matches.length === 0) {
+        const needle = normalized.toLowerCase()
+        const candidates = toolCatalog
+          .filter(isRecord)
+          .map((entry) => String((entry as any).name ?? ''))
+          .filter((name) => name.length > 0)
+        const suggestions = candidates
+          .filter((name) => name.toLowerCase().includes(needle) || needle.includes(name.toLowerCase()))
+          .slice(0, 8)
+        const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : ''
+        throw new Error(`Unknown tool: ${normalized}.${hint}`)
+      }
+
+      const canonical = matches.find((entry) => (entry as any).kind === 'canonical')
+      return canonical ?? matches[0]
+    },
+    search: async (input: unknown) => {
+      const payload = isRecord(input) ? input : {}
+      const processRoot = (() => {
+        const raw = parseString(payload.processRoot)
+        return raw ? normalizeProcessRoot(raw) : process.cwd()
+      })()
+
+      const sectionRaw = parseString(payload.section)?.toLowerCase()
+      const section = sectionRaw === 'docs' ? 'docs' : 'spec'
+
+      const pattern =
+        parseString(payload.pattern) ??
+        parseString(payload.query) ??
+        parseString(payload.q)
+      if (!pattern) {
+        throw new Error('pattern is required (or query/q).')
+      }
+
+      const rgArgs: string[] = []
+      if (parseBoolean(payload.ignoreCase)) rgArgs.push('--ignore-case')
+      if (parseBoolean(payload.caseSensitive)) rgArgs.push('--case-sensitive')
+      if (parseBoolean(payload.smartCase)) rgArgs.push('--smart-case')
+      if (parseBoolean(payload.fixedStrings)) rgArgs.push('--fixed-strings')
+      if (parseBoolean(payload.wordRegexp)) rgArgs.push('--word-regexp')
+      if (parseBoolean(payload.includeHidden)) rgArgs.push('--hidden')
+      if (parseBoolean(payload.filesWithMatches)) rgArgs.push('--files-with-matches')
+      if (parseBoolean(payload.filesWithoutMatch)) rgArgs.push('--files-without-match')
+      if (parseBoolean(payload.countOnly)) rgArgs.push('--count')
+      if (parseBoolean(payload.onlyMatching)) rgArgs.push('--only-matching')
+
+      const maxCount = typeof payload.maxCount === 'number' ? payload.maxCount : Number(payload.maxCount)
+      if (Number.isFinite(maxCount) && maxCount > 0) {
+        rgArgs.push('--max-count', String(Math.floor(maxCount)))
+      }
+
+      for (const glob of parseStringArray(payload.globs)) {
+        rgArgs.push('--glob', glob)
+      }
+
+      rgArgs.push(pattern)
+      const paths = parseStringArray(payload.paths)
+      if (paths.length > 0) {
+        rgArgs.push(...paths)
+      }
+
+      const projectName = ensureProjectName(parseString(payload.projectName), processRoot)
+
+      const searchOptions: Record<string, unknown> = {
+        processRoot,
+      }
+
+      const source = parseString(payload.source)?.toLowerCase()
+      if (source) {
+        searchOptions.source = source
+      }
+      const ref = parseString(payload.ref)
+      if (ref) {
+        searchOptions.ref = ref
+      }
+      if (parseBoolean(payload.refresh)) {
+        searchOptions.refresh = true
+      }
+      const cacheDir = parseString(payload.cacheDir)
+      if (cacheDir) {
+        searchOptions.cacheDir = cacheDir
+      }
+
+      return section === 'docs'
+        ? await projectsApi.searchDocs(projectName, ...rgArgs, searchOptions)
+        : await projectsApi.searchSpecs(projectName, ...rgArgs, searchOptions)
+    },
+  } satisfies ToolNamespace
+
   const api: ApiEndpoint = {
     agents: agentsApi,
     projects: projectsApi,
+    mcp: mcpApi,
   }
 
   const allRoots = Object.keys(api) as Array<keyof ApiEndpoint>
@@ -386,6 +1457,7 @@ export const createExampleMcpServer = (options: ExampleMcpServerOptions = {}): E
   })()
 
   const selectedTools = selectedRoots.flatMap((root) => collectTools(api[root], [root]))
+  buildToolMeta(selectedTools)
   const adminFilteredTools = Boolean(options.admin)
     ? selectedTools
     : selectedTools.filter((tool) => !isAdminTool(tool.name))
@@ -393,8 +1465,116 @@ export const createExampleMcpServer = (options: ExampleMcpServerOptions = {}): E
     ? 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',
@@ -408,100 +1588,157 @@ export const createExampleMcpServer = (options: ExampleMcpServerOptions = {}): E
   )
 
   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),
+    tools: buildToolList(tools, batchToolName, prefix, exposeUnprefixedAliases),
   }))
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const requestedName = request.params.name
 
-    if (requestedName === batchToolName) {
+    const isBatchName = requestedName === batchToolName || (prefix && requestedName === 'batch')
+    if (isBatchName) {
       try {
-        const { calls, continueOnError } = normalizeBatchPayload(request.params.arguments)
+        const { calls, continueOnError, maxConcurrency } = normalizeBatchPayload(request.params.arguments)
         const executions = calls.map(({ tool, args = [], options = {} }, index) => ({ tool, args, options, index }))
-        const results = await Promise.all(
-          executions.map(async ({ tool, args, options, index }) => {
-            const toolDefinition = toolByName.get(tool)
-            if (!toolDefinition) {
-              return {
-                index,
-                tool,
-                isError: true,
-                data: `Unknown tool: ${tool}`,
-              } as BatchResult
+
+        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,
-              } as BatchResult
-            } catch (error) {
-              if (continueOnError) {
-                return {
-                  index,
-                  tool,
-                  isError: true,
-                  data: error instanceof Error ? error.message : String(error),
-                } as BatchResult
-              }
-              throw error
+          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)
             }
-          }),
-        )
-
-        return {
-          isError: results.some((result) => result.isError),
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(results, null, 2),
-            },
-          ],
+            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 {
-          isError: true,
-          content: [
-            {
-              type: 'text',
-              text: error instanceof Error ? error.message : String(error),
-            },
-          ],
-        }
+        return toolErr(error instanceof Error ? error.message : String(error))
       }
     }
 
-    const tool = toolByName.get(requestedName)
+    const tool = resolveTool(requestedName)
 
     if (!tool) {
-      throw new Error(`Unknown tool: ${requestedName}`)
+      const suggestions = suggestToolNames(requestedName)
+      return toolErr(`Unknown tool: ${requestedName}`, suggestions.length > 0 ? { suggestions } : undefined)
     }
 
     try {
       const data = await invokeTool(tool, request.params.arguments)
-      return {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify(data, null, 2),
-          },
-        ],
-      }
+      return toolOk(data)
     } catch (error) {
-      return {
-        isError: true,
-        content: [
-          {
-            type: 'text',
-            text: error instanceof Error ? error.message : String(error),
-          },
-        ],
-      }
+      const message = error instanceof Error ? error.message : String(error)
+      const enriched = enrichToolError(requestedName, message)
+      return toolErr(enriched.message, enriched.details)
     }
   })
 
@@ -519,4 +1756,4 @@ export const runExampleMcpServer = async (options: ExampleMcpServerOptions = {})
 }
 
 export const normalizeToolCallNameForServer = (prefix: string | undefined, toolName: string): string =>
-  prefix ? toolName.replace(new RegExp(`^${prefix}\\.`), '') : toolName
+  prefix ? toolName.replace(new RegExp(`^${escapeRegExp(prefix)}\\.`), '') : toolName