165 lines
6.1 KiB
Markdown
165 lines
6.1 KiB
Markdown
# 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
|