gitlab-mcp 1.3.0 → 1.4.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 (27) hide show
  1. package/README.md +6 -2
  2. package/dist/config/env.d.ts +2 -1
  3. package/dist/config/env.js +12 -0
  4. package/dist/config/env.js.map +1 -1
  5. package/dist/http.js +1 -0
  6. package/dist/http.js.map +1 -1
  7. package/dist/index.js +1 -0
  8. package/dist/index.js.map +1 -1
  9. package/dist/lib/policy.d.ts +5 -1
  10. package/dist/lib/policy.js +11 -1
  11. package/dist/lib/policy.js.map +1 -1
  12. package/dist/lib/tool-capabilities.d.ts +3 -0
  13. package/dist/lib/tool-capabilities.js +3 -0
  14. package/dist/lib/tool-capabilities.js.map +1 -0
  15. package/dist/lib/tool-schema.d.ts +14 -0
  16. package/dist/lib/tool-schema.js +52 -0
  17. package/dist/lib/tool-schema.js.map +1 -0
  18. package/dist/tools/gitlab.js +326 -319
  19. package/dist/tools/gitlab.js.map +1 -1
  20. package/dist/tools/mr-code-context.d.ts +1 -1
  21. package/dist/tools/mr-code-context.js +2 -1
  22. package/dist/tools/mr-code-context.js.map +1 -1
  23. package/docs/architecture.md +6 -5
  24. package/docs/configuration.md +2 -1
  25. package/docs/deployment.md +7 -1
  26. package/docs/tools.md +52 -52
  27. package/package.json +1 -1
package/docs/tools.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Tools Reference
2
2
 
3
- 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`.
3
+ This document lists all MCP tools provided by gitlab-mcp. Each tool is prefixed with `gitlab_` (except `health_check`). The **Mutating** column is a legacy shorthand for read-only mode visibility; runtime policy additionally classifies tools by capability (`read`, `write`, `delete`, `admin`, `graphql`).
4
4
 
5
5
  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.
6
6
 
@@ -126,43 +126,43 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
126
126
 
127
127
  ## MR Discussions
128
128
 
129
- | Tool | Mutating | Description |
130
- | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
131
- | `gitlab_list_merge_request_discussions` | No | List MR discussions. |
132
- | `gitlab_mr_discussions` | No | Alias of `list_merge_request_discussions`. |
133
- | `gitlab_create_merge_request_thread` | **Yes** | Create a new discussion thread. Params: `body` (required). Supports `position` (for diff comments), `created_at`. |
134
- | `gitlab_create_merge_request_discussion_note` | **Yes** | Reply to an existing discussion thread. Params: `discussion_id`, `body` (required). |
135
- | `gitlab_update_merge_request_discussion_note` | **Yes** | Update a discussion note. Provide either `body` or `resolved` (not both). |
136
- | `gitlab_delete_merge_request_discussion_note` | **Yes** | Delete a note from a discussion thread. |
137
- | `gitlab_resolve_merge_request_thread` | **Yes** | Resolve/unresolve a discussion note. Params: `discussion_id`, `note_id`, `resolved` (default `true`). |
129
+ | Tool | Mutating | Description |
130
+ | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
131
+ | `gitlab_list_merge_request_discussions` | No | List MR discussions. |
132
+ | `gitlab_mr_discussions` | No | Alias of `list_merge_request_discussions`. |
133
+ | `gitlab_create_merge_request_thread` | **Yes** | Create a new discussion thread. Params: `body` (required). Supports `position` (for diff comments), `created_at`. |
134
+ | `gitlab_create_merge_request_discussion_note` | **Yes** | Reply to an existing discussion thread. Params: `discussion_id`, `body` (required). |
135
+ | `gitlab_update_merge_request_discussion_note` | **Yes** | Update a discussion note. Provide either `body` or `resolved` (not both). |
136
+ | `gitlab_delete_merge_request_discussion_note` | **Yes** | Delete an MR discussion note permanently. Irreversible. Requires `merge_request_iid`, `discussion_id`, `note_id`. Pre-check with `list_merge_request_discussions`. |
137
+ | `gitlab_resolve_merge_request_thread` | **Yes** | Resolve/unresolve a discussion note. Params: `discussion_id`, `note_id`, `resolved` (default `true`). |
138
138
 
139
139
  ---
140
140
 
141
141
  ## MR Notes (Comments)
142
142
 
143
- | Tool | Mutating | Description |
144
- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
145
- | `gitlab_list_merge_request_notes` | No | List top-level MR notes. Supports `sort`, `order_by`. |
146
- | `gitlab_get_merge_request_notes` | No | Alias of `list_merge_request_notes`. |
147
- | `gitlab_get_merge_request_note` | No | Get a single MR note by ID. |
148
- | `gitlab_create_merge_request_note` | **Yes** | Create a top-level MR comment. Params: `body` (required). |
149
- | `gitlab_update_merge_request_note` | **Yes** | Update MR note body. Params: `note_id`, `body` (required). |
150
- | `gitlab_delete_merge_request_note` | **Yes** | Delete an MR note. |
151
- | `gitlab_create_note` | **Yes** | Create a note on an issue or MR. Params: `noteable_type` (`issue`/`merge_request`), `noteable_iid`, `body` (required). |
143
+ | Tool | Mutating | Description |
144
+ | ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
145
+ | `gitlab_list_merge_request_notes` | No | List top-level MR notes. Supports `sort`, `order_by`. |
146
+ | `gitlab_get_merge_request_notes` | No | Alias of `list_merge_request_notes`. |
147
+ | `gitlab_get_merge_request_note` | No | Get a single MR note by ID. |
148
+ | `gitlab_create_merge_request_note` | **Yes** | Create a top-level MR comment. Params: `body` (required). |
149
+ | `gitlab_update_merge_request_note` | **Yes** | Update MR note body. Params: `note_id`, `body` (required). |
150
+ | `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
+ | `gitlab_create_note` | **Yes** | Create a note on an issue or MR. Params: `noteable_type` (`issue`/`merge_request`), `noteable_iid`, `body` (required). |
152
152
 
