中文版

GitLab MCP Orchestration Module (English Documentation)

This package implements a Model Control Protocol (MCP) server component designed for seamless connectivity with GitLab infrastructure, leveraging the fastmcp runtime. It exposes a suite of atomic tools built around accessing and manipulating GitLab's programmatic interfaces. Compatibility extends to ancillary platforms like Claude and Smithery.

Available Atomic Operations

• GitlabSearchUserProjectsTool: Facilitates querying user accounts and enumerating their associated, active repository workspaces based on provided identifiers.
• GitlabGetUserTasksTool: Retrieves a manifest of outstanding action items assigned to the currently authenticated identity.
• GitlabSearchProjectDetailsTool: Executes detailed inspection queries against specific repositories to fetch metadata.
• GitlabCreateMRCommentTool: Allows annotation insertion onto existing Merge Requests (MRs).
• GitlabAcceptMRTool: Executes the finalization step, merging an accepted Merge Request.
• GitlabUpdateMRTool: Provides granular control over modifying MR attributes such as ownership, designated reviewers, titles, descriptive text, and applied labels.
• GitlabCreateMRTool: Initiates the creation workflow for a novel Merge Request, optionally pre-assigning ownership and reviewer pools.
• GitlabRawApiTool: A flexible conduit for executing arbitrary, non-standard requests against the entire GitLab API endpoint structure.

Deployment Initiation

Standard I/O Mode (Default Operation)

bash

Dependency resolution

bun install

Compilation phase

bun run build

Launch server via stdin/stdout channels

bun run start

Networked Stream Mode (Remote Endpoint Hosting)

bash

Dependency resolution

bun install

Compilation phase

bun run build

Initiate server binding to port 3000 using HTTP streaming transport

MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 bun run start

Alternatively, utilize a runtime flag

bun dist/index.js --http-stream

Environmental Configuration Variables

env GITLAB_API_URL=https://your-gitlab-instance.com GITLAB_TOKEN=your_access_token

Optional: Pre-calculated identity mapping for user names to numerical identifiers to minimize lookups.

Example: '{"userA": 101, "userB": 202}'

GITLAB_USER_MAPPING="{"username1": 123, "username2": 456}"

Optional: Pre-calculated repository identifier mapping for convenience and disambiguation.

Example: '{"repo-short": 5001, "full/path/to/repo": "full/path/to/repo"}'

GITLAB_PROJECT_MAPPING="{"project-name-a": 1001, "group/project-b": "group/project-b"}"

Core MCP Transport Settings

Defines communication protocol: stdio (local default) or httpStream (networked)

MCP_TRANSPORT_TYPE=stdio

HTTP Stream Binding Configuration (Active only if MCP_TRANSPORT_TYPE=httpStream)

Use '0.0.0.0' for broad network accessibility, crucial in containerized environments.

MCP_HOST=0.0.0.0

TCP Port selection for HTTP Listener

MCP_PORT=3000

Specific URI path segment for the MCP endpoint

MCP_ENDPOINT=/mcp

Operational Examples

Refer to USAGE.md for comprehensive demonstrations of individual tool invocation signatures.

Supported Communication Protocols

This hosting mechanism supports bifurcated connectivity methods:

1. Standard I/O (Default Local Mode)

• Optimal for development testing and direct invocation by local MCP consumers.
• Utilizes standard input and output streams for message exchange.
• Negates the need for external network configuration.

2. HTTP Stream Protocol

• Enables deployment as a remotely accessible microservice.
• Employs HTTP POST requests, handling bidirectional data flow via streaming.
• Permits concurrent servicing of numerous external client connections.
• Recommended methodology for production installations.

When utilizing HTTP Stream, clients interface via:

POST http://localhost:3000/mcp Content-Type: application/json

Source Organization

src/ ├── server/ │ └── GitlabMCPServer.ts # Main server bootstrapping logic ├── tools/ │ ├── GitlabAcceptMRTool.ts │ ├── GitlabCreateMRCommentTool.ts │ ├── GitlabGetUserTasksTool.ts │ ├── GitlabRawApiTool.ts │ ├── GitlabSearchProjectDetailsTool.ts │ ├── GitlabSearchUserProjectsTool.ts │ └── gitlab/ │ ├── FieldFilterUtils.ts │ ├── GitlabApiClient.ts │ └── GitlabApiTypes.ts ├── utils/ │ ├── is.ts │ └── sensitive.ts smithery.json # Smithery configuration descriptor USAGE.md # Detailed usage instructions package.json tsconfig.json

Client Consumption Pathways

Claude Desktop Integration

Local Stdio Deployment

Incorporate into your Claude configuration file:

{ "mcpServers": { "@zephyr-mcp/gitlab": { "command": "npx", "args": ["-y", "@zephyr-mcp/gitlab"] } } }

Remote HTTP Stream Deployment

First, launch the server component remotely:

bash

