gitlab-mcp 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +45 -34
  2. package/dist/config/env.d.ts +7 -1
  3. package/dist/config/env.js +17 -0
  4. package/dist/config/env.js.map +1 -1
  5. package/dist/http-app.js +422 -17
  6. package/dist/http-app.js.map +1 -1
  7. package/dist/http.js +10 -1
  8. package/dist/http.js.map +1 -1
  9. package/dist/index.js +8 -1
  10. package/dist/index.js.map +1 -1
  11. package/dist/lib/download-token.d.ts +24 -0
  12. package/dist/lib/download-token.js +84 -0
  13. package/dist/lib/download-token.js.map +1 -0
  14. package/dist/lib/gitlab-client.d.ts +78 -1
  15. package/dist/lib/gitlab-client.js +451 -7
  16. package/dist/lib/gitlab-client.js.map +1 -1
  17. package/dist/lib/http-auth-guard.d.ts +8 -0
  18. package/dist/lib/http-auth-guard.js +19 -0
  19. package/dist/lib/http-auth-guard.js.map +1 -0
  20. package/dist/lib/mcp-oauth-provider.d.ts +2 -0
  21. package/dist/lib/mcp-oauth-provider.js +61 -0
  22. package/dist/lib/mcp-oauth-provider.js.map +1 -0
  23. package/dist/lib/oauth.d.ts +3 -1
  24. package/dist/lib/oauth.js +5 -5
  25. package/dist/lib/oauth.js.map +1 -1
  26. package/dist/lib/patch-helper.d.ts +13 -0
  27. package/dist/lib/patch-helper.js +156 -0
  28. package/dist/lib/patch-helper.js.map +1 -0
  29. package/dist/lib/request-runtime.d.ts +1 -0
  30. package/dist/lib/request-runtime.js +42 -4
  31. package/dist/lib/request-runtime.js.map +1 -1
  32. package/dist/lib/tool-schema.js +1 -1
  33. package/dist/lib/tool-schema.js.map +1 -1
  34. package/dist/tools/gitlab.js +2690 -52
  35. package/dist/tools/gitlab.js.map +1 -1
  36. package/docs/authentication.md +37 -8
  37. package/docs/configuration.md +7 -4
  38. package/docs/tools.md +153 -51
  39. package/package.json +1 -1
package/docs/authentication.md CHANGED
@@ -8,9 +8,10 @@ gitlab-mcp supports multiple authentication methods. Token behavior depends on w
8
8
 
9
9
  ```
10
10
  Static PAT (GITLAB_PERSONAL_ACCESS_TOKEN)
11
- └─> OAuth 2.0 PKCE
12
- └─> External token script
13
- └─> Token file
11
+ └─> CI job token (GITLAB_JOB_TOKEN)
12
+ └─> OAuth 2.0 PKCE
13
+ └─> External token script
14
+ └─> Token file
14
15
  ```
15
16
 
16
17
  ### Remote Authorization Mode (`REMOTE_AUTHORIZATION=true`, HTTP)
@@ -40,7 +41,20 @@ When `REMOTE_AUTHORIZATION=true`, request headers are required and PAT fallback
40
41
 
41
42
  ---
42
43
 
43
- ## 2. OAuth 2.0 PKCE
44
+ ## 2. CI Job Token
45
+
46
+ For GitLab CI contexts, set `GITLAB_JOB_TOKEN` when no personal access token is configured.
47
+ Requests use GitLab's `JOB-TOKEN` header.
48
+
49
+ ```bash
50
+ GITLAB_JOB_TOKEN="$CI_JOB_TOKEN"
51
+ ```
52
+
53
+ If both `GITLAB_PERSONAL_ACCESS_TOKEN` and `GITLAB_JOB_TOKEN` are set, the personal access token takes precedence.
54
+
55
+ ---
56
+
57
+ ## 3. OAuth 2.0 PKCE
44
58
 
45
59
  Browser-based OAuth flow for interactive use. The server launches a local callback server and opens the browser for authorization.
46
60
 
@@ -98,7 +112,7 @@ GITLAB_OAUTH_AUTO_OPEN_BROWSER=false
98
112
 
99
113
  ---
100
114
 
101
- ## 3. External Token Script
115
+ ## 4. External Token Script
102
116
 
103
117
  Execute a shell command to obtain a token dynamically. Useful for integration with secret managers, vault systems, or custom token providers.
104
118
 
@@ -149,7 +163,7 @@ The resolved token is cached for `GITLAB_TOKEN_CACHE_SECONDS` to avoid repeated
149
163
 
150
164
  ---
151
165
 
152
- ## 4. Token File
166
+ ## 5. Token File
153
167
 