153
153
  ---
154
154
 
155
155
  ## Draft Notes
156
156
 
157
- | Tool | Mutating | Description |
158
- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
159
- | `gitlab_get_draft_note` | No | Get a single draft note. |
160
- | `gitlab_list_draft_notes` | No | List draft notes on an MR. |
161
- | `gitlab_create_draft_note` | **Yes** | Create a draft note. Params: `body` (required). Supports `position`, `resolve_discussion`. |
162
- | `gitlab_update_draft_note` | **Yes** | Update a draft note. At least one of `body`, `position`, or `resolve_discussion` required. |
163
- | `gitlab_delete_draft_note` | **Yes** | Delete a draft note. |
164
- | `gitlab_publish_draft_note` | **Yes** | Publish one draft note. |
165
- | `gitlab_bulk_publish_draft_notes` | **Yes** | Publish all draft notes on an MR. |
157
+ | Tool | Mutating | Description |
158
+ | --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
159
+ | `gitlab_get_draft_note` | No | Get a single draft note. |
160
+ | `gitlab_list_draft_notes` | No | List draft notes on an MR. |
161
+ | `gitlab_create_draft_note` | **Yes** | Create a draft note. Params: `body` (required). Supports `position`, `resolve_discussion`. |
162
+ | `gitlab_update_draft_note` | **Yes** | Update a draft note. At least one of `body`, `position`, or `resolve_discussion` required. |
163
+ | `gitlab_delete_draft_note` | **Yes** | Delete a draft note permanently. Irreversible. Requires `merge_request_iid`, `draft_note_id`. Pre-check with `get_draft_note` or `list_draft_notes`. |
164
+ | `gitlab_publish_draft_note` | **Yes** | Publish one draft note. |
165
+ | `gitlab_bulk_publish_draft_notes` | **Yes** | Publish all draft notes on an MR. |
166
166
 
167
167
  ---
168
168
 
@@ -175,7 +175,7 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
175
175
  | `gitlab_get_issue` | No | Get issue by IID. |
