@foundation0/git 1.2.4 → 1.2.5

package/mcp/README.md

@@ -12,6 +12,20 @@ Each tool is addressed by the full API path (`repo.issue.create`, `search.issues
 - `args`: array of positional string arguments
 - `options`: object for request body/query/header customisation
 
+Tool results are returned as a compact envelope by default:
+
+```json
+{ "ok": true, "data": { "...": "..." }, "meta": { "status": 200 } }
+```
+
+If the upstream git API returns `{ ok: false }` or an HTTP status `>= 400`, the MCP tool call is marked as an error (`isError: true`) and a typed error envelope is returned:
+
+```json
+{ "ok": false, "error": { "code": "HTTP_NOT_FOUND", "status": 404, "message": "HTTP 404", "retryable": false }, "meta": { "status": 404 } }
+```
+
+To include the full debug payload (mapping/request/response headers), pass `format: "debug"` (either top-level or in `options`).
+
 Use the `batch` tool to run multiple calls in one request. It is the preferred mode when you want to issue multiple MCP calls because it executes them in parallel and returns a combined response.
 
 Batch payload format:
@@ -111,6 +125,12 @@ await client.call('repo.issue.create', {
 })
 ```
 
+To return a debug payload for a specific call:
+
+```ts
+await client.call('repo.issue.list', { format: 'debug' })
+```
+
 ## Using with MCP-compatible agents
 
 Create a small server entry file for your agent (for example `packages/git/mcp/server-entry.ts`):
@@ -214,3 +234,17 @@ Tips:
   and `repo.actions.artifacts.downloadZipUrl`
 - Includes a discovery helper:
   `help.actionsLogs` (also available under `repo.help.actionsLogs`)
+
+## Notes: jobs.logsForRunTail
+
+`repo.actions.jobs.logsForRunTail` (and the `help.*` variants) expect a `headSha` and a `runNumber`. Prefer the named form to avoid positional confusion:
+
+```json
+{
+  "owner": "F0",
+  "repo": "adl",
+  "headSha": "6dd4062ec271277e7e83ac6864fec9208559564c",
+  "runNumber": 11,
+  "maxLines": 250
+}
+```

package/mcp/src/client.ts

@@ -12,6 +12,9 @@ type ToolResult = {
   content?: ToolResultText[]
 }
 
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
 const toText = (result: ToolResult | null): string => {
   if (!result || !result.content || result.content.length === 0) {
     return ''
@@ -116,8 +119,14 @@ export class GitMcpClient {
 
     const text = toText(response as ToolResult)
     const parsed = tryParseResult(text)
+
+    // Back-compat: if a server returns an { ok:false } envelope but forgets to mark MCP isError,
+    // treat it as an error on the client side as well.
+    const parsedIsError =
+      isRecord(parsed.parsed) && typeof parsed.parsed.ok === 'boolean' ? parsed.parsed.ok === false : false
+
     return {
-      isError: Boolean(response.isError),
+      isError: Boolean(response.isError) || parsedIsError,
       text: parsed.text,
       data: parsed.parsed,
     }

package/mcp/src/server.ts

@@ -16,6 +16,8 @@ type ToolInvocationPayload = {
   [key: string]: unknown
 }
 
+type McpToolOutputFormat = 'terse' | 'debug'
+
 type BatchToolCall = {
   tool: string
   args?: unknown[]
@@ -32,8 +34,7 @@ type BatchResult = {
   index: number
   tool: string
   isError: boolean
-  data: unknown
-}
+} & (McpTerseOk | McpTerseErr)
 
 type ToolDefinition = {
   name: string
@@ -44,21 +45,205 @@ type ToolDefinition = {
 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
+}
+
+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 >= 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 } : {}),
+  }
+
+  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> } => {
-  if (!isRecord(payload)) {
+  const normalized = normalizeArgumentPayload(payload)
+
+  if (normalized === null || normalized === undefined) {
     return {
       args: [],
       options: {},
     }
   }
 
-  const explicitArgs = Array.isArray(payload.args) ? payload.args : undefined
-  const explicitOptions = isRecord(payload.options) ? payload.options : undefined
+  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(payload)) {
+  for (const [key, value] of Object.entries(normalized)) {
     if (key === 'args' || key === 'options') {
       continue
     }
@@ -74,6 +259,17 @@ const normalizePayload = (payload: unknown): { args: string[]; options: Record<s
   }
 }
 
+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
+  }
+  return next
+}
+
 const normalizeBatchToolCall = (
   call: unknown,
   index: number,
@@ -107,22 +303,23 @@ const normalizeBatchToolCall = (
 }
 
 const normalizeBatchPayload = (payload: unknown): BatchToolCallPayload => {
-  if (!isRecord(payload)) {
+  const normalized = normalizeArgumentPayload(payload)
+  if (!isRecord(normalized)) {
     throw new Error('Batch tool call requires an object payload')
   }
 
-  if (!Array.isArray(payload.calls)) {
+  if (!Array.isArray(normalized.calls)) {
     throw new Error('Batch tool call requires a "calls" array')
   }
 
-  const calls = payload.calls.map((call, index) => normalizeBatchToolCall(call, index))
+  const calls = (normalized.calls as unknown[]).map((call, index) => normalizeBatchToolCall(call, index))
 
   return {
     calls: calls.map(({ tool, payload }) => ({
       tool,
       ...payload,
     })),
-    continueOnError: Boolean(payload.continueOnError),
+    continueOnError: Boolean((normalized as Record<string, unknown>).continueOnError),
   }
 }
 
@@ -165,26 +362,111 @@ export type GitMcpServerInstance = {
 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: {
-      type: 'object',
-      additionalProperties: true,
-      properties: {
-        args: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Positional path arguments for the git API method',
-        },
-        options: {
-          type: 'object',
-          additionalProperties: true,
-          description: 'Method options (for query, headers, payload/body/json/data)',
-        },
-      },
-    },
+    inputSchema: buildToolInputSchema(tool),
   }))
 
   const batchTool = {
@@ -216,6 +498,11 @@ const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?:
                 additionalProperties: true,
                 description: 'Tool invocation options',
               },
+              format: {
+                type: 'string',
+                enum: ['terse', 'debug'],
+                description: 'Per-call output format (default: "terse").',
+              },
             },
             required: ['tool'],
           },
