# GitLab MCP Server for AgenticLedger
A Model Context Protocol (MCP) server that enables AI agents to interact with GitLab repositories, monitor documentation changes, and manage issues and merge requests.
## Overview
This MCP server provides comprehensive GitLab integration for the AgenticLedger platform, enabling AI agents to:
- **Monitor Documentation Changes**: Track commits, compare branches, and detect file modifications
- **Read Repository Contents**: Access files, directory structures, and wiki pages
- **Manage Issues & MRs**: Create and track issues, merge requests, and comments
- **Search Across GitLab**: Find projects, code, commits, and more
## Authentication Pattern
- [x] **API Key** (Direct Personal Access Token)
## Token Format
```
accessToken: "glpat-xxxxxxxxxxxxxxxxxxxx"
```
GitLab Personal Access Token (PAT) with appropriate scopes:
- `read_api` - For read-only operations
- `read_repository` - For file access
- `api` - For full access (issues, MRs, wikis)
### Creating a Token
1. Go to GitLab > Settings > Access Tokens
2. Create a new token with required scopes
3. Copy the token (starts with `glpat-`)
## Installation
```bash
# Clone the repository
git clone https://github.com/oregpt/Agenticledger_MCP_Gitlab.git
cd Agenticledger_MCP_Gitlab
# Install dependencies
npm install
# Build
npm run build
```
## Configuration
### For Claude Code / MCP Clients
Add to your MCP configuration:
```json
{
"mcpServers": {
"gitlab": {
"command": "node",
"args": ["path/to/GitlabMCP/dist/index.js"],
"env": {
"GITLAB_API_URL": "https://gitlab.com/api/v4"
}
}
}
}
```
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GITLAB_API_URL` | No | `https://gitlab.com/api/v4` | GitLab API base URL (for self-hosted instances) |
## Available Tools
### Project Operations
#### `gitlab_search_projects`
**Description:** Search for GitLab projects by name or description.
**Parameters:**
- `accessToken` (string, required): GitLab Personal Access Token
- `search` (string, required): Search query
- `page` (number, optional): Page number
- `per_page` (number, optional): Results per page (1-100)
**Example:**
```json
{
"accessToken": "glpat-xxxx",
"search": "documentation",
"per_page": 10
}
```
#### `gitlab_get_project`
**Description:** Get detailed project information.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `project_id` (string, required): Project ID or URL-encoded path
#### `gitlab_list_group_projects`
**Description:** List all projects in a group.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `group_id` (string, required): Group ID or path
- `include_subgroups` (boolean, optional): Include subgroup projects
- `search` (string, optional): Filter by name
- `order_by` (string, optional): Sort field
- `sort` (string, optional): asc or desc
---
### File Operations
#### `gitlab_get_file_contents`
**Description:** Read file contents from a repository. Essential for documentation monitoring.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `project_id` (string, required): Project ID
- `file_path` (string, required): Path to file (e.g., "docs/README.md")
- `ref` (string, optional): Branch, tag, or commit SHA
**Response:**
```json
{
"success": true,
"data": {
"file_name": "README.md",
"file_path": "docs/README.md",
"content": "# Documentation\n...",
"encoding": "base64",
"ref": "main"
}
}
```
#### `gitlab_get_tree`
**Description:** List files and directories in a repository path.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `project_id` (string, required): Project ID
- `path` (string, optional): Directory path
- `ref` (string, optional): Branch/tag/SHA
- `recursive` (boolean, optional): List recursively
#### `gitlab_create_or_update_file`
**Description:** Create or update a file with a commit.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `project_id` (string, required): Project ID
- `file_path` (string, required): Target file path
- `branch` (string, required): Target branch
- `content` (string, required): File content
- `commit_message` (string, required): Commit message
---
### Commit Operations (Critical for Monitoring)
#### `gitlab_list_commits`
**Description:** List recent commits. Primary tool for detecting documentation changes.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `project_id` (string, required): Project ID
- `ref_name` (string, optional): Branch or tag
- `since` (string, optional): ISO 8601 date
- `until` (string, optional): ISO 8601 date
- `path` (string, optional): Filter by file path
- `author` (string, optional): Filter by author email
- `with_stats` (boolean, optional): Include stats
**Example - Monitor docs folder:**
```json
{
"accessToken": "glpat-xxxx",
"project_id": "12345",
"path": "docs/",
"since": "2024-01-01T00:00:00Z",
"with_stats": true
}
```
#### `gitlab_get_commit_diff`
**Description:** Get file changes for a specific commit.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `project_id` (string, required): Project ID
- `sha` (string, required): Commit SHA
#### `gitlab_compare`
**Description:** Compare two branches/tags/commits.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `project_id` (string, required): Project ID
- `from` (string, required): Source ref
- `to` (string, required): Target ref
---
### Activity Monitoring
#### `gitlab_get_project_events`
**Description:** Get recent project activity. Best tool for real-time monitoring.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `project_id` (string, required): Project ID
- `action` (string, optional): Filter by action type (pushed, commented, etc.)
- `target_type` (string, optional): Filter by target (issue, merge_request, etc.)
- `after` (string, optional): Events after this date (ISO 8601)
- `before` (string, optional): Events before this date
**Example - Monitor push events:**
```json
{
"accessToken": "glpat-xxxx",
"project_id": "12345",
"action": "pushed",
"after": "2024-12-01T00:00:00Z"
}
```
---
### Issue Operations
#### `gitlab_list_issues`
List project issues with filtering.
#### `gitlab_get_issue`
Get specific issue details.
#### `gitlab_create_issue`
Create a new issue.
#### `gitlab_list_issue_notes`
List comments on an issue.
---
### Merge Request Operations
#### `gitlab_list_merge_requests`
List MRs with filtering.
#### `gitlab_get_merge_request`
Get MR details.
#### `gitlab_get_merge_request_changes`
Get file changes in an MR.
#### `gitlab_create_merge_request`
Create a new MR.
---
### Wiki Operations
#### `gitlab_list_wiki_pages`
List all wiki pages.
#### `gitlab_get_wiki_page`
Get wiki page content.
#### `gitlab_create_wiki_page`
Create a wiki page.
#### `gitlab_update_wiki_page`
Update a wiki page.
---
### Search Operations
#### `gitlab_search`
**Description:** Search across GitLab.
**Parameters:**
- `accessToken` (string, required): GitLab PAT
- `search` (string, required): Search query
- `scope` (string, optional): projects, issues, merge_requests, blobs, commits, etc.
- `project_id` (string, optional): Limit to project
- `group_id` (string, optional): Limit to group
---
## Response Format
All tools return a standardized response:
```typescript
{
success: boolean;
data?: any; // Present on success
error?: string; // Present on failure
}
```
**Success Example:**
```json
{
"success": true,
"data": {
"id": 12345,
"name": "my-project",
"description": "..."
}
}
```
**Error Example:**
```json
{
"success": false,
"error": "Resource not found: /projects/99999"
}
```
## Testing
```bash
# Run unit tests
npm test
# Run integration tests (requires GITLAB_TEST_TOKEN)
GITLAB_TEST_TOKEN=glpat-xxx npm run test:integration
```
## Use Case: Documentation Monitoring
This is the primary use case for this MCP server. Here's how to monitor a customer's documentation repo:
### Workflow
1. **Initial Scan**: Use `gitlab_get_tree` to discover documentation files
2. **Monitor Changes**: Periodically call `gitlab_get_project_events` or `gitlab_list_commits`
3. **Fetch Updates**: When changes detected, use `gitlab_get_file_contents` to read updated files
4. **Process**: Feed updated content to your D7 data pipeline
### Example Monitoring Script
```javascript
// 1. Get recent commits affecting docs
const commits = await gitlab_list_commits({
accessToken: "glpat-xxx",
project_id: "customer/docs-repo",
path: "docs/",
since: lastCheckTime,
with_stats: true
});
// 2. For each new commit, get the changes
for (const commit of commits.data) {
const diff = await gitlab_get_commit_diff({
accessToken: "glpat-xxx",
project_id: "customer/docs-repo",
sha: commit.id
});
// 3. Process changed files
for (const file of diff.data) {
if (file.new_path.startsWith('docs/')) {
const content = await gitlab_get_file_contents({
accessToken: "glpat-xxx",
project_id: "customer/docs-repo",
file_path: file.new_path
});
// Update your knowledge base
}
}
}
```
## Platform Integration Notes
### Self-Hosted GitLab
Set `GITLAB_API_URL` to your instance:
```json
{
"env": {
"GITLAB_API_URL": "https://gitlab.yourcompany.com/api/v4"
}
}
```
### Rate Limits
GitLab has rate limits:
- **Authenticated**: 2000 requests/minute
- Consider pagination for large datasets
- Use `since` filters to reduce response size
### Token Scopes
Minimum required scopes:
| Operation | Required Scope |
|-----------|---------------|
| Read files | `read_repository` |
| Read issues/MRs | `read_api` |
| Create issues/MRs | `api` |
| Write files | `api` |
## License
MIT
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make changes
4. Run tests
5. Submit a pull request
## Support
For issues, please file a GitHub issue at: https://github.com/oregpt/Agenticledger_MCP_Gitlab/issues
