# GitLab Code Review MCP Server
A Model Context Protocol (MCP) server that provides GitLab code review functionality for AI assistants. This server enables AI assistants to interact with GitLab merge requests, review code changes, and create draft comments.
## Features
- **Project Discovery**: Search and list GitLab projects
- **Merge Request Management**: List and filter merge requests
- **Code Diff Analysis**: Retrieve detailed code changes for merge requests
- **Draft Comment Creation**: Create both general and line-specific draft comments
## Quick Start
### Prerequisites
- Node.js (ES2022+ support required)
- pnpm package manager (version 10.11.1+ recommended)
- GitLab Personal Access Token with API access
### Installation
1. **Clone the repository:**
```bash
git clone <repository-url>
cd code-review-mcp
```
2. **Install dependencies:**
```bash
pnpm install
```
3. **Configure environment:**
```bash
cp .env.example .env
```
Edit `.env` with your GitLab configuration:
```env
GITLAB_PAT=your_gitlab_personal_access_token_here
GITLAB_API_URL=https://gitlab.com
GITLAB_PROJECT_ID=your_project_id_here
SERVER_NAME=code-review-mcp
SERVER_VERSION=1.0.0
```
4. **Build the project:**
```bash
pnpm run build
```
5. **Run the server:**
```bash
node build/index.js
```
## MCP Tools
The server exposes four main tools for GitLab integration:
### `get-projects`
Search and list GitLab projects.
**Parameters:**
- `search` (optional): Search term to filter projects
- `per_page` (optional): Number of results per page (default: 20, max: 100)
- `visibility` (optional): Filter by visibility ('private', 'internal', 'public')
- `owned` (optional): Limit to owned projects (boolean)
### `get-merge-requests`
List merge requests from a project.
**Parameters:**
- `state` (optional): Filter by state ('opened', 'closed', 'merged', 'all') - default: 'opened'
- `per_page` (optional): Number of results per page (default: 20, max: 100)
### `get-merge-request-diffs`
Get detailed code changes for a specific merge request.
**Parameters:**
- `mr_iid` (optional): Internal ID of the merge request
- `source_branch` (optional): Source branch name to search for
- `mrTitle` (optional): Title or partial title to search for
### `create-draft-note`
Create draft comments on merge requests.
**Parameters:**
- `project_id` (optional): Project ID (uses default if not provided)
- `mr_iid` (required): Internal ID of the merge request
- `note` (required): Content of the draft note
- `position_type` (optional): Set to 'text' for line-specific comments
- `old_path`, `new_path` (optional): File paths for line comments
- `old_line`, `new_line` (optional): Line numbers for line comments
- `base_sha`, `start_sha`, `head_sha` (optional): SHA values for line comments
## Configuration
### Environment Variables
All environment variables are validated at startup using Zod schemas:
- `GITLAB_PAT` (required): GitLab Personal Access Token with API access
- `GITLAB_API_URL` (required): GitLab instance URL (e.g., https://gitlab.com)
- `GITLAB_PROJECT_ID` (required): Default project ID (numeric)
- `SERVER_NAME` (required): MCP server name identifier
- `SERVER_VERSION` (required): Server version string
### GitLab Personal Access Token
Your GitLab PAT needs the following scopes:
- `api` - Full API access
- `read_user` - Read user information
- `read_repository` - Read repository content
## Development
### Project Structure
```
├── src/
│ ├── index.ts # Main MCP server implementation
│ └── env.ts # Environment configuration and validation
├── build/ # Compiled output (generated)
├── docs/
│ └── system-prompt.md # AI assistant usage documentation
├── test_mcp_server.js # Comprehensive test suite
├── test_draft_note.js # Example requests for draft note tool
├── test_projects.js # Example data for projects tool
├── .env.example # Environment variable template
├── package.json # Project configuration
└── tsconfig.json # TypeScript configuration
```
### Building
```bash
pnpm run build
```
This compiles TypeScript from `src/` to `build/` directory and makes the output executable.
### Testing
Run the comprehensive test suite:
```bash
node test_mcp_server.js
```
This test verifies:
- Build process functionality
- Output file generation and permissions
- Environment variable validation
- MCP server initialization
### Code Architecture
**Entry Point**: `src/index.ts`
- Creates MCP server instance
- Registers four GitLab tools
- Handles stdio transport communication
**Environment Management**: `src/env.ts`
- Uses Zod for runtime environment validation
- Exports typed environment configuration
- Fails fast on invalid configuration
**Key Components**:
- `makeGitLabRequest<T>()` - Generic GitLab API client function
- Interface definitions for GitLab entities (MergeRequest, Diff, Project, DraftNote)
- MCP tool handlers with Zod schema validation
## Usage with AI Assistants
This MCP server is designed to be used with AI assistants that support the Model Context Protocol. See `docs/system-prompt.md` for detailed instructions on how AI assistants can use this server for code review workflows.
### Example Workflow
1. **Discover Projects**: Use `get-projects` to find target repositories
2. **List Merge Requests**: Use `get-merge-requests` to see open merge requests
3. **Analyze Code**: Use `get-merge-request-diffs` to review code changes
4. **Provide Feedback**: Use `create-draft-note` to create constructive comments
### MCP Client Configuration
To use this MCP server with AI assistants like Claude Code, you need to add the server configuration to your MCP client settings. Here's how to configure it:
#### For Claude Code
Add the following configuration to your MCP client settings (typically in a JSON configuration file):
```json
{
"mcpServers": {
"code-review": {
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_code-review-mcp/build/index.js>"
],
"env": {
"GITLAB_PROJECT_ID": "",
"GITLAB_PAT": "",
"GITLAB_API_URL": "",
"SERVER_NAME": "",
"SERVER_VERSION": ""
}
}
}
}
```
#### Configuration Steps
1. **Build the project** first (if not already done):
```bash
pnpm run build
```
2. **Replace the placeholder values**:
- `<ABSOLUTE_PATH_TO_code-review-mcp/build/index.js>`: Replace with the full absolute path to your built server file
- `GITLAB_PROJECT_ID`: Your GitLab project ID (numeric)
- `GITLAB_PAT`: Your GitLab Personal Access Token
- `GITLAB_API_URL`: Your GitLab instance URL (e.g., `https://gitlab.com`)
- `SERVER_NAME`: A name for your server instance (e.g., `code-review-mcp`)
- `SERVER_VERSION`: Version identifier (e.g., `1.0.0`)
3. **Example with actual values**:
```json
{
"mcpServers": {
"code-review": {
"command": "node",
"args": [
"/Users/yourname/projects/code-review-mcp/build/index.js"
],
"env": {
"GITLAB_PROJECT_ID": "12345678",
"GITLAB_PAT": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com",
"SERVER_NAME": "code-review-mcp",
"SERVER_VERSION": "1.0.0"
}
}
}
}
```
4. **Restart your MCP client** after adding the configuration.
#### Security Notes
- Keep your GitLab Personal Access Token secure and never commit it to version control
- Use environment-specific configuration files that are excluded from your repository
- Ensure your GitLab PAT has only the minimum required permissions (api, read_user, read_repository)
## API Integration
The server integrates with GitLab's REST API v4:
- **Authentication**: Uses `PRIVATE-TOKEN` header with GitLab PAT
- **Base URL Pattern**: `${GITLAB_API_URL}/api/v4/...`
- **Error Handling**: All API calls include comprehensive error handling
- **Rate Limiting**: Respects GitLab API rate limits
## Security Considerations
- **Token Security**: Store GitLab PAT securely and use minimal required permissions
- **Input Validation**: All user inputs are validated through Zod schemas
- **Error Messages**: Sensitive information is not exposed in error responses
- **Environment Variables**: Never commit actual credentials to version control
## License
ISC
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## Support
For issues and questions:
1. Check the existing documentation in `docs/`
2. Review the test files for usage examples
3. Open an issue with detailed information about your problem