154
168
  Read a token from a file on disk. The file should contain a raw token string or JSON (same format as the token script output).
155
169
 
@@ -171,7 +185,7 @@ The token is cached for `GITLAB_TOKEN_CACHE_SECONDS` (default: 300s).
171
185
 
172
186
  ---
173
187
 
174
- ## 5. Cookie-Based Auth
188
+ ## 6. Cookie-Based Auth
175
189
 
176
190
  Use browser cookies from a Netscape-format cookie file. This is useful when working with GitLab instances that use SSO or other browser-based authentication.
177
191
 
@@ -207,7 +221,7 @@ Lines starting with `#HttpOnly_` are parsed as HttpOnly cookies.
207
221
 
208
222
  ---
209
223
 
210
- ## 6. Remote Authorization (HTTP Mode)
224
+ ## 7. Remote Authorization (HTTP Mode)
211
225
 
212
226
  In HTTP transport mode, this enables strict per-request credentials. This is the recommended approach for shared/multi-user deployments.
213
227
 
@@ -248,6 +262,21 @@ X-GitLab-API-URL: https://other-gitlab.example.com/api/v4
248
262
  4. All GitLab API calls within that request use the per-session credentials
249
263
  5. Requests missing required headers are rejected before tool execution
250
264
 
265
+ ### MCP OAuth Discovery
266
+
267
+ For clients that support MCP OAuth, enable GitLab-backed discovery/proxy endpoints:
268
+
269
+ ```bash
270
+ GITLAB_MCP_OAUTH=true
271
+ MCP_SERVER_URL=https://mcp.example.com
272
+ ```
273
+
274
+ The HTTP server then exposes OAuth metadata and authorize/token/register/revoke endpoints backed by the configured GitLab instance. `/mcp` accepts validated `Authorization: Bearer <oauth_token>` requests, while `Private-Token` and `Job-Token` headers remain supported as direct bypass headers.
275
+
276
+ ### Stateless HTTP Mode
277
+
278
+ Set `OAUTH_STATELESS_MODE=true` for multi-replica HTTP deployments where MCP session affinity is not available. The server creates a fresh Streamable HTTP transport for each request and does not store MCP sessions in memory. In `REMOTE_AUTHORIZATION` or `GITLAB_MCP_OAUTH` mode, clients must send the auth header on every request.
279
+
251
280
  ---
252
281
 
253
282
  ## Cloudflare Bypass
package/docs/configuration.md CHANGED
@@ -24,6 +24,7 @@ node dist/http.js --env-file=.env.production
24
24
  | ------------------------------ | ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
25
25
  | `GITLAB_API_URL` | string | `https://gitlab.com/api/v4` | Base API URL. Supports **comma-separated** URLs for multi-instance rotation. Each URL is automatically normalized to end with `/api/v4`. |
26
26
  | `GITLAB_PERSONAL_ACCESS_TOKEN` | string | — | Static default token for requests in default mode (`REMOTE_AUTHORIZATION=false`). If omitted, runtime can still resolve OAuth/script/file tokens. |
27
+ | `GITLAB_JOB_TOKEN` | string | — | Static CI job token fallback. Used with the `JOB-TOKEN` header only when `GITLAB_PERSONAL_ACCESS_TOKEN` is not configured. |
27
28
 
28
29
  ### Multi-Instance Example
29
30
 
@@ -35,11 +36,12 @@ The client will normalize each entry and rotate across them for load distributio
35
36
 
36
37
  ## Authentication
37
38
 
38
- ### Personal Access Token
39
+ ### Personal Access Token and CI Job Token
39
40
 
40
- | Variable | Type | Default | Description |
41
- | ------------------------------ | ------ | ------- | ------------------------------------------------------------------- |
42
- | `GITLAB_PERSONAL_ACCESS_TOKEN` | string | — | Token with `api` scope. Used as the default request token when set. |
41
+ | Variable | Type | Default | Description |
42
+ | ------------------------------ | ------ | ------- | ----------------------------------------------------------------------------- |
43
+ | `GITLAB_PERSONAL_ACCESS_TOKEN` | string | — | Token with `api` scope. Used as the default request token when set. |
44
+ | `GITLAB_JOB_TOKEN` | string | — | CI job token. Used as the default `JOB-TOKEN` only when no PAT is configured. |
43
45
 
44
46
  ### OAuth 2.0 PKCE
45
47
 
@@ -154,4 +156,5 @@ The server enforces these cross-field constraints at startup:
154
156
  - `GITLAB_USE_OAUTH=true` requires `GITLAB_OAUTH_CLIENT_ID`
155
157
  - `ENABLE_DYNAMIC_API_URL=true` requires `REMOTE_AUTHORIZATION=true`
