Research Findings

GitLab Capabilities

• REST API v4 covers all core resources: projects, issues, merge requests, repository files, pipelines, groups, users.


• GraphQL API available but more complex; REST is fine for MVP.


• Webhooks allow event‑driven reactions but not directly MCP‑compatible (can be a supplement later).


• Authentication: PAT is simplest; OAuth adds consent flow but not needed for autonomous server.

Tool Design Patterns

• Projects identified by numeric ID or URL‑encoded path (e.g., `group%2Fproject`). Normalization required.


• Issues and MRs have per‑project `iid` numbers; use `project` + `iid` to reference.


• File operations: GitLab has separate “create” and “update” endpoints requiring `sha` for updates. We can unify under `upsert_file` by checking existence first, then acting.


• CI/CD: Pipelines are triggered per ref; jobs can be played manually.


• Pagination: default 20, max 100 per page. For small instances full lists fit; for larger we need to paginate. MVP can set `per_page=100` and document limitation; later we may implement transparent multi‑page fetch.

Existing MCP Landscape

• Official MCP servers include GitHub but not GitLab.


• Community: no widely‑adopted GitLab MCP server found.


• An opportunity exists to fill this gap.

Implementation Strategy

• Build a `gitlab.Client` that wraps HTTP methods, adds token, rate limiting, retries, and pagination helpers.


• MCP server registers each tool method with a Go function that calls the client.


• Maintain a clear mapping between MCP tool params and GitLab API fields.


• Write unit tests using `httptest.Server` with canned JSON responses for each endpoint.

Security Notes

• PAT should have minimal scopes: `api` for full access; for file ops also `write_repository`; read‑only mode: `read_api` + `read_repository`.


• Do not log the token. Use structured logging that filters sensitive fields.


• If exposing web transport, protect with bearer token or bind to localhost.

Potential Enhancements

• GraphQL fallback for complex queries (e.g., fetching MR with diffs and approvals in one call).


• Webhook receiver that translates events into MCP notifications (would require long‑running agent).


• Caching layer for project lookups (reduce API calls for repeated references).


• Dry‑run mode for destructive operations (create, delete, merge).