gitlab-mcp 1.2.1 → 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 (52) hide show
  1. package/README.md +36 -29
  2. package/dist/config/dotenv.js +6 -2
  3. package/dist/config/dotenv.js.map +1 -1
  4. package/dist/config/env.d.ts +5 -2
  5. package/dist/config/env.js +27 -1
  6. package/dist/config/env.js.map +1 -1
  7. package/dist/http-app.js +10 -3
  8. package/dist/http-app.js.map +1 -1
  9. package/dist/http.js +6 -4
  10. package/dist/http.js.map +1 -1
  11. package/dist/index.js +6 -4
  12. package/dist/index.js.map +1 -1
  13. package/dist/lib/auth-context.d.ts +2 -1
  14. package/dist/lib/auth-context.js.map +1 -1
  15. package/dist/lib/gitlab-client.d.ts +42 -8
  16. package/dist/lib/gitlab-client.js +380 -42
  17. package/dist/lib/gitlab-client.js.map +1 -1
  18. package/dist/lib/network.js +12 -6
  19. package/dist/lib/network.js.map +1 -1
  20. package/dist/lib/oauth-scopes.d.ts +2 -0
  21. package/dist/lib/oauth-scopes.js +16 -0
  22. package/dist/lib/oauth-scopes.js.map +1 -0
  23. package/dist/lib/policy.d.ts +5 -1
  24. package/dist/lib/policy.js +11 -1
  25. package/dist/lib/policy.js.map +1 -1
  26. package/dist/lib/regex.d.ts +5 -0
  27. package/dist/lib/regex.js +111 -0
  28. package/dist/lib/regex.js.map +1 -0
  29. package/dist/lib/request-runtime.js +24 -11
  30. package/dist/lib/request-runtime.js.map +1 -1
  31. package/dist/lib/tool-capabilities.d.ts +3 -0
  32. package/dist/lib/tool-capabilities.js +3 -0
  33. package/dist/lib/tool-capabilities.js.map +1 -0
  34. package/dist/lib/tool-schema.d.ts +14 -0
  35. package/dist/lib/tool-schema.js +52 -0
  36. package/dist/lib/tool-schema.js.map +1 -0
  37. package/dist/tools/gitlab.js +496 -299
  38. package/dist/tools/gitlab.js.map +1 -1
  39. package/dist/tools/mr-code-context.d.ts +1 -1
  40. package/dist/tools/mr-code-context.js +2 -1
  41. package/dist/tools/mr-code-context.js.map +1 -1
  42. package/dist/types/auth.d.ts +1 -0
  43. package/dist/types/auth.js +2 -0
  44. package/dist/types/auth.js.map +1 -0
  45. package/dist/types/context.d.ts +1 -0
  46. package/docs/architecture.md +7 -6
  47. package/docs/authentication.md +4 -1
  48. package/docs/configuration.md +25 -22
  49. package/docs/deployment.md +9 -1
  50. package/docs/mcp-integration-testing-best-practices.md +381 -730
  51. package/docs/tools.md +76 -66
  52. package/package.json +1 -1
package/docs/configuration.md CHANGED
@@ -43,16 +43,16 @@ The client will normalize each entry and rotate across them for load distributio
43
43
 
44
44
  ### OAuth 2.0 PKCE
45
45
 