156
158
  - `SSE=true` is not compatible with `REMOTE_AUTHORIZATION=true`
159
+ - `HTTP_HOST` values other than `127.0.0.1`, `localhost`, or `::1` cannot use a server-side `GITLAB_PERSONAL_ACCESS_TOKEN` or `GITLAB_JOB_TOKEN` unless `REMOTE_AUTHORIZATION=true`
157
160
  - `NODE_TLS_REJECT_UNAUTHORIZED=0` requires `GITLAB_ALLOW_INSECURE_TLS=true`
package/docs/tools.md CHANGED
@@ -21,13 +21,17 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
21
21
  | Tool | Mutating | Description |
22
22
  | ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
23
23
  | `gitlab_get_project` | No | Get project details by ID or path. |
24
- | `gitlab_list_projects` | No | List projects available to the current user. Supports `search`, `visibility`, `membership`, `owned`, `archived`, `order_by`, `sort`. |
24
+ | `gitlab_list_projects` | No | List projects available to the current user. Supports `search`, `topic`, `visibility`, `membership`, `owned`, `archived`, `order_by`, `sort`. |
25
25
  | `gitlab_create_repository` | **Yes** | Create a new GitLab project. Params: `name`, `description`, `visibility`, `initialize_with_readme`, `path`, `namespace_id`, `default_branch`. |
26
+ | `gitlab_create_group` | **Yes** | Create a new GitLab group or subgroup. Params: `name`, `path` (required). Supports `description`, `visibility`, `parent_id`. |
26
27
  | `gitlab_fork_repository` | **Yes** | Fork a project to another namespace. Params: `namespace`, `namespace_id`, `path`, `name`, `description`, `visibility`, `default_branch`. |
27
28
  | `gitlab_list_project_members` | No | List members of a project. Supports `query`, `user_ids`, `skip_users`, `include_inheritance`. |
28
- | `gitlab_list_group_projects` | No | List projects under a group. Params: `group_id` (required). Supports `include_subgroups`, `search`, filters. |
29
+ | `gitlab_list_group_projects` | No | List projects under a group. Params: `group_id` (required). Supports `include_subgroups`, `search`, `topic`, filters. |
29
30
  | `gitlab_list_group_iterations` | No | List iterations for a group. Params: `group_id` (required). Supports `state`, `search`, date filters. |
30
31
  | `gitlab_search_repositories` | No | Search repositories by keyword. Params: `search` (required). |
32
+ | `gitlab_search_code` | No | Search code globally. Params: `search` (required). Supports `filename`, `path`, `extension`, pagination. |
33
+ | `gitlab_search_project_code` | No | Search code in a project. Params: `project_id`, `search` (required). Supports `ref`, `filename`, `path`, `extension`, pagination. |
34
+ | `gitlab_search_group_code` | No | Search code in a group. Params: `group_id`, `search` (required). Supports `filename`, `path`, `extension`, pagination. |
31
35
 
32
36
  ---
33
37
 
@@ -36,6 +40,8 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
36
40
  | Tool | Mutating | Description |
37
41
  | ------------------------- | -------- | -------------------------------------------------------------------------------- |
38
42
  | `gitlab_get_users` | No | Search users. Supports `username`, `search`, `active`, `extern_uid`, `provider`. |
43
+ | `gitlab_get_user` | No | Get one user by ID. Params: `user_id` (required). |
44
+ | `gitlab_whoami` | No | Get the current authenticated user. |
39
45
  | `gitlab_list_namespaces` | No | List namespaces visible to user. Supports `search`, `owned`. |
40
46
  | `gitlab_get_namespace` | No | Get namespace by ID or path. Params: `namespace_id_or_path` or `namespace_id`. |
41
47
  | `gitlab_verify_namespace` | No | Verify if a namespace path exists. Params: `path` (required). |
@@ -51,44 +57,63 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
51
57
 
52
58
  ---
53
59
 
60
+ ## Webhooks
61
+
62
+ | Tool | Mutating | Description |
63
+ | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
64
+ | `gitlab_list_webhooks` | No | List webhooks for exactly one `project_id` or `group_id`. Supports pagination. |
65
+ | `gitlab_list_webhook_events` | No | List recent webhook events for `hook_id`. Supports `status`, `summary`, `page`, `per_page` (max 20). |
66
+ | `gitlab_get_webhook_event` | No | Find one webhook event by `event_id`. Supports direct `page`; otherwise scans up to 500 most recent events. |
67
+
68
+ ---
69
+
54
70
  ## Repository & Files
55
71
 
56
72
  | Tool | Mutating | Description |
57
73
  | ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
