# GitLab MCP Server - Abilities & Limitations
This document enables AI agents to provide intelligent confirmations and smart alternatives when user requests hit limitations.
---
## ABILITIES - What This Capability CAN Do
### Project Operations
| Action | Tool | Description |
|--------|------|-------------|
| Search projects | `gitlab_search_projects` | Find projects by name or description |
| Get project details | `gitlab_get_project` | Retrieve full project metadata |
| List group projects | `gitlab_list_group_projects` | List all projects in a group/subgroups |
**User Command Examples:**
- "Find all projects with 'docs' in the name"
- "Get details for project ID 12345"
- "List all projects in the customer-group"
---
### File Operations
| Action | Tool | Description |
|--------|------|-------------|
| Read file contents | `gitlab_get_file_contents` | Fetch any file from a repo |
| List directory | `gitlab_get_tree` | Browse repository structure |
| Create/update file | `gitlab_create_or_update_file` | Commit file changes |
**User Command Examples:**
- "Read the README.md from project docs-repo"
- "Show me all files in the docs/ folder"
- "Update the config.yaml with this content"
---
### Change Monitoring (Primary Use Case)
| Action | Tool | Description |
|--------|------|-------------|
| List commits | `gitlab_list_commits` | Get commit history with filters |
| Get commit diff | `gitlab_get_commit_diff` | See exact file changes |
| Compare branches | `gitlab_compare` | Diff between any two refs |
| Get project events | `gitlab_get_project_events` | Activity feed (pushes, comments, etc.) |
**User Command Examples:**
- "Show commits to docs/ folder since December 1st"
- "What files changed in commit abc123?"
- "Compare main branch with release-v2"
- "Show all push events in the last week"
---
### Issue Management
| Action | Tool | Description |
|--------|------|-------------|
| List issues | `gitlab_list_issues` | Filter by state, labels, dates |
| Get issue | `gitlab_get_issue` | Full issue details |
| Create issue | `gitlab_create_issue` | Open new issues |
| List comments | `gitlab_list_issue_notes` | Read issue discussion |
**User Command Examples:**
- "Show open issues labeled 'documentation'"
- "Create an issue about outdated API docs"
- "Get all comments on issue #42"
---
### Merge Request Management
| Action | Tool | Description |
|--------|------|-------------|
| List MRs | `gitlab_list_merge_requests` | Filter by state, branch, labels |
| Get MR details | `gitlab_get_merge_request` | Full MR info |
| Get MR changes | `gitlab_get_merge_request_changes` | File diffs in MR |
| Create MR | `gitlab_create_merge_request` | Open new merge requests |
**User Command Examples:**
- "Show all open merge requests for the docs branch"
- "What files are changed in MR !15?"
- "Create a draft MR for my documentation updates"
---
### Wiki Operations
| Action | Tool | Description |
|--------|------|-------------|
| List wiki pages | `gitlab_list_wiki_pages` | Browse project wiki |
| Get wiki page | `gitlab_get_wiki_page` | Read wiki content |
| Create wiki page | `gitlab_create_wiki_page` | Add new pages |
| Update wiki page | `gitlab_update_wiki_page` | Edit existing pages |
**User Command Examples:**
- "List all wiki pages in the project"
- "Read the 'Getting Started' wiki page"
- "Update the API reference wiki"
---
### Search Operations
| Action | Tool | Description |
|--------|------|-------------|
| Global search | `gitlab_search` | Search projects, code, issues, commits, users |
**Search Scopes:** `projects`, `issues`, `merge_requests`, `milestones`, `users`, `blobs` (code), `commits`, `notes`, `wiki_blobs`
**User Command Examples:**
- "Search for 'authentication' in the codebase"
- "Find all issues mentioning 'deprecated'"
- "Search commits with 'fix' in the message"
---
## LIMITATIONS - What This Capability CANNOT Do
### Repository Operations
| Limitation | Why | Impact |
|------------|-----|--------|
| Cannot clone repositories | No git protocol support | Must read files individually |
| Cannot create repositories | API scope limitation | User must create manually |
| Cannot delete repositories | Safety restriction | User must delete via GitLab UI |
| Cannot manage deploy keys | Scope not implemented | User must configure in settings |
### Branch Operations
| Limitation | Why | Impact |
|------------|-----|--------|
| Cannot delete branches | Safety restriction | User must delete via UI |
| Cannot protect/unprotect branches | Admin scope required | User must configure in settings |
| Cannot set default branch | Admin scope required | User must change in settings |
### File Operations
| Limitation | Why | Impact |
|------------|-----|--------|
| Cannot delete files | Safety restriction | User must delete via UI or commit |
| Cannot upload binary files | Base64 encoding limits | User must upload via UI |
| File size limit ~1MB | API constraint | Large files need Git LFS |
### Merge Request Operations
| Limitation | Why | Impact |
|------------|-----|--------|
| Cannot merge MRs | Requires maintainer approval | User must merge manually |
| Cannot approve MRs | Approval workflow restriction | User must approve in UI |
| Cannot add reviewers after creation | API limitation | Edit MR in UI |
### Issue Operations
| Limitation | Why | Impact |
|------------|-----|--------|
| Cannot close issues | Safety restriction | User must close manually |
| Cannot delete issues | Safety restriction | User must delete in UI |
| Cannot manage issue boards | Scope not implemented | Use GitLab UI |
### CI/CD Operations
| Limitation | Why | Impact |
|------------|-----|--------|
| Cannot trigger pipelines | Scope not implemented | Use GitLab UI or webhooks |
| Cannot view pipeline logs | Scope not implemented | View in GitLab UI |
| Cannot manage CI variables | Security restriction | Configure in settings |
### Administrative
| Limitation | Why | Impact |
|------------|-----|--------|
| Cannot manage users/permissions | Admin scope required | Admin must configure |
| Cannot manage webhooks | Scope not implemented | Configure in settings |
| Cannot access audit logs | Admin scope required | Admin must access |
---
## SMART ALTERNATIVES - When Actions Are Blocked
### Scenario 1: User wants to delete a file
**User Request:** "Delete the old-config.yaml file"
**AI Response:**
```
I cannot delete files directly from GitLab. Here are alternatives:
1. **Create replacement commit**: I can update the file to be empty or add a deprecation notice
2. **Create an issue**: I can create an issue requesting file deletion
3. **Guide you**: Go to Repository > Files > old-config.yaml > Delete
Would you like me to do option 1 or 2?
```
---
### Scenario 2: User wants to merge an MR
**User Request:** "Merge MR !42"
**AI Response:**
```
I cannot merge MRs directly - this requires maintainer approval. I can:
1. **Check MR status**: Show you the current approval status and any blockers
2. **Add a comment**: Comment on the MR that it's ready for merge
3. **Guide you**: Open GitLab and navigate to the MR to merge
Want me to check the MR status first?
```
---
### Scenario 3: User wants to trigger a pipeline
**User Request:** "Run the CI pipeline on the main branch"
**AI Response:**
```
I cannot trigger CI/CD pipelines. Alternatives:
1. **Push a commit**: I can create a small commit to trigger the pipeline
2. **Check recent runs**: I can show you recent pipeline statuses via project events
3. **Guide you**: Go to CI/CD > Pipelines > Run pipeline
Would you like me to check recent pipeline activity instead?
```
---
### Scenario 4: User wants to clone a repository
**User Request:** "Clone the docs-repo to my local machine"
**AI Response:**
```
I cannot clone repositories directly. However, I can:
1. **List all files**: Show you the complete repository structure
2. **Read multiple files**: Fetch the contents of specific files you need
3. **Guide you**: Run `git clone https://gitlab.com/group/docs-repo.git`
Want me to list the repository structure so you know what to expect?
```
---
### Scenario 5: User wants real-time notifications
**User Request:** "Notify me whenever the docs change"
**AI Response:**
```
I cannot set up real-time notifications or webhooks. I can:
1. **Poll for changes**: Periodically check for new commits/events
2. **Create monitoring script**: Help you set up a scheduled job that calls `gitlab_list_commits`
3. **Guide webhook setup**: Walk you through creating a GitLab webhook
For your use case, option 1 (polling) is best integrated with your D7 pipeline. Want me to set that up?
```
---
## AUTO-EXECUTE CLASSIFICATION
### Safe Auto-Execute (Read Operations)
These tools are safe to execute immediately without user confirmation:
| Tool | Reason |
|------|--------|
| `gitlab_search_projects` | Read-only search |
| `gitlab_get_project` | Read-only query |
| `gitlab_list_group_projects` | Read-only listing |
| `gitlab_get_file_contents` | Read-only file access |
| `gitlab_get_tree` | Read-only directory listing |
| `gitlab_list_branches` | Read-only listing |
| `gitlab_list_commits` | Read-only history |
| `gitlab_get_commit` | Read-only query |
| `gitlab_get_commit_diff` | Read-only diff |
| `gitlab_compare` | Read-only comparison |
| `gitlab_get_project_events` | Read-only activity |
| `gitlab_list_issues` | Read-only listing |
| `gitlab_get_issue` | Read-only query |
| `gitlab_list_issue_notes` | Read-only listing |
| `gitlab_list_merge_requests` | Read-only listing |
| `gitlab_get_merge_request` | Read-only query |
| `gitlab_get_merge_request_changes` | Read-only diff |
| `gitlab_list_wiki_pages` | Read-only listing |
| `gitlab_get_wiki_page` | Read-only query |
| `gitlab_list_project_members` | Read-only listing |
| `gitlab_list_group_members` | Read-only listing |
| `gitlab_search` | Read-only search |
### Requires Confirmation (Write Operations)
These tools modify data and require explicit user confirmation:
| Tool | Confirmation Prompt |
|------|---------------------|
| `gitlab_create_or_update_file` | "Commit '{message}' to {branch}. Confirm?" |
| `gitlab_create_branch` | "Create branch '{name}' from {ref}. Confirm?" |
| `gitlab_create_issue` | "Create issue '{title}' in {project}. Confirm?" |
| `gitlab_create_merge_request` | "Create MR '{title}' ({source} -> {target}). Confirm?" |
| `gitlab_create_wiki_page` | "Create wiki page '{title}'. Confirm?" |
| `gitlab_update_wiki_page` | "Update wiki page '{slug}'. Confirm?" |
---
## CONFIRMATION EXAMPLES
### Good (Concise)
```
Commit "Update API docs" to main branch. Confirm?
```
```
Create issue "Fix broken link in README" in docs-repo. Confirm?
```
```
Create draft MR "Documentation update v2" (feature/docs -> main). Confirm?
```
### Bad (Too Verbose)
```
I'm going to use the gitlab_create_or_update_file tool to commit a file
called README.md with your changes to the main branch. The commit message
will be "Update API docs". This will modify the repository. Would you like
me to proceed with this action?
```
---
## RATE LIMIT AWARENESS
| Limit Type | Value | Mitigation |
|------------|-------|------------|
| Authenticated requests | 2000/minute | Use pagination, cache results |
| Per-user limit | Varies by plan | Batch operations when possible |
| Search requests | Lower limit | Be specific with search queries |
**When hitting rate limits, inform user:**
```
GitLab rate limit reached. I can:
1. Wait 60 seconds and retry
2. Reduce the number of results requested
3. Try a more specific query
Which would you prefer?
```
---
## VERSION & COMPATIBILITY
- **GitLab API Version:** v4
- **Minimum GitLab Version:** 13.0+
- **Self-hosted support:** Yes (set GITLAB_API_URL)
- **GitLab.com support:** Yes (default)
---
*Last Updated: December 2024*
*MCP Server Version: 1.0.0*