46
- | Variable | Type | Default | Description |
47
- | -------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------ |
48
- | `GITLAB_USE_OAUTH` | boolean | `false` | Enable OAuth PKCE flow. |
49
- | `GITLAB_OAUTH_CLIENT_ID` | string | — | **Required** when OAuth is enabled. Application ID from GitLab OAuth settings. |
50
- | `GITLAB_OAUTH_CLIENT_SECRET` | string | — | Optional. Required only for confidential OAuth applications. |
51
- | `GITLAB_OAUTH_GITLAB_URL` | string | derived from `GITLAB_API_URL` | GitLab base URL for OAuth endpoints (e.g. `https://gitlab.com`). |
52
- | `GITLAB_OAUTH_REDIRECT_URI` | string (URL) | `http://127.0.0.1:8765/callback` | Local callback URL for the OAuth flow. |
53
- | `GITLAB_OAUTH_SCOPES` | string | `api` | Space or comma-separated OAuth scopes. |
54
- | `GITLAB_OAUTH_TOKEN_PATH` | string | `~/.gitlab-mcp-oauth-token.json` | File path for persisting OAuth tokens. Stored with `chmod 600`. |
55
- | `GITLAB_OAUTH_AUTO_OPEN_BROWSER` | boolean | `true` | Automatically open the browser for authorization. |
46
+ | Variable | Type | Default | Description |
47
+ | -------------------------------- | ------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
48
+ | `GITLAB_USE_OAUTH` | boolean | `false` | Enable OAuth PKCE flow. |
49
+ | `GITLAB_OAUTH_CLIENT_ID` | string | — | **Required** when OAuth is enabled. Application ID from GitLab OAuth settings. |
50
+ | `GITLAB_OAUTH_CLIENT_SECRET` | string | — | Optional. Required only for confidential OAuth applications. |
51
+ | `GITLAB_OAUTH_GITLAB_URL` | string | derived from `GITLAB_API_URL` | GitLab base URL for OAuth endpoints (e.g. `https://gitlab.com`). |
52
+ | `GITLAB_OAUTH_REDIRECT_URI` | string (URL) | `http://127.0.0.1:8765/callback` | Local callback URL for the OAuth flow. |
53
+ | `GITLAB_OAUTH_SCOPES` | string | `api` (`read_api` in read-only mode) | Space or comma-separated OAuth scopes. If omitted, gitlab-mcp defaults to `read_api` when `GITLAB_READ_ONLY_MODE=true`, otherwise `api`. |
54
+ | `GITLAB_OAUTH_TOKEN_PATH` | string | `~/.gitlab-mcp-oauth-token.json` | File path for persisting OAuth tokens. Stored with `chmod 600`. |
55
+ | `GITLAB_OAUTH_AUTO_OPEN_BROWSER` | boolean | `true` | Automatically open the browser for authorization. |
56
56
 
57
57
  ### External Token Script
58
58
 
@@ -78,19 +78,20 @@ The client will normalize each entry and rotate across them for load distributio
78
78
 
79
79
  ### Remote Authorization (HTTP Mode)
80
80
 
81
- | Variable | Type | Default | Description |
82
- | ------------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
83
- | `REMOTE_AUTHORIZATION` | boolean | `false` | Require per-request tokens via `Authorization` (Bearer) or `Private-Token` headers for HTTP requests. Disables fallback auth chain. |
84
- | `ENABLE_DYNAMIC_API_URL` | boolean | `false` | Require per-request API URL via `X-GitLab-API-URL` header. Requires `REMOTE_AUTHORIZATION=true`. |
81
+ | Variable | Type | Default | Description |
82
+ | ------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
83
+ | `REMOTE_AUTHORIZATION` | boolean | `false` | Require per-request tokens via `Authorization` (Bearer), `Private-Token`, or `Job-Token` headers for HTTP requests. Disables fallback auth chain. |
84
+ | `ENABLE_DYNAMIC_API_URL` | boolean | `false` | Require per-request API URL via `X-GitLab-API-URL` header. Requires `REMOTE_AUTHORIZATION=true`. |
85
85
 
86
86
  ## Policy
87
87
 
88
88
  | Variable | Type | Default | Description |
89
89
  | ----------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
90
- | `GITLAB_READ_ONLY_MODE` | boolean | `false` | Disable all mutating tools (create, update, delete, merge, etc.). |
90
+ | `GITLAB_READ_ONLY_MODE` | boolean | `false` | Disable tools that require `write`, `delete`, or `admin` capabilities. |
91
91
  | `GITLAB_ALLOWED_PROJECT_IDS` | string | — | Comma-separated project IDs. If set, only these projects can be accessed. Empty = no restriction. |
92
92
  | `GITLAB_ALLOWED_TOOLS` | string | — | Comma-separated tool allowlist. Accepts names with or without `gitlab_` prefix (e.g. `get_project` or `gitlab_get_project`). Empty = all tools enabled. |
93
- | `GITLAB_DENIED_TOOLS_REGEX` | string | — | Regex pattern to deny tools by name (example: `^gitlab_delete_`). |
93
+ | `GITLAB_DISABLED_CAPABILITIES` | string | — | Comma-separated capability denylist. Valid values: `read`, `write`, `delete`, `admin`, `graphql`. |
94
+ | `GITLAB_DENIED_TOOLS_REGEX` | string | — | Regex pattern to deny tools by name (example: `^gitlab_delete_`). Unsafe nested-quantifier, overly long, or invalid patterns fail startup. |
94
95
  | `GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE` | boolean | `false` | Keep GraphQL tools enabled when `GITLAB_ALLOWED_PROJECT_IDS` is set. By default, GraphQL tools are disabled in project-scoped mode. |