176
176
  | `gitlab_create_issue` | **Yes** | Create an issue. Params: `title` (required). Supports `description`, `labels`, `milestone_id`, `due_date`, `confidential`, `issue_type`, `assignee_ids`. |
177
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. |
178
+ | `gitlab_delete_issue` | **Yes** | Delete an issue permanently. Irreversible. Requires `issue_iid`. Pre-check with `get_issue`. |
179
179
  | `gitlab_list_issue_discussions` | No | List issue discussions. |
180
180
  | `gitlab_create_issue_note` | **Yes** | Create issue comment. Params: `body` (required). Supports `discussion_id` (to reply to thread), `created_at`. |
181
181
  | `gitlab_update_issue_note` | **Yes** | Update an issue note. Provide either `body` or `resolved` (not both). |
@@ -187,7 +187,7 @@ Most list endpoints support `page` and `per_page`. Notable exceptions are `gitla
187
187
  | `gitlab_list_issue_links` | No | List related issue links. |
188
188
  | `gitlab_get_issue_link` | No | Get a single issue link by ID. |
189
189
  | `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`). |
190
- | `gitlab_delete_issue_link` | **Yes** | Delete a relation between issues. |
190
+ | `gitlab_delete_issue_link` | **Yes** | Delete an issue link permanently. Irreversible for that relation. Requires `issue_iid`, `issue_link_id`. Pre-check with `get_issue_link` or `list_issue_links`. |
191
191
 
192
192
  ---
193
193
 
@@ -201,7 +201,7 @@ Requires `USE_GITLAB_WIKI=true` (default).
201
201
  | `gitlab_get_wiki_page` | No | Get wiki page by slug. Supports `version`. |
202
202
  | `gitlab_create_wiki_page` | **Yes** | Create a wiki page. Params: `title`, `content` (required). Supports `format` (`markdown`, `rdoc`, `asciidoc`, `org`). |
203
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 wiki page by slug. |
204
+ | `gitlab_delete_wiki_page` | **Yes** | Delete a wiki page permanently. Irreversible. Requires `slug`. Pre-check with `get_wiki_page` or `list_wiki_pages`. |
205
205
 
206
206
  ---
207
207
 
@@ -239,18 +239,18 @@ Requires `USE_PIPELINE=true` (default).
239
239
 
240
240
  Requires `USE_MILESTONE=true` (default).
241
241
 
242
- | Tool | Mutating | Description |
243
- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
244
- | `gitlab_list_milestones` | No | List project milestones. Supports `iids`, `state`, `title`, `search`, `include_ancestors`, date filters. |
245
- | `gitlab_get_milestone` | No | Get a milestone by ID. |
246
- | `gitlab_create_milestone` | **Yes** | Create a milestone. Params: `title` (required). Supports `description`, `due_date`, `start_date`. |
247
- | `gitlab_update_milestone` | **Yes** | Update milestone fields. |
248
- | `gitlab_edit_milestone` | **Yes** | Alias of `update_milestone`. |
249
- | `gitlab_delete_milestone` | **Yes** | Delete a milestone. |
250
- | `gitlab_get_milestone_issue` | No | List issues assigned to a milestone. |
251
- | `gitlab_get_milestone_merge_requests` | No | List MRs assigned to a milestone. |
252
- | `gitlab_promote_milestone` | **Yes** | Promote a project milestone to a group milestone. |
253
- | `gitlab_get_milestone_burndown_events` | No | List burndown events for a milestone. |
242
+ | Tool | Mutating | Description |
243
+ | -------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
244
+ | `gitlab_list_milestones` | No | List project milestones. Supports `iids`, `state`, `title`, `search`, `include_ancestors`, date filters. |
245
+ | `gitlab_get_milestone` | No | Get a milestone by ID. |
246
+ | `gitlab_create_milestone` | **Yes** | Create a milestone. Params: `title` (required). Supports `description`, `due_date`, `start_date`. |
247
+ | `gitlab_update_milestone` | **Yes** | Update milestone fields. |
248
+ | `gitlab_edit_milestone` | **Yes** | Alias of `update_milestone`. |
249
+ | `gitlab_delete_milestone` | **Yes** | Delete a milestone permanently. Irreversible. Requires `milestone_id`. Pre-check with `get_milestone` or `list_milestones`. |
250
+ | `gitlab_get_milestone_issue` | No | List issues assigned to a milestone. |
251
+ | `gitlab_get_milestone_merge_requests` | No | List MRs assigned to a milestone. |
252
+ | `gitlab_promote_milestone` | **Yes** | Promote a project milestone to a group milestone. |
253
+ | `gitlab_get_milestone_burndown_events` | No | List burndown events for a milestone. |
254
254
 
255
255
  ---
256
256
 
@@ -264,7 +264,7 @@ Requires `USE_RELEASE=true` (default).
264
264
  | `gitlab_get_release` | No | Get one release by tag name. |
265
265
  | `gitlab_create_release` | **Yes** | Create a release. Params: `tag_name` (required). Supports `name`, `tag_message`, `description`, `ref`, `released_at`, `milestones`, `assets`. |
266
266
  | `gitlab_update_release` | **Yes** | Update existing release. |
267
- | `gitlab_delete_release` | **Yes** | Delete a release by tag. |
267
+ | `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
268
  | `gitlab_create_release_evidence` | **Yes** | Create evidence for an existing release. |
