mcp-server/README.md

# GitCaddy MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like Claude to interact directly with your GitCaddy instance.

## Features

- **Query Runners** - List runners, check status, view capabilities, monitor queue depth
- **Manage Workflows** - List, trigger, rerun, cancel, and approve workflow runs
- **View Logs** - Get job logs with automatic error extraction for failed jobs
- **Access Artifacts** - List and download workflow artifacts
- **Manage Releases** - List releases, get assets, check download counts
- **AI Learning** - Query error patterns, report solutions, help other AIs learn
- **AI-Friendly** - Structured JSON responses designed for AI consumption

## Quick Start

### 1. Download

Download the latest binary from [Releases](https://git.marketally.com/gitcaddy/mcp-server/releases).

### 2. Configure Claude Code

Add to your Claude Code settings:

**Option A: Command line arguments**
```json
{
  "mcpServers": {
    "gitcaddy": {
      "command": "/path/to/gitcaddy-mcp-server",
      "args": ["--url", "https://git.marketally.com", "--token", "YOUR_API_TOKEN"]
    }
  }
}
```

**Option B: Environment variables**
```json
{
  "mcpServers": {
    "gitcaddy": {
      "command": "/path/to/gitcaddy-mcp-server",
      "env": {
        "GITCADDY_URL": "https://git.marketally.com",
        "GITCADDY_TOKEN": "your-token-here"
      }
    }
  }
}
```

### 3. Use It

Ask Claude things like:
- "What runners are online?"
- "Show me the latest workflow runs for gitcaddy/act_runner"
- "Why did run #77 fail?"
- "Rerun the failed jobs in run #77"
- "Cancel run #80"
- "Trigger the build.yml workflow on the main branch"
- "What workflows are available in myorg/myrepo?"
- "Show me the build.yml workflow file"
- "Validate the build.yml workflow in myorg/myrepo"
- "What artifacts were produced by run #77?"
- "What's the queue depth for each runner label?"
- "Approve the workflow run from the fork PR"
- "What assets are in the v0.3.6 release?"
- "Are there any known solutions for NETSDK1147?"
- "Diagnose why job 456 failed"
- "What secrets are available for myorg/myrepo?"
- "List all NuGet packages for myorg"
- "What are the package defaults for myorg?"
- "List all repos for myorg"
- "List open issues for gitcaddy/server"
- "Show me issue #42 in myorg/myrepo"

## Available Tools

### Runner Tools

| Tool | Description |
|------|-------------|
| `list_runners` | List all runners with status, capabilities, disk space |
| `get_runner` | Get detailed runner info by ID |
| `get_queue_depth` | Get waiting jobs per runner label (capacity insight) |

### Workflow Tools

| Tool | Description |
|------|-------------|
| `list_workflows` | List available workflow files in a repository (includes validation status) |
| `get_workflow_file` | Get the YAML content of a workflow file |
| `validate_workflow` | Validate a workflow YAML file for parse errors (from repo or raw content) |
| `list_workflow_runs` | List workflow runs for a repository |
| `get_workflow_run` | Get run details with all jobs |
| `get_job_logs` | Get logs from a specific job (auto-extracts errors for failed jobs) |
| `trigger_workflow` | Manually trigger a workflow_dispatch workflow with inputs |
| `rerun_workflow` | Rerun a completed workflow or specific failed job |
| `cancel_workflow_run` | Cancel a running workflow and all its jobs |
| `approve_workflow` | Approve a workflow run that requires approval (fork PRs) |

### Artifact Tools

| Tool | Description |
|------|-------------|
| `list_artifacts` | List artifacts from a workflow run |
| `get_artifact_download_url` | Get the download URL for a specific artifact |

### Repository & Issue Tools

| Tool | Description |
|------|-------------|
| `list_repos` | List repositories for an owner (org or user) |
| `list_issues` | List issues for a repository with pagination and state filtering |
| `get_issue` | Get issue details including body content and comments |

### Release & Package Tools

| Tool | Description |
|------|-------------|
| `list_releases` | List releases for a repository |
| `get_release` | Get release details with all assets |
| `list_secrets` | List secret names and descriptions (not values) for global, org, and repo scopes |
| `list_packages` | List packages for an owner or globally with version and visibility info |
| `get_package_defaults` | Get preconfigured package defaults (authors, company, copyright, icon, URLs) for an org |

### AI Learning Tools

| Tool | Description |
|------|-------------|
| `get_error_patterns` | Query known CI/CD error patterns with diagnoses and solutions |
| `report_error_solution` | Report a solution that fixed an error (helps other AIs learn) |
| `report_solution_success` | Mark a solution as successful (improves ranking) |
| `get_compatibility_matrix` | See what project types work on which runners |
| `diagnose_job_failure` | Auto-analyze failed job logs and suggest solutions |

## AI Learning System

GitCaddy includes a collaborative AI learning system. When you encounter and fix CI/CD errors, you can report your solutions to help other AI assistants:

```
AI encounters error -> get_error_patterns -> finds solution -> applies fix
                                                  |
                                                  v
                                        report_solution_success
                                        (improves ranking)

AI finds NEW solution -> report_error_solution -> stored in database
                                                  |
                                                  v
                                        Other AIs can now find it
```

### Example: Diagnosing a Failed Build

```
User: "Why did job 789 fail?"

Claude uses: diagnose_job_failure(owner="myorg", repo="myapp", job_id=789)

Response:
{
  "extracted_errors": ["NETSDK1147", "XA5300"],
  "diagnoses": [
    {
      "pattern": "NETSDK1147",
      "diagnosis": "The .NET MAUI Android workload is not installed",
      "solution": "Install the workload: dotnet workload install maui-android",
      "success_rate": 94.5
    }
  ]
}
```

## Building from Source

```bash
git clone https://git.marketally.com/gitcaddy/mcp-server.git
cd mcp-server
go build -o gitcaddy-mcp-server .
```

### Cross-compile for all platforms

```bash
# Linux
GOOS=linux GOARCH=amd64 go build -o gitcaddy-mcp-server-linux-amd64 .

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o gitcaddy-mcp-server-darwin-amd64 .

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o gitcaddy-mcp-server-darwin-arm64 .

# Windows
GOOS=windows GOARCH=amd64 go build -o gitcaddy-mcp-server-windows-amd64.exe .
```

## Architecture

```
+-------------+     stdio      +------------------+     HTTP      +-------------+
| Claude Code | <------------> | gitcaddy-mcp     | <-----------> |  GitCaddy   |
|  (AI Tool)  |   JSON-RPC     |   (This binary)  |  /api/v2/mcp  |   Server    |
+-------------+                +------------------+               +-------------+
```

The MCP server:
1. Receives JSON-RPC requests over stdio from Claude Code
2. Forwards them to GitCaddy's `/api/v2/mcp` endpoint
3. Returns responses back to Claude Code

## Configuration Options

| Flag | Env Variable | Description |
|------|-------------|-------------|
| `--url` | `GITCADDY_URL` | GitCaddy server URL (required) |
| `--token` | `GITCADDY_TOKEN` | API token for authentication |
| `--debug` | - | Enable debug logging to stderr |

**Note:** `GITEA_URL` and `GITEA_TOKEN` are also supported for backwards compatibility.

## Obtaining an API Token

1. Go to your GitCaddy instance -> Settings -> Applications
2. Generate a new token with appropriate scopes
3. Copy the token and use it in your configuration

## Requirements

- GitCaddy Server (Gitea 1.26+ with GitCaddy enhancements)
- Go 1.21+ (for building from source)

## License

MIT License - See [LICENSE](LICENSE) file.

## Related Projects

- [GitCaddy Server](https://git.marketally.com/gitcaddy/gitea) - Enhanced Gitea fork with AI-friendly APIs
- [GitCaddy Runner](https://git.marketally.com/gitcaddy/act_runner) - Enhanced runner with capabilities detection