@foundation0/git 1.2.5 → 1.3.1

package/mcp/src/server.ts

@@ -1,749 +1,1809 @@
-import { createGitServiceApi } from '@foundation0/git'
-import type {
-  GitServiceApi,
-  GitServiceApiExecutionResult,
-  GitServiceApiFactoryOptions,
-  GitServiceApiMethod,
-} from '@foundation0/git'
-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 { redactSecretsForMcpOutput, redactSecretsInText } from './redaction'
-
-type ToolInvocationPayload = {
-  args?: unknown[]
-  options?: Record<string, unknown>
-  [key: string]: unknown
-}
-
-type McpToolOutputFormat = 'terse' | 'debug'
-
-type BatchToolCall = {
-  tool: string
-  args?: unknown[]
-  options?: Record<string, unknown>
-  [key: string]: unknown
-}
-
-type BatchToolCallPayload = {
-  calls: BatchToolCall[]
-  continueOnError: boolean
-}
-
-type BatchResult = {
-  index: number
-  tool: string
-  isError: boolean
-} & (McpTerseOk | McpTerseErr)
-
-type ToolDefinition = {
-  name: string
-  path: string[]
-  method: GitServiceApiMethod
-}
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
-const tryParseJsonObject = (value: string): unknown => {
-  const trimmed = value.trim()
-  if (!trimmed) return {}
-
-  try {
-    return JSON.parse(trimmed) as unknown
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    throw new Error(`Invalid args JSON: ${message}`)
-  }
-}
-
-const normalizeArgumentPayload = (payload: unknown): unknown => {
-  if (typeof payload === 'string' || payload instanceof String) {
-    const parsed = tryParseJsonObject(String(payload))
-    if (!isRecord(parsed)) {
-      const kind = Array.isArray(parsed) ? 'array' : typeof parsed
-      throw new Error(`Invalid args: expected a JSON object, got ${kind}`)
-    }
-    return parsed
-  }
-
-  return payload
-}
-
-const toTrimmedString = (value: unknown): string => (value === null || value === undefined ? '' : String(value)).trim()
-
-const toPositiveInteger = (value: unknown): number | null => {
-  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
-    return Math.floor(value)
-  }
-
-  if (typeof value !== 'string') return null
-
-  const trimmed = value.trim()
-  if (!trimmed) return null
-  const parsed = Number(trimmed)
-  if (!Number.isFinite(parsed) || parsed <= 0) return null
-  return Math.floor(parsed)
-}
-
-const pickFirst = <T>(...candidates: Array<T | null | undefined>): T | null => {
-  for (const candidate of candidates) {
-    if (candidate !== null && candidate !== undefined) return candidate
-  }
-  return null
-}
-
-const pickRecord = (value: unknown): Record<string, unknown> => (isRecord(value) ? (value as Record<string, unknown>) : {})
-
-const parseOutputFormat = (value: unknown): McpToolOutputFormat | null => {
-  if (value === null || value === undefined) return null
-  const raw = toTrimmedString(value).toLowerCase()
-  if (!raw) return null
-  if (raw === 'debug') return 'debug'
-  if (raw === 'terse') return 'terse'
-  return null
-}
-
-const extractOutputControls = (payload: unknown): { format: McpToolOutputFormat | null } => {
-  const normalized = normalizeArgumentPayload(payload)
-  if (!isRecord(normalized)) {
-    return { format: null }
-  }
-
-  const topLevelFormat = parseOutputFormat(normalized.format)
-  const optionsFormat = parseOutputFormat(pickRecord(normalized.options).format)
-
-  // Support either { format:"debug" } or { options:{ format:"debug" } }.
-  return { format: pickFirst(topLevelFormat, optionsFormat) }
-}
-
-type McpTerseOk = {
-  ok: true
-  data: unknown
-  meta: {
-    status: number
-  }
-  debug?: unknown
-}
-
-type McpTerseErr = {
-  ok: false
-  error: {
-    code: string
-    status?: number
-    message: string
-    details?: unknown
-    hint?: string
-    retryable: boolean
-  }
-  meta?: {
-    status?: number
-  }
-  debug?: unknown
-}
-
+import { createGitServiceApi } from '@foundation0/git'
+import type {
+  GitServiceApi,
+  GitServiceApiExecutionResult,
+  GitServiceApiFactoryOptions,
+  GitServiceApiMethod,
+} from '@foundation0/git'
+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 { redactSecretsForMcpOutput, redactSecretsInText } from './redaction'
+
+type ToolInvocationPayload = {
+  args?: unknown[]
+  options?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+type McpToolOutputFormat = 'terse' | 'debug'
+
+type McpFieldSelection = string[]
+
+type BatchToolCall = {
+  tool: string
+  args?: unknown[]
+  options?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+type BatchToolCallPayload = {
+  calls: BatchToolCall[]
+  continueOnError: boolean
+}
+
+type BatchResult = {
+  index: number
+  tool: string
+  isError: boolean
+} & (McpTerseOk | McpTerseErr)
+
+type ToolDefinition = {
+  name: string
+  path: string[]
+  method: GitServiceApiMethod
+}
+
+type McpToolListEntry = {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const tryParseJsonObject = (value: string): unknown => {
+  const trimmed = value.trim()
+  if (!trimmed) return {}
+
+  try {
+    return JSON.parse(trimmed) as unknown
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Invalid args JSON: ${message}`)
+  }
+}
+
+const normalizeArgumentPayload = (payload: unknown): unknown => {
+  if (typeof payload === 'string' || payload instanceof String) {
+    const parsed = tryParseJsonObject(String(payload))
+    if (!isRecord(parsed)) {
+      const kind = Array.isArray(parsed) ? 'array' : typeof parsed
+      throw new Error(`Invalid args: expected a JSON object, got ${kind}`)
+    }
+    return parsed
+  }
+
+  return payload
+}
+
+const toTrimmedString = (value: unknown): string => (value === null || value === undefined ? '' : String(value)).trim()
+
+const toPositiveInteger = (value: unknown): number | null => {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return Math.floor(value)
+  }
+
+  if (typeof value !== 'string') return null
+
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  const parsed = Number(trimmed)
+  if (!Number.isFinite(parsed) || parsed <= 0) return null
+  return Math.floor(parsed)
+}
+
+const toNonNegativeInteger = (value: unknown): number | null => {
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+    return Math.floor(value)
+  }
+
+  if (typeof value !== 'string') return null
+
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  const parsed = Number(trimmed)
+  if (!Number.isFinite(parsed) || parsed < 0) return null
+  return Math.floor(parsed)
+}
+
+const pickFirst = <T>(...candidates: Array<T | null | undefined>): T | null => {
+  for (const candidate of candidates) {
+    if (candidate !== null && candidate !== undefined) return candidate
+  }
+  return null
+}
+
+const pickRecord = (value: unknown): Record<string, unknown> => (isRecord(value) ? (value as Record<string, unknown>) : {})
+
+const parseOutputFormat = (value: unknown): McpToolOutputFormat | null => {
+  if (value === null || value === undefined) return null
+  const raw = toTrimmedString(value).toLowerCase()
+  if (!raw) return null
+  if (raw === 'debug') return 'debug'
+  if (raw === 'terse') return 'terse'
+  return null
+}
+
+const parseBoolean = (value: unknown): boolean | null => {
+  if (value === null || value === undefined) return null
+  if (typeof value === 'boolean') return value
+
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase()
+    if (!normalized) return null
+    if (normalized === 'true') return true
+    if (normalized === 'false') return false
+  }
+
+  return null
+}
+
+const parseFieldSelection = (value: unknown): McpFieldSelection | null => {
+  if (value === null || value === undefined) return null
+
+  if (Array.isArray(value)) {
+    const fields = value.map((entry) => toTrimmedString(entry)).filter((entry) => entry.length > 0)
+    return fields.length > 0 ? fields : null
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (!trimmed) return null
+    const fields = trimmed
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0)
+    return fields.length > 0 ? fields : null
+  }
+
+  return null
+}
+
+const extractMcpControls = (
+  payload: unknown,
+): { format: McpToolOutputFormat | null; validateOnly: boolean; fields: McpFieldSelection | null } => {
+  const normalized = normalizeArgumentPayload(payload)
+  if (!isRecord(normalized)) {
+    return { format: null, validateOnly: false, fields: null }
+  }
+
+  const topLevelFormat = parseOutputFormat(normalized.format)
+  const topLevelValidateOnly = parseBoolean(normalized.validateOnly)
+  const topLevelFields = parseFieldSelection(normalized.fields)
+  const optionsFormat = parseOutputFormat(pickRecord(normalized.options).format)
+  const optionsValidateOnly = parseBoolean(pickRecord(normalized.options).validateOnly)
+  const optionsFields = parseFieldSelection(pickRecord(normalized.options).fields)
+
+  // Support either { format:"debug" } or { options:{ format:"debug" } }.
+  return {
+    format: pickFirst(topLevelFormat, optionsFormat),
+    validateOnly: Boolean(pickFirst(topLevelValidateOnly, optionsValidateOnly)),
+    fields: pickFirst(topLevelFields, optionsFields),
+  }
+}
+
+type McpTerseOk = {
+  ok: true
+  data: unknown
+  meta: {
+    status: number
+  }
+  debug?: unknown
+}
+
+type McpTerseErr = {
+  ok: false
+  error: {
+    code: string
+    status?: number
+    message: string
+    details?: unknown
+    hint?: string
+    retryable: boolean
+  }
+  meta?: {
+    status?: number
+  }
+  debug?: unknown
+}
+
 const httpErrorCodeForStatus = (status: number): string => {
   if (status === 400) return 'HTTP_BAD_REQUEST'
   if (status === 401) return 'HTTP_UNAUTHORIZED'
   if (status === 403) return 'HTTP_FORBIDDEN'
-  if (status === 404) return 'HTTP_NOT_FOUND'
-  if (status === 409) return 'HTTP_CONFLICT'
-  if (status === 422) return 'HTTP_UNPROCESSABLE_ENTITY'
-  if (status === 429) return 'HTTP_RATE_LIMITED'
-  if (status >= 500) return 'HTTP_SERVER_ERROR'
+  if (status === 404) return 'HTTP_NOT_FOUND'
+  if (status === 409) return 'HTTP_CONFLICT'
+  if (status === 422) return 'HTTP_UNPROCESSABLE_ENTITY'
+  if (status === 429) return 'HTTP_RATE_LIMITED'
+  if (status >= 500) return 'HTTP_SERVER_ERROR'
   if (status >= 400) return 'HTTP_ERROR'
   return 'UNKNOWN'
 }
 
-const buildErrorMessage = (status: number | undefined, body: unknown): string => {
-  if (typeof body === 'string') {
-    const trimmed = body.trim()
-    if (trimmed) {
-      const firstLine = trimmed.split(/\r?\n/, 1)[0]
-      return firstLine.length > 0 ? firstLine : trimmed
-    }
-  }
-
-  if (isRecord(body) && typeof body.message === 'string' && body.message.trim()) {
-    return body.message.trim()
-  }
-
-  if (typeof status === 'number') {
-    return `HTTP ${status}`
-  }
-
-  return 'Request failed'
-}
-
-const toMcpEnvelope = (
-  result: GitServiceApiExecutionResult,
-  format: McpToolOutputFormat,
-): { isError: boolean; envelope: McpTerseOk | McpTerseErr } => {
-  const sanitized = redactSecretsForMcpOutput(result)
-
-  if (result.ok && result.status < 400) {
-    const envelope: McpTerseOk = {
-      ok: true,
-      data: result.body,
-      meta: {
-        status: result.status,
-      },
-      ...(format === 'debug' ? { debug: sanitized } : {}),
-    }
-
-    return { isError: false, envelope: redactSecretsForMcpOutput(envelope) as McpTerseOk }
-  }
-
-  const status = result.status
-  const envelope: McpTerseErr = {
-    ok: false,
-    error: {
-      code: httpErrorCodeForStatus(status),
-      status,
-      message: buildErrorMessage(status, result.body),
-      details: result.body,
-      retryable: status >= 500 || status === 429,
-    },
-    meta: {
-      status,
-    },
-    ...(format === 'debug' ? { debug: sanitized } : {}),
+const tryParseJsonLikeString = (value: string): unknown | null => {
+  try {
+    return JSON.parse(value) as unknown
+  } catch {
+    return null
   }
-
-  return { isError: true, envelope: redactSecretsForMcpOutput(envelope) as McpTerseErr }
 }
 
-const toMcpThrownErrorEnvelope = (error: unknown): McpTerseErr => ({
-  ok: false,
-  error: {
-    code: 'TOOL_ERROR',
-    message: redactSecretsInText(error instanceof Error ? error.message : String(error)),
-    retryable: false,
-  },
-})
-
-const normalizePayload = (payload: unknown): { args: string[]; options: Record<string, unknown> } => {
-  const normalized = normalizeArgumentPayload(payload)
-
-  if (normalized === null || normalized === undefined) {
-    return {
-      args: [],
-      options: {},
+const extractBodyMessage = (body: unknown): string | null => {
+  if (isRecord(body)) {
+    if (typeof body.message === 'string' && body.message.trim()) {
+      return body.message.trim()
     }
-  }
 
-  if (!isRecord(normalized)) {
-    const kind = Array.isArray(normalized) ? 'array' : typeof normalized
-    throw new Error(`Invalid args: expected a JSON object, got ${kind}`)
-  }
-
-  const explicitArgs = Array.isArray(normalized.args) ? normalized.args : undefined
-  const explicitOptions = isRecord(normalized.options) ? normalized.options : undefined
-
-  const args = explicitArgs ? explicitArgs.map((entry) => String(entry)) : []
-  const options: Record<string, unknown> = explicitOptions ? { ...explicitOptions } : {}
-
-  for (const [key, value] of Object.entries(normalized)) {
-    if (key === 'args' || key === 'options') {
-      continue
+    if (typeof body.error === 'string' && body.error.trim()) {
+      return body.error.trim()
     }
 
-    if (value !== undefined) {
-      options[key] = value
+    if (isRecord(body.error)) {
+      const nested = extractBodyMessage(body.error)
+      if (nested) return nested
     }
   }
 
-  return {
-    args,
-    options,
+  if (typeof body !== 'string') {
+    return null
   }
-}
-
-const OMITTED_OPTION_KEYS = new Set(['format'])
 
-const stripMcpOnlyOptions = (options: Record<string, unknown>): Record<string, unknown> => {
-  const next: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(options)) {
-    if (OMITTED_OPTION_KEYS.has(key)) continue
-    next[key] = value
+  const trimmed = body.trim()
+  if (!trimmed) {
+    return null
   }
-  return next
-}
 
-const normalizeBatchToolCall = (
-  call: unknown,
-  index: number,
-): { tool: string; payload: ToolInvocationPayload } => {
-  if (!isRecord(call)) {
-    throw new Error(`Invalid batch call at index ${index}: expected object`)
-  }
+  const parsed =
+    trimmed.startsWith('{') || trimmed.startsWith('[')
+      ? tryParseJsonLikeString(trimmed)
+      : null
 
-  const tool = typeof call.tool === 'string' ? call.tool.trim() : ''
-  if (!tool) {
-    throw new Error(`Invalid batch call at index ${index}: missing "tool"`)
+  if (parsed && isRecord(parsed)) {
+    const parsedMessage = extractBodyMessage(parsed)
+    if (parsedMessage) return parsedMessage
   }
 
-  const args = Array.isArray(call.args) ? call.args : []
-  const { options, ...extras } = call
-  const normalized: ToolInvocationPayload = {
-    args,
-    options: isRecord(options) ? options : {},
+  const firstLine = trimmed.split(/\r?\n/, 1)[0]?.trim() ?? ''
+  if (firstLine === '{' || firstLine === '[') {
+    return null
   }
 
-  for (const [key, value] of Object.entries(extras)) {
-    if (value !== undefined) {
-      normalized.options[key] = value
-    }
-  }
-
-  return {
-    tool,
-    payload: normalized,
-  }
-}
-
-const normalizeBatchPayload = (payload: unknown): BatchToolCallPayload => {
-  const normalized = normalizeArgumentPayload(payload)
-  if (!isRecord(normalized)) {
-    throw new Error('Batch tool call requires an object payload')
-  }
-
-  if (!Array.isArray(normalized.calls)) {
-    throw new Error('Batch tool call requires a "calls" array')
-  }
-
-  const calls = (normalized.calls as unknown[]).map((call, index) => normalizeBatchToolCall(call, index))
-
-  return {
-    calls: calls.map(({ tool, payload }) => ({
-      tool,
-      ...payload,
-    })),
-    continueOnError: Boolean((normalized as Record<string, unknown>).continueOnError),
-  }
+  return firstLine.length > 0 ? firstLine : null
 }
 
-const collectGitTools = (api: GitServiceApi, parentPath: string[] = []): ToolDefinition[] => {
-  const tools: ToolDefinition[] = []
-
-  for (const [segment, value] of Object.entries(api)) {
-    const currentPath = [...parentPath, segment]
-
-    if (typeof value === 'function') {
-      tools.push({
-        name: currentPath.join('.'),
-        path: currentPath,
-        method: value as GitServiceApiMethod,
-      })
-      continue
-    }
-
-    if (isRecord(value)) {
-      tools.push(...collectGitTools(value as GitServiceApi, currentPath))
-    }
-  }
-
-  return tools
-}
-
-export interface GitMcpServerOptions extends GitServiceApiFactoryOptions {
-  serverName?: string
-  serverVersion?: string
-  toolsPrefix?: string
-}
-
-export type GitMcpServerInstance = {
-  api: GitServiceApi
-  tools: ToolDefinition[]
-  server: Server
-  run: () => Promise<Server>
-}
-
-const buildToolName = (tool: ToolDefinition, prefix?: string): string =>
-  prefix ? `${prefix}.${tool.name}` : tool.name
-
-const isLogsForRunTailTool = (toolName: string): boolean => toolName.endsWith('jobs.logsForRunTail')
-
-const buildGenericToolSchema = (): Record<string, unknown> => ({
-  type: 'object',
-  additionalProperties: true,
-  properties: {
-    args: {
-      type: 'array',
-      items: { type: 'string' },
-      description: 'Positional arguments for the git API method (strings are safest).',
-    },
-    options: {
-      type: 'object',
-      additionalProperties: true,
-      description: 'Method options (query/headers/body payload). Extra top-level keys are merged into options.',
-    },
-    format: {
-      type: 'string',
-      enum: ['terse', 'debug'],
-      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
-    },
-  },
-})
-
-const buildLogsForRunTailSchema = (): Record<string, unknown> => ({
-  type: 'object',
-  additionalProperties: true,
-  properties: {
-    // Preferred named form (no positional confusion).
-    owner: {
-      type: 'string',
-      description: 'Repository owner/org. Optional if the server was started with a default owner.',
-    },
-    repo: {
-      type: 'string',
-      description: 'Repository name. Optional if the server was started with a default repo.',
-    },
-    headSha: {
-      type: 'string',
-      description: 'Commit SHA for the run (alias: head_sha).',
-    },
-    head_sha: {
-      type: 'string',
-      description: 'Alias for headSha.',
-    },
-    runNumber: {
-      type: 'integer',
-      minimum: 1,
-      description: 'Workflow run_number (alias: run_number).',
-    },
-    run_number: {
-      type: 'integer',
-      minimum: 1,
-      description: 'Alias for runNumber.',
-    },
-    maxLines: {
-      type: 'integer',
-      minimum: 1,
-      description: 'Max lines to return from the end of the logs.',
-    },
-    maxBytes: {
-      type: 'integer',
-      minimum: 1,
-      description: 'Max bytes to return from the end of the logs.',
-    },
-    contains: {
-      type: 'string',
-      description: 'If set, only return log lines containing this substring.',
-    },
-    format: {
-      type: 'string',
-      enum: ['terse', 'debug'],
-      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
-    },
-
-    // Legacy / compatibility: allow calling with positional args.
-    args: {
-      type: 'array',
-      items: {},
-      description:
-        'Legacy positional form. Preferred is named params. If used, pass [headSha, runNumber] (or the legacy-mistake [owner, repo] with options.headSha/options.runNumber).',
-    },
-    options: {
-      type: 'object',
-      additionalProperties: true,
-      description:
-        'Options object. Supports owner/repo, maxLines/maxBytes/contains, and format. Extra top-level keys are merged into options.',
-    },
-  },
-  anyOf: [
-    { required: ['headSha', 'runNumber'] },
-    { required: ['head_sha', 'run_number'] },
-    { required: ['headSha', 'run_number'] },
-    { required: ['head_sha', 'runNumber'] },
-  ],
-})
-
-const buildToolInputSchema = (tool: ToolDefinition): Record<string, unknown> =>
-  isLogsForRunTailTool(tool.name) ? buildLogsForRunTailSchema() : buildGenericToolSchema()
-
-const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?: string) => {
-  const toolNames = tools.map((tool) => ({
-    name: buildToolName(tool, prefix),
-    description: `Call git API method ${tool.path.join('.')}`,
-    inputSchema: buildToolInputSchema(tool),
-  }))
-
-  const batchTool = {
-    name: batchToolName,
-    description:
-      'Preferred mode for client calls: execute multiple MCP tool calls in one request with parallel execution.',
-    inputSchema: {
-      type: 'object',
-      additionalProperties: true,
-      properties: {
-        calls: {
-          type: 'array',
-          minItems: 1,
-          items: {
-            type: 'object',
-            additionalProperties: true,
-            properties: {
-              tool: {
-                type: 'string',
-                description: 'Full MCP tool name to execute',
-              },
-              args: {
-                type: 'array',
-                items: { type: 'string' },
-                description: 'Positional args for the tool',
-              },
-              options: {
-                type: 'object',
-                additionalProperties: true,
-                description: 'Tool invocation options',
-              },
-              format: {
-                type: 'string',
-                enum: ['terse', 'debug'],
-                description: 'Per-call output format (default: "terse").',
-              },
-            },
-            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,
-        },
-        format: {
-          type: 'string',
-          enum: ['terse', 'debug'],
-          description: 'Default output format for calls that do not specify one (default: "terse").',
-        },
-      },
-      required: ['calls'],
-    },
-  }
-
-  return [...toolNames, batchTool]
-}
-
-const normalizeToolCallName = (prefix: string | undefined, toolName: string): string =>
-  prefix ? toolName.replace(new RegExp(`^${prefix}\\.`), '') : toolName
-
-const invokeTool = async (
-  tool: ToolDefinition,
-  payload: unknown,
-): Promise<GitServiceApiExecutionResult> => {
-  const { args, options } = normalizePayload(payload)
-  const cleanedOptions = stripMcpOnlyOptions(options)
-  const invocationArgs: unknown[] = args
-
-  if (Object.keys(cleanedOptions).length > 0) {
-    invocationArgs.push(cleanedOptions)
-  }
-
-  return tool.method(...invocationArgs)
-}
-
-const invokeLogsForRunTailTool = async (tool: ToolDefinition, payload: unknown): Promise<GitServiceApiExecutionResult> => {
-  const normalized = normalizeArgumentPayload(payload)
-  const record = isRecord(normalized) ? normalized : {}
-  const args = Array.isArray(record.args) ? record.args : []
-  const options = pickRecord(record.options)
-
-  const headShaNamed = toTrimmedString(pickFirst(record.headSha, record.head_sha, options.headSha, options.head_sha))
-  const runNumberNamed = pickFirst(
-    toPositiveInteger(pickFirst(record.runNumber, record.run_number, options.runNumber, options.run_number)),
-    null,
-  )
-
-  // Positional preferred legacy: [headSha, runNumber]
-  const headShaPositional = args.length >= 1 ? toTrimmedString(args[0]) : ''
-  const runNumberPositional = args.length >= 2 ? toPositiveInteger(args[1]) : null
-
-  // Legacy-mistake support: args=[owner, repo], options has headSha/runNumber.
-  const shouldTreatArgsAsOwnerRepo =
-    args.length >= 2 &&
-    (!headShaPositional || !runNumberPositional) &&
-    Boolean(headShaNamed) &&
-    Boolean(runNumberNamed)
-
-  const ownerFromArgs = shouldTreatArgsAsOwnerRepo ? toTrimmedString(args[0]) : ''
-  const repoFromArgs = shouldTreatArgsAsOwnerRepo ? toTrimmedString(args[1]) : ''
-
-  const owner = toTrimmedString(pickFirst(record.owner, options.owner, ownerFromArgs)) || undefined
-  const repo = toTrimmedString(pickFirst(record.repo, options.repo, repoFromArgs)) || undefined
-
-  const sha = toTrimmedString(pickFirst(headShaNamed || null, headShaPositional || null)) || ''
-  const run = pickFirst(runNumberNamed, runNumberPositional) ?? null
-
-  if (!sha || !run) {
-    throw new Error(
-      'headSha (string) and runNumber (positive integer) are required. Preferred invocation: { owner, repo, headSha, runNumber, maxLines }.',
-    )
-  }
-
-  const cleanedOptions = stripMcpOnlyOptions({
-    ...options,
-    ...(owner ? { owner } : {}),
-    ...(repo ? { repo } : {}),
-  })
-
-  return tool.method(sha, run, cleanedOptions)
-}
-
-export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpServerInstance => {
-  const api = createGitServiceApi(options)
-  const tools = collectGitTools(api)
-  const prefix = options.toolsPrefix
-  const batchToolName = prefix ? `${prefix}.batch` : 'batch'
-
-  const server = new Server(
-    {
-      name: options.serverName ?? 'git',
-      version: options.serverVersion ?? '1.0.0',
-    },
-    {
-      capabilities: {
-        tools: {},
-      },
-    },
-  )
-
-  const toolByName = new Map<string, ToolDefinition>(tools.map((tool) => [buildToolName(tool, prefix), tool]))
-
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: buildToolList(tools, batchToolName, prefix),
-  }))
-
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const requestedName = request.params.name
-
-    if (requestedName === batchToolName) {
-      try {
-        const { calls, continueOnError } = normalizeBatchPayload(request.params.arguments)
-        const batchControls = extractOutputControls(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,
-                ...({
-                  ok: false,
-                  error: {
-                    code: 'UNKNOWN_TOOL',
-                    message: `Unknown tool: ${tool}`,
-                    retryable: false,
-                  },
-                } satisfies McpTerseErr),
-              } as BatchResult
-            }
-
-            try {
-              const mergedPayload = { args, options }
-              const callControls = extractOutputControls(mergedPayload)
-              const effectiveFormat = callControls.format ?? batchControls.format ?? 'terse'
-
-              const data = await (isLogsForRunTailTool(toolDefinition.name)
-                ? invokeLogsForRunTailTool(toolDefinition, mergedPayload)
-                : invokeTool(toolDefinition, mergedPayload))
-
-              const { isError, envelope } = toMcpEnvelope(data, effectiveFormat)
-              return {
-                index,
-                tool,
-                isError,
-                ...(envelope as McpTerseOk | McpTerseErr),
-              } as BatchResult
-            } catch (error) {
-              if (continueOnError) {
-                return {
-                  index,
-                  tool,
-                  isError: true,
-                  ...(toMcpThrownErrorEnvelope(error) as McpTerseErr),
-                } as BatchResult
-              }
-              throw error
-            }
-          }),
-        )
-
-        return {
-          isError: results.some((result) => result.isError),
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(redactSecretsForMcpOutput(results)),
-            },
-          ],
-        }
-      } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(toMcpThrownErrorEnvelope(error)),
-            },
-          ],
-        }
-      }
-    }
-
-    const tool = toolByName.get(requestedName)
-
-    if (!tool) {
-      throw new Error(`Unknown tool: ${requestedName}`)
-    }
-
-    try {
-      const controls = extractOutputControls(request.params.arguments)
-      const result = await (isLogsForRunTailTool(tool.name)
-        ? invokeLogsForRunTailTool(tool, request.params.arguments)
-        : invokeTool(tool, request.params.arguments))
-
-      const { isError, envelope } = toMcpEnvelope(result, controls.format ?? 'terse')
-      return {
-        ...(isError ? { isError: true } : {}),
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify(envelope),
-          },
-        ],
-      }
-    } catch (error) {
-      return {
-        isError: true,
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify(toMcpThrownErrorEnvelope(error)),
-          },
-        ],
-      }
-    }
-  })
-
-  const run = async (): Promise<Server> => {
-    await server.connect(new StdioServerTransport())
-    return server
+const buildErrorMessage = (status: number | undefined, body: unknown): string => {
+  const extracted = extractBodyMessage(body)
+  if (extracted) {
+    return extracted
   }
 
-  return { api, tools, server, run }
-}
-
-export const runGitMcpServer = async (options: GitMcpServerOptions = {}): Promise<Server> => {
-  const instance = createGitMcpServer(options)
-  return instance.run()
-}
-
-export const normalizeToolCallNameForServer = (
-  prefix: string | undefined,
-  toolName: string,
-): string => normalizeToolCallName(prefix, toolName)
+  if (typeof status === 'number') {
+    return `HTTP ${status}`
+  }
+
+  return 'Request failed'
+}
+
+const toMcpEnvelope = (
+  result: GitServiceApiExecutionResult,
+  format: McpToolOutputFormat,
+): { isError: boolean; envelope: McpTerseOk | McpTerseErr } => {
+  const sanitized = redactSecretsForMcpOutput(result)
+
+  if (result.ok && result.status < 400) {
+    const envelope: McpTerseOk = {
+      ok: true,
+      data: result.body,
+      meta: {
+        status: result.status,
+      },
+      ...(format === 'debug' ? { debug: sanitized } : {}),
+    }
+
+    return { isError: false, envelope: redactSecretsForMcpOutput(envelope) as McpTerseOk }
+  }
+
+  const status = result.status
+  const message = buildErrorMessage(status, result.body)
+  const retryable = status >= 500 || status === 429 || /try again later/i.test(message)
+
+  const envelope: McpTerseErr = {
+    ok: false,
+    error: {
+      code: httpErrorCodeForStatus(status),
+      status,
+      message,
+      details: result.body,
+      retryable,
+    },
+    meta: {
+      status,
+    },
+    ...(format === 'debug' ? { debug: sanitized } : {}),
+  }
+
+  return { isError: true, envelope: redactSecretsForMcpOutput(envelope) as McpTerseErr }
+}
+
+const toMcpThrownErrorEnvelope = (error: unknown): McpTerseErr => {
+  const message = redactSecretsInText(error instanceof Error ? error.message : String(error))
+
+  const hint =
+    message.includes('Missing required path arguments') || message.includes('Unresolved parameters')
+      ? 'Likely missing required positional args. Prefer { args:[...], owner, repo } or set server defaults, and avoid putting path params inside options.data/options.query.'
+      : message.startsWith('Invalid args JSON:')
+        ? 'If you are calling through a router/proxy, ensure tool arguments are a JSON object (not an array/string).'
+      : message.startsWith('Invalid args: expected a JSON object')
+        ? 'Pass an object payload like { args:[...], options:{...} }. Some proxies require arguments to be a JSON string containing an object.'
+      : undefined
+
+  return {
+    ok: false,
+    error: {
+      code: 'TOOL_ERROR',
+      message,
+      ...(hint ? { hint } : {}),
+      retryable: false,
+    },
+  }
+}
+
+const normalizePayload = (payload: unknown): { args: string[]; options: Record<string, unknown> } => {
+  const normalized = normalizeArgumentPayload(payload)
+
+  if (normalized === null || normalized === undefined) {
+    return {
+      args: [],
+      options: {},
+    }
+  }
+
+  if (!isRecord(normalized)) {
+    const kind = Array.isArray(normalized) ? 'array' : typeof normalized
+    throw new Error(`Invalid args: expected a JSON object, got ${kind}`)
+  }
+
+  const explicitArgs = Array.isArray(normalized.args) ? normalized.args : undefined
+  const explicitOptions = isRecord(normalized.options) ? normalized.options : undefined
+
+  const args = explicitArgs ? explicitArgs.map((entry) => String(entry)) : []
+  const options: Record<string, unknown> = explicitOptions ? { ...explicitOptions } : {}
+
+  for (const [key, value] of Object.entries(normalized)) {
+    if (key === 'args' || key === 'options') {
+      continue
+    }
+
+    if (value !== undefined) {
+      options[key] = value
+    }
+  }
+
+  return {
+    args,
+    options: normalizeNestedOptions(options),
+  }
+}
+
+const OMITTED_OPTION_KEYS = new Set(['format', 'fields', 'validateOnly'])
+
+const stripMcpOnlyOptions = (options: Record<string, unknown>): Record<string, unknown> => {
+  const next: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(options)) {
+    if (OMITTED_OPTION_KEYS.has(key)) continue
+    next[key] = value
+  }
+  return next
+}
+
+const tryParseJson = (value: string): unknown => {
+  const trimmed = value.trim()
+  if (!trimmed) return undefined
+  try {
+    return JSON.parse(trimmed) as unknown
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Invalid nested JSON: ${message}`)
+  }
+}
+
+const normalizeNestedJsonOption = (value: unknown): unknown => {
+  if (typeof value !== 'string') return value
+
+  const trimmed = value.trim()
+  if (!trimmed) return value
+
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[') && trimmed !== 'null' && trimmed !== 'true' && trimmed !== 'false') {
+    return value
+  }
+
+  return tryParseJson(trimmed)
+}
+
+const normalizeNestedOptions = (options: Record<string, unknown>): Record<string, unknown> => {
+  const next = { ...options }
+
+  if ('data' in next) {
+    next.data = normalizeNestedJsonOption(next.data)
+  }
+
+  if ('json' in next) {
+    next.json = normalizeNestedJsonOption(next.json)
+  }
+
+  if ('payload' in next) {
+    next.payload = normalizeNestedJsonOption(next.payload)
+  }
+
+  if ('query' in next) {
+    next.query = normalizeNestedJsonOption(next.query)
+  }
+
+  return next
+}
+
+const applyFieldSelection = (data: unknown, fields: McpFieldSelection | null): unknown => {
+  if (!fields || fields.length === 0) return data
+
+  const pickFromRecord = (record: Record<string, unknown>): Record<string, unknown> => {
+    const out: Record<string, unknown> = {}
+
+    for (const field of fields) {
+      const parts = field.split('.').map((part) => part.trim()).filter(Boolean)
+      if (parts.length === 0) continue
+
+      let current: unknown = record
+      for (const part of parts) {
+        if (!isRecord(current)) {
+          current = undefined
+          break
+        }
+        current = (current as Record<string, unknown>)[part]
+      }
+
+      if (current === undefined) continue
+
+      let target: Record<string, unknown> = out
+      for (const part of parts.slice(0, -1)) {
+        if (!isRecord(target[part])) {
+          target[part] = {}
+        }
+        target = target[part] as Record<string, unknown>
+      }
+      target[parts[parts.length - 1]] = current
+    }
+
+    return out
+  }
+
+  if (Array.isArray(data)) {
+    return data.map((entry) => (isRecord(entry) ? pickFromRecord(entry as Record<string, unknown>) : entry))
+  }
+
+  if (isRecord(data)) {
+    return pickFromRecord(data)
+  }
+
+  return data
+}
+
+const normalizeBatchToolCall = (
+  call: unknown,
+  index: number,
+): { tool: string; payload: ToolInvocationPayload } => {
+  if (!isRecord(call)) {
+    throw new Error(`Invalid batch call at index ${index}: expected object`)
+  }
+
+  const tool = typeof call.tool === 'string' ? call.tool.trim() : ''
+  if (!tool) {
+    throw new Error(`Invalid batch call at index ${index}: missing "tool"`)
+  }
+
+  const args = Array.isArray(call.args) ? call.args : []
+  const { options, ...extras } = call
+  const normalized: ToolInvocationPayload = {
+    args,
+    options: isRecord(options) ? options : {},
+  }
+
+  for (const [key, value] of Object.entries(extras)) {
+    if (value !== undefined) {
+      normalized.options[key] = value
+    }
+  }
+
+  return {
+    tool,
+    payload: normalized,
+  }
+}
+
+const normalizeBatchPayload = (payload: unknown): BatchToolCallPayload => {
+  const normalized = normalizeArgumentPayload(payload)
+  if (!isRecord(normalized)) {
+    throw new Error('Batch tool call requires an object payload')
+  }
+
+  if (!Array.isArray(normalized.calls)) {
+    throw new Error('Batch tool call requires a "calls" array')
+  }
+
+  const calls = (normalized.calls as unknown[]).map((call, index) => normalizeBatchToolCall(call, index))
+
+  return {
+    calls: calls.map(({ tool, payload }) => ({
+      tool,
+      ...payload,
+    })),
+    continueOnError: Boolean((normalized as Record<string, unknown>).continueOnError),
+  }
+}
+
+const collectGitTools = (api: GitServiceApi, parentPath: string[] = []): ToolDefinition[] => {
+  const tools: ToolDefinition[] = []
+
+  for (const [segment, value] of Object.entries(api)) {
+    const currentPath = [...parentPath, segment]
+
+    if (typeof value === 'function') {
+      tools.push({
+        name: currentPath.join('.'),
+        path: currentPath,
+        method: value as GitServiceApiMethod,
+      })
+      continue
+    }
+
+    if (isRecord(value)) {
+      tools.push(...collectGitTools(value as GitServiceApi, currentPath))
+    }
+  }
+
+  return tools
+}
+
+export interface GitMcpServerOptions extends GitServiceApiFactoryOptions {
+  serverName?: string
+  serverVersion?: string
+  toolsPrefix?: string
+}
+
+export type GitMcpServerInstance = {
+  api: GitServiceApi
+  tools: ToolDefinition[]
+  server: Server
+  listTools: () => McpToolListEntry[]
+  callTool: (toolName: string, payload: unknown) => Promise<{ isError: boolean; text: string }>
+  run: () => Promise<Server>
+}
+
+const buildToolName = (tool: ToolDefinition, prefix?: string): string =>
+  prefix ? `${prefix}.${tool.name}` : tool.name
+
+const isLogsForRunTailTool = (toolName: string): boolean => toolName.endsWith('jobs.logsForRunTail')
+const isArtifactsByRunTool = (toolName: string): boolean => toolName.endsWith('runs.artifacts')
+const isDiagnoseLatestFailureTool = (toolName: string): boolean =>
+  toolName.endsWith('diagnoseLatestFailure') && toolName.includes('.actions.')
+
+const buildGenericToolSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with defaults or context was set.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with defaults or context was set.',
+    },
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Positional arguments for the git API method (strings are safest).',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Method options (query/headers/body payload). Extra top-level keys are merged into options.',
+    },
+    validateOnly: {
+      type: 'boolean',
+      description:
+        'If true, do not execute the underlying HTTP request. Returns the normalized call payload (args/options) that would be sent.',
+    },
+    fields: {
+      description:
+        'Optional field selection for the response body to reduce token usage. Accepts a string[] or a comma-separated string of dot-paths.',
+      anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+  },
+})
+
+const buildArtifactsByRunSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with a default owner.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with a default repo.',
+    },
+    runId: {
+      description: 'Workflow run id (alias: run_id).',
+      anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }],
+    },
+    run_id: {
+      description: 'Alias for runId.',
+      anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }],
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    // Legacy positional forms:
+    // - Preferred by humans/LLMs: [owner, repo, runId]
+    // - Back-compat with the underlying helper signature: [runId, owner, repo]
+    args: {
+      type: 'array',
+      items: {},
+      description:
+        'Legacy positional form. Prefer named params. If used, pass [owner, repo, runId] (recommended) or the legacy [runId, owner, repo]. You can also pass only [runId] if defaults are configured.',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Options object (query/headers/body payload). Extra top-level keys are merged into options.',
+    },
+  },
+  anyOf: [{ required: ['runId'] }, { required: ['run_id'] }, { required: ['args'] }],
+})
+
+const buildLogsForRunTailSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    // Preferred named form (no positional confusion).
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with a default owner.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with a default repo.',
+    },
+    headSha: {
+      type: 'string',
+      description: 'Commit SHA for the run (alias: head_sha).',
+    },
+    head_sha: {
+      type: 'string',
+      description: 'Alias for headSha.',
+    },
+    runNumber: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Workflow run_number (alias: run_number).',
+    },
+    run_number: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Alias for runNumber.',
+    },
+    maxLines: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max lines to return from the end of the logs.',
+    },
+    maxBytes: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max bytes to return from the end of the logs.',
+    },
+    contains: {
+      type: 'string',
+      description: 'If set, only return log lines containing this substring.',
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+
+    // Legacy / compatibility: allow calling with positional args.
+    args: {
+      type: 'array',
+      items: {},
+      description:
+        'Legacy positional form. Preferred is named params. If used, pass [headSha, runNumber] (or the legacy-mistake [owner, repo] with options.headSha/options.runNumber).',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description:
+        'Options object. Supports owner/repo, maxLines/maxBytes/contains, and format. Extra top-level keys are merged into options.',
+    },
+  },
+  anyOf: [
+    { required: ['headSha', 'runNumber'] },
+    { required: ['head_sha', 'run_number'] },
+    { required: ['headSha', 'run_number'] },
+    { required: ['head_sha', 'runNumber'] },
+  ],
+})
+
+const buildDiagnoseLatestFailureSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with a default owner.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with a default repo.',
+    },
+    workflowName: {
+      type: 'string',
+      description: 'Optional filter: match failing runs by name/display_title (case-insensitive substring).',
+    },
+    limit: {
+      type: 'integer',
+      minimum: 1,
+      description: 'How many tasks/runs to fetch before filtering (default: 50).',
+    },
+    maxLines: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max lines to return from the end of the logs (default: 200).',
+    },
+    maxBytes: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max bytes to return from the end of the logs.',
+    },
+    contains: {
+      type: 'string',
+      description: 'If set, only return log lines containing this substring.',
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Legacy positional form: [owner, repo] plus options.workflowName/maxLines/etc.',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Options object. Extra top-level keys are merged into options.',
+    },
+  },
+})
+
+const buildToolInputSchema = (tool: ToolDefinition): Record<string, unknown> =>
+  isLogsForRunTailTool(tool.name)
+    ? buildLogsForRunTailSchema()
+    : isArtifactsByRunTool(tool.name)
+      ? buildArtifactsByRunSchema()
+      : isDiagnoseLatestFailureTool(tool.name)
+        ? buildDiagnoseLatestFailureSchema()
+      : buildGenericToolSchema()
+
+const buildToolList = (
+  tools: ToolDefinition[],
+  batchToolName: string,
+  prefix: string | undefined,
+  customTools: McpToolListEntry[],
+) => {
+  const toolNames: McpToolListEntry[] = tools.map((tool) => ({
+    name: buildToolName(tool, prefix),
+    description: `Call git API method ${tool.path.join('.')}`,
+    inputSchema: buildToolInputSchema(tool),
+  }))
+
+  const batchTool = {
+    name: batchToolName,
+    description:
+      'Preferred mode for client calls: execute multiple MCP tool calls in one request with parallel execution.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: true,
+      properties: {
+        calls: {
+          type: 'array',
+          minItems: 1,
+          items: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              tool: {
+                type: 'string',
+                description: 'Full MCP tool name to execute',
+              },
+              args: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Positional args for the tool',
+              },
+              options: {
+                type: 'object',
+                additionalProperties: true,
+                description: 'Tool invocation options',
+              },
+              validateOnly: {
+                type: 'boolean',
+                description: 'If true, validate and normalize without executing the underlying request.',
+              },
+              fields: {
+                description:
+                  'Optional field selection for the response body (reduces token usage). Accepts a string[] or comma-separated string.',
+                anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+              },
+              format: {
+                type: 'string',
+                enum: ['terse', 'debug'],
+                description: 'Per-call output format (default: "terse").',
+              },
+            },
+            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,
+        },
+        format: {
+          type: 'string',
+          enum: ['terse', 'debug'],
+          description: 'Default output format for calls that do not specify one (default: "terse").',
+        },
+        validateOnly: {
+          type: 'boolean',
+          description: 'If true, validate and normalize calls without executing them.',
+        },
+        fields: {
+          description:
+            'Default field selection for calls that do not specify one. Accepts a string[] or comma-separated string.',
+          anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+        },
+      },
+      required: ['calls'],
+    },
+  }
+
+  return [...toolNames, ...customTools, batchTool]
+}
+
+const normalizeToolCallName = (prefix: string | undefined, toolName: string): string =>
+  prefix ? toolName.replace(new RegExp(`^${prefix}\\.`), '') : toolName
+
+const invokeTool = async (
+  tool: ToolDefinition,
+  payload: unknown,
+): Promise<GitServiceApiExecutionResult> => {
+  const { args, options } = normalizePayload(payload)
+  const cleanedOptions = stripMcpOnlyOptions(options)
+  const invocationArgs: unknown[] = args
+
+  if (Object.keys(cleanedOptions).length > 0) {
+    invocationArgs.push(cleanedOptions)
+  }
+
+  return tool.method(...invocationArgs)
+}
+
+const pickArgsFromNormalizedPayload = (normalized: unknown, record: Record<string, unknown>): unknown[] => {
+  if (Array.isArray(normalized)) {
+    return normalized
+  }
+  return Array.isArray(record.args) ? record.args : []
+}
+
+const pickNestedRecord = (value: unknown): Record<string, unknown> => (isRecord(value) ? (value as Record<string, unknown>) : {})
+
+const normalizeQueryRecord = (query: unknown): Record<string, unknown> => {
+  if (isRecord(query)) {
+    return query
+  }
+
+  if (!Array.isArray(query)) {
+    return {}
+  }
+
+  const merged: Record<string, unknown> = {}
+
+  for (const entry of query) {
+    if (!isRecord(entry)) continue
+
+    const name = typeof entry.name === 'string' ? entry.name.trim() : ''
+    if (name) {
+      merged[name] = entry.value
+      continue
+    }
+
+    // Support [{ headSha: "..." }, { runNumber: 11 }] style arrays.
+    for (const [key, value] of Object.entries(entry)) {
+      if (value !== undefined) merged[key] = value
+    }
+  }
+
+  return merged
+}
+
+const invokeLogsForRunTailTool = async (tool: ToolDefinition, payload: unknown): Promise<GitServiceApiExecutionResult> => {
+  const normalized = normalizeArgumentPayload(payload)
+  const record = isRecord(normalized) ? normalized : {}
+  const args = pickArgsFromNormalizedPayload(normalized, record)
+  const options = normalizeNestedOptions(pickRecord(record.options))
+  const query = normalizeQueryRecord(options.query)
+  const data = pickNestedRecord(options.data)
+
+  const headShaNamed = toTrimmedString(
+    pickFirst(
+      record.headSha,
+      record.head_sha,
+      options.headSha,
+      options.head_sha,
+      query.headSha,
+      query.head_sha,
+      data.headSha,
+      data.head_sha,
+    ),
+  )
+  const runNumberNamed = pickFirst(
+    toPositiveInteger(pickFirst(record.runNumber, record.run_number, options.runNumber, options.run_number)),
+    toPositiveInteger(pickFirst(query.runNumber, query.run_number, data.runNumber, data.run_number)),
+    null,
+  )
+
+  // Positional preferred legacy: [headSha, runNumber]
+  const headShaPositional = args.length >= 1 ? toTrimmedString(args[0]) : ''
+  const runNumberPositional = args.length >= 2 ? toPositiveInteger(args[1]) : null
+
+  // Legacy-mistake support: args=[owner, repo], options has headSha/runNumber.
+  const shouldTreatArgsAsOwnerRepo =
+    args.length >= 2 &&
+    (!headShaPositional || !runNumberPositional) &&
+    Boolean(headShaNamed) &&
+    Boolean(runNumberNamed)
+
+  const ownerFromArgs = shouldTreatArgsAsOwnerRepo ? toTrimmedString(args[0]) : ''
+  const repoFromArgs = shouldTreatArgsAsOwnerRepo ? toTrimmedString(args[1]) : ''
+
+  const owner =
+    toTrimmedString(pickFirst(record.owner, options.owner, query.owner, data.owner, ownerFromArgs)) || undefined
+  const repo = toTrimmedString(pickFirst(record.repo, options.repo, query.repo, data.repo, repoFromArgs)) || undefined
+
+  const sha = toTrimmedString(pickFirst(headShaNamed || null, headShaPositional || null)) || ''
+  const run = pickFirst(runNumberNamed, runNumberPositional) ?? null
+
+  if (!sha || !run) {
+    throw new Error(
+      'headSha (string) and runNumber (positive integer) are required. Preferred invocation: { owner, repo, headSha, runNumber, maxLines }. (Compatibility: options.query.{headSha,runNumber} is also accepted.)',
+    )
+  }
+
+  const containsFromQuery = typeof query.contains === 'string' ? query.contains : undefined
+  const maxLinesFromQuery = toPositiveInteger(query.maxLines)
+  const maxBytesFromQuery = toPositiveInteger(query.maxBytes)
+
+  const cleanedOptions = stripMcpOnlyOptions({
+    ...options,
+    ...(containsFromQuery ? { contains: containsFromQuery } : {}),
+    ...(maxLinesFromQuery ? { maxLines: maxLinesFromQuery } : {}),
+    ...(maxBytesFromQuery ? { maxBytes: maxBytesFromQuery } : {}),
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+  })
+
+  return tool.method(sha, run, cleanedOptions)
+}
+
+const invokeArtifactsByRunTool = async (
+  tool: ToolDefinition,
+  payload: unknown,
+): Promise<GitServiceApiExecutionResult> => {
+  const normalized = normalizeArgumentPayload(payload)
+  const record = isRecord(normalized) ? normalized : {}
+  const args = pickArgsFromNormalizedPayload(normalized, record)
+  const options = normalizeNestedOptions(pickRecord(record.options))
+
+  const runIdNamed = toTrimmedString(pickFirst(record.runId, record.run_id, options.runId, options.run_id)) || ''
+
+  const a0 = args.length >= 1 ? toTrimmedString(args[0]) : ''
+  const a1 = args.length >= 2 ? toTrimmedString(args[1]) : ''
+  const a2 = args.length >= 3 ? toTrimmedString(args[2]) : ''
+
+  // Heuristic:
+  // - If named runId is set, use it.
+  // - Else if args look like [owner, repo, runId], use that.
+  // - Else treat args as legacy [runId, owner, repo] (or [runId] with defaults).
+  const shouldTreatAsOwnerRepoRunId = Boolean(a0) && Boolean(a1) && Boolean(a2) && !runIdNamed
+
+  const owner =
+    toTrimmedString(pickFirst(record.owner, options.owner, shouldTreatAsOwnerRepoRunId ? a0 : a1)) || undefined
+  const repo =
+    toTrimmedString(pickFirst(record.repo, options.repo, shouldTreatAsOwnerRepoRunId ? a1 : a2)) || undefined
+  const runId = toTrimmedString(pickFirst(runIdNamed || null, shouldTreatAsOwnerRepoRunId ? a2 : a0)) || ''
+
+  if (!runId) {
+    throw new Error('runId is required. Preferred invocation: { owner, repo, runId }.')
+  }
+
+  const cleanedOptions = stripMcpOnlyOptions({
+    ...options,
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+  })
+
+  // Underlying helper signature is (runId, owner?, repo?, options?).
+  // We always pass runId first, and owner/repo if we have them.
+  if (owner && repo) {
+    return tool.method(runId, owner, repo, cleanedOptions)
+  }
+
+  if (owner && !repo) {
+    // Unusual: allow passing only owner explicitly.
+    return tool.method(runId, owner, cleanedOptions)
+  }
+
+  return tool.method(runId, cleanedOptions)
+}
+
+export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpServerInstance => {
+  const api = createGitServiceApi(options)
+  const tools = collectGitTools(api)
+  const prefix = options.toolsPrefix
+  const batchToolName = prefix ? `${prefix}.batch` : 'batch'
+  const contextSetToolName = prefix ? `${prefix}.context.set` : 'context.set'
+  const contextGetToolName = prefix ? `${prefix}.context.get` : 'context.get'
+  const searchToolsToolName = prefix ? `${prefix}.searchTools` : 'searchTools'
+  const prPreflightToolName = prefix ? `${prefix}.pr.preflight` : 'pr.preflight'
+  const prMergeAndVerifyToolName = prefix ? `${prefix}.pr.mergeAndVerify` : 'pr.mergeAndVerify'
+
+  const context: { owner?: string; repo?: string } = {
+    owner: toTrimmedString(options.defaultOwner) || undefined,
+    repo: toTrimmedString(options.defaultRepo) || undefined,
+  }
+
+  const resolveOwnerRepo = (options: Record<string, unknown>): { owner?: string; repo?: string } => {
+    const owner = toTrimmedString(pickFirst(options.owner, context.owner)) || undefined
+    const repo = toTrimmedString(pickFirst(options.repo, context.repo)) || undefined
+    return { owner, repo }
+  }
+
+  const resolvePrNumber = (args: string[], options: Record<string, unknown>): string => {
+    const fromArgs = args.length >= 1 ? toTrimmedString(args[0]) : ''
+    const fromNamed = toTrimmedString(pickFirst(options.number, (options as Record<string, unknown>).prNumber, options.index))
+    return fromArgs || fromNamed
+  }
+
+  const normalizePayloadWithContext = (
+    tool: ToolDefinition,
+    payload: unknown,
+  ): { args: string[]; options: Record<string, unknown> } => {
+    const normalized = normalizePayload(payload)
+    const optionsWithDefaults = { ...normalized.options }
+    const { owner, repo } = resolveOwnerRepo(optionsWithDefaults)
+    if (owner && optionsWithDefaults.owner === undefined) optionsWithDefaults.owner = owner
+    if (repo && optionsWithDefaults.repo === undefined) optionsWithDefaults.repo = repo
+
+    // LLM-friendly: allow { number: 123 } instead of args:[\"123\"] for PR tools.
+    const args = [...normalized.args]
+    if (args.length === 0 && tool.name.includes('.pr.') && tool.name.startsWith('repo.')) {
+      const number = resolvePrNumber(args, optionsWithDefaults)
+      if (number) {
+        args.push(number)
+      }
+    }
+
+    return {
+      args,
+      options: optionsWithDefaults,
+    }
+  }
+
+  const customTools: McpToolListEntry[] = [
+    {
+      name: contextSetToolName,
+      description: 'Set default {owner, repo} for subsequent git tool calls in this session.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          owner: { type: 'string', description: 'Default repository owner/org' },
+          repo: { type: 'string', description: 'Default repository name' },
+          args: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Legacy positional form: [owner, repo]',
+          },
+          format: {
+            type: 'string',
+            enum: ['terse', 'debug'],
+            description: 'Output format. Default: "terse".',
+          },
+        },
+      },
+    },
+    {
+      name: contextGetToolName,
+      description: 'Get the current default {owner, repo} for this session.',
+      inputSchema: { type: 'object', additionalProperties: true, properties: {} },
+    },
+    {
+      name: searchToolsToolName,
+      description: 'Search available git MCP tools by substring (returns names + descriptions).',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          query: { type: 'string', description: 'Search query (substring match on tool name/path)' },
+          limit: { type: 'integer', minimum: 1, description: 'Max matches to return (default: 20)' },
+          format: { type: 'string', enum: ['terse', 'debug'] },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: prPreflightToolName,
+      description: 'Fetch PR metadata + checks + review artifacts in one call.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          owner: { type: 'string', description: 'Repository owner/org (optional if context/defaults set)' },
+          repo: { type: 'string', description: 'Repository name (optional if context/defaults set)' },
+          number: { anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }], description: 'PR number' },
+          includeIssues: { type: 'boolean', description: 'If true, fetch referenced issues mentioned as "Fixes #123".' },
+          validateOnly: { type: 'boolean', description: 'Validate and normalize without executing HTTP calls.' },
+          fields: {
+            description: 'Optional field selection applied to pr/checks/review bodies.',
+            anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+          },
+          format: { type: 'string', enum: ['terse', 'debug'] },
+        },
+        anyOf: [{ required: ['number'] }, { required: ['args'] }],
+      },
+    },
+    {
+      name: prMergeAndVerifyToolName,
+      description: 'Merge a PR via hosting API and verify PR state transitions to merged/closed.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          owner: { type: 'string', description: 'Repository owner/org (optional if context/defaults set)' },
+          repo: { type: 'string', description: 'Repository name (optional if context/defaults set)' },
+          number: { anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }], description: 'PR number' },
+          mergeMethod: { type: 'string', description: 'Merge method. Maps to Gitea merge Do field (default: "merge").' },
+          maxAttempts: { type: 'integer', minimum: 1, description: 'Max poll attempts (default: 6)' },
+          delayMs: { type: 'integer', minimum: 0, description: 'Delay between polls in ms (default: 1000)' },
+          validateOnly: { type: 'boolean', description: 'Validate and normalize without executing HTTP calls.' },
+          format: { type: 'string', enum: ['terse', 'debug'] },
+        },
+        anyOf: [{ required: ['number'] }, { required: ['args'] }],
+      },
+    },
+  ]
+
+  const customToolMetaByName = new Map<string, McpToolListEntry>(customTools.map((tool) => [tool.name, tool]))
+
+  const sleep = async (ms: number): Promise<void> => {
+    if (ms <= 0) return
+    await new Promise<void>((resolve) => setTimeout(resolve, ms))
+  }
+
+  const toOk = (data: unknown, format: McpToolOutputFormat, debug?: unknown, status: number = 0): McpTerseOk => {
+    const envelope: McpTerseOk = {
+      ok: true,
+      data,
+      meta: {
+        status,
+      },
+      ...(format === 'debug' && debug !== undefined ? { debug } : {}),
+    }
+
+    return redactSecretsForMcpOutput(envelope) as McpTerseOk
+  }
+
+  const toErr = (error: McpTerseErr, format: McpToolOutputFormat, debug?: unknown): McpTerseErr => {
+    const enriched: McpTerseErr = {
+      ...error,
+      ...(format === 'debug' && debug !== undefined ? { debug } : {}),
+    }
+    return redactSecretsForMcpOutput(enriched) as McpTerseErr
+  }
+
+  const invokeCustomTool = async (
+    toolName: string,
+    payload: unknown,
+    controls: { format: McpToolOutputFormat | null; validateOnly: boolean; fields: McpFieldSelection | null },
+  ): Promise<{ isError: boolean; envelope: McpTerseOk | McpTerseErr }> => {
+    const format = controls.format ?? 'terse'
+
+    if (toolName === contextGetToolName) {
+      return { isError: false, envelope: toOk({ owner: context.owner ?? null, repo: context.repo ?? null }, format) }
+    }
+
+    if (toolName === contextSetToolName) {
+      const normalized = normalizePayload(payload)
+      const ownerFromArgs = normalized.args.length >= 1 ? toTrimmedString(normalized.args[0]) : ''
+      const repoFromArgs = normalized.args.length >= 2 ? toTrimmedString(normalized.args[1]) : ''
+
+      const owner = toTrimmedString(pickFirst(normalized.options.owner, ownerFromArgs)) || ''
+      const repo = toTrimmedString(pickFirst(normalized.options.repo, repoFromArgs)) || ''
+
+      context.owner = owner || undefined
+      context.repo = repo || undefined
+
+      return { isError: false, envelope: toOk({ owner: context.owner ?? null, repo: context.repo ?? null }, format) }
+    }
+
+    if (toolName === searchToolsToolName) {
+      const normalized = normalizePayload(payload)
+      const query = toTrimmedString(pickFirst(normalized.options.query, normalized.args[0])) || ''
+      if (!query) {
+        return {
+          isError: true,
+          envelope: toErr(
+            {
+              ok: false,
+              error: {
+                code: 'INVALID_INPUT',
+                message: 'query is required. Example: { query: \"pr.merge\" }',
+                retryable: false,
+              },
+            },
+            format,
+          ),
+        }
+      }
+
+      const limitRaw = pickFirst(normalized.options.limit, normalized.args[1])
+      const limit = toPositiveInteger(limitRaw) ?? 20
+
+      const haystack = [
+        ...toolByName.keys(),
+        ...customTools.map((tool) => tool.name),
+        batchToolName,
+      ]
+      const q = query.toLowerCase()
+      const matches = haystack
+        .filter((name) => name.toLowerCase().includes(q))
+        .slice(0, limit)
+        .map((name) => {
+          const meta =
+            toolByName.has(name)
+              ? { name, description: `Call git API method ${toolByName.get(name)?.path.join('.') ?? name}` }
+              : customToolMetaByName.get(name) ?? (name === batchToolName ? { name, description: 'Batch tool' } : { name, description: '' })
+          return meta
+        })
+
+      return { isError: false, envelope: toOk({ matches }, format) }
+    }
+
+    if (toolName === prPreflightToolName) {
+      const normalized = normalizePayload(payload)
+      const optionsWithDefaults = { ...normalized.options }
+      const { owner, repo } = resolveOwnerRepo(optionsWithDefaults)
+      if (owner) optionsWithDefaults.owner = owner
+      if (repo) optionsWithDefaults.repo = repo
+
+      const number = resolvePrNumber(normalized.args, optionsWithDefaults)
+      if (!number) {
+        return {
+          isError: true,
+          envelope: toErr(
+            {
+              ok: false,
+              error: {
+                code: 'INVALID_INPUT',
+                message: 'number is required. Example: { owner, repo, number: 766 } (or { args:[\"766\"], owner, repo }).',
+                retryable: false,
+              },
+            },
+            format,
+          ),
+        }
+      }
+
+      const includeIssues = Boolean((optionsWithDefaults as Record<string, unknown>).includeIssues)
+
+      if (controls.validateOnly) {
+        const toolPrefix = prefix ? `${prefix}.` : ''
+        return {
+          isError: false,
+          envelope: toOk(
+            {
+              valid: true,
+              owner: owner ?? null,
+              repo: repo ?? null,
+              number,
+              calls: [
+                { tool: `${toolPrefix}repo.pr.view`, args: [number], options: { owner, repo } },
+                { tool: `${toolPrefix}repo.pr.checks`, args: [number], options: { owner, repo } },
+                { tool: `${toolPrefix}repo.pr.review`, args: [number], options: { owner, repo, method: 'GET' } },
+              ],
+              includeIssues,
+            },
+            format,
+          ),
+        }
+      }
+
+      const callOptionsBase = stripMcpOnlyOptions(optionsWithDefaults)
+      const callOptions: Record<string, unknown> = { ...callOptionsBase }
+      delete (callOptions as any).includeIssues
+      delete (callOptions as any).number
+      delete (callOptions as any).prNumber
+      delete (callOptions as any).index
+
+      const pr = await (api as any).repo.pr.view(number, callOptions)
+      const checks = await (api as any).repo.pr.checks(number, callOptions)
+      const review = await (api as any).repo.pr.review(number, { ...callOptions, method: 'GET' })
+
+      const referencedIssueNumbers: number[] = []
+      if (isRecord(pr.body) && typeof (pr.body as any).body === 'string') {
+        const body = String((pr.body as any).body)
+        const matches = body.matchAll(/\b(?:fixes|closes|resolves)\s+#(\d+)\b/gi)
+        for (const match of matches) {
+          const n = Number(match[1])
+          if (Number.isFinite(n) && n > 0) referencedIssueNumbers.push(n)
+        }
+      }
+
+      const uniqueReferenced = Array.from(new Set(referencedIssueNumbers))
+      const issues: unknown[] = []
+      if (includeIssues && uniqueReferenced.length > 0) {
+        for (const n of uniqueReferenced) {
+          try {
+            const issue = await (api as any).repo.issue.view(String(n), callOptions)
+            issues.push(issue.body)
+          } catch {
+            // best effort
+          }
+        }
+      }
+
+      const data = {
+        pr: applyFieldSelection(pr.body, controls.fields),
+        checks: applyFieldSelection(checks.body, controls.fields),
+        review: applyFieldSelection(review.body, controls.fields),
+        referencedIssueNumbers: uniqueReferenced,
+        ...(includeIssues ? { issues } : {}),
+      }
+
+      const allOk = pr.ok && checks.ok && review.ok
+      if (!allOk) {
+        return {
+          isError: true,
+          envelope: toErr(
+            {
+              ok: false,
+              error: {
+                code: 'PREFLIGHT_FAILED',
+                message: 'One or more preflight calls failed. See details.',
+                details: {
+                  pr: { ok: pr.ok, status: pr.status },
+                  checks: { ok: checks.ok, status: checks.status },
+                  review: { ok: review.ok, status: review.status },
+                },
+                retryable: false,
+              },
+            },
+            format,
+            { pr, checks, review },
+          ),
+        }
+      }
+
+      return { isError: false, envelope: toOk(data, format, { pr, checks, review }, 200) }
+    }
+
+    if (toolName === prMergeAndVerifyToolName) {
+      const normalized = normalizePayload(payload)
+      const optionsWithDefaults = { ...normalized.options }
+      const { owner, repo } = resolveOwnerRepo(optionsWithDefaults)
+      if (owner) optionsWithDefaults.owner = owner
+      if (repo) optionsWithDefaults.repo = repo
+
+      const number = resolvePrNumber(normalized.args, optionsWithDefaults)
+      if (!number) {
+        return {
+          isError: true,
+          envelope: toErr(
+            {
+              ok: false,
+              error: {
+                code: 'INVALID_INPUT',
+                message: 'number is required. Example: { owner, repo, number: 766 }',
+                retryable: false,
+              },
+            },
+            format,
+          ),
+        }
+      }
+
+      const maxAttempts = toPositiveInteger((optionsWithDefaults as Record<string, unknown>).maxAttempts) ?? 6
+      const delayMs = toNonNegativeInteger((optionsWithDefaults as Record<string, unknown>).delayMs) ?? 1000
+      const mergeMethod = toTrimmedString((optionsWithDefaults as Record<string, unknown>).mergeMethod) || 'merge'
+
+      if (controls.validateOnly) {
+        return {
+          isError: false,
+          envelope: toOk(
+            {
+              valid: true,
+              owner: owner ?? null,
+              repo: repo ?? null,
+              number,
+              mergeMethod,
+              maxAttempts,
+              delayMs,
+            },
+            format,
+          ),
+        }
+      }
+
+      const callOptionsBase = stripMcpOnlyOptions(optionsWithDefaults)
+      const callOptions: Record<string, unknown> = { ...callOptionsBase }
+      delete (callOptions as any).maxAttempts
+      delete (callOptions as any).delayMs
+      delete (callOptions as any).number
+      delete (callOptions as any).prNumber
+      delete (callOptions as any).index
+      delete (callOptions as any).mergeMethod
+
+      let mergeResult: GitServiceApiExecutionResult | null = null
+      let lastMergeError: unknown = null
+
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        mergeResult = await (api as any).repo.pr.merge(number, { ...callOptions, mergeMethod })
+        if (mergeResult.ok && mergeResult.status < 400) {
+          break
+        }
+
+        lastMergeError = mergeResult.body
+        const message = buildErrorMessage(mergeResult.status, mergeResult.body)
+        if (!/try again later/i.test(message) && mergeResult.status !== 429 && mergeResult.status < 500) {
+          break
+        }
+
+        await sleep(delayMs)
+      }
+
+      if (!mergeResult || !mergeResult.ok || mergeResult.status >= 400) {
+        return {
+          isError: true,
+          envelope: toErr(
+            {
+              ok: false,
+              error: {
+                code: 'MERGE_FAILED',
+                status: mergeResult?.status,
+                message: buildErrorMessage(mergeResult?.status, mergeResult?.body ?? lastMergeError),
+                details: mergeResult?.body ?? lastMergeError,
+                retryable: true,
+              },
+              meta: mergeResult?.status ? { status: mergeResult.status } : undefined,
+            },
+            format,
+            { mergeResult },
+          ),
+        }
+      }
+
+      const views: GitServiceApiExecutionResult[] = []
+      let prAfter: GitServiceApiExecutionResult | null = null
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        prAfter = await (api as any).repo.pr.view(number, callOptions)
+        views.push(prAfter)
+
+        const merged = isRecord(prAfter.body) ? Boolean((prAfter.body as any).merged) : false
+        const state = isRecord(prAfter.body) && typeof (prAfter.body as any).state === 'string' ? String((prAfter.body as any).state) : ''
+        if (merged || state.toLowerCase() === 'closed') {
+          break
+        }
+
+        await sleep(delayMs)
+      }
+
+      const data = {
+        merge: mergeResult.body,
+        pr: prAfter ? prAfter.body : null,
+        polled: views.length,
+      }
+
+      const merged = prAfter && isRecord(prAfter.body) ? Boolean((prAfter.body as any).merged) : false
+      const state = prAfter && isRecord(prAfter.body) && typeof (prAfter.body as any).state === 'string' ? String((prAfter.body as any).state) : ''
+
+      if (!merged && state.toLowerCase() !== 'closed') {
+        return {
+          isError: true,
+          envelope: toErr(
+            {
+              ok: false,
+              error: {
+                code: 'MERGE_VERIFY_FAILED',
+                message: 'Merge request succeeded, but PR state did not transition to merged/closed within polling window.',
+                details: { merged, state },
+                retryable: true,
+              },
+            },
+            format,
+            { mergeResult, prAfter, views },
+          ),
+        }
+      }
+
+      return { isError: false, envelope: toOk(data, format, { mergeResult, prAfter, views }, 200) }
+    }
+
+    return {
+      isError: true,
+      envelope: toErr(
+        {
+          ok: false,
+          error: { code: 'UNKNOWN_TOOL', message: `Unknown tool: ${toolName}`, retryable: false },
+        },
+        format,
+      ),
+    }
+  }
+
+  const server = new Server(
+    {
+      name: options.serverName ?? 'git',
+      version: options.serverVersion ?? '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  )
+
+  const toolByName = new Map<string, ToolDefinition>(tools.map((tool) => [buildToolName(tool, prefix), tool]))
+
+  const listTools = (): McpToolListEntry[] => buildToolList(tools, batchToolName, prefix, customTools)
+
+  const callTool = async (requestedName: string, payload: unknown): Promise<{ isError: boolean; text: string }> => {
+    if (customToolMetaByName.has(requestedName)) {
+      const controls = extractMcpControls(payload)
+      const { isError, envelope } = await invokeCustomTool(requestedName, payload, controls)
+      return { isError, text: JSON.stringify(envelope) }
+    }
+
+    if (requestedName === batchToolName) {
+      const { calls, continueOnError } = normalizeBatchPayload(payload)
+      const batchControls = extractMcpControls(payload)
+
+      const executions = calls.map(({ tool, args = [], options = {} }, index) => ({ tool, args, options, index }))
+      const results = await Promise.all(
+        executions.map(async ({ tool, args, options, index }) => {
+          if (customToolMetaByName.has(tool)) {
+            const mergedPayload = { args, options }
+            const callControls = extractMcpControls(mergedPayload)
+            const effectiveControls = {
+              ...callControls,
+              format: callControls.format ?? batchControls.format ?? null,
+              fields: callControls.fields ?? batchControls.fields ?? null,
+              validateOnly: callControls.validateOnly || batchControls.validateOnly,
+            }
+
+            try {
+              const { isError, envelope } = await invokeCustomTool(tool, mergedPayload, effectiveControls)
+              return {
+                index,
+                tool,
+                isError,
+                ...(envelope as McpTerseOk | McpTerseErr),
+              } as BatchResult
+            } catch (error) {
+              if (continueOnError) {
+                return {
+                  index,
+                  tool,
+                  isError: true,
+                  ...(toMcpThrownErrorEnvelope(error) as McpTerseErr),
+                } as BatchResult
+              }
+              throw error
+            }
+          }
+
+          const toolDefinition = toolByName.get(tool)
+          if (!toolDefinition) {
+            return {
+              index,
+              tool,
+              isError: true,
+              ...({
+                ok: false,
+                error: {
+                  code: 'UNKNOWN_TOOL',
+                  message: `Unknown tool: ${tool}`,
+                  retryable: false,
+                },
+              } satisfies McpTerseErr),
+            } as BatchResult
+          }
+
+          try {
+            const mergedPayload = { args, options }
+            const callControls = extractMcpControls(mergedPayload)
+            const effectiveFormat = callControls.format ?? batchControls.format ?? 'terse'
+            const effectiveFields = callControls.fields ?? batchControls.fields ?? null
+            const validateOnly = callControls.validateOnly || batchControls.validateOnly
+
+            if (validateOnly) {
+              const normalized = normalizePayloadWithContext(toolDefinition, mergedPayload)
+              const envelope: McpTerseOk = {
+                ok: true,
+                data: {
+                  valid: true,
+                  tool,
+                  args: normalized.args,
+                  options: stripMcpOnlyOptions(normalized.options),
+                },
+                meta: {
+                  status: 0,
+                },
+              }
+
+              return {
+                index,
+                tool,
+                isError: false,
+                ...(redactSecretsForMcpOutput(envelope) as McpTerseOk),
+              } as BatchResult
+            }
+
+            const normalized = normalizePayloadWithContext(toolDefinition, mergedPayload)
+            const normalizedPayload = { args: normalized.args, options: normalized.options }
+
+            const data = await (isLogsForRunTailTool(toolDefinition.name)
+              ? invokeLogsForRunTailTool(toolDefinition, normalizedPayload)
+              : isArtifactsByRunTool(toolDefinition.name)
+                ? invokeArtifactsByRunTool(toolDefinition, normalizedPayload)
+              : invokeTool(toolDefinition, normalizedPayload))
+
+            const selected = effectiveFields ? { ...data, body: applyFieldSelection(data.body, effectiveFields) } : data
+            const { isError, envelope } = toMcpEnvelope(selected, effectiveFormat)
+            return {
+              index,
+              tool,
+              isError,
+              ...(envelope as McpTerseOk | McpTerseErr),
+            } as BatchResult
+          } catch (error) {
+            if (continueOnError) {
+              return {
+                index,
+                tool,
+                isError: true,
+                ...(toMcpThrownErrorEnvelope(error) as McpTerseErr),
+              } as BatchResult
+            }
+            throw error
+          }
+        }),
+      )
+
+      return {
+        isError: results.some((result) => result.isError),
+        text: JSON.stringify(redactSecretsForMcpOutput(results)),
+      }
+    }
+
+    const tool = toolByName.get(requestedName)
+    if (!tool) {
+      throw new Error(`Unknown tool: ${requestedName}`)
+    }
+
+    const controls = extractMcpControls(payload)
+
+    if (controls.validateOnly) {
+      const normalized = normalizePayloadWithContext(tool, payload)
+      const envelope: McpTerseOk = {
+        ok: true,
+        data: {
+          valid: true,
+          tool: requestedName,
+          args: normalized.args,
+          options: stripMcpOnlyOptions(normalized.options),
+        },
+        meta: {
+          status: 0,
+        },
+      }
+
+      return { isError: false, text: JSON.stringify(redactSecretsForMcpOutput(envelope)) }
+    }
+
+    const normalized = normalizePayloadWithContext(tool, payload)
+    const normalizedPayload = { args: normalized.args, options: normalized.options }
+
+    const result = await (isLogsForRunTailTool(tool.name)
+      ? invokeLogsForRunTailTool(tool, normalizedPayload)
+      : isArtifactsByRunTool(tool.name)
+        ? invokeArtifactsByRunTool(tool, normalizedPayload)
+      : invokeTool(tool, normalizedPayload))
+
+    const selected = controls.fields ? { ...result, body: applyFieldSelection(result.body, controls.fields) } : result
+    const { isError, envelope } = toMcpEnvelope(selected, controls.format ?? 'terse')
+    return { isError, text: JSON.stringify(envelope) }
+  }
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: listTools(),
+  }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+      const result = await callTool(request.params.name, request.params.arguments)
+      return {
+        ...(result.isError ? { isError: true } : {}),
+        content: [
+          {
+            type: 'text',
+            text: result.text,
+          },
+        ],
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith('Unknown tool:')) {
+        throw error
+      }
+
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(toMcpThrownErrorEnvelope(error)),
+          },
+        ],
+      }
+    }
+  })
+
+  const run = async (): Promise<Server> => {
+    await server.connect(new StdioServerTransport())
+    return server
+  }
+
+  return { api, tools, server, listTools, callTool, run }
+}
+
+export const runGitMcpServer = async (options: GitMcpServerOptions = {}): Promise<Server> => {
+  const instance = createGitMcpServer(options)
+  return instance.run()
+}
+
+export const normalizeToolCallNameForServer = (
+  prefix: string | undefined,
+  toolName: string,
+): string => normalizeToolCallName(prefix, toolName)