269
269
  | `gitlab_download_release_asset` | No | Download a release asset. Params: `tag_name`, `direct_asset_path` (required). |
270
270
 
@@ -272,13 +272,13 @@ Requires `USE_RELEASE=true` (default).
272
272
 
273
273
  ## Labels
274
274
 
275
- | Tool | Mutating | Description |
276
- | --------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
277
- | `gitlab_list_labels` | No | List project labels. Supports `with_counts`, `include_ancestor_groups`, `search`. |
278
- | `gitlab_get_label` | No | Get one label by ID. Supports `include_ancestor_groups`. |
279
- | `gitlab_create_label` | **Yes** | Create a label. Params: `name`, `color` (required). Supports `description`, `priority`. |
280
- | `gitlab_update_label` | **Yes** | Update a label. Identify by `name` or `label_id`. Supports `new_name`, `color`, `description`, `priority`. |
281
- | `gitlab_delete_label` | **Yes** | Delete a label. Identify by `name` or `label_id`. |
275
+ | Tool | Mutating | Description |
276
+ | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
277
+ | `gitlab_list_labels` | No | List project labels. Supports `with_counts`, `include_ancestor_groups`, `search`. |
278
+ | `gitlab_get_label` | No | Get one label by ID. Supports `include_ancestor_groups`. |
279
+ | `gitlab_create_label` | **Yes** | Create a label. Params: `name`, `color` (required). Supports `description`, `priority`. |
280
+ | `gitlab_update_label` | **Yes** | Update a label. Identify by `name` or `label_id`. Supports `new_name`, `color`, `description`, `priority`. |
281
+ | `gitlab_delete_label` | **Yes** | Delete a label permanently. Irreversible. Identify by `name` or `label_id`. Pre-check with `get_label` or `list_labels`. |
282
282
 
283
283
  ---
284
284
 
@@ -299,6 +299,6 @@ Requires `USE_RELEASE=true` (default).
299
299
  | `gitlab_execute_graphql_mutation` | **Yes** | Execute a GraphQL mutation. Disabled in read-only mode. |
300
300
  | `gitlab_execute_graphql` | No\* | Backward-compatible executor. Automatically detects mutations and enforces read-only policy. |
301
301
 
302
- \* `gitlab_execute_graphql` is registered as non-mutating but dynamically checks mutation content against the policy engine at execution time.
302
+ \* `gitlab_execute_graphql` is registered with read + graphql capability and dynamically requires write + graphql capability when the payload contains a mutation.
303
303
 
304
304
  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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gitlab-mcp",
3
- "version": "1.3.0",
3
+ "version": "1.4.0",
4
4
  "description": "A MCP server for GitLab",
5
5
  "type": "module",
6
6
  "bin": {