# kopfrechner/gitlab-mr-mcp architecture

> Architecture diagram of the GitHub repository kopfrechner/gitlab-mr-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kopfrechner/gitlab-mr-mcp
- Repository: https://github.com/kopfrechner/gitlab-mr-mcp

## Overview

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`](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/index.js) (index.js), [`package.json`](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/package.json) (package.json), [`tests/tools.test.js`](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/tests/tools.test.js) (Tool tests), [`Dockerfile`](https://github.com/kopfrechner/gitlab-mr-mcp/tree/main/Dockerfile) (Dockerfile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["MCP side"]
  node_mcp_host(("MCP host<br/>client"))
  node_gitlab_api[("GitLab API<br/>external service")]
end

subgraph group_core["Core server"]
  node_server_entry["index.js<br/>mcp server<br/>[index.js]"]
  node_env_config["Env config<br/>runtime config"]
  node_tool_router["Tool router<br/>mcp tools"]
  node_project_tools["Project tools<br/>read tools"]
  node_mr_read_tools["MR reads<br/>read tools"]
  node_mr_write_tools["MR writes<br/>write tools"]
  node_issue_tools["Issue details<br/>read tool"]
  node_result_norm["Normalize results<br/>response shaping"]
end

subgraph group_delivery["Delivery"]
  node_package_json["package.json<br/>node package<br/>[package.json]"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_smithery_yaml["smithery.yaml<br/>smithery package<br/>[smithery.yaml]"]
end

subgraph group_quality["Quality"]
  node_ci_workflows["CI workflows<br/>automation<br/>[ci.yml]"]
  node_dependabot["Dependabot<br/>automation<br/>[dependabot.yml]"]
  node_tool_tests["Tool tests<br/>test suite<br/>[tools.test.js]"]
end

node_mcp_host -->|"invoke tools"| node_server_entry
node_server_entry -->|"load config"| node_env_config
node_server_entry -->|"register"| node_tool_router
node_tool_router -->|"projects"| node_project_tools
node_tool_router -->|"read MRs"| node_mr_read_tools
node_tool_router -->|"write MRs"| node_mr_write_tools
node_tool_router -->|"issues"| node_issue_tools
node_project_tools -->|"query"| node_gitlab_api
node_mr_read_tools -->|"fetch"| node_gitlab_api
node_mr_write_tools -->|"mutate"| node_gitlab_api
node_issue_tools -->|"fetch"| node_gitlab_api
node_gitlab_api -->|"return data"| node_result_norm
node_result_norm -->|"respond"| node_mcp_host
node_package_json -.->|"npm entry"| node_server_entry
node_dockerfile -.->|"container run"| node_server_entry
node_smithery_yaml -.->|"smithery run"| node_server_entry
node_ci_workflows -.->|"run checks"| node_tool_tests
node_dependabot -.->|"update deps"| node_package_json
node_tool_tests -.->|"exercise tools"| node_server_entry

click node_server_entry "https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/index.js"
click node_package_json "https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/package.json"
click node_dockerfile "https://github.com/kopfrechner/gitlab-mr-mcp/tree/main/Dockerfile"
click node_smithery_yaml "https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/smithery.yaml"
click node_ci_workflows "https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/.github/workflows/ci.yml"
click node_dependabot "https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/.github/dependabot.yml"
click node_tool_tests "https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/tests/tools.test.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_host,node_gitlab_api toneBlue
class node_server_entry,node_env_config,node_tool_router,node_project_tools,node_mr_read_tools,node_mr_write_tools,node_issue_tools,node_result_norm toneAmber
class node_package_json,node_dockerfile,node_smithery_yaml toneMint
class node_ci_workflows,node_dependabot,node_tool_tests toneRose
```

## Components

### MCP side

External MCP hosts and the protocol-facing server boundary.

- **MCP host**: client · Claude Desktop or another MCP client invoking tools.
- **GitLab API**: external service · REST API used for all durable state and authorization decisions.

### Core server

Stateless request translation between MCP tools and GitLab.

- [index.js](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/index.js): mcp server · Main entrypoint that registers tools and handles protocol requests. · `index.js`
- **Env config**: runtime config · Required GitLab host/token plus optional project filters.
- **Tool router**: mcp tools · Dispatches MCP tool calls to GitLab-backed operations.
- **Project tools**: read tools · Lists projects and applies access-level or search filters.
- **MR reads**: read tools · Fetches merge request lists, details, comments, and diffs.
- **MR writes**: write tools · Adds comments and edits merge request title or description.
- **Issue details**: read tool · Fetches issue details from GitLab.
- **Normalize results**: response shaping · Formats GitLab data into MCP-friendly responses.

### Delivery

Packaging and deployment wrappers for running the server.

- [package.json](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/package.json): node package · Declares dependencies and npm scripts. · `package.json`
- [Dockerfile](https://github.com/kopfrechner/gitlab-mr-mcp/tree/main/Dockerfile): container build · Containerizes the server for portable execution. · `Dockerfile`
- [smithery.yaml](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/smithery.yaml): smithery package · Defines Smithery distribution and install metadata. · `smithery.yaml`

### Quality

Validation and automated checks around the tool contract.

- [CI workflows](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/.github/workflows/ci.yml): automation · GitHub Actions for validation and dependency maintenance. · `.github/workflows/ci.yml`
- [Dependabot](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/.github/dependabot.yml): automation · Automated dependency update configuration and merge workflow. · `.github/dependabot.yml`
- [Tool tests](https://github.com/kopfrechner/gitlab-mr-mcp/blob/main/tests/tools.test.js): test suite · Validates tool behavior and response contract. · `tests/tools.test.js`

## Connections

- 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.