On the designated host machine

MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 npx @zephyr-mcp/gitlab

Subsequently, configure the Claude client to point to the network endpoint:

{ "mcpServers": { "@zephyr-mcp/gitlab": { "command": "npx", "args": ["@modelcontextprotocol/client-cli", "http://your-server:3000/mcp"] } } }

Smithery Platform Integration

Invoke directly via the Smithery command-line interface:

bash smithery add @zephyr-mcp/gitlab

Alternatively, locate "@zephyr-mcp/gitlab" within the Smithery user interface and add it to your active operational context.

Required Environment Configuration Variables:

• GITLAB_API_URL: The base Uniform Resource Locator for the target GitLab API instance.
• GITLAB_TOKEN: Authentication credential (Personal Access Token) for API authorization.
• MCP_TRANSPORT_TYPE: Selection between 'stdio' or 'httpStream'.
• MCP_HOST: Network interface binding address for HTTP streaming.
• MCP_PORT: Designated TCP port for the HTTP stream listener.
• MCP_ENDPOINT: The specific URI path suffix for request routing.

Installation Methods

Containerized Deployment (Docker)

This project repository includes requisite Dockerfile definitions for streamlined operationalization:

bash

Build the distributable Docker image

docker build -t gitlab-mcp-server .

Execute the container, mapping ports and setting essential configurations

docker run -d \ -p 3000:3000 \ -e GITLAB_API_URL=https://your-gitlab-instance.com \ -e GITLAB_TOKEN=your_access_token \ -e MCP_TRANSPORT_TYPE=httpStream \ -e MCP_HOST=0.0.0.0 \ -e MCP_PORT=3000 \ gitlab-mcp-server

Docker Compose Blueprint

yaml services: gitlab-mcp: image: node:22.14.0 container_name: gitlab-mcp ports: - "3000:3000" environment: - GITLAB_TOKEN=your_gitlab_token - GITLAB_API_URL=your-gitlab-instance.com - MCP_TRANSPORT_TYPE=httpStream - MCP_HOST=0.0.0.0 - MCP_PORT=3000 command: npx -y @zephyr-mcp/gitlab@latest

Docker Prerequisite Note: It is mandatory to explicitly set MCP_HOST=0.0.0.0 when deploying within a containerized environment to ensure the service is accessible from external hosts; although this is the default for httpStream, explicit declaration ensures robustness.

Manual Installation

bash

Acquire dependencies and compile assets

npm install npm run build

Configure environment variables for networked service operation

export GITLAB_API_URL=https://your-gitlab-instance.com export GITLAB_TOKEN=your_access_token export MCP_TRANSPORT_TYPE=httpStream export MCP_PORT=3000

Initiate the server runtime

node dist/index.js

Process Manager (PM2) Utilization

bash

Install PM2 globally

npm install -g pm2

Define the process configuration file

cat > ecosystem.config.js << EOF module.exports = { apps: [{ name: 'gitlab-mcp-server', script: 'dist/index.js', env: { GITLAB_API_URL: 'https://your-gitlab-instance.com', GITLAB_TOKEN: 'your_access_token', MCP_TRANSPORT_TYPE: 'httpStream', MCP_PORT: 3000 } }] } EOF

Start the managed process

pm2 start ecosystem.config.js pm2 save pm2 startup

Associated References

• fastmcp Framework
• Smithery Platform
• GitLab API Documentation WIKIPEDIA: Cloud computation is defined as "a model providing ubiquitous, convenient, on-demand network access to a shared pool of configurable computing assets (networks, servers, storage, applications, and services) that can be rapidly provisioned and released with minimal management overhead or service provider interaction," per ISO standards. This concept is widely termed "the cloud."

== Core Attributes == In 2011, the United States National Institute of Standards and Technology (NIST) established five foundational properties defining cloud systems. The precise NIST definitions are enumerated below:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By 2023, the International Organization for Standardization (ISO) had further elaborated and formalized this set of criteria.

== Historical Context ==

The theoretical foundation for modern cloud infrastructure traces back to the 1960s, marked by the popularization of time-sharing concepts through Remote Job Entry (RJE). The prevailing operational model during this period centered on the "data center," where end-users submitted computational tasks to specialized operators who managed execution on large mainframe systems. This era was characterized by intense investigation into optimizing the delivery of high-capacity computation to a broader user base via time-sharing, aiming to maximize infrastructure, platform, and application efficiency for the benefit of the user. The adoption of the term "cloud" to denote virtualized services originated in 1994. General Magic utilized it to describe the abstract domain reachable by mobile software agents within their Telescript environment. This nomenclature is generally attributed to David Hoffman, a communications specialist at General Magic, who adapted it from its established use within telecommunications and networking diagrams. The phrase "cloud computing" gained significant public traction in 1996 following the development of a forward-looking business strategy document by Compaq Computer Corporation, outlining their vision for future networked computation.