gitlab-mcp 0.1.5 → 1.1.0

package/docs/tools.md

@@ -0,0 +1,294 @@
+# Tools Reference
+
+This document lists all MCP tools provided by gitlab-mcp. Each tool is prefixed with `gitlab_` (except `health_check`). Tools marked as **mutating** are disabled when `GITLAB_READ_ONLY_MODE=true`.
+
+All project-scoped tools accept an optional `project_id` parameter. When `GITLAB_ALLOWED_PROJECT_IDS` is configured with a single project, `project_id` is automatically inferred.
+
+Most list endpoints support `page` and `per_page`. Notable exceptions are `gitlab_list_merge_request_versions` and `gitlab_list_draft_notes`.
+
+---
+
+## Health
+
+| Tool           | Mutating | Description                                   |
+| -------------- | -------- | --------------------------------------------- |
+| `health_check` | No       | Return server liveness and current timestamp. |
+
+---
+
+## Projects & Organization
+
+| Tool                           | Mutating | Description                                                                                                                                   |
+| ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_get_project`           | No       | Get project details by ID or path.                                                                                                            |
+| `gitlab_list_projects`         | No       | List projects available to the current user. Supports `search`, `visibility`, `membership`, `owned`, `archived`, `order_by`, `sort`.          |
+| `gitlab_create_repository`     | **Yes**  | Create a new GitLab project. Params: `name`, `description`, `visibility`, `initialize_with_readme`, `path`, `namespace_id`, `default_branch`. |
+| `gitlab_fork_repository`       | **Yes**  | Fork a project to another namespace. Params: `namespace`, `namespace_id`, `path`, `name`, `description`, `visibility`, `default_branch`.      |
+| `gitlab_list_project_members`  | No       | List members of a project. Supports `query`, `user_ids`, `skip_users`, `include_inheritance`.                                                 |
+| `gitlab_list_group_projects`   | No       | List projects under a group. Params: `group_id` (required). Supports `include_subgroups`, `search`, filters.                                  |
+| `gitlab_list_group_iterations` | No       | List iterations for a group. Params: `group_id` (required). Supports `state`, `search`, date filters.                                         |
+| `gitlab_search_repositories`   | No       | Search repositories by keyword. Params: `search` (required).                                                                                  |
+
+---
+
+## Users & Namespaces
+
+| Tool                      | Mutating | Description                                                                      |
+| ------------------------- | -------- | -------------------------------------------------------------------------------- |
+| `gitlab_get_users`        | No       | Search users. Supports `username`, `search`, `active`, `extern_uid`, `provider`. |
+| `gitlab_list_namespaces`  | No       | List namespaces visible to user. Supports `search`, `owned`.                     |
+| `gitlab_get_namespace`    | No       | Get namespace by ID or path. Params: `namespace_id_or_path` or `namespace_id`.   |
+| `gitlab_verify_namespace` | No       | Verify if a namespace path exists. Params: `path` (required).                    |
+
+---
+
+## Events
+
+| Tool                        | Mutating | Description                                                                                     |
+| --------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `gitlab_list_events`        | No       | List current user events. Supports `action`, `target_type`, `before`, `after`, `scope`, `sort`. |
+| `gitlab_get_project_events` | No       | List events for a specific project. Same filters as `list_events`.                              |
+
+---
+
+## Repository & Files
+
+| Tool                           | Mutating | Description                                                                                                                                                                                        |
+| ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_get_repository_tree`   | No       | List files and directories. Supports `path`, `ref`, `recursive`.                                                                                                                                   |
+| `gitlab_get_file_contents`     | No       | Get file by path and ref. Params: `file_path` (required), `ref` (defaults to project's default branch).                                                                                            |
+| `gitlab_create_or_update_file` | **Yes**  | Create or update a single file. Params: `file_path`, `branch`, `content`, `commit_message` (all required). Supports `encoding`, `author_email`, `author_name`, `start_branch`, `last_commit_id`.   |
+| `gitlab_push_files`            | **Yes**  | Create a commit with multiple file actions. Params: `branch`, `commit_message` (required), `actions` array (each with `action`, `file_path`, `content`, etc.). Also accepts legacy `files` format. |
+| `gitlab_create_branch`         | **Yes**  | Create a new branch. Params: `branch` (required), `ref` (defaults to default branch).                                                                                                              |
+| `gitlab_get_branch_diffs`      | No       | Compare two branches/refs and return diffs. Params: `from`, `to` (required), `straight`, `excluded_file_patterns`.                                                                                 |
+| `gitlab_search_code_blobs`     | No       | Search code in a project. Params: `search` (required), `ref`.                                                                                                                                      |
+
+---
+
+## Commits
+
+| Tool                     | Mutating | Description                                                                                          |
+| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------- |
+| `gitlab_list_commits`    | No       | List commits. Supports `ref_name`, `since`, `until`, `path`, `author`, `all`, `with_stats`, `order`. |
+| `gitlab_get_commit`      | No       | Get one commit by SHA. Params: `sha` (required), `stats`.                                            |
+| `gitlab_get_commit_diff` | No       | Get diff for one commit. Params: `sha` (required), `full_diff`.                                      |
+
+---
+
+## Merge Requests
+
+| Tool                                 | Mutating | Description                                                                                                                                                                                                                               |
+| ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_merge_requests`         | No       | List MRs. When `project_id` is omitted, lists globally. Supports `assignee_id`, `author_id`, `reviewer_id`, `state`, `labels`, `milestone`, `source_branch`, `target_branch`, `scope`, `order_by`, `sort`, date filters, `search`, `wip`. |
+| `gitlab_get_merge_request`           | No       | Get one MR. Params: `merge_request_iid` or `source_branch`.                                                                                                                                                                               |
+| `gitlab_create_merge_request`        | **Yes**  | Create an MR. Params: `source_branch`, `target_branch`, `title` (required). Supports `description`, `assignee_ids`, `reviewer_ids`, `labels`, `draft`, `squash`, `remove_source_branch`.                                                  |
+| `gitlab_update_merge_request`        | **Yes**  | Update MR fields. Params: `merge_request_iid` (required). Supports `title`, `description`, `target_branch`, `state_event`, `labels`, `assignee_ids`, `reviewer_ids`, `draft`, `squash`.                                                   |
+| `gitlab_merge_merge_request`         | **Yes**  | Merge an MR. Accepts `merge_request_iid` or `source_branch`. Supports `merge_commit_message`, `squash_commit_message`, `squash`, `should_remove_source_branch`, `merge_when_pipeline_succeeds`.                                           |
+| `gitlab_get_merge_request_diffs`     | No       | Get MR diffs with changed files. Supports `view` (`inline`/`parallel`), `excluded_file_patterns`.                                                                                                                                         |
+| `gitlab_list_merge_request_diffs`    | No       | List detailed MR diffs (versions/changes view). Supports `unidiff`.                                                                                                                                                                       |
+| `gitlab_list_merge_request_versions` | No       | List MR diff versions.                                                                                                                                                                                                                    |
+| `gitlab_get_merge_request_version`   | No       | Get one MR diff version. Params: `version_id` (required), `unidiff`.                                                                                                                                                                      |
+
+### MR Code Context
+
+| Tool                                    | Mutating | Description                                                    |
+| --------------------------------------- | -------- | -------------------------------------------------------------- |
+| `gitlab_get_merge_request_code_context` | No       | High-signal MR code context with filtering and budget control. |
+
+**Parameters:**
+
+| Parameter           | Type     | Default         | Description                                                                                             |
+| ------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------- |
+| `merge_request_iid` | string   | —               | **Required.** MR IID.                                                                                   |
+| `include_paths`     | string[] | —               | Glob patterns for files to include.                                                                     |
+| `exclude_paths`     | string[] | —               | Glob patterns for files to exclude.                                                                     |
+| `extensions`        | string[] | —               | File extension filter (e.g. `.ts`, `.py`).                                                              |
+| `languages`         | string[] | —               | Language filter (e.g. `typescript`, `python`, `go`). Maps to extensions automatically.                  |
+| `max_files`         | number   | `30`            | Maximum number of files to process (1–500).                                                             |
+| `max_total_chars`   | number   | `120000`        | Character budget (500–2,000,000). Stops fetching when budget is exhausted.                              |
+| `context_lines`     | number   | `20`            | Lines of context around changes (0–200). Used in `surrounding` mode.                                    |
+| `mode`              | enum     | `patch`         | Content mode: `patch` (raw diff), `surrounding` (changed lines with context), `fullfile` (entire file). |
+| `sort`              | enum     | `changed_lines` | Sort files by: `changed_lines`, `path`, `file_size`.                                                    |
+| `list_only`         | boolean  | `false`         | If `true`, returns file list without content (for two-stage retrieval).                                 |
+
+**Supported languages:** typescript, javascript, python, go, rust, java, kotlin, csharp, cpp, c, ruby, php, swift, scala, shell, yaml, json, markdown.
+
+### MR Approvals
+
+| Tool                                      | Mutating | Description                                         |
+| ----------------------------------------- | -------- | --------------------------------------------------- |
+| `gitlab_approve_merge_request`            | **Yes**  | Approve an MR. Supports `sha`, `approval_password`. |
+| `gitlab_unapprove_merge_request`          | **Yes**  | Remove current user's approval from an MR.          |
+| `gitlab_get_merge_request_approval_state` | No       | Get approval state for an MR.                       |
+
+---
+
+## MR Discussions
+
+| Tool                                          | Mutating | Description                                                                                                       |
+| --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_merge_request_discussions`       | No       | List MR discussions.                                                                                              |
+| `gitlab_mr_discussions`                       | No       | Alias of `list_merge_request_discussions`.                                                                        |
+| `gitlab_create_merge_request_thread`          | **Yes**  | Create a new discussion thread. Params: `body` (required). Supports `position` (for diff comments), `created_at`. |
+| `gitlab_create_merge_request_discussion_note` | **Yes**  | Reply to an existing discussion thread. Params: `discussion_id`, `body` (required).                               |
+| `gitlab_update_merge_request_discussion_note` | **Yes**  | Update a discussion note. Provide either `body` or `resolved` (not both).                                         |
+| `gitlab_delete_merge_request_discussion_note` | **Yes**  | Delete a note from a discussion thread.                                                                           |
+| `gitlab_resolve_merge_request_thread`         | **Yes**  | Resolve/unresolve a discussion note. Params: `discussion_id`, `note_id`, `resolved` (default `true`).             |
+
+---
+
+## MR Notes (Comments)
+
+| Tool                               | Mutating | Description                                                                                                            |
+| ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_merge_request_notes`  | No       | List top-level MR notes. Supports `sort`, `order_by`.                                                                  |
+| `gitlab_get_merge_request_notes`   | No       | Alias of `list_merge_request_notes`.                                                                                   |
+| `gitlab_get_merge_request_note`    | No       | Get a single MR note by ID.                                                                                            |
+| `gitlab_create_merge_request_note` | **Yes**  | Create a top-level MR comment. Params: `body` (required).                                                              |
+| `gitlab_update_merge_request_note` | **Yes**  | Update MR note body. Params: `note_id`, `body` (required).                                                             |
+| `gitlab_delete_merge_request_note` | **Yes**  | Delete an MR note.                                                                                                     |
+| `gitlab_create_note`               | **Yes**  | Create a note on an issue or MR. Params: `noteable_type` (`issue`/`merge_request`), `noteable_iid`, `body` (required). |
+
+---
+
+## Draft Notes
+
+| Tool                              | Mutating | Description                                                                                |
+| --------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
+| `gitlab_get_draft_note`           | No       | Get a single draft note.                                                                   |
+| `gitlab_list_draft_notes`         | No       | List draft notes on an MR.                                                                 |
+| `gitlab_create_draft_note`        | **Yes**  | Create a draft note. Params: `body` (required). Supports `position`, `resolve_discussion`. |
+| `gitlab_update_draft_note`        | **Yes**  | Update a draft note. At least one of `body`, `position`, or `resolve_discussion` required. |
+| `gitlab_delete_draft_note`        | **Yes**  | Delete a draft note.                                                                       |
+| `gitlab_publish_draft_note`       | **Yes**  | Publish one draft note.                                                                    |
+| `gitlab_bulk_publish_draft_notes` | **Yes**  | Publish all draft notes on an MR.                                                          |
+
+---
+
+## Issues
+
+| Tool                            | Mutating | Description                                                                                                                                                                                    |
+| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_issues`            | No       | List issues. When `project_id` is omitted, lists globally. Supports `assignee_id`, `author_id`, `state`, `labels`, `milestone`, `scope`, `search`, `issue_type`, `confidential`, date filters. |
+| `gitlab_my_issues`              | No       | List issues assigned to the current user. Supports `state`, `labels`, `search`, date filters.                                                                                                  |
+| `gitlab_get_issue`              | No       | Get issue by IID.                                                                                                                                                                              |
+| `gitlab_create_issue`           | **Yes**  | Create an issue. Params: `title` (required). Supports `description`, `labels`, `milestone_id`, `due_date`, `confidential`, `issue_type`, `assignee_ids`.                                       |
+| `gitlab_update_issue`           | **Yes**  | Update issue fields. Supports `title`, `description`, `state_event`, `labels`, `assignee_ids`, `weight`, `issue_type`, `discussion_locked`.                                                    |
+| `gitlab_delete_issue`           | **Yes**  | Delete an issue.                                                                                                                                                                               |
+| `gitlab_list_issue_discussions` | No       | List issue discussions.                                                                                                                                                                        |
+| `gitlab_create_issue_note`      | **Yes**  | Create issue comment. Params: `body` (required). Supports `discussion_id` (to reply to thread), `created_at`.                                                                                  |
+| `gitlab_update_issue_note`      | **Yes**  | Update an issue note. Provide either `body` or `resolved` (not both).                                                                                                                          |
+
+### Issue Links
+
+| Tool                       | Mutating | Description                                                                                                                                                       |
+| -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_issue_links`  | No       | List related issue links.                                                                                                                                         |
+| `gitlab_get_issue_link`    | No       | Get a single issue link by ID.                                                                                                                                    |
+| `gitlab_create_issue_link` | **Yes**  | Create a relation between two issues. Params: `target_project_id`, `target_issue_iid` (required). Supports `link_type` (`relates_to`, `blocks`, `is_blocked_by`). |
+| `gitlab_delete_issue_link` | **Yes**  | Delete a relation between issues.                                                                                                                                 |
+
+---
+
+## Wiki
+
+Requires `USE_GITLAB_WIKI=true` (default).
+
+| Tool                      | Mutating | Description                                                                                                           |
+| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_wiki_pages`  | No       | List wiki pages. Supports `with_content`.                                                                             |
+| `gitlab_get_wiki_page`    | No       | Get wiki page by slug. Supports `version`.                                                                            |
+| `gitlab_create_wiki_page` | **Yes**  | Create a wiki page. Params: `title`, `content` (required). Supports `format` (`markdown`, `rdoc`, `asciidoc`, `org`). |
+| `gitlab_update_wiki_page` | **Yes**  | Update wiki page by slug. Params: `slug`, `content` (required). Supports `title`, `format`.                           |
+| `gitlab_delete_wiki_page` | **Yes**  | Delete wiki page by slug.                                                                                             |
+
+---
+
+## Pipelines & Jobs
+
+Requires `USE_PIPELINE=true` (default).
+
+| Tool                                | Mutating | Description                                                                                                       |
+| ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_pipelines`             | No       | List pipelines. Supports `scope`, `status`, `ref`, `sha`, `username`, `source`, `order_by`, `sort`, date filters. |
+| `gitlab_get_pipeline`               | No       | Get one pipeline by ID.                                                                                           |
+| `gitlab_list_pipeline_jobs`         | No       | List jobs in a pipeline. Supports `scope`, `include_retried`.                                                     |
+| `gitlab_list_pipeline_trigger_jobs` | No       | List downstream/bridge trigger jobs in a pipeline.                                                                |
+| `gitlab_get_pipeline_job`           | No       | Get one job by ID.                                                                                                |
+| `gitlab_get_pipeline_job_output`    | No       | Get raw job trace/log output.                                                                                     |
+| `gitlab_create_pipeline`            | **Yes**  | Trigger a new pipeline. Params: `ref` (required). Supports `variables` array (`key`, `value`, `variable_type`).   |
+| `gitlab_retry_pipeline`             | **Yes**  | Retry failed jobs in a pipeline.                                                                                  |
+| `gitlab_cancel_pipeline`            | **Yes**  | Cancel a running pipeline.                                                                                        |
+| `gitlab_retry_pipeline_job`         | **Yes**  | Retry one failed job.                                                                                             |
+| `gitlab_cancel_pipeline_job`        | **Yes**  | Cancel one running job.                                                                                           |
+| `gitlab_play_pipeline_job`          | **Yes**  | Play/trigger a manual job.                                                                                        |
+
+---
+
+## Milestones
+
+Requires `USE_MILESTONE=true` (default).
+
+| Tool                                   | Mutating | Description                                                                                              |
+| -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_milestones`               | No       | List project milestones. Supports `iids`, `state`, `title`, `search`, `include_ancestors`, date filters. |
+| `gitlab_get_milestone`                 | No       | Get a milestone by ID.                                                                                   |
+| `gitlab_create_milestone`              | **Yes**  | Create a milestone. Params: `title` (required). Supports `description`, `due_date`, `start_date`.        |
+| `gitlab_update_milestone`              | **Yes**  | Update milestone fields.                                                                                 |
+| `gitlab_edit_milestone`                | **Yes**  | Alias of `update_milestone`.                                                                             |
+| `gitlab_delete_milestone`              | **Yes**  | Delete a milestone.                                                                                      |
+| `gitlab_get_milestone_issue`           | No       | List issues assigned to a milestone.                                                                     |
+| `gitlab_get_milestone_merge_requests`  | No       | List MRs assigned to a milestone.                                                                        |
+| `gitlab_promote_milestone`             | **Yes**  | Promote a project milestone to a group milestone.                                                        |
+| `gitlab_get_milestone_burndown_events` | No       | List burndown events for a milestone.                                                                    |
+
+---
+
+## Releases
+
+Requires `USE_RELEASE=true` (default).
+
+| Tool                             | Mutating | Description                                                                                                                                   |
+| -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_releases`           | No       | List project releases. Supports `order_by`, `sort`, `include_html_description`.                                                               |
+| `gitlab_get_release`             | No       | Get one release by tag name.                                                                                                                  |
+| `gitlab_create_release`          | **Yes**  | Create a release. Params: `tag_name` (required). Supports `name`, `tag_message`, `description`, `ref`, `released_at`, `milestones`, `assets`. |
+| `gitlab_update_release`          | **Yes**  | Update existing release.                                                                                                                      |
+| `gitlab_delete_release`          | **Yes**  | Delete a release by tag.                                                                                                                      |
+| `gitlab_create_release_evidence` | **Yes**  | Create evidence for an existing release.                                                                                                      |
+| `gitlab_download_release_asset`  | No       | Download a release asset. Params: `tag_name`, `direct_asset_path` (required).                                                                 |
+
+---
+
+## Labels
+
+| Tool                  | Mutating | Description                                                                                                |
+| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `gitlab_list_labels`  | No       | List project labels. Supports `with_counts`, `include_ancestor_groups`, `search`.                          |
+| `gitlab_get_label`    | No       | Get one label by ID. Supports `include_ancestor_groups`.                                                   |
+| `gitlab_create_label` | **Yes**  | Create a label. Params: `name`, `color` (required). Supports `description`, `priority`.                    |
+| `gitlab_update_label` | **Yes**  | Update a label. Identify by `name` or `label_id`. Supports `new_name`, `color`, `description`, `priority`. |
+| `gitlab_delete_label` | **Yes**  | Delete a label. Identify by `name` or `label_id`.                                                          |
+
+---
+
+## Uploads & Attachments
+
+| Tool                         | Mutating | Description                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gitlab_upload_markdown`     | **Yes**  | Upload markdown file/attachment to project. Provide either `file_path` (local file) or `content` with `filename`.                                                                                                                                                                                                                                                          |
+| `gitlab_download_attachment` | No       | Download attachment. Provide either `url_or_path` or both `secret` and `filename`. Absolute `url_or_path` must be same-origin with configured GitLab API URL. In project-scoped mode (`GITLAB_ALLOWED_PROJECT_IDS`), `url_or_path` must be a GitLab upload URL/path and `project_id` must be provided (or inferred from a single allowed project). Returns base64 content. |
+
+---
+
+## GraphQL
+
+| Tool                              | Mutating | Description                                                                                  |
+| --------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `gitlab_execute_graphql_query`    | No       | Execute a read-only GraphQL query. Rejects mutations.                                        |
+| `gitlab_execute_graphql_mutation` | **Yes**  | Execute a GraphQL mutation. Disabled in read-only mode.                                      |
+| `gitlab_execute_graphql`          | No\*     | Backward-compatible executor. Automatically detects mutations and enforces read-only policy. |
+
+\* `gitlab_execute_graphql` is registered as non-mutating but dynamically checks mutation content against the policy engine at execution time.
+
+When `GITLAB_ALLOWED_PROJECT_IDS` is configured, GraphQL tools are disabled by default. Set `GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE=true` to enable them explicitly.

package/eslint.config.js

@@ -0,0 +1,23 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import prettier from "eslint-config-prettier";
+
+export default tseslint.config(
+  {
+    ignores: ["dist/**", "coverage/**", "node_modules/**", "other/**"]
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ["**/*.ts"],
+    rules: {
+      "@typescript-eslint/consistent-type-imports": [
+        "error",
+        {
+          prefer: "type-imports"
+        }
+      ]
+    }
+  },
+  prettier
+);

package/package.json

@@ -1,44 +1,90 @@
 {
   "name": "gitlab-mcp",
-  "version": "0.1.5",
-  "description": "Model Context Protocol server for GitLab integration",
-  "main": "./build/index.js",
+  "version": "1.1.0",
+  "description": "A MCP server for GitLab",
   "type": "module",
-  "bin": {
-    "gitlab-mcp": "build/index.js"
+  "packageManager": "pnpm@10.28.1",
+  "engines": {
+    "node": ">=20.11.0"
   },
-  "files": [
-    "build"
-  ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcpland/gitlab-mcp.git"
   },
   "scripts": {
-    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
-    "prepare": "npm run build",
-    "watch": "tsc --watch",
-    "deploy": "npm publish --access public"
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx watch src/index.ts",
+    "dev:http": "tsx watch src/http.ts",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint-staged": "lint-staged",
+    "commit": "git-cz",
+    "inspector": "pnpm exec @modelcontextprotocol/inspector node dist/index.js",
+    "prepare": "husky"
   },
-  "engines": {
-    "node": ">=18.0.0"
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "fetch-cookie": "^3.2.0",
+    "open": "^11.0.0",
+    "picomatch": "^4.0.3",
+    "pino": "^10.3.1",
+    "pkce-challenge": "^6.0.0",
+    "tough-cookie": "^6.0.0",
+    "undici": "^7.21.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
   },
-  "author": "unadlib",
-  "license": "MIT",
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "1.8.0",
-    "@types/express": "^5.0.1",
-    "@types/node-fetch": "^2.6.12",
-    "@types/yargs": "^17.0.33",
-    "node-fetch": "^3.3.2",
-    "zod-to-json-schema": "^3.23.5"
+    "@eslint/js": "^9.39.2",
+    "@modelcontextprotocol/inspector": "^0.20.0",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.2.3",
+    "@types/picomatch": "^4.0.2",
+    "commitizen": "^4.3.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18"
   },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "1.8.0",
-    "@types/node-fetch": "^2.6.12",
-    "dotenv": "^16.5.0",
-    "express": "^5.1.0",
-    "node-fetch": "^3.3.2",
-    "yargs": "^17.7.2",
-    "zod-to-json-schema": "^3.23.5"
-  }
+  "lint-staged": {
+    "*.{ts,js,json,md,yml,yaml}": [
+      "prettier --write"
+    ],
+    "*.ts": [
+      "eslint --fix"
+    ]
+  },
+  "config": {
+    "commitizen": {
+      "path": "cz-conventional-changelog"
+    }
+  },
+  "keywords": [
+    "gitlab",
+    "mcp",
+    "ai",
+    "agent",
+    "tool",
+    "automation"
+  ],
+  "author": "unadlib",
+  "license": "MIT"
 }