95
96
 
96
97
  ## Feature Toggles
@@ -104,12 +105,13 @@ The client will normalize each entry and rotate across them for load distributio
104
105
 
105
106
  ## Output
106
107
 
107
- | Variable | Type | Default | Description |
108
- | --------------------------- | ---------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
109
- | `GITLAB_RESPONSE_MODE` | `json` \| `compact-json` \| `yaml` | `json` | Response serialization format. `compact-json` omits indentation. |
110
- | `GITLAB_MAX_RESPONSE_BYTES` | number | `200000` | Maximum response size in bytes (1,024–2,000,000). Responses exceeding this limit are truncated with a `[truncated N bytes]` suffix. |
111
- | `GITLAB_HTTP_TIMEOUT_MS` | number | `20000` | GitLab API request timeout in milliseconds (1,000–120,000). |
112
- | `GITLAB_ERROR_DETAIL_MODE` | `safe` \| `full` | `safe` in production, `full` otherwise | Controls error response verbosity. `safe` returns only the error message; `full` includes upstream details. |
108
+ | Variable | Type | Default | Description |
109
+ | ----------------------------- | ---------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
110
+ | `GITLAB_RESPONSE_MODE` | `json` \| `compact-json` \| `yaml` | `json` | Response serialization format. `compact-json` omits indentation. |
111
+ | `GITLAB_MAX_RESPONSE_BYTES` | number | `200000` | Maximum response size in bytes (1,024–2,000,000). Responses exceeding this limit are truncated with a `[truncated N bytes]` suffix. |
112
+ | `GITLAB_MAX_LOCAL_FILE_BYTES` | number | `250000000` | Maximum size in bytes for files saved locally by download tools such as job artifacts (1,024–2,000,000,000). |
113
+ | `GITLAB_HTTP_TIMEOUT_MS` | number | `20000` | GitLab API request timeout in milliseconds (1,000–120,000). |
114
+ | `GITLAB_ERROR_DETAIL_MODE` | `safe` \| `full` | `safe` in production, `full` otherwise | Controls error response verbosity. `safe` returns only the error message; `full` includes upstream details. |
113
115
 
114
116
  ## Network
115
117
 
@@ -117,6 +119,7 @@ The client will normalize each entry and rotate across them for load distributio
117
119
  | ------------------------------ | ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
118
120
  | `HTTP_PROXY` | string | — | HTTP proxy URL. |
119
121
  | `HTTPS_PROXY` | string | — | HTTPS proxy URL. Takes precedence over `HTTP_PROXY` for HTTPS requests. |
122
+ | `NO_PROXY` | string | — | Comma-separated host, suffix, wildcard, or `host:port` entries that bypass the configured proxy. |
120
123
  | `GITLAB_CA_CERT_PATH` | string | — | Path to a custom CA certificate file (PEM format). |
121
124
  | `NODE_TLS_REJECT_UNAUTHORIZED` | string | — | Set to `0` to disable TLS verification. **Requires** `GITLAB_ALLOW_INSECURE_TLS=true` as explicit acknowledgment. |
122
125
  | `GITLAB_ALLOW_INSECURE_TLS` | boolean | `false` | Acknowledge insecure TLS. Required when `NODE_TLS_REJECT_UNAUTHORIZED=0`. |
package/docs/deployment.md CHANGED
@@ -233,7 +233,13 @@ For safety in production environments:
233
233
  GITLAB_READ_ONLY_MODE=true
234
234
  ```
235
235
 
236
- This disables all mutating tools (create, update, delete, merge, etc.) at registration time.
236
+ This disables tools that require `write`, `delete`, or `admin` capabilities at registration time.
237
+
238
+ To disable only specific capability classes instead of going fully read-only:
239
+
240
+ ```bash
241
+ GITLAB_DISABLED_CAPABILITIES=delete,graphql
242
+ ```
237
243
 
238
244
  ### Tool Restrictions
239
245
 
@@ -250,6 +256,8 @@ GITLAB_DENIED_TOOLS_REGEX=^gitlab_(delete|create)_
250
256
  GITLAB_ALLOWED_PROJECT_IDS=123,456
251
257
  ```
252
258
 
259
+ Unsafe `GITLAB_DENIED_TOOLS_REGEX` patterns are ignored instead of failing startup.
260
+
253
261
  ---
254
262
 
255
263
  ## Multi-Instance Deployment