@structured-world/gitlab-mcp 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Roo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,486 @@
+# GitLab MCP Server
+
+**Maintained by:** [Dmitry Prudnikov](https://github.com/polaz) | **Original Author:** [zereight](https://github.com/zereight)
+
+## @structured-world/gitlab-mcp
+
+A fork of the original [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp)
+
+![npm version](https://img.shields.io/npm/v/@structured-world/gitlab-mcp) ![npm downloads](https://img.shields.io/npm/dm/@structured-world/gitlab-mcp) ![Release](https://github.com/structured-world/gitlab-mcp/workflows/Release/badge.svg) ![Codecov](https://codecov.io/gh/structured-world/gitlab-mcp/branch/main/graph/badge.svg) [![Coverage Report](https://img.shields.io/badge/Coverage-Live%20Report-brightgreen?logo=github)](https://structured-world.github.io/gitlab-mcp/coverage/)
+
+GitLab MCP(Model Context Protocol) Server. **Includes bug fixes and improvements over the original GitLab MCP server.**
+
+This fork is actively maintained and enhanced with strict TypeScript standards, Yarn 4 support, and improved development workflows.
+
+## Requirements
+
+- **Node.js**: >=18.0.0 (required for native fetch API support)
+- **GitLab**: Compatible with GitLab.com and self-hosted instances
+
+## Usage
+
+### Using with Claude App, Cline, Roo Code, Cursor, Kilo Code
+
+When using with the Claude App, you need to set up your API key and URLs directly.
+
+#### npx
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "npx",
+      "args": ["-y", "@structured-world/gitlab-mcp"],
+      "env": {
+        "GITLAB_TOKEN": "your_gitlab_token",
+        "GITLAB_API_URL": "your_gitlab_api_url",
+        "GITLAB_PROJECT_ID": "your_project_id", // Optional: default project
+        "GITLAB_ALLOWED_PROJECT_IDS": "", // Optional: comma-separated list of allowed project IDs
+        "GITLAB_READ_ONLY_MODE": "false",
+        "USE_GITLAB_WIKI": "false", // use wiki api?
+        "USE_MILESTONE": "false", // use milestone api?
+        "USE_PIPELINE": "false", // use pipeline api?
+        "USE_VARIABLES": "true", // use variables api?
+        "SKIP_TLS_VERIFY": "false" // skip SSL cert verification (dev only)
+      }
+    }
+  }
+}
+```
+
+#### vscode .vscode/mcp.json
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "gitlab-token",
+      "description": "Gitlab Token to read API",
+      "password": true
+    }
+  ],
+  "servers": {
+    "GitLab-MCP": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@structured-world/gitlab-mcp"],
+      "env": {
+        "GITLAB_TOKEN": "${input:gitlab-token}",
+        "GITLAB_API_URL": "your-fancy-gitlab-url",
+        "GITLAB_READ_ONLY_MODE": "true",
+        ...
+      }
+    }
+  }
+}
+```
+
+#### Docker
+
+- stdio mcp.json
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITLAB_TOKEN",
+        "-e",
+        "GITLAB_API_URL",
+        "-e",
+        "GITLAB_READ_ONLY_MODE",
+        "-e",
+        "USE_GITLAB_WIKI",
+        "-e",
+        "USE_MILESTONE",
+        "-e",
+        "USE_PIPELINE",
+        "-e",
+        "USE_VARIABLES",
+        "ghcr.io/structured-world/gitlab-mcp:latest"
+      ],
+      "env": {
+        "GITLAB_TOKEN": "your_gitlab_token",
+        "GITLAB_API_URL": "https://gitlab.com", // Optional, for self-hosted GitLab
+        "GITLAB_READ_ONLY_MODE": "false",
+        "USE_GITLAB_WIKI": "true",
+        "USE_MILESTONE": "true",
+        "USE_PIPELINE": "true",
+        "USE_VARIABLES": "true"
+      }
+    }
+  }
+}
+```
+
+- sse
+
+```shell
+docker run -i --rm \
+  -e GITLAB_TOKEN=your_gitlab_token \
+  -e GITLAB_API_URL="https://gitlab.com" \
+  -e GITLAB_READ_ONLY_MODE=true \
+  -e USE_GITLAB_WIKI=true \
+  -e USE_MILESTONE=true \
+  -e USE_PIPELINE=true \
+  -e SSE=true \
+  -p 3333:3002 \
+  ghcr.io/structured-world/gitlab-mcp:latest
+```
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "type": "sse",
+      "url": "http://localhost:3333/sse"
+    }
+  }
+}
+```
+
+- streamable-http
+
+```shell
+docker run -i --rm \
+  -e GITLAB_TOKEN=your_gitlab_token \
+  -e GITLAB_API_URL="https://gitlab.com" \
+  -e GITLAB_READ_ONLY_MODE=true \
+  -e USE_GITLAB_WIKI=true \
+  -e USE_MILESTONE=true \
+  -e USE_PIPELINE=true \
+  -e STREAMABLE_HTTP=true \
+  -p 3333:3002 \
+  ghcr.io/structured-world/gitlab-mcp:latest
+```
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "type": "streamable-http",
+      "url": "http://localhost:3333/mcp"
+    }
+  }
+}
+```
+
+### Environment Variables
+
+- `GITLAB_TOKEN`: Your GitLab personal access token.
+- `GITLAB_API_URL`: Your GitLab API URL. (Default: `https://gitlab.com`)
+- `GITLAB_PROJECT_ID`: Default project ID. If set, Overwrite this value when making an API request.
+- `GITLAB_ALLOWED_PROJECT_IDS`: Optional comma-separated list of allowed project IDs. When set with a single value, acts as a default project (like the old "lock" mode). When set with multiple values, restricts access to only those projects. Examples:
+  - Single value `123`: MCP server can only access project 123 and uses it as default
+  - Multiple values `123,456,789`: MCP server can access projects 123, 456, and 789 but requires explicit project ID in requests
+- `GITLAB_READ_ONLY_MODE`: When set to 'true', restricts the server to only expose read-only operations. Useful for enhanced security or when write access is not needed. Also useful for using with Cursor and it's 40 tool limit.
+- `GITLAB_DENIED_TOOLS_REGEX`: When set as a regular expression, it excludes the matching tools.
+- `USE_GITLAB_WIKI`: When set to 'true', enables the wiki-related tools (list_wiki_pages, get_wiki_page, create_wiki_page, update_wiki_page, delete_wiki_page). Supports both project-level and group-level wikis. By default, wiki features are disabled.
+- `USE_MILESTONE`: When set to 'true', enables the milestone-related tools (list_milestones, get_milestone, create_milestone, edit_milestone, delete_milestone, get_milestone_issue, get_milestone_merge_requests, promote_milestone, get_milestone_burndown_events). By default, milestone features are disabled.
+- `USE_PIPELINE`: When set to 'true', enables the pipeline-related tools (list_pipelines, get_pipeline, list_pipeline_jobs, list_pipeline_trigger_jobs, get_pipeline_job, get_pipeline_job_output, create_pipeline, retry_pipeline, cancel_pipeline, play_pipeline_job, retry_pipeline_job, cancel_pipeline_job). By default, pipeline features are disabled.
+- `USE_LABELS`: When set to 'true', enables the label-related tools (list_labels, get_label, create_label, update_label, delete_label). By default, label features are enabled.
+- `USE_MRS`: When set to 'true', enables the merge request-related tools (list_merge_requests, get_merge_request, create_merge_request, update_merge_request, merge_merge_request, get_merge_request_diffs, list_merge_request_diffs, mr_discussions, create_merge_request_thread, create_merge_request_note, update_merge_request_note, create_draft_note, update_draft_note, delete_draft_note, publish_draft_note, bulk_publish_draft_notes, get_draft_note, list_draft_notes). By default, merge request features are enabled.
+- `USE_FILES`: When set to 'true', enables the file-related tools (get_file_contents, get_repository_tree, create_or_update_file, push_files, upload_markdown). By default, file operation features are enabled.
+- `USE_VARIABLES`: When set to 'true', enables the CI/CD variables-related tools (list_variables, get_variable, create_variable, update_variable, delete_variable). Supports both project-level and group-level variables. By default, variables features are enabled.
+- `GITLAB_AUTH_COOKIE_PATH`: Path to an authentication cookie file for GitLab instances that require cookie-based authentication. When provided, the cookie will be included in all GitLab API requests.
+- `SKIP_TLS_VERIFY`: When set to 'true', skips TLS certificate verification for all GitLab API requests (both REST and GraphQL). **WARNING**: This bypasses SSL certificate validation and should only be used for testing with self-signed certificates or trusted internal GitLab instances. Never use this in production environments.
+- `SSE`: When set to 'true', enables the Server-Sent Events transport.
+- `STREAMABLE_HTTP`: When set to 'true', enables the Streamable HTTP transport. If both **SSE** and **STREAMABLE_HTTP** are set to 'true', the server will prioritize Streamable HTTP over SSE transport.
+
+### Dynamic Tool Description Customization
+
+You can customize tool descriptions at runtime using environment variables following the pattern `GITLAB_TOOL_{TOOL_NAME}`. This is useful for:
+
+- Providing context-specific descriptions for your team
+- Translating tool descriptions to different languages
+- Adding organization-specific documentation or warnings
+- Simplifying descriptions for non-technical users
+
+#### Format
+```bash
+GITLAB_TOOL_{TOOL_NAME}="Your custom description"
+```
+
+Where `{TOOL_NAME}` is the uppercase version of the tool name with underscores preserved.
+
+#### Examples
+```bash
+# Customize the list_projects tool description
+export GITLAB_TOOL_LIST_PROJECTS="Show all available GitLab projects in our organization"
+
+# Customize the create_merge_request tool description
+export GITLAB_TOOL_CREATE_MERGE_REQUEST="Create a new MR following our team's review process"
+
+# Customize the get_file_contents tool description
+export GITLAB_TOOL_GET_FILE_CONTENTS="Read source code files from the repository"
+
+# Multiple customizations
+export GITLAB_TOOL_LIST_PROJECTS="List user projects"
+export GITLAB_TOOL_GET_PROJECT="Get project details including settings"
+export GITLAB_TOOL_CREATE_WORK_ITEM="Create tickets for our sprint planning"
+```
+
+#### Usage in Configuration Files
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "npx",
+      "args": ["-y", "@structured-world/gitlab-mcp"],
+      "env": {
+        "GITLAB_TOKEN": "your_token",
+        "GITLAB_API_URL": "https://gitlab.com",
+
+        "GITLAB_TOOL_LIST_PROJECTS": "Show our team's GitLab projects",
+        "GITLAB_TOOL_CREATE_MERGE_REQUEST": "Create MR with our review standards",
+        "GITLAB_TOOL_GET_FILE_CONTENTS": "Read code from repo"
+      }
+    }
+  }
+}
+```
+
+#### Important Notes
+
+- **Description Override Only**: Only the tool description is overridden - the tool name and functionality remain unchanged
+- **Schema Preservation**: Schema field descriptions are NOT affected - they remain hardcoded for consistency
+- **Case Sensitivity**: Tool names in environment variables must be UPPERCASE (e.g., `LIST_PROJECTS` not `list_projects`)
+- **Invalid Names**: Invalid tool names in environment variables are ignored with a warning in debug logs
+- **Content Guidelines**: Descriptions can be any valid string but should be kept concise for better UX
+- **Scope**: Works with all 86 available tools across all entities (Core, Work Items, Merge Requests, Files, etc.)
+
+## Tools 🛠️
+
+**86 Tools Available** - Organized by entity and functionality below.
+
+### Key Features:
+- **Modular Entity Architecture** - Separate entities for Labels, Merge Requests, Files, Pipelines, etc.
+- **Environment-Gated Features** - Enable/disable tool groups with USE_* environment variables
+- **Work Items Management** - Modern GraphQL API for Issues, Epics, Tasks, and more
+- **Complete GitLab API Coverage** - Repository, Merge Requests, Pipelines, Wiki, and more
+- **Tier-based Feature Detection** - Automatically enables features based on your GitLab tier
+- **Read-only Mode Support** - Safe operation mode for production environments
+
+### Migration from v2.0:
+All issue management has been migrated to the Work Items GraphQL API. The legacy REST API issue tools (`create_issue`, `update_issue`, etc.) have been removed. Use the Work Items tools (`create_work_item`, `update_work_item`, etc.) instead for better performance and more features.
+
+<details>
+<summary>Removed/Migrated Tools from v2.0</summary>
+
+The following issue-related tools have been removed and replaced by Work Items GraphQL API:
+
+- `create_issue` → Use `create_work_item` instead
+- `update_issue` → Use `update_work_item` instead
+- `delete_issue` → Use `delete_work_item` instead
+- `list_issues` → Use `list_work_items` instead
+- `my_issues` → Use `list_work_items` with assignee filter
+- `get_issue` → Use `get_work_item` instead
+- `create_issue_link` → Use `update_work_item` with LINKED_ITEMS widget
+- `delete_issue_link` → Use `update_work_item` with LINKED_ITEMS widget
+- `update_issue_note` → Use `update_work_item` with NOTES widget
+- `create_issue_note` → Use `update_work_item` with NOTES widget
+- `list_issue_links` → Use Work Items GraphQL API
+- `list_issue_discussions` → Use Work Items GraphQL API
+- `get_issue_link` → Use Work Items GraphQL API
+
+</details>
+
+## Complete Tool Reference
+
+### Legend
+- 📖 = Read-only tool (available in GITLAB_READ_ONLY_MODE)
+- ✏️ = Read/Write tool (disabled in GITLAB_READ_ONLY_MODE)
+
+### Core Tools (22 tools)
+Core GitLab functionality always available.
+
+#### Repository & Project Management
+- ✏️ **`create_repository`**: Create a new GitLab project
+- 📖 **`get_project`**: Get details of a specific project
+- 📖 **`list_projects`**: List projects accessible by the current user
+- 📖 **`search_repositories`**: Search for GitLab projects
+- 📖 **`list_group_projects`**: List projects in a GitLab group with filtering options
+- 📖 **`list_project_members`**: List members of a GitLab project
+
+#### Branch Management
+- ✏️ **`create_branch`**: Create a new branch in a GitLab project
+- 📖 **`get_branch_diffs`**: Get the changes/diffs between two branches or commits in a GitLab project
+- ✏️ **`fork_repository`**: Fork a GitLab project to your account or specified namespace
+
+#### Comments & General Notes
+- ✏️ **`create_note`**: Create a new note (comment) to an issue or merge request
+- 📖 **`download_attachment`**: Download an uploaded file from a GitLab project by secret and filename
+
+#### Commits & History
+- 📖 **`get_commit`**: Get details of a specific commit
+- 📖 **`get_commit_diff`**: Get changes/diffs of a specific commit
+- 📖 **`list_commits`**: List repository commits with filtering options
+
+#### Namespaces & Users
+- 📖 **`get_namespace`**: Get details of a namespace by ID or path
+- 📖 **`list_namespaces`**: List all namespaces available to the current user
+- 📖 **`verify_namespace`**: Verify if a namespace path exists
+- 📖 **`get_users`**: Get GitLab user details by usernames
+
+#### Events & Activity
+- 📖 **`get_project_events`**: List all visible events for a specified project. Note: before/after parameters accept date format YYYY-MM-DD only
+- 📖 **`list_events`**: List all events for the currently authenticated user. Note: before/after parameters accept date format YYYY-MM-DD only
+- 📖 **`list_group_iterations`**: List group iterations with filtering options
+
+### Labels Management (5 tools)
+Requires USE_LABELS=true environment variable (enabled by default). Supports both project and group labels.
+
+- ✏️ **`create_label`**: Create a new label in a project or group
+- ✏️ **`update_label`**: Update an existing label in a project or group
+- ✏️ **`delete_label`**: Delete a label from a project or group
+- 📖 **`get_label`**: Get a single label from a project or group
+- 📖 **`list_labels`**: List labels for a project or group
+
+### Merge Requests Management (17 tools)
+Requires USE_MRS=true environment variable (enabled by default).
+
+#### Merge Request Operations
+- ✏️ **`create_merge_request`**: Create a new merge request in a GitLab project
+- ✏️ **`update_merge_request`**: Update a merge request (Either mergeRequestIid or branchName must be provided)
+- ✏️ **`merge_merge_request`**: Merge a merge request in a GitLab project
+- 📖 **`get_merge_request`**: Get details of a merge request (Either mergeRequestIid or branchName must be provided)
+- 📖 **`get_merge_request_diffs`**: Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)
+- 📖 **`list_merge_request_diffs`**: List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)
+- 📖 **`list_merge_requests`**: List merge requests in a GitLab project with filtering options
+- 📖 **`mr_discussions`**: List discussion items for a merge request
+
+#### MR Comments & Discussions
+- ✏️ **`create_merge_request_thread`**: Create a new thread on a merge request
+- ✏️ **`create_merge_request_note`**: Add a new note to an existing merge request thread
+- ✏️ **`update_merge_request_note`**: Modify an existing merge request thread note
+
+#### MR Draft Notes
+- ✏️ **`create_draft_note`**: Create a draft note for a merge request
+- ✏️ **`update_draft_note`**: Update an existing draft note
+- ✏️ **`delete_draft_note`**: Delete a draft note
+- ✏️ **`publish_draft_note`**: Publish a single draft note
+- ✏️ **`bulk_publish_draft_notes`**: Publish all draft notes for a merge request
+- 📖 **`get_draft_note`**: Get a single draft note from a merge request
+- 📖 **`list_draft_notes`**: List draft notes for a merge request
+
+### File Operations (5 tools)
+Requires USE_FILES=true environment variable (enabled by default).
+
+- ✏️ **`create_or_update_file`**: Create or update a single file in a GitLab project
+- ✏️ **`push_files`**: Push multiple files to a GitLab project in a single commit
+- 📖 **`get_file_contents`**: Get the contents of a file or directory from a GitLab project
+- 📖 **`get_repository_tree`**: Get the repository tree for a GitLab project (list files and directories)
+- ✏️ **`upload_markdown`**: Upload a file to a GitLab project for use in markdown content
+
+### CI/CD Variables (5 tools)
+Requires USE_VARIABLES=true environment variable (enabled by default). Supports both project-level and group-level variables.
+
+- 📖 **`list_variables`**: List all CI/CD variables for a project or group with their configuration and security settings
+- 📖 **`get_variable`**: Get a specific CI/CD variable by key from a project or group, optionally filtered by environment scope
+- ✏️ **`create_variable`**: Create a new CI/CD variable for automated deployments and pipeline configuration in a project or group
+- ✏️ **`update_variable`**: Update an existing CI/CD variable's value, security settings, or configuration in a project or group
+- ✏️ **`delete_variable`**: Remove a CI/CD variable from a project or group
+
+### Work Items (6 tools)
+Modern GraphQL API for issues, epics, tasks, and more. Requires USE_WORKITEMS=true (enabled by default).
+
+- ✏️ **`create_work_item`**: Create a new work item (epic, issue, task, etc.) in a GitLab group
+- ✏️ **`update_work_item`**: Update an existing work item
+- ✏️ **`delete_work_item`**: Delete a work item
+- 📖 **`get_work_item`**: Get details of a specific work item by ID
+- 📖 **`get_work_item_types`**: Get available work item types for a group
+- 📖 **`list_work_items`**: List work items from a GitLab group with optional filtering by type
+
+### Wiki Management (5 tools)
+Requires USE_GITLAB_WIKI=true environment variable. Supports both project-level and group-level wikis.
+
+- ✏️ **`create_wiki_page`**: Create a new wiki page in a GitLab project or group
+- ✏️ **`update_wiki_page`**: Update an existing wiki page in a GitLab project or group
+- ✏️ **`delete_wiki_page`**: Delete a wiki page from a GitLab project or group
+- 📖 **`get_wiki_page`**: Get details of a specific wiki page from a project or group
+- 📖 **`list_wiki_pages`**: List wiki pages in a GitLab project or group
+
+### Milestones (9 tools)
+Requires USE_MILESTONE=true environment variable. Supports both project and group milestones.
+
+- ✏️ **`create_milestone`**: Create a new milestone in a GitLab project or group
+- ✏️ **`edit_milestone`**: Edit an existing milestone in a GitLab project or group
+- ✏️ **`delete_milestone`**: Delete a milestone from a GitLab project or group
+- ✏️ **`promote_milestone`**: Promote a project milestone to a group milestone
+- 📖 **`get_milestone`**: Get details of a specific project or group milestone
+- 📖 **`get_milestone_issue`**: Get issues associated with a specific project or group milestone
+- 📖 **`get_milestone_merge_requests`**: Get merge requests associated with a specific project or group milestone
+- 📖 **`get_milestone_burndown_events`**: Get burndown events for a specific project or group milestone
+- 📖 **`list_milestones`**: List milestones in a GitLab project or group with filtering options
+
+### Pipelines & CI/CD (12 tools)
+Requires USE_PIPELINE=true environment variable.
+
+- ✏️ **`create_pipeline`**: Create a new pipeline for a branch or tag
+- ✏️ **`retry_pipeline`**: Retry a failed or canceled pipeline
+- ✏️ **`cancel_pipeline`**: Cancel a running pipeline
+- ✏️ **`play_pipeline_job`**: Run a manual pipeline job
+- ✏️ **`retry_pipeline_job`**: Retry a failed or canceled pipeline job
+- ✏️ **`cancel_pipeline_job`**: Cancel a running pipeline job
+- 📖 **`get_pipeline`**: Get details of a specific pipeline in a GitLab project
+- 📖 **`get_pipeline_job`**: Get details of a GitLab pipeline job number
+- 📖 **`get_pipeline_job_output`**: Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage
+- 📖 **`list_pipelines`**: List pipelines in a GitLab project with filtering options
+- 📖 **`list_pipeline_jobs`**: List all jobs in a specific pipeline
+- 📖 **`list_pipeline_trigger_jobs`**: List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
+
+## Testing
+
+This project includes comprehensive integration tests that verify functionality against a real GitLab instance.
+
+### Running Tests
+
+```bash
+# Run all tests (requires .env.test configuration)
+yarn test
+
+# Run with verbose output
+yarn test --verbose
+
+# Run specific test suites
+yarn test tests/integration/data-lifecycle.test.ts
+yarn test tests/integration/schemas/workitems.test.ts
+```
+
+### Test Architecture
+
+- **200+ integration tests** running against real GitLab 18.3 Ultimate instance
+- **Data lifecycle pattern** - Creates test infrastructure once, shared across dependent tests
+- **Work Items CRUD testing** - Complete Create/Read/Update/Delete for both Issues and Epics
+- **Schema validation** - All 50+ schemas validated against real API responses
+- **Dependency chain** - Tests run in proper order using `--runInBand` for reliable results
+
+For detailed testing documentation, see [TESTING.md](TESTING.md).
+
+## 💖 Support the Project
+
+This GitLab MCP Server is developed and maintained with care for the community. If it saves you time or helps your workflow, consider supporting its continued development!
+
+<div align="center">
+
+![USDT TRC-20 Donation QR Code](assets/usdt-qr.svg)
+
+☕ **Buy me a coffee with USDT (TRC-20)**
+`TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`
+
+📱 *Scan QR code with your wallet (TronLink, Trust Wallet, Exodus, etc.)*
+
+**Every contribution helps keep this project alive and growing! 🚀**
+
+</div>
+
+---
+
+**Maintained with ❤️ by [Dmitry Prudnikov](https://github.com/polaz)**
+**Original work by [zereight](https://github.com/zereight) - Thank you for the foundation!**

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+export declare const GITLAB_TOKEN: string | undefined;
+export declare const GITLAB_AUTH_COOKIE_PATH: string | undefined;
+export declare const IS_OLD: boolean;
+export declare const GITLAB_READ_ONLY_MODE: boolean;
+export declare const GITLAB_DENIED_TOOLS_REGEX: RegExp | undefined;
+export declare const USE_GITLAB_WIKI: boolean;
+export declare const USE_MILESTONE: boolean;
+export declare const USE_PIPELINE: boolean;
+export declare const USE_WORKITEMS: boolean;
+export declare const USE_LABELS: boolean;
+export declare const USE_MRS: boolean;
+export declare const USE_FILES: boolean;
+export declare const USE_VARIABLES: boolean;
+export declare const SSE: boolean;
+export declare const STREAMABLE_HTTP: boolean;
+export declare const HOST: string;
+export declare const PORT: string | number;
+export declare const SKIP_TLS_VERIFY: boolean;
+export declare const HTTP_PROXY: string | undefined;
+export declare const HTTPS_PROXY: string | undefined;
+export declare const NODE_TLS_REJECT_UNAUTHORIZED: string | undefined;
+export declare const GITLAB_CA_CERT_PATH: string | undefined;
+export declare const GITLAB_BASE_URL: string;
+export declare const GITLAB_API_URL: string;
+export declare const GITLAB_PROJECT_ID: string | undefined;
+export declare const GITLAB_ALLOWED_PROJECT_IDS: string[];
+export declare function getEffectiveProjectId(projectId: string): string;
+declare let packageName: string;
+declare let packageVersion: string;
+export { packageName, packageVersion };
+export declare function getToolDescriptionOverrides(): Map<string, string>;

package/dist/config.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageVersion = exports.packageName = exports.GITLAB_ALLOWED_PROJECT_IDS = exports.GITLAB_PROJECT_ID = exports.GITLAB_API_URL = exports.GITLAB_BASE_URL = exports.GITLAB_CA_CERT_PATH = exports.NODE_TLS_REJECT_UNAUTHORIZED = exports.HTTPS_PROXY = exports.HTTP_PROXY = exports.SKIP_TLS_VERIFY = exports.PORT = exports.HOST = exports.STREAMABLE_HTTP = exports.SSE = exports.USE_VARIABLES = exports.USE_FILES = exports.USE_MRS = exports.USE_LABELS = exports.USE_WORKITEMS = exports.USE_PIPELINE = exports.USE_MILESTONE = exports.USE_GITLAB_WIKI = exports.GITLAB_DENIED_TOOLS_REGEX = exports.GITLAB_READ_ONLY_MODE = exports.IS_OLD = exports.GITLAB_AUTH_COOKIE_PATH = exports.GITLAB_TOKEN = void 0;
+exports.getEffectiveProjectId = getEffectiveProjectId;
+exports.getToolDescriptionOverrides = getToolDescriptionOverrides;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const packageJsonPath = path.resolve(process.cwd(), 'package.json');
+exports.GITLAB_TOKEN = process.env.GITLAB_TOKEN;
+exports.GITLAB_AUTH_COOKIE_PATH = process.env.GITLAB_AUTH_COOKIE_PATH;
+exports.IS_OLD = process.env.GITLAB_IS_OLD === 'true';
+exports.GITLAB_READ_ONLY_MODE = process.env.GITLAB_READ_ONLY_MODE === 'true';
+exports.GITLAB_DENIED_TOOLS_REGEX = process.env.GITLAB_DENIED_TOOLS_REGEX
+    ? new RegExp(process.env.GITLAB_DENIED_TOOLS_REGEX)
+    : undefined;
+exports.USE_GITLAB_WIKI = process.env.USE_GITLAB_WIKI !== 'false';
+exports.USE_MILESTONE = process.env.USE_MILESTONE !== 'false';
+exports.USE_PIPELINE = process.env.USE_PIPELINE !== 'false';
+exports.USE_WORKITEMS = process.env.USE_WORKITEMS !== 'false';
+exports.USE_LABELS = process.env.USE_LABELS !== 'false';
+exports.USE_MRS = process.env.USE_MRS !== 'false';
+exports.USE_FILES = process.env.USE_FILES !== 'false';
+exports.USE_VARIABLES = process.env.USE_VARIABLES !== 'false';
+exports.SSE = process.env.SSE === 'true';
+exports.STREAMABLE_HTTP = process.env.STREAMABLE_HTTP === 'true';
+exports.HOST = process.env.HOST ?? '0.0.0.0';
+exports.PORT = process.env.PORT ?? 3002;
+exports.SKIP_TLS_VERIFY = process.env.SKIP_TLS_VERIFY === 'true';
+exports.HTTP_PROXY = process.env.HTTP_PROXY;
+exports.HTTPS_PROXY = process.env.HTTPS_PROXY;
+exports.NODE_TLS_REJECT_UNAUTHORIZED = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+exports.GITLAB_CA_CERT_PATH = process.env.GITLAB_CA_CERT_PATH;
+function normalizeGitLabBaseUrl(url) {
+    if (!url) {
+        return 'https://gitlab.com';
+    }
+    if (url.endsWith('/')) {
+        url = url.slice(0, -1);
+    }
+    if (url.endsWith('/api/v4')) {
+        url = url.slice(0, -7);
+    }
+    return url;
+}
+exports.GITLAB_BASE_URL = normalizeGitLabBaseUrl(process.env.GITLAB_API_URL ?? '');
+exports.GITLAB_API_URL = `${exports.GITLAB_BASE_URL}/api/v4`;
+exports.GITLAB_PROJECT_ID = process.env.GITLAB_PROJECT_ID;
+exports.GITLAB_ALLOWED_PROJECT_IDS = process.env.GITLAB_ALLOWED_PROJECT_IDS?.split(',').map((id) => id.trim()) ?? [];
+function getEffectiveProjectId(projectId) {
+    if (exports.GITLAB_PROJECT_ID) {
+        return exports.GITLAB_PROJECT_ID;
+    }
+    if (exports.GITLAB_ALLOWED_PROJECT_IDS.length > 0) {
+        if (!exports.GITLAB_ALLOWED_PROJECT_IDS.includes(projectId)) {
+            throw new Error(`Project ID ${projectId} is not allowed. Allowed project IDs: ${exports.GITLAB_ALLOWED_PROJECT_IDS.join(', ')}`);
+        }
+    }
+    return projectId;
+}
+let packageName = 'gitlab-mcp';
+exports.packageName = packageName;
+let packageVersion = 'unknown';
+exports.packageVersion = packageVersion;
+try {
+    const packageInfo = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    exports.packageName = packageName = packageInfo.name ?? packageName;
+    exports.packageVersion = packageVersion = packageInfo.version ?? packageVersion;
+}
+catch {
+}
+function getToolDescriptionOverrides() {
+    const overrides = new Map();
+    const prefix = 'GITLAB_TOOL_';
+    for (const [key, value] of Object.entries(process.env)) {
+        if (key.startsWith(prefix) && value) {
+            const toolName = key.substring(prefix.length).toLowerCase();
+            overrides.set(toolName, value);
+        }
+    }
+    return overrides;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,sDAcC;AAwBD,kEAgBC;AAjHD,2CAA6B;AAC7B,uCAAyB;AAEzB,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAC;AAGvD,QAAA,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;AACxC,QAAA,uBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;AAC9D,QAAA,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,MAAM,CAAC;AAC9C,QAAA,qBAAqB,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,MAAM,CAAC;AACrE,QAAA,yBAAyB,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB;IAC5E,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IACnD,CAAC,CAAC,SAAS,CAAC;AACD,QAAA,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,OAAO,CAAC;AAC1D,QAAA,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,OAAO,CAAC;AACtD,QAAA,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,OAAO,CAAC;AACpD,QAAA,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,OAAO,CAAC;AACtD,QAAA,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,KAAK,OAAO,CAAC;AAChD,QAAA,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,KAAK,OAAO,CAAC;AAC1C,QAAA,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,OAAO,CAAC;AAC9C,QAAA,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,OAAO,CAAC;AACtD,QAAA,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,MAAM,CAAC;AACjC,QAAA,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,MAAM,CAAC;AACzD,QAAA,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,SAAS,CAAC;AACrC,QAAA,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC;AAGhC,QAAA,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,MAAM,CAAC;AAGzD,QAAA,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;AACpC,QAAA,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;AACtC,QAAA,4BAA4B,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC;AACxE,QAAA,mBAAmB,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;AAGnE,SAAS,sBAAsB,CAAC,GAAY;IAC1C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAGD,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAEY,QAAA,eAAe,GAAG,sBAAsB,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;AAC3E,QAAA,cAAc,GAAG,GAAG,uBAAe,SAAS,CAAC;AAC7C,QAAA,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;AAClD,QAAA,0BAA0B,GACrC,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;AAElF,SAAgB,qBAAqB,CAAC,SAAiB;IACrD,IAAI,yBAAiB,EAAE,CAAC;QACtB,OAAO,yBAAiB,CAAC;IAC3B,CAAC;IAED,IAAI,kCAA0B,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,kCAA0B,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CACb,cAAc,SAAS,yCAAyC,kCAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACxG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAGD,IAAI,WAAW,GAAG,YAAY,CAAC;AActB,kCAAW;AAbpB,IAAI,cAAc,GAAG,SAAS,CAAC;AAaT,wCAAc;AAXpC,IAAI,CAAC;IACH,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAGtE,CAAC;IACF,sBAAA,WAAW,GAAG,WAAW,CAAC,IAAI,IAAI,WAAW,CAAC;IAC9C,yBAAA,cAAc,GAAG,WAAW,CAAC,OAAO,IAAI,cAAc,CAAC;AACzD,CAAC;AAAC,MAAM,CAAC;AAET,CAAC;AASD,SAAgB,2BAA2B;IACzC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,MAAM,MAAM,GAAG,cAAc,CAAC;IAG9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YAGpC,MAAM,QAAQ,GAAG,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;YAE5D,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/entities/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from '../shared';
+export * from './schema-readonly';
+export * from './schema';
+export * from './registry';
+import type { ToolDefinition } from '../../types';
+export declare const coreTools: ToolDefinition[];
+export declare const coreReadOnlyTools: string[];