# act-mcp

MCP stdio server exposing three tools for running GitHub Actions locally via [act](https://github.com/nektos/act).

## Peer dependency: act

`act` must be installed and in `PATH`:

```bash
# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
```

## MCP Tools

### `list_workflows`
Globs `.github/workflows/*.yml` and returns job names from each file.

| Field | Type | Description |
|---|---|---|
| `cwd` | `string?` | Repo root (default: `process.cwd()`) |

**Returns**: `Array<{ file: string, jobs: string[] }>`

### `run_job`
Spawns `act -j <jobName>`, captures stdout+stderr, caches logs.

| Field | Type | Description |
|---|---|---|
| `jobName` | `string` | Job ID (key under `jobs:` in the YAML) |
| `cwd` | `string?` | Repo root (default: `process.cwd()`) |

**Returns**: `{ exitCode: number, logs: string }`

### `get_logs`
Returns logs cached by the most recent `run_job` call.

**Returns**: `{ logs: string | null }`

## Agent loop

```
list_workflows → pick failing job
run_job        → read exitCode + logs
get_logs       → inspect failure output
(patch YAML)
run_job        → verify fix
```

## MCP client config (Claude Desktop)

```json
{
  "mcpServers": {
    "act-mcp": {
      "command": "npx",
      "args": ["act-mcp"]
    }
  }
}
```

Or point `cwd` at a specific repo:

```json
{
  "mcpServers": {
    "act-mcp": {
      "command": "npx",
      "args": ["act-mcp"],
      "env": {}
    }
  }
}
```

Pass `cwd` as a tool argument at call time:

```json
{ "name": "list_workflows", "arguments": { "cwd": "/path/to/repo" } }
```

## Development

```bash
npm install
npm run build   # tsc → dist/
npm test        # vitest (uses mock act binary, no act required)
npm run dev     # run via tsx without building
```

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `ACT_BIN` | `act` | Path to the act binary (useful for testing) |