# Woodpecker CI MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to Woodpecker CI.
Debug pipeline failures, analyze build logs, and troubleshoot CI/CD configurations with AI assistance.

This is a Go implementation of [j04n-f/woodpecker-mcp](https://github.com/j04n-f/woodpecker-mcp)
built with [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go). It speaks the MCP
protocol over stdio (JSON-RPC) and talks to the Woodpecker CI REST API.

## Requirements

- Go 1.26+

## Build

```sh
go build -o woodpecker-mcp ./cmd/woodpecker-mcp
```

The version embedded in the `initialize` handshake can be set at build time:

```sh
go build -ldflags "-X gitea.fe.kaien.ru/kaien/woodpecker-mcp/internal/version.Version=v1.2.3" -o woodpecker-mcp ./cmd/woodpecker-mcp
```

## Configuration

| Environment variable | Required | Description                                                                  |
| -------------------- | -------- | ---------------------------------------------------------------------------- |
| `WOODPECKER_URL`     | yes      | Base URL of your Woodpecker CI instance, e.g. `https://woodpecker.example.com` |
| `WOODPECKER_TOKEN`   | yes      | Personal access token (profile icon → "CLI & API")                           |

The server refuses to start with a missing or invalid configuration.

## Transports

The server speaks MCP over **stdio by default** (the standard mode for local
MCP clients such as Claude Desktop, Cursor, etc.). A remote **Streamable HTTP**
transport is also available:

| Flag        | Default  | Description                                          |
| ----------- | -------- | ---------------------------------------------------- |
| `--transport` | `stdio`  | `stdio` or `http`                                    |
| `--listen`  | `:8080`  | HTTP listen address (used with `--transport=http`)   |

```sh
# stdio (default)
woodpecker-mcp

# remote Streamable HTTP on :8080 (endpoint /mcp)
woodpecker-mcp --transport=http --listen=:8080
```

The HTTP endpoint is `http://<host>:8080/mcp` (Streamable HTTP, MCP spec
2025-06-18). No authentication is enforced — run it inside your trusted
network only. In Docker, expose the port when using HTTP mode:

```sh
docker run -i --rm -p 8080:8080 \
  -e WOODPECKER_URL=https://your-woodpecker-instance.com \
  -e WOODPECKER_TOKEN=your-token-here \
  your-registry/woodpecker_mcp/woodpecker_mcp --transport=http
```

## Deployment (Kubernetes)

The repository ships a `k8s-deploy.yaml` (Service + Deployment) that runs the
binary in **HTTP mode** (`--transport=http`) on port 8080.

- Namespace: `mcp-servers`
- Service: `woodpecker-mcp` (ClusterIP, `8080 -> 8080`); in-cluster URL:
  `http://woodpecker-mcp.mcp-servers:8080/mcp`
- Image: `registry.be.kaien.ru/woodpecker_mcp/woodpecker_mcp:$CI_COMMIT_SHA`
  (rendered by `envsubst` in CI; every commit triggers a rollout via the
  `deployment.l-ai/commit` annotation)
- Secrets: `WOODPECKER_TOKEN` comes from the SealedSecret
  `woodpecker-mcp-sealed.yaml` (name `woodpecker-mcp`, ns `mcp-servers`).
  `WOODPECKER_URL` is not secret and is set as a plain env var
  (`https://ci.be.kaien.ru/` — a trailing slash is harmless, the config
  trims it before appending `/api`).

To reseal the token after rotation, run kubeseal and replace
`spec.encryptedData.WOODPECKER_TOKEN`:

```sh
echo -n 'your-token' | kubeseal --namespace mcp-servers --name woodpecker-mcp --raw
```

Woodpecker CI secrets required by the pipeline: `SSH_PRIVATE_KEY`,
`DEPLOY_HOST`, `DEPLOY_USER` (deploy step) plus `ZOT_USERNAME`,
`ZOT_PASSWORD` (build step).

## MCP Client Setup

Add to your MCP client configuration:

```json
{
  "woodpecker-ci": {
    "command": "woodpecker-mcp",
    "env": {
      "WOODPECKER_TOKEN": "your-token-here",
      "WOODPECKER_URL": "https://your-woodpecker-instance.com"
    }
  }
}
```

## API Reference

| Tool                  | Description                              | Parameters                                                                   |
| --------------------- | ---------------------------------------- | ---------------------------------------------------------------------------- |
| `search_repository`   | Find repository by name                  | `name` (e.g. `"owner/repo"`)                                                   |
| `get_repository_by_id`| Get repository details by ID             | `repoId`                                                                     |
| `list_repositories`   | List all repositories                    | Optional: `page`, `perPage`, `active`, `trusted`                              |
| `list_pipelines`      | List repository pipelines                | `repoId`, optional: `page`, `perPage`, `before`, `after`                      |
| `get_pipeline`        | Get detailed pipeline info               | `repoId`, `number`                                                           |
| `get_pipeline_config` | View pipeline configuration              | `repoId`, `number`                                                           |
| `get_step_logs`       | Get logs for debugging                   | `repoId`, `number`, `stepId`                                                 |

All tools are read-only (GET requests only). Errors are returned as structured
JSON with a status-aware description and suggested next steps.

## Development

```sh
go vet ./...
go test -race ./...
```

## Examples

### Debug a Failed Pipeline

```
AI: Can you check why pipeline #42 failed for repository owner/project?
```

### Analyze Build Performance

```
AI: Show me the recent pipeline performance for my main repository and identify any bottlenecks.
```

### Configuration Review

```
AI: Review the pipeline configuration for repository owner/project and suggest improvements.
```

## Project Layout

```
cmd/woodpecker-mcp/  entry point: config load, signal handling, stdio transport
internal/config/     environment configuration and validation
internal/server/     MCP server assembly
internal/tools/      MCP tool definitions and handlers (repositories, pipelines, logs)
internal/woodpecker/ Woodpecker CI REST API client (types, client, error contexts)
internal/version/    server name and version
```

## License

MIT License