- | `gitlab_get_repository_tree` | No | List files and directories. Supports `path`, `ref`, `recursive`. |
59
- | `gitlab_get_file_contents` | No | Get file by path and ref. Params: `file_path` (required), `ref` (defaults to project's default branch). |
74
+ | `gitlab_get_repository_tree` | No | List files and directories. Supports `path`, `ref`, `recursive`, and pagination. Keyset responses include `next_page_token` when GitLab returns one. |
75
+ | `gitlab_get_file_contents` | No | Get file by path and ref. Params: `file_path` (required), `ref` (defaults to project's default branch). Set `decode_base64` to return UTF-8 text for GitLab base64 file payloads. |
76
+ | `gitlab_get_file_blame` | No | Get git blame for a file. Params: `file_path`, `ref` (required). Supports paired `range_start` and `range_end`. |
60
77
  | `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`. |
61
78
  | `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. |
62
79
  | `gitlab_create_branch` | **Yes** | Create a new branch. Params: `branch` (required), `ref` (defaults to default branch). |
80
+ | `gitlab_list_branches` | No | List repository branches. Supports `search`, `regex`, `sort`, and pagination. |
81
+ | `gitlab_get_branch` | No | Get details for one branch. Params: `branch` (required). |
82
+ | `gitlab_delete_branch` | **Yes** | Delete a repository branch. Params: `branch` (required). |
63
83
  | `gitlab_get_branch_diffs` | No | Compare two branches/refs and return diffs. Params: `from`, `to` (required), `straight`, `excluded_file_patterns`. |
64
- | `gitlab_search_code_blobs` | No | Search code in a project. Params: `search` (required), `ref`. |
84
+ | `gitlab_search_code_blobs` | No | Search code in a project. Params: `search` (required), `ref`. Also supports `filename`, `path`, `extension`. |
65
85
 
66
86
  ---
67
87
 
68
88
  ## Commits
69
89
 
70
- | Tool | Mutating | Description |
71
- | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------- |
72
- | `gitlab_list_commits` | No | List commits. Supports `ref_name`, `since`, `until`, `path`, `author`, `all`, `with_stats`, `order`. |
73
- | `gitlab_get_commit` | No | Get one commit by SHA. Params: `sha` (required), `stats`. |
74
- | `gitlab_get_commit_diff` | No | Get diff for one commit. Params: `sha` (required), `full_diff`. |
90
+ | Tool | Mutating | Description |
91
+ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
92
+ | `gitlab_list_commits` | No | List commits. Supports `ref_name`, `since`, `until`, `path`, `author`, `all`, `with_stats`, `order`. |
93
+ | `gitlab_get_commit` | No | Get one commit by SHA. Params: `sha` (required), `stats`. |
94
+ | `gitlab_get_commit_diff` | No | Get diff for one commit. Params: `sha` (required), `full_diff`. |
95
+ | `gitlab_list_commit_statuses` | No | List statuses for a commit. Params: `sha` (required). Supports `ref`, `stage`, `name`, `pipeline_id`, `all`, sorting, and pagination. |
96
+ | `gitlab_create_commit_status` | **Yes** | Create or update commit status. Params: `sha`, `state` (required). Supports `ref`, `name` or `context`, `target_url`, `description`, `coverage`. |
75
97
 
76
98
  ---
77
99
 
78
100
  ## Merge Requests
79
101
 
80
- | Tool | Mutating | Description |
81
- | ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
82
- | `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`. |
83
- | `gitlab_get_merge_request` | No | Get one MR. Params: `merge_request_iid` or `source_branch`. |
84
- | `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`. |
85
- | `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`. |
86
- | `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`. |
87
- | `gitlab_get_merge_request_diffs` | No | Get MR diffs with changed files. Supports `view` (`inline`/`parallel`), `excluded_file_patterns`. |
88
- | `gitlab_list_merge_request_diffs` | No | List detailed MR diffs (versions/changes view). Supports `unidiff`. |
89
- | `gitlab_list_merge_request_versions` | No | List MR diff versions. |
90
- | `gitlab_get_merge_request_version` | No | Get one MR diff version. Params: `version_id` (required), `unidiff`. |
91
- | `gitlab_get_merge_request_conflicts` | No | Get merge request conflict details from GitLab's conflicts endpoint. |
102
+ | Tool | Mutating | Description |
103
+ | ----------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
104
+ | `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`. |
105
+ | `gitlab_get_merge_request` | No | Get one MR. Includes diverged commit count when GitLab returns it, plus commit addition and approval summaries. Params: `merge_request_iid` or `source_branch`. |
106
+ | `gitlab_list_merge_request_pipelines` | No | List pipelines associated with an MR. Params: `merge_request_iid` (required), supports pagination. |
107
+ | `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`. |
108
+ | `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`. |
109
+ | `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`. |
110
+ | `gitlab_get_merge_request_diffs` | No | Get MR diffs with changed files. Supports `view` (`inline`/`parallel`), `excluded_file_patterns`. |
111
+ | `gitlab_list_merge_request_changed_files` | No | Step 1 for large MR review: list changed file paths and flags without diff content. Supports `merge_request_iid` or `source_branch`, plus `excluded_file_patterns`. |
112
+ | `gitlab_list_merge_request_diffs` | No | List detailed MR diffs (versions/changes view). Supports `unidiff`. |
113
+ | `gitlab_get_merge_request_file_diff` | No | Step 2 for large MR review: fetch diffs for specific `file_paths`. Supports batching and `unidiff`. |
114
+ | `gitlab_list_merge_request_versions` | No | List MR diff versions. |
115
+ | `gitlab_get_merge_request_version` | No | Get one MR diff version. Params: `version_id` (required), `unidiff`. |
116
+ | `gitlab_get_merge_request_conflicts` | No | Get merge request conflict details from GitLab's conflicts endpoint. |
92
117
 
93
118
  ### MR Code Context
94
119
 
@@ -116,11 +141,11 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
116
141
 
117
142
  ### MR Approvals
118
143
 
119
- | Tool | Mutating | Description |
120
- | ----------------------------------------- | -------- | --------------------------------------------------- |
121
- | `gitlab_approve_merge_request` | **Yes** | Approve an MR. Supports `sha`, `approval_password`. |
122
- | `gitlab_unapprove_merge_request` | **Yes** | Remove current user's approval from an MR. |
123
- | `gitlab_get_merge_request_approval_state` | No | Get approval state for an MR. |
144
+ | Tool | Mutating | Description |
145
+ | ----------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
146
+ | `gitlab_approve_merge_request` | **Yes** | Approve an MR. Supports `sha`, `approval_password`. |
147
+ | `gitlab_unapprove_merge_request` | **Yes** | Remove current user's approval from an MR. |
148
+ | `gitlab_get_merge_request_approval_state` | No | Get approval state for an MR, with approvals fallback when `approval_state` is unavailable. |
124
149
 
125
150
  ---
126
151
 
@@ -150,6 +175,17 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
150
175
  | `gitlab_delete_merge_request_note` | **Yes** | Delete a top-level MR note permanently. Irreversible. Requires `merge_request_iid`, `note_id`. Pre-check with `get_merge_request_note` or `list_merge_request_notes`. |
151
176
  | `gitlab_create_note` | **Yes** | Create a note on an issue or MR. Params: `noteable_type` (`issue`/`merge_request`), `noteable_iid`, `body` (required). |
152
177
 
178
+ ### MR Emoji Reactions
179
+
180
+ | Tool | Mutating | Description |
181
+ | ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
182
+ | `gitlab_list_merge_request_emoji_reactions` | No | List emoji reactions on an MR. Params: `merge_request_iid` (required). |
183
+ | `gitlab_list_merge_request_note_emoji_reactions` | No | List emoji reactions on an MR note. Params: `merge_request_iid`, `note_id` (required). Supports `discussion_id`. |
184
+ | `gitlab_create_merge_request_emoji_reaction` | **Yes** | Add an emoji reaction to an MR. Params: `merge_request_iid`, `name` (required). |
185
+ | `gitlab_delete_merge_request_emoji_reaction` | **Yes** | Delete an emoji reaction from an MR. Irreversible for that reaction. Params: `merge_request_iid`, `award_id` (required). |
186
+ | `gitlab_create_merge_request_note_emoji_reaction` | **Yes** | Add an emoji reaction to an MR note. Params: `merge_request_iid`, `note_id`, `name` (required). Supports `discussion_id`. |
187
+ | `gitlab_delete_merge_request_note_emoji_reaction` | **Yes** | Delete an emoji reaction from an MR note. Irreversible for that reaction. Params: `merge_request_iid`, `note_id`, `award_id`. |
188
+
153
189
  ---
154
190
 
155
191
  ## Draft Notes
@@ -168,17 +204,37 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
168
204
 
169
205
  ## Issues
170
206
 
171
- | Tool | Mutating | Description |
172
- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
173
- | `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. |
174
- | `gitlab_my_issues` | No | List issues assigned to the current user. Supports `state`, `labels`, `search`, date filters. |
175
- | `gitlab_get_issue` | No | Get issue by IID. |
176
- | `gitlab_create_issue` | **Yes** | Create an issue. Params: `title` (required). Supports `description`, `labels`, `milestone_id`, `due_date`, `confidential`, `issue_type`, `assignee_ids`. |
177
- | `gitlab_update_issue` | **Yes** | Update issue fields. Supports `title`, `description`, `state_event`, `labels`, `assignee_ids`, `weight`, `issue_type`, `discussion_locked`. |
178
- | `gitlab_delete_issue` | **Yes** | Delete an issue permanently. Irreversible. Requires `issue_iid`. Pre-check with `get_issue`. |
179
- | `gitlab_list_issue_discussions` | No | List issue discussions. |
180
- | `gitlab_create_issue_note` | **Yes** | Create issue comment. Params: `body` (required). Supports `discussion_id` (to reply to thread), `created_at`. |
181
- | `gitlab_update_issue_note` | **Yes** | Update an issue note. Provide either `body` or `resolved` (not both). |
207
+ | Tool | Mutating | Description |
208
+ | --------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
209
+ | `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. |
210
+ | `gitlab_my_issues` | No | List issues assigned to the current user. Supports `state`, `labels`, `search`, date filters. |
211
+ | `gitlab_get_issue` | No | Get issue by IID. |
212
+ | `gitlab_create_issue` | **Yes** | Create an issue. Params: `title` (required). Supports `description`, `labels`, `milestone_id`, `due_date`, `confidential`, `issue_type`, `assignee_ids`. |
213
+ | `gitlab_update_issue` | **Yes** | Update issue fields. Supports `title`, `description`, `state_event`, `labels`, `assignee_ids`, `weight`, `issue_type`, `discussion_locked`. |
214
+ | `gitlab_update_issue_description_patch` | **Yes** | Apply `search_replace` or `unified_diff` patch to an issue description. Supports `dry_run`, `create_note`, `allow_multiple`. |
215
+ | `gitlab_delete_issue` | **Yes** | Delete an issue permanently. Irreversible. Requires `issue_iid`. Pre-check with `get_issue`. |
216
+ | `gitlab_list_issue_discussions` | No | List issue discussions. |
217
+ | `gitlab_create_issue_note` | **Yes** | Create issue comment. Params: `body` (required). Supports `discussion_id` (to reply to thread), `created_at`. |
218
+ | `gitlab_update_issue_note` | **Yes** | Update an issue note. Provide either `body` or `resolved` (not both). |
219
+
220
+ ### Issue Emoji Reactions
221
+
222
+ | Tool | Mutating | Description |
223
+ | ----------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
224
+ | `gitlab_list_issue_emoji_reactions` | No | List emoji reactions on an issue. Params: `issue_iid` (required). |
225
+ | `gitlab_list_issue_note_emoji_reactions` | No | List emoji reactions on an issue note. Params: `issue_iid`, `note_id` (required). Supports `discussion_id`. |
226
+ | `gitlab_create_issue_emoji_reaction` | **Yes** | Add an emoji reaction to an issue. Params: `issue_iid`, `name` (required). |
227
+ | `gitlab_delete_issue_emoji_reaction` | **Yes** | Delete an emoji reaction from an issue. Irreversible for that reaction. Params: `issue_iid`, `award_id` (required). |
228
+ | `gitlab_create_issue_note_emoji_reaction` | **Yes** | Add an emoji reaction to an issue note. Params: `issue_iid`, `note_id`, `name` (required). Supports `discussion_id`. |
229
+ | `gitlab_delete_issue_note_emoji_reaction` | **Yes** | Delete an emoji reaction from an issue note. Irreversible for that reaction. Params: `issue_iid`, `note_id`, `award_id`. |
230
+
231
+ ### Todos
232
+
233
+ | Tool | Mutating | Description |
234
+ | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
235
+ | `gitlab_list_todos` | No | List to-do items for the current user. Supports `action`, `author_id`, `project_id`, `group_id`, `state`, `type`, pagination. |
236
+ | `gitlab_mark_todo_done` | **Yes** | Mark one to-do item as done. Params: `todo_id` (required). |
237
+ | `gitlab_mark_all_todos_done` | **Yes** | Mark all pending to-do items as done for the current authenticated user. |
182
238
 
183
239
  ### Issue Links
184
240
 
@@ -195,13 +251,18 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
195
251
 
196
252
  Requires `USE_GITLAB_WIKI=true` (default).
197
253
 
198
- | Tool | Mutating | Description |
199
- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
200
- | `gitlab_list_wiki_pages` | No | List wiki pages. Supports `with_content`. |
201
- | `gitlab_get_wiki_page` | No | Get wiki page by slug. Supports `version`. |
202
- | `gitlab_create_wiki_page` | **Yes** | Create a wiki page. Params: `title`, `content` (required). Supports `format` (`markdown`, `rdoc`, `asciidoc`, `org`). |
203
- | `gitlab_update_wiki_page` | **Yes** | Update wiki page by slug. Params: `slug`, `content` (required). Supports `title`, `format`. |
204
- | `gitlab_delete_wiki_page` | **Yes** | Delete a wiki page permanently. Irreversible. Requires `slug`. Pre-check with `get_wiki_page` or `list_wiki_pages`. |
254
+ | Tool | Mutating | Description |
255
+ | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
256
+ | `gitlab_list_wiki_pages` | No | List wiki pages. Supports `with_content`. |
257
+ | `gitlab_get_wiki_page` | No | Get wiki page by slug. Supports `version`. |
258
+ | `gitlab_create_wiki_page` | **Yes** | Create a wiki page. Params: `title`, `content` (required). Supports `format` (`markdown`, `rdoc`, `asciidoc`, `org`). |
259
+ | `gitlab_update_wiki_page` | **Yes** | Update wiki page by slug. Params: `slug`, `content` (required). Supports `title`, `format`. |
260
+ | `gitlab_delete_wiki_page` | **Yes** | Delete a wiki page permanently. Irreversible. Requires `slug`. Pre-check with `get_wiki_page` or `list_wiki_pages`. |
261
+ | `gitlab_list_group_wiki_pages` | No | List group wiki pages. Params: `group_id` (required). Supports `with_content`, pagination. |
262
+ | `gitlab_get_group_wiki_page` | No | Get group wiki page by slug. Params: `group_id`, `slug` (required). Supports `version`. |
263
+ | `gitlab_create_group_wiki_page` | **Yes** | Create a group wiki page. Params: `group_id`, `title`, `content` (required). Supports `format`. |
264
+ | `gitlab_update_group_wiki_page` | **Yes** | Update a group wiki page. Params: `group_id`, `slug` (required). Supports `title`, `content`, `format`. |
265
+ | `gitlab_delete_group_wiki_page` | **Yes** | Delete a group wiki page permanently. Irreversible. Requires `group_id`, `slug`. Pre-check with group wiki get/list. |
205
266
 
206
267
  ---
207
268
 
@@ -221,8 +282,10 @@ Requires `USE_PIPELINE=true` (default).
221
282
  | `gitlab_list_pipeline_trigger_jobs` | No | List downstream/bridge trigger jobs in a pipeline. |
222
283
  | `gitlab_get_pipeline_job` | No | Get one job by ID. |
223
284
  | `gitlab_get_pipeline_job_output` | No | Get raw job trace/log output. |
285
+ | `gitlab_validate_ci_lint` | No | Validate provided GitLab CI/CD YAML content. Supports `dry_run`, `include_jobs`, and `ref`. |
286
+ | `gitlab_validate_project_ci_lint` | No | Validate the project's existing CI/CD config. Supports `content_ref`, `dry_run`, `dry_run_ref`, and `include_jobs`. |
224
287
  | `gitlab_list_job_artifacts` | No | List files and directories inside a job artifacts archive. Supports `path`, `recursive`. |
225
- | `gitlab_download_job_artifacts` | No | Download the full artifacts archive as base64 content. |
288
+ | `gitlab_download_job_artifacts` | No | Download the full artifacts archive as base64 content on local transports. HTTP remote mode returns a short-lived `download_url`. |
226
289
  | `gitlab_download_job_artifacts_local` | **Yes** | Download the full artifacts archive to a local directory. Supports `local_path`. Available only on local transports; not exposed over HTTP. |
227
290
  | `gitlab_get_job_artifact_file` | No | Return one file from a job artifacts archive as inline content. Text-like files are UTF-8; binary files are base64. |
228
291
  | `gitlab_get_job_artifact_file_local` | **Yes** | Save one file from a job artifacts archive to a local directory. Supports `local_path`. Available only on local transports; not exposed over HTTP. |
@@ -266,7 +329,19 @@ Requires `USE_RELEASE=true` (default).
266
329
  | `gitlab_update_release` | **Yes** | Update existing release. |
267
330
  | `gitlab_delete_release` | **Yes** | Delete the release entry for `tag_name` permanently. Irreversible for the release record. Pre-check with `get_release` or `list_releases`. |
268
331
  | `gitlab_create_release_evidence` | **Yes** | Create evidence for an existing release. |
269
- | `gitlab_download_release_asset` | No | Download a release asset. Params: `tag_name`, `direct_asset_path` (required). |
332
+ | `gitlab_download_release_asset` | No | Download a release asset. Params: `tag_name`, `direct_asset_path` (required). HTTP remote mode returns a short-lived `download_url`. |
333
+
334
+ ---
335
+
336
+ ## Tags
337
+
338
+ | Tool | Mutating | Description |
339
+ | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
340
+ | `gitlab_list_tags` | No | List repository tags. Supports `order_by`, `sort`, `search`, and pagination. |
341
+ | `gitlab_get_tag` | No | Get one repository tag by name. Params: `tag_name` (required). |
342
+ | `gitlab_create_tag` | **Yes** | Create a repository tag. Params: `tag_name`, `ref` (required). Supports optional `message` for annotated tags. |
343
+ | `gitlab_delete_tag` | **Yes** | Delete a repository tag permanently. Irreversible. Requires `tag_name`. Pre-check with `get_tag` or `list_tags`. |
344
+ | `gitlab_get_tag_signature` | No | Get the X.509 signature for a signed repository tag. Params: `tag_name` (required). |
270
345
 
271
346
  ---
272
347
 
@@ -284,10 +359,37 @@ Requires `USE_RELEASE=true` (default).
284
359
 
285
360
  ## Uploads & Attachments
286
361
 
287
- | Tool | Mutating | Description |
288
- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
289
- | `gitlab_upload_markdown` | **Yes** | Upload markdown file/attachment to project. Provide either `file_path` (local file) or `content` with `filename`. |
290
- | `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. |
362
+ | Tool | Mutating | Description |
363
+ | ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
364
+ | `gitlab_upload_markdown` | **Yes** | Upload markdown file/attachment to project. Provide either `file_path` (local file) or `content` with `filename`; HTTP remote mode rejects `file_path` and requires inline `content`. |
365
+ | `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). HTTP remote mode returns a short-lived `download_url` for project upload paths. |
366
+
367
+ ---
368
+
369
+ ## Work Items
370
+
371
+ These tools use GitLab GraphQL and are hidden when `GITLAB_ALLOWED_PROJECT_IDS` is configured unless `GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE=true`.
372
+
373
+ | Tool | Mutating | Description |
374
+ | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
375
+ | `gitlab_get_work_item` | No | Get a work item with status, hierarchy, labels, assignees, linked items, custom fields, timeline-related widgets, and development data. |
376
+ | `gitlab_list_work_items` | No | List work items in a project. Supports `types`, `state`, `search`, `assignee_usernames`, `label_names`, `first`, and cursor `after`. |
377
+ | `gitlab_create_work_item` | **Yes** | Create a work item. Supports all GitLab work item types plus description, labels, assignees, parent, weight, dates, milestone, iteration, confidentiality. |
378
+ | `gitlab_update_work_item` | **Yes** | Update fields, labels, assignees, state, status, hierarchy, linked items, custom fields, dates, milestone, iteration, and incident severity/escalation. |
379
+ | `gitlab_convert_work_item_type` | **Yes** | Convert a work item to another type. Params: `iid`, `new_type` (required). |
380
+ | `gitlab_list_work_item_statuses` | No | List statuses, conversion types, and allowed hierarchy types for a work item type. |
381
+ | `gitlab_list_custom_field_definitions` | No | List custom field IDs, types, select options, and supported work item types. |
382
+ | `gitlab_move_work_item` | **Yes** | Move a work item to another project. Params: `iid`, `target_project_id` (required). |
383
+ | `gitlab_list_work_item_notes` | No | List threaded work item discussions and notes with pagination. |
384
+ | `gitlab_create_work_item_note` | **Yes** | Add a work item note or threaded reply. Supports `internal` and `discussion_id`. |
385
+ | `gitlab_list_work_item_emoji_reactions` | No | List emoji reactions on a work item. |
386
+ | `gitlab_list_work_item_note_emoji_reactions` | No | List emoji reactions on a work item note by GraphQL `note_id`. |
387
+ | `gitlab_create_work_item_emoji_reaction` | **Yes** | Add an emoji reaction to a work item. Params: `iid`, `name` (required). |
388
+ | `gitlab_delete_work_item_emoji_reaction` | **Yes** | Remove the current user's emoji reaction from a work item by emoji name. |
389
+ | `gitlab_create_work_item_note_emoji_reaction` | **Yes** | Add an emoji reaction to a work item note by GraphQL `note_id`. |
390
+ | `gitlab_delete_work_item_note_emoji_reaction` | **Yes** | Remove the current user's emoji reaction from a work item note by GraphQL `note_id` and emoji name. |
391
+ | `gitlab_get_timeline_events` | No | List incident timeline events. Params: `incident_iid` (required). |
392
+ | `gitlab_create_timeline_event` | **Yes** | Create an incident timeline event. Params: `incident_iid`, `note`, `occurred_at` (required), optional `tag_names`. |
291
393
 
292
394
  ---
293
395
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gitlab-mcp",
3
- "version": "1.4.0",
3
+ "version": "1.5.0",
4
4
  "description": "A MCP server for GitLab",
5
5
  "type": "module",
6
6
  "bin": {