# 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