How kopfrechner/gitlab-mr-mcp works
1. This repository is a small, single-service Node.js application that implements a Model Context Protocol (MCP) server for GitLab. The main entrypoint is index.js, and the project has no separate backend/frontend split, database, or worker processes.
2. The core architectural boundary is: MCP clients on one side, GitLab’s REST API on the other. The server translates MCP tool calls into GitLab operations and returns normalized results back to the client. All durable state lives in GitLab; the server itself is stateless.
3. The exposed surface is a set of MCP tools for GitLab merge requests and issues. The tools cover read operations (get_projects, list_open_merge_requests, get_merge_request_details, get_merge_request_comments, get_merge_request_diff, get_issue_details) and write operations (add_merge_request_comment, add_merge_request_diff_comment, set_merge_request_title, set_merge_request_description).
4. The data flow is straightforward: an MCP host invokes a tool, the server reads configuration from environment variables, calls the GitLab API using the configured token and host, then formats the response for the MCP protocol. Comment and edit tools feed back into GitLab immediately; there is no intermediate storage layer.
5. Configuration is environment-driven. MR_MCP_GITLAB_TOKEN and MR_MCP_GITLAB_HOST are required, and optional filters such as MR_MCP_MIN_ACCESS_LEVEL and MR_MCP_PROJECT_SEARCH_TERM constrain what get_projects returns. This makes the runtime portable across local execution, Claude Desktop, and Smithery-managed installs.
6. The project is designed around GitLab-specific access control and permissions. The README calls out API scopes and project access as a primary operational dependency, so authorization failures are expected to surface directly from GitLab rather than being abstracted away by the server.
7. Tests are concentrated in tests/tools.test.js, suggesting the repo focuses on validating tool behavior and contract shape rather than a broad application stack. This is consistent with an MCP server where correctness mostly means “tool names, inputs, and GitLab responses are handled properly.”
8. Tooling and delivery are intentionally lightweight: package.json/package-lock.json define the Node package, Dockerfile supports containerized execution, and smithery.yaml enables packaging for Smithery distribution. These artifacts indicate the server can be launched in multiple deployment modes without changing architecture.
9. GitHub Actions in .github/workflows provide CI and Dependabot automation. That implies the repo’s operational model is standard npm-based validation plus dependency maintenance, with no custom build pipeline beyond install/test/package checks.
10. From an architecture-diagram perspective, the important boxes are:
- MCP client / host
- index.js MCP server
- GitLab REST API
- Environment configuration
- Test suite
- Distribution/deployment wrappers: Docker and Smithery
11. The system is intentionally narrow in scope: it is not a general GitLab integration platform, but a protocol adapter for AI agents to inspect and mutate merge requests and issues. That makes the main design pattern “thin stateless server over external API.”
Main entry points: index.js index.js · package.json package.json · tools.test.js Tool tests · Dockerfile Dockerfile
Components 16
MCP side
External MCP hosts and the protocol-facing server boundary.
- MCP host · Claude Desktop or another MCP client invoking tools.
- GitLab API · REST API used for all durable state and authorization decisions.
Core server
Stateless request translation between MCP tools and GitLab.
- index.js · Main entrypoint that registers tools and handles protocol requests.
index.js - Env config · Required GitLab host/token plus optional project filters.
- Tool router · Dispatches MCP tool calls to GitLab-backed operations.
- Project tools · Lists projects and applies access-level or search filters.
- MR reads · Fetches merge request lists, details, comments, and diffs.
- MR writes · Adds comments and edits merge request title or description.
- Issue details · Fetches issue details from GitLab.
- Normalize results · Formats GitLab data into MCP-friendly responses.
Delivery
Packaging and deployment wrappers for running the server.
- package.json · Declares dependencies and npm scripts.
package.json - Dockerfile · Containerizes the server for portable execution.
Dockerfile - smithery.yaml · Defines Smithery distribution and install metadata.
smithery.yaml
Quality
Validation and automated checks around the tool contract.
- CI workflows · GitHub Actions for validation and dependency maintenance.
.github/workflows/ci.yml - Dependabot · Automated dependency update configuration and merge workflow.
.github/dependabot.yml - Tool tests · Validates tool behavior and response contract.
tests/tools.test.js
Connections 19
- MCP host → index.js: invoke tools · An MCP client sends tool calls to the server.
- index.js → Env config: load config · The entrypoint reads GitLab host, token, and filters from the environment.
- index.js → Tool router: register · The server wires incoming protocol requests to tool handlers.
- Tool router → Project tools: projects · Routes project discovery requests.
- Tool router → MR reads: read MRs · Routes merge request read operations.
- Tool router → MR writes: write MRs · Routes merge request mutation operations.
- Tool router → Issue details: issues · Routes issue detail requests.
- Project tools → GitLab API: query · Uses GitLab project listing and permission checks.
- MR reads → GitLab API: fetch · Reads merge request data, comments, and diffs from GitLab.
- MR writes → GitLab API: mutate · Sends comments and field updates back to GitLab immediately.
- Issue details → GitLab API: fetch · Retrieves issue details from GitLab.
- GitLab API → Normalize results: return data · Raw API responses are normalized before being sent to the client.
- Normalize results → MCP host: respond · The server returns protocol-shaped results to the MCP host.
- package.json → index.js: npm entry · Defines the package and launch scripts for the server.
- Dockerfile → index.js: container run · Builds a container image that executes the Node server.
- smithery.yaml → index.js: smithery run · Packages the server for Smithery-managed installs.
- CI workflows → Tool tests: run checks · CI validates the repository with automated tests.
- Dependabot → package.json: update deps · Keeps npm dependencies current through automation.
- Tool tests → index.js: exercise tools · Tests focus on tool contracts and behavior exposed by the server.