@@ -226,6 +513,11 @@ const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?:
           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'],
     },
@@ -242,15 +534,63 @@ const invokeTool = async (
   payload: unknown,
 ): Promise<GitServiceApiExecutionResult> => {
   const { args, options } = normalizePayload(payload)
+  const cleanedOptions = stripMcpOnlyOptions(options)
   const invocationArgs: unknown[] = args
 
-  if (Object.keys(options).length > 0) {
-    invocationArgs.push(options)
+  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)
@@ -281,6 +621,8 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
     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 }) => {
@@ -290,17 +632,32 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
                 index,
                 tool,
                 isError: true,
-                data: `Unknown tool: ${tool}`,
+                ...({
+                  ok: false,
+                  error: {
+                    code: 'UNKNOWN_TOOL',
+                    message: `Unknown tool: ${tool}`,
+                    retryable: false,
+                  },
+                } satisfies McpTerseErr),
               } as BatchResult
             }
 
             try {
-              const data = await invokeTool(toolDefinition, { args, options })
+              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: false,
-                data: redactSecretsForMcpOutput(data),
+                isError,
+                ...(envelope as McpTerseOk | McpTerseErr),
               } as BatchResult
             } catch (error) {
               if (continueOnError) {
@@ -308,7 +665,7 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
                   index,
                   tool,
                   isError: true,
-                  data: redactSecretsInText(error instanceof Error ? error.message : String(error)),
+                  ...(toMcpThrownErrorEnvelope(error) as McpTerseErr),
                 } as BatchResult
               }
               throw error
@@ -321,7 +678,7 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
           content: [
             {
               type: 'text',
-              text: JSON.stringify(redactSecretsForMcpOutput(results), null, 2),
+              text: JSON.stringify(redactSecretsForMcpOutput(results)),
             },
           ],
         }
@@ -331,7 +688,7 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
           content: [
             {
               type: 'text',
-              text: redactSecretsInText(error instanceof Error ? error.message : String(error)),
+              text: JSON.stringify(toMcpThrownErrorEnvelope(error)),
             },
           ],
         }
@@ -345,13 +702,18 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
     }
 
     try {
-      const result = await invokeTool(tool, request.params.arguments)
-      const sanitized = redactSecretsForMcpOutput(result)
+      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(sanitized, null, 2),
+            text: JSON.stringify(envelope),
           },
         ],
       }
@@ -361,7 +723,7 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
         content: [
           {
             type: 'text',
-            text: redactSecretsInText(error instanceof Error ? error.message : String(error)),
+            text: JSON.stringify(toMcpThrownErrorEnvelope(error)),
           },
         ],
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundation0/git",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "Foundation 0 Git API and MCP server",
   "type": "module",
   "bin": {