# GitLab CI MCP Server

Model Context Protocol (MCP) server for GitLab CI/CD pipeline monitoring.

## Purpose

Provides AI agents with structured access to GitLab CI/CD pipelines for the egirl-platform project. Enables agents to:

- List recent pipelines
- Get pipeline details and job information
- Retrieve job logs for debugging
- Analyze recent failures
- Extract likely root causes from error logs

## Features

### Available Tools

| Tool | Description |
|------|-------------|
| `gitlab_list_pipelines` | List recent pipelines with status |
| `gitlab_get_pipeline` | Get detailed info for a specific pipeline |
| `gitlab_list_jobs` | List all jobs in a pipeline |
| `gitlab_get_job_logs` | Retrieve logs for a specific job |
| `gitlab_get_recent_failures` | Get recent failed pipelines with details |
| `gitlab_find_failure_cause` | Analyze failed pipeline and extract error patterns |

### Intelligent Features

- **Error Pattern Extraction**: Automatically identifies error lines in logs
- **Structured Responses**: Returns JSON for easy agent parsing
- **Failure Analysis**: Groups related failures and extracts root causes
- **Auto `.env` Loading**: Automatically loads `GITLAB_PAT` from project `.env` file

## Installation

```bash
# Install dependencies
pnpm install

# Build the server
pnpm run build
```

## Configuration

The server automatically loads `.env` from the project root, so no manual configuration needed if you have `GITLAB_PAT` in your `.env` file.

### For Claude Code MCP Configuration

Add to your Claude Code MCP configuration:

```json
{
  "mcpServers": {
    "gitlab-ci": {
      "command": "node",
      "args": [
        "/absolute/path/to/egirl-platform/packages/mcp-gitlab-ci/dist/index.js"
      ]
    }
  }
}
```

**Note**: No `env` section needed - the server loads `.env` automatically!

## Usage

### For AI Agents

Agents can invoke MCP tools directly:

```typescript
// List recent pipelines
gitlab_list_pipelines({ count: 10 })

// Analyze why a pipeline failed
gitlab_find_failure_cause({ pipelineId: "2160207941" })

// Get job logs
gitlab_get_job_logs({
  pipelineId: "2160207941",
  jobNameOrId: "test"
})
```

### Response Format

All tools return structured JSON:

**Pipeline List**:
```json
{
  "pipelines": [
    {
      "id": 2160207941,
      "status": "failed",
      "ref": "main",
      "sha": "a1b2c3d4",
      "updated_at": "2025-12-09T10:30:00Z",
      "web_url": "https://gitlab.com/..."
    }
  ]
}
```

**Failure Analysis**:
```json
{
  "pipeline_id": "2160207941",
  "analysis": [
    {
      "job": {
        "id": 123456,
        "name": "test",
        "stage": "test",
        "failure_reason": "script_failure"
      },
      "extracted_errors": [
        "Error: Cannot find module '@transftw/types'",
        "TypeError: undefined is not a function"
      ]
    }
  ]
}
```

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `GITLAB_PAT` or `GPLAT` | GitLab Personal Access Token | Yes |

The server checks for both `GITLAB_PAT` (preferred) and `GPLAT` (legacy).

Token must have `read_api` scope to access pipeline information.

## Architecture

```
Claude Code Agent
    ↓ (MCP Protocol)
GitLab CI MCP Server (this package)
    ↓ (imports)
@transftw/platform-tools/ci (GitLab API wrapper)
    ↓ (HTTPS)
GitLab API
```

## Troubleshooting

### "GPLAT or GITLAB_PAT environment variable not set"

Add `GITLAB_PAT=your-token` to the project root `.env` file.

### Server not responding

Verify the `.env` file exists and contains a valid token:
```bash
cat .env | grep GITLAB_PAT
```

## Related

- **CLI Tool**: `packages/platform-tools/src/cli/gitlab-ci.ts` - Direct CLI access
- **API Library**: `packages/platform-tools/src/lib/ci/gitlab-api.ts` - Underlying API wrapper
- **Documentation**: `.claude/instructions/mcp-tools-usage.md` - MCP usage guide

---

**Last Updated**: 2025-12-09
**Created By**: The Collective
**Purpose**: Enable AI agents to monitor GitLab CI/CD pipelines efficiently