@foundation0/git 1.2.4 → 1.3.0

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`):
@@ -211,6 +231,36 @@ Tips:
   `repo.label.listManaged`, `repo.label.getByName`, `repo.label.upsert`, and `repo.label.deleteByName`
 - Includes Gitea Actions convenience tools exposed from the API object (best-effort helpers):
   `repo.actions.tasks.list`, `repo.actions.jobs.logs`, `repo.actions.jobs.logsTail`, `repo.actions.jobs.logsForRunTail`,
-  and `repo.actions.artifacts.downloadZipUrl`
+  `repo.actions.diagnoseLatestFailure`, 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
+}
+```
+
+## Notes: actions.diagnoseLatestFailure
+
+`repo.actions.diagnoseLatestFailure` is a convenience tool that finds the most recent failing Actions task and returns a log tail.
+
+```json
+{ "owner": "F0", "repo": "adl", "workflowName": "TypeScript", "maxLines": 250 }
+```
+
+## Notes: actions.runs.artifacts
+
+`repo.actions.runs.artifacts` accepts a named form to avoid legacy positional ordering:
+
+```json
+{ "owner": "F0", "repo": "adl", "runId": 11 }
+```

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,
     }