package/scripts/get-oauth-token.example.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Example external token script for GITLAB_TOKEN_SCRIPT.
+# The MCP server accepts either:
+# 1) Raw token on stdout
+# 2) JSON: {"access_token":"..."} or {"token":"..."}
+
+if [[ -n "${GITLAB_OAUTH_ACCESS_TOKEN:-}" ]]; then
+  printf '{"access_token":"%s"}\n' "${GITLAB_OAUTH_ACCESS_TOKEN}"
+  exit 0
+fi
+
+echo "GITLAB_OAUTH_ACCESS_TOKEN is not set" >&2
+exit 1

package/src/config/env.ts

@@ -0,0 +1,171 @@
+import "dotenv/config";
+
+import { z } from "zod";
+
+const logLevelSchema = z.enum(["fatal", "error", "warn", "info", "debug", "trace", "silent"]);
+
+const responseModeSchema = z.enum(["json", "compact-json", "yaml"]);
+const errorDetailModeSchema = z.enum(["safe", "full"]);
+
+function parseBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined) {
+    return fallback;
+  }
+
+  return value.toLowerCase() === "true";
+}
+
+function parseCsv(value: string | undefined): string[] {
+  if (!value) {
+    return [];
+  }
+
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  LOG_LEVEL: logLevelSchema.default("info"),
+  MCP_SERVER_NAME: z.string().min(1).default("gitlab-mcp"),
+  MCP_SERVER_VERSION: z.string().min(1).default("0.1.0"),
+  GITLAB_API_URL: z.string().min(1).default("https://gitlab.com/api/v4"),
+  GITLAB_PERSONAL_ACCESS_TOKEN: z.string().min(1).optional(),
+  GITLAB_USE_OAUTH: z.enum(["true", "false"]).default("false"),
+  GITLAB_OAUTH_CLIENT_ID: z.string().optional(),
+  GITLAB_OAUTH_CLIENT_SECRET: z.string().optional(),
+  GITLAB_OAUTH_GITLAB_URL: z.string().optional(),
+  GITLAB_OAUTH_REDIRECT_URI: z.string().url().optional(),
+  GITLAB_OAUTH_SCOPES: z.string().default("api"),
+  GITLAB_OAUTH_TOKEN_PATH: z.string().optional(),
+  GITLAB_OAUTH_AUTO_OPEN_BROWSER: z.enum(["true", "false"]).default("true"),
+  GITLAB_READ_ONLY_MODE: z
+    .enum(["true", "false"])
+    .default("false")
+    .transform((value) => value === "true"),
+  GITLAB_ALLOWED_PROJECT_IDS: z.string().optional(),
+  GITLAB_ALLOWED_TOOLS: z.string().optional(),
+  GITLAB_DENIED_TOOLS_REGEX: z.string().optional(),
+  GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE: z.enum(["true", "false"]).default("false"),
+  GITLAB_RESPONSE_MODE: responseModeSchema.default("json"),
+  GITLAB_MAX_RESPONSE_BYTES: z.coerce.number().int().min(1024).max(2_000_000).default(200_000),
+  GITLAB_HTTP_TIMEOUT_MS: z.coerce.number().int().min(1_000).max(120_000).default(20_000),
+  GITLAB_ERROR_DETAIL_MODE: errorDetailModeSchema.optional(),
+  GITLAB_AUTH_COOKIE_PATH: z.string().optional(),
+  GITLAB_COOKIE_WARMUP_PATH: z.string().default("/user"),
+  GITLAB_CLOUDFLARE_BYPASS: z.enum(["true", "false"]).default("false"),
+  GITLAB_USER_AGENT: z.string().optional(),
+  GITLAB_ACCEPT_LANGUAGE: z.string().optional(),
+  GITLAB_TOKEN_SCRIPT: z.string().optional(),
+  GITLAB_TOKEN_SCRIPT_TIMEOUT_MS: z.coerce.number().int().min(500).max(120_000).default(10_000),
+  GITLAB_TOKEN_CACHE_SECONDS: z.coerce.number().int().min(0).max(86_400).default(300),
+  GITLAB_TOKEN_FILE: z.string().optional(),
+  GITLAB_ALLOW_INSECURE_TOKEN_FILE: z.enum(["true", "false"]).default("false"),
+  GITLAB_ALLOW_INSECURE_TLS: z.enum(["true", "false"]).default("false"),
+  NODE_TLS_REJECT_UNAUTHORIZED: z.string().optional(),
+  GITLAB_CA_CERT_PATH: z.string().optional(),
+  HTTP_PROXY: z.string().optional(),
+  HTTPS_PROXY: z.string().optional(),
+  USE_GITLAB_WIKI: z.enum(["true", "false"]).default("true"),
+  USE_MILESTONE: z.enum(["true", "false"]).default("true"),
+  USE_PIPELINE: z.enum(["true", "false"]).default("true"),
+  USE_RELEASE: z.enum(["true", "false"]).default("true"),
+  REMOTE_AUTHORIZATION: z.enum(["true", "false"]).default("false"),
+  ENABLE_DYNAMIC_API_URL: z.enum(["true", "false"]).default("false"),
+  SESSION_TIMEOUT_SECONDS: z.coerce.number().int().min(1).max(86_400).default(3_600),
+  MAX_SESSIONS: z.coerce.number().int().min(1).max(10_000).default(1_000),
+  MAX_REQUESTS_PER_MINUTE: z.coerce.number().int().min(1).max(10_000).default(300),
+  HTTP_HOST: z.string().min(1).default("127.0.0.1"),
+  HTTP_PORT: z.coerce.number().int().min(1).max(65_535).default(3333),
+  HTTP_JSON_ONLY: z.enum(["true", "false"]).default("false"),
+  SSE: z.enum(["true", "false"]).default("false")
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  const issues = parsed.error.issues
+    .map((issue) => `- ${issue.path.join(".") || "(root)"}: ${issue.message}`)
+    .join("\n");
+
+  throw new Error(`Invalid environment variables:\n${issues}`);
+}
+
+const data = parsed.data;
+const rawApiUrls = parseCsv(data.GITLAB_API_URL);
+
+if (rawApiUrls.length === 0) {
+  throw new Error("GITLAB_API_URL must contain at least one URL");
+}
+
+const normalizedApiUrls = rawApiUrls.map((item) => {
+  try {
+    return normalizeApiUrl(item);
+  } catch {
+    throw new Error(`Invalid GITLAB_API_URL entry: '${item}'`);
+  }
+});
+
+if (data.ENABLE_DYNAMIC_API_URL === "true" && data.REMOTE_AUTHORIZATION !== "true") {
+  throw new Error("ENABLE_DYNAMIC_API_URL=true requires REMOTE_AUTHORIZATION=true");
+}
+
+if (data.GITLAB_USE_OAUTH === "true" && !data.GITLAB_OAUTH_CLIENT_ID) {
+  throw new Error("GITLAB_USE_OAUTH=true requires GITLAB_OAUTH_CLIENT_ID");
+}
+
+if (data.SSE === "true" && data.REMOTE_AUTHORIZATION === "true") {
+  throw new Error("SSE=true is not compatible with REMOTE_AUTHORIZATION=true");
+}
+
+if (data.NODE_TLS_REJECT_UNAUTHORIZED === "0" && data.GITLAB_ALLOW_INSECURE_TLS !== "true") {
+  throw new Error(
+    "NODE_TLS_REJECT_UNAUTHORIZED=0 requires GITLAB_ALLOW_INSECURE_TLS=true acknowledgment"
+  );
+}
+
+export const env = {
+  ...data,
+  GITLAB_READ_ONLY_MODE: data.GITLAB_READ_ONLY_MODE,
+  GITLAB_ERROR_DETAIL_MODE:
+    data.GITLAB_ERROR_DETAIL_MODE ?? (data.NODE_ENV === "production" ? "safe" : "full"),
+  GITLAB_USE_OAUTH: parseBoolean(data.GITLAB_USE_OAUTH, false),
+  GITLAB_OAUTH_AUTO_OPEN_BROWSER: parseBoolean(data.GITLAB_OAUTH_AUTO_OPEN_BROWSER, true),
+  GITLAB_CLOUDFLARE_BYPASS: parseBoolean(data.GITLAB_CLOUDFLARE_BYPASS, false),
+  GITLAB_ALLOW_INSECURE_TOKEN_FILE: parseBoolean(data.GITLAB_ALLOW_INSECURE_TOKEN_FILE, false),
+  GITLAB_ALLOW_INSECURE_TLS: parseBoolean(data.GITLAB_ALLOW_INSECURE_TLS, false),
+  USE_GITLAB_WIKI: parseBoolean(data.USE_GITLAB_WIKI, true),
+  USE_MILESTONE: parseBoolean(data.USE_MILESTONE, true),
+  USE_PIPELINE: parseBoolean(data.USE_PIPELINE, true),
+  USE_RELEASE: parseBoolean(data.USE_RELEASE, true),
+  REMOTE_AUTHORIZATION: parseBoolean(data.REMOTE_AUTHORIZATION, false),
+  ENABLE_DYNAMIC_API_URL: parseBoolean(data.ENABLE_DYNAMIC_API_URL, false),
+  HTTP_JSON_ONLY: parseBoolean(data.HTTP_JSON_ONLY, false),
+  SSE: parseBoolean(data.SSE, false),
+  GITLAB_ALLOWED_PROJECT_IDS: parseCsv(data.GITLAB_ALLOWED_PROJECT_IDS),
+  GITLAB_ALLOWED_TOOLS: parseCsv(data.GITLAB_ALLOWED_TOOLS),
+  GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE: parseBoolean(
+    data.GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE,
+    false
+  ),
+  GITLAB_API_URLS: normalizedApiUrls,
+  GITLAB_API_URL: normalizedApiUrls[0] ?? normalizeApiUrl("https://gitlab.com/api/v4")
+};
+
+export type AppEnv = typeof env;
+
+function normalizeApiUrl(rawUrl: string): string {
+  const url = new URL(rawUrl);
+  const pathname = url.pathname.replace(/\/+$/, "");
+
+  if (pathname.endsWith("/api/v4")) {
+    url.pathname = pathname;
+    return url.toString();
+  }
+
+  url.pathname = `${pathname}/api/v4`.replace(/\/\//g, "/");
+
+  return url.toString();
+}