@foundation0/git 1.2.5 → 1.3.1

package/mcp/README.md

@@ -1,250 +1,266 @@
-# mcp
-
-`@foundation0/git/mcp` exposes `@foundation0/git`'s `GitServiceApi` over an MCP server/client boundary.
-
-## Purpose
-
-- **Server**: exposes each leaf `gitServiceApi` method as an MCP tool.
-- **Client**: connects to the server with stdio and calls exposed tools.
-
-Each tool is addressed by the full API path (`repo.issue.create`, `search.issues`, etc.) and accepts:
-
-- `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:
-
-```json
-{
-  "calls": [
-    { "tool": "repo.issue.create", "options": { "data": { "title": "Bug report", "body": "Details" } } },
-    { "tool": "repo.contents.view", "args": ["README.md"] }
-  ],
-  "continueOnError": false
-}
-```
-
-## Install
-
-Global install:
-
-```bash
-pnpm add -g @foundation0/git
-```
-
-Run from npm without global install:
-
-```bash
-npx -y -p @foundation0/git f0-git-mcp --help
-```
-
-Using pnpm:
-
-```bash
-pnpm dlx @foundation0/git f0-git-mcp --help
-```
-
-From the monorepo root:
-
-```bash
-pnpm -C packages/git test
-```
-
-## Server
-
-```ts
-import { createGitMcpServer } from '@foundation0/git/mcp'
-
-const server = createGitMcpServer({
-  config: {
-    platform: 'GITEA',
-    giteaHost: 'https://gitea.example.com',
-    giteaToken: process.env.GITEA_TOKEN,
-  },
-  defaultOwner: 'example-org',
-  defaultRepo: 'example-repo',
-})
-
-await server.run()
-```
-
-To customize tool names:
-
-```ts
-createGitMcpServer({ toolsPrefix: 'git' })
-```
-
-This emits tools like `git.repo.issue.create`.
-
-## Client
-
-```ts
-import { GitMcpClient } from '@foundation0/git/mcp'
-
-const client = new GitMcpClient()
-await client.connect('node', ['path/to/mcp-server-entry.mjs'])
-
-const tools = await client.listTools()
-console.log(tools)
-
-const result = await client.callByPath('repo.issue.create', [
-], {
-  data: {
-    title: 'Bug report',
-    body: 'Details',
-  },
-})
-
-console.log(result.isError)
-console.log(result.text)
-```
-
-`callByPath` converts positional args and options for convenience. `call` can also be used with the raw tool arguments object:
-
-```ts
-await client.call('repo.issue.create', {
-  options: {
-    data: { title: 'Issue from MCP' },
-  },
-})
-```
-
-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`):
-
-```ts
-import { runGitMcpServer } from '@foundation0/git/mcp'
-
-await runGitMcpServer({
-  config: {
-    platform: 'GITEA',
-    giteaHost: process.env.GITEA_HOST ?? 'https://gitea.example.com',
-    giteaToken: process.env.GITEA_TOKEN,
-  },
-  defaultOwner: 'example-org',
-  defaultRepo: 'example-repo',
-  toolsPrefix: process.env.MCP_TOOLS_PREFIX ?? undefined,
-})
-```
-
-Then point any MCP client at this file with stdio transport.
-
-You can also invoke the packaged CLI directly:
-
-```bash
-f0-git-mcp --tools-prefix git
-```
-
-Claude Desktop:
-
-```json
-{
-  "mcpServers": {
-    "workspace-git": {
-      "command": "bun",
-          "args": ["run", "/abs/path/packages/git/mcp/server-entry.ts"],
-      "env": {
-        "GITEA_HOST": "https://gitea.example.com",
-        "GITEA_TOKEN": "YOUR_TOKEN",
-        "MCP_TOOLS_PREFIX": "git"
-      }
-    }
-  }
-}
-```
-
-Cursor:
-
-```json
-{
-  "mcpServers": {
-    "workspace-git": {
-      "command": "bun",
-          "args": ["run", "/abs/path/packages/git/mcp/server-entry.ts"],
-      "env": {
-        "GITEA_HOST": "https://gitea.example.com",
-        "GITEA_TOKEN": "YOUR_TOKEN"
-      }
-    }
-  }
-}
-```
-
-Windsurf / any MCP-compatible client using the same schema:
-
-```json
-{
-  "mcpServers": {
-    "workspace-git": {
-      "command": "bun",
-          "args": ["run", "/abs/path/packages/git/mcp/server-entry.ts"],
-      "env": {
-        "GITEA_HOST": "https://gitea.example.com",
-        "GITEA_TOKEN": "YOUR_TOKEN"
-      }
-    }
-  }
-}
-```
-
-Tips:
-
-- Use a tool-name prefix (for example `git`) to avoid collisions with other MCP servers.
-- For Node-only agents, transpile/bundle this package first and point `command` to the compiled JS entrypoint.
-
-## Security notes
-
-- Prefer `https://` for `GITEA_HOST` to avoid leaking `GITEA_TOKEN` over plaintext HTTP.
-- The CLI entrypoint in `packages/git/mcp/src/cli.ts` rejects `http://` hosts unless `--allow-insecure-http` is passed for local testing.
-- Set `GITEA_TOKEN` in the MCP process environment. The package does not auto-load `.env` files.
-
-## API surface
-
-- `createGitMcpServer(options)` / `runGitMcpServer(options)`
-- `GitMcpClient`
-- `createGitMcpClient(options)`
-- `normalizeToolCallNameForServer(prefix, toolName)`
-- Includes label-management tools exposed from the API object:
-  `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`
-- 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
-}
-```
+# mcp
+
+`@foundation0/git/mcp` exposes `@foundation0/git`'s `GitServiceApi` over an MCP server/client boundary.
+
+## Purpose
+
+- **Server**: exposes each leaf `gitServiceApi` method as an MCP tool.
+- **Client**: connects to the server with stdio and calls exposed tools.
+
+Each tool is addressed by the full API path (`repo.issue.create`, `search.issues`, etc.) and accepts:
+
+- `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:
+
+```json
+{
+  "calls": [
+    { "tool": "repo.issue.create", "options": { "data": { "title": "Bug report", "body": "Details" } } },
+    { "tool": "repo.contents.view", "args": ["README.md"] }
+  ],
+  "continueOnError": false
+}
+```
+
+## Install
+
+Global install:
+
+```bash
+pnpm add -g @foundation0/git
+```
+
+Run from npm without global install:
+
+```bash
+npx -y -p @foundation0/git f0-git-mcp --help
+```
+
+Using pnpm:
+
+```bash
+pnpm dlx @foundation0/git f0-git-mcp --help
+```
+
+From the monorepo root:
+
+```bash
+pnpm -C packages/git test
+```
+
+## Server
+
+```ts
+import { createGitMcpServer } from '@foundation0/git/mcp'
+
+const server = createGitMcpServer({
+  config: {
+    platform: 'GITEA',
+    giteaHost: 'https://gitea.example.com',
+    giteaToken: process.env.GITEA_TOKEN,
+  },
+  defaultOwner: 'example-org',
+  defaultRepo: 'example-repo',
+})
+
+await server.run()
+```
+
+To customize tool names:
+
+```ts
+createGitMcpServer({ toolsPrefix: 'git' })
+```
+
+This emits tools like `git.repo.issue.create`.
+
+## Client
+
+```ts
+import { GitMcpClient } from '@foundation0/git/mcp'
+
+const client = new GitMcpClient()
+await client.connect('node', ['path/to/mcp-server-entry.mjs'])
+
+const tools = await client.listTools()
+console.log(tools)
+
+const result = await client.callByPath('repo.issue.create', [
+], {
+  data: {
+    title: 'Bug report',
+    body: 'Details',
+  },
+})
+
+console.log(result.isError)
+console.log(result.text)
+```
+
+`callByPath` converts positional args and options for convenience. `call` can also be used with the raw tool arguments object:
+
+```ts
+await client.call('repo.issue.create', {
+  options: {
+    data: { title: 'Issue from MCP' },
+  },
+})
+```
+
+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`):
+
+```ts
+import { runGitMcpServer } from '@foundation0/git/mcp'
+
+await runGitMcpServer({
+  config: {
+    platform: 'GITEA',
+    giteaHost: process.env.GITEA_HOST ?? 'https://gitea.example.com',
+    giteaToken: process.env.GITEA_TOKEN,
+  },
+  defaultOwner: 'example-org',
+  defaultRepo: 'example-repo',
+  toolsPrefix: process.env.MCP_TOOLS_PREFIX ?? undefined,
+})
+```
+
+Then point any MCP client at this file with stdio transport.
+
+You can also invoke the packaged CLI directly:
+
+```bash
+f0-git-mcp --tools-prefix git
+```
+
+Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "workspace-git": {
+      "command": "bun",
+          "args": ["run", "/abs/path/packages/git/mcp/server-entry.ts"],
+      "env": {
+        "GITEA_HOST": "https://gitea.example.com",
+        "GITEA_TOKEN": "YOUR_TOKEN",
+        "MCP_TOOLS_PREFIX": "git"
+      }
+    }
+  }
+}
+```
+
+Cursor:
+
+```json
+{
+  "mcpServers": {
+    "workspace-git": {
+      "command": "bun",
+          "args": ["run", "/abs/path/packages/git/mcp/server-entry.ts"],
+      "env": {
+        "GITEA_HOST": "https://gitea.example.com",
+        "GITEA_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+Windsurf / any MCP-compatible client using the same schema:
+
+```json
+{
+  "mcpServers": {
+    "workspace-git": {
+      "command": "bun",
+          "args": ["run", "/abs/path/packages/git/mcp/server-entry.ts"],
+      "env": {
+        "GITEA_HOST": "https://gitea.example.com",
+        "GITEA_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+Tips:
+
+- Use a tool-name prefix (for example `git`) to avoid collisions with other MCP servers.
+- For Node-only agents, transpile/bundle this package first and point `command` to the compiled JS entrypoint.
+
+## Security notes
+
+- Prefer `https://` for `GITEA_HOST` to avoid leaking `GITEA_TOKEN` over plaintext HTTP.
+- The CLI entrypoint in `packages/git/mcp/src/cli.ts` rejects `http://` hosts unless `--allow-insecure-http` is passed for local testing.
+- Set `GITEA_TOKEN` in the MCP process environment. The package does not auto-load `.env` files.
+
+## API surface
+
+- `createGitMcpServer(options)` / `runGitMcpServer(options)`
+- `GitMcpClient`
+- `createGitMcpClient(options)`
+- `normalizeToolCallNameForServer(prefix, toolName)`
+- Includes label-management tools exposed from the API object:
+  `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`,
+  `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/cli.mjs

@@ -1,37 +1,37 @@
-#!/usr/bin/env node
-import { spawnSync } from 'node:child_process'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const cliPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'src', 'cli.ts')
-
-try {
-  const result = spawnSync(
-    'bun',
-    ['run', cliPath, ...process.argv.slice(2)],
-    {
-      stdio: 'inherit',
-    },
-  )
-
-  if (result.error) {
-    throw result.error
-  }
-
-  const code = result.status
-  if (typeof code === 'number') {
-    process.exit(code)
-  }
-
-  process.exit(0)
-} catch (error) {
-  const typedError = error instanceof Object ? error : null
-  const errno = typedError && 'code' in typedError ? typedError.code : undefined
-  if (errno === 'ENOENT') {
-    console.error('Bun is required to run f0-git-mcp. Install it and retry: https://bun.sh/docs/installation')
-    process.exit(1)
-  }
-
-  console.error('Failed to launch Git MCP server', error)
-  process.exit(1)
-}
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const cliPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'src', 'cli.ts')
+
+try {
+  const result = spawnSync(
+    'bun',
+    ['run', cliPath, ...process.argv.slice(2)],
+    {
+      stdio: 'inherit',
+    },
+  )
+
+  if (result.error) {
+    throw result.error
+  }
+
+  const code = result.status
+  if (typeof code === 'number') {
+    process.exit(code)
+  }
+
+  process.exit(0)
+} catch (error) {
+  const typedError = error instanceof Object ? error : null
+  const errno = typedError && 'code' in typedError ? typedError.code : undefined
+  if (errno === 'ENOENT') {
+    console.error('Bun is required to run f0-git-mcp. Install it and retry: https://bun.sh/docs/installation')
+    process.exit(1)
+  }
+
+  console.error('Failed to launch Git MCP server', error)
+  process.exit(1)
+}