# GitLab CLI MCP Server

This MCP server provides integration with GitLab through the GitLab CLI (`glab`) tool. It allows LLM agents to interact with GitLab repositories and resources using the GitLab API.

## Features

- Check if the GitLab CLI is available and accessible
- Find GitLab projects by name and retrieve their IDs
- Search for GitLab issues with various filters
- Create new GitLab issues
- Get merge request diffs with automatic handling of large diffs
- More features to be added in the future

## Prerequisites

- Python 3.11 or higher
- GitLab CLI (`glab`) installed and accessible in the system PATH
- GitLab account with proper authentication set up via `glab auth login`

## Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/dawids-mcp-servers.git
cd dawids-mcp-servers

# Install the server
cd servers/gitlab_glab
uv pip install -e .
```

## Usage

### Running the server with stdio transport (for local development)

```bash
mcp-gitlab-glab --transport stdio
```

### Running the server with remote transport

```bash
mcp-gitlab-glab --transport remote --host 0.0.0.0 --port 8080
```

## Available Tools

### check_glab_availability

Checks if the GitLab CLI tool is installed and accessible.

```python
result = use_mcp_tool(
    server_name="gitlab_glab",
    tool_name="check_glab_availability",
    arguments={
        "working_directory": "/path/to/current/directory"
    }
)
```

### find_project

Finds GitLab projects by name and returns their details.

```python
result = use_mcp_tool(
    server_name="gitlab_glab",
    tool_name="find_project",
    arguments={
        "project_name": "my-project",
        "working_directory": "/path/to/current/directory"
    }
)
```

The function returns a list of matching projects, each containing the following fields:
- `id`: The project ID
- `name`: The project name
- `path_with_namespace`: The project path with namespace
- `web_url`: The project web URL
- `description`: The project description

### search_issues

Search for GitLab issues with various filters.

```python
result = use_mcp_tool(
    server_name="gitlab_glab",
    tool_name="search_issues",
    arguments={
        "working_directory": "/path/to/current/directory",
        # Optional filters
        "author": "username",  # Filter by author
        "assignee": "username",  # Filter by assignee
        "closed": True,  # Get only closed issues
        "confidential": True,  # Filter by confidential issues
        "group": "group-name",  # Select a group or subgroup
        "issue_type": "issue",  # Filter by type: issue, incident, test_case
        "iteration": 123,  # Filter by iteration ID
        "label": ["bug", "critical"],  # Filter by labels
        "milestone": "v1.0",  # Filter by milestone
        "not_assignee": "username",  # Filter by not being assigned to
        "not_author": "username",  # Filter by not being authored by
        "not_label": ["wontfix"],  # Filter by lack of labels
        "page": 1,  # Page number (default: 1)
        "per_page": 30,  # Items per page (default: 30)
        "project": "group/project"  # Project path with namespace
    }
)
```

The function returns a dictionary containing:
- `issues`: A list of issues, each with:
  - `id`: The issue ID
  - `iid`: The internal issue ID
  - `title`: The issue title
  - `web_url`: The issue URL
  - `state`: The issue state (opened/closed)
  - `created_at`: Creation timestamp
  - `updated_at`: Last update timestamp
- `error`: Error message if the operation failed

### create_issue

Creates a new GitLab issue and returns its URL.

```python
result = use_mcp_tool(
    server_name="gitlab_glab",
    tool_name="create_issue",
    arguments={
        "title": "Issue title",
        "description": "Issue description",
        "working_directory": "/path/to/current/directory",
        # Optional parameters
        "labels": ["bug", "critical"],  # List of labels
        "assignee": ["username1", "username2"],  # List of usernames
        "milestone": "v1.0",  # Milestone title or ID
        "epic_id": 123,  # Epic ID
        "project": "group/project"  # Project path with namespace
    }
)
```

The function returns a dictionary containing:
- `url`: The URL of the created issue
- `error`: Error message if the operation failed

### get_mr_diff

Get the diff for a merge request using `glab mr diff`.

```python
result = use_mcp_tool(
    server_name="gitlab_glab",
    tool_name="get_mr_diff",
    arguments={
        "working_directory": "/path/to/current/directory",
        # Optional parameters
        "mr_id": "123",  # MR ID or branch name (if None, uses current branch)
        "color": "never",  # Use color in diff output: always, never, auto (default: never)
        "raw": True,  # Use raw diff format (default: False)
        "repo": "group/project",  # Project path with namespace
        "max_size_kb": 100  # Maximum size in KB before saving to temp file (default: 100)
    }
)
```

The function returns a dictionary containing:
- `diff`: The diff content (if small enough)
- `size_kb`: The size of the diff in KB
- `temp_file_path`: Path to temporary file if diff is too large (None otherwise)
- `diff_too_large`: Boolean indicating if diff was saved to temp file
- `max_size_kb`: The configured maximum size threshold
- `message`: Human-readable message about temp file creation (if applicable)
- `error`: Error message if the operation failed

**Note on Large Diffs**: To prevent overwhelming LLMs with extremely large diffs, this tool automatically saves diffs larger than `max_size_kb` (default: 100KB) to a temporary file and returns the file path instead of the content. This allows you to process large merge request diffs without hitting token limits.

## Working Directory Context

All tools require a `working_directory` parameter that specifies the directory context in which the GitLab CLI commands should be executed. This ensures that commands are run in the same directory as the agent, maintaining proper context for repository operations.

The working directory should be the absolute path to the directory where you want the GitLab CLI commands to be executed. For example, if you're working with a GitLab repository cloned to `/home/user/projects/my-repo`, you would pass that path as the `working_directory` parameter.

## Development

### Running tests

```bash
cd servers/gitlab_glab
uv run pytest
```

### Running tests with coverage

```bash
cd servers/gitlab_glab
uv run pytest --cov=mcp_server_gitlab_glab
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.