mcp-server/README.md

GitCaddy MCP Server

A Model Context Protocol (MCP) 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.

2. Configure Claude Code

Add to your Claude Code settings:

Option A: Command line arguments

{
  "mcpServers": {
    "gitcaddy": {
      "command": "/path/to/gitcaddy-mcp-server",
      "args": ["--url", "https://git.marketally.com", "--token", "YOUR_API_TOKEN"]
    }
  }
}

Option B: Environment variables

{
  "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

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

Cross-compile for all platforms

# 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 file.

Related Projects

• GitCaddy Server - Enhanced Gitea fork with AI-friendly APIs
• GitCaddy Runner - Enhanced runner with capabilities detection