gitlab-mcp 1.2.0 → 1.3.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 (42) hide show
  1. package/README.md +42 -28
  2. package/dist/config/dotenv.d.ts +2 -0
  3. package/dist/config/dotenv.js +44 -0
  4. package/dist/config/dotenv.js.map +1 -0
  5. package/dist/config/env.d.ts +3 -2
  6. package/dist/config/env.js +17 -2
  7. package/dist/config/env.js.map +1 -1
  8. package/dist/http-app.js +10 -3
  9. package/dist/http-app.js.map +1 -1
  10. package/dist/http.js +5 -4
  11. package/dist/http.js.map +1 -1
  12. package/dist/index.js +5 -4
  13. package/dist/index.js.map +1 -1
  14. package/dist/lib/auth-context.d.ts +2 -1
  15. package/dist/lib/auth-context.js.map +1 -1
  16. package/dist/lib/gitlab-client.d.ts +42 -8
  17. package/dist/lib/gitlab-client.js +380 -42
  18. package/dist/lib/gitlab-client.js.map +1 -1
  19. package/dist/lib/network.js +12 -6
  20. package/dist/lib/network.js.map +1 -1
  21. package/dist/lib/oauth-scopes.d.ts +2 -0
  22. package/dist/lib/oauth-scopes.js +16 -0
  23. package/dist/lib/oauth-scopes.js.map +1 -0
  24. package/dist/lib/regex.d.ts +5 -0
  25. package/dist/lib/regex.js +111 -0
  26. package/dist/lib/regex.js.map +1 -0
  27. package/dist/lib/request-runtime.js +24 -11
  28. package/dist/lib/request-runtime.js.map +1 -1
  29. package/dist/tools/gitlab.js +193 -3
  30. package/dist/tools/gitlab.js.map +1 -1
  31. package/dist/tools/mr-code-context.d.ts +1 -1
  32. package/dist/types/auth.d.ts +1 -0
  33. package/dist/types/auth.js +2 -0
  34. package/dist/types/auth.js.map +1 -0
  35. package/dist/types/context.d.ts +1 -0
  36. package/docs/architecture.md +11 -11
  37. package/docs/authentication.md +4 -1
  38. package/docs/configuration.md +29 -22
  39. package/docs/deployment.md +2 -0
  40. package/docs/mcp-integration-testing-best-practices.md +381 -730
  41. package/docs/tools.md +24 -14
  42. package/package.json +1 -1
package/docs/configuration.md CHANGED
@@ -2,7 +2,12 @@
2
2
 
3
3
  All configuration is done through environment variables. The server validates all values at startup using [Zod](https://zod.dev/) schemas and will fail fast with descriptive errors if any value is invalid.
4
4
 
5
- You can set variables in a `.env` file (loaded automatically via `dotenv`) or pass them directly as environment variables.
5
+ You can set variables in a `.env` file (loaded automatically via `dotenv`) or pass them directly as environment variables. To load a different file, use `--env-file`:
6
+
7
+ ```bash
8
+ node dist/index.js --env-file .env.local
9
+ node dist/http.js --env-file=.env.production
10
+ ```
6
11
 
7
12
  ## Core Settings
8
13
 
@@ -38,16 +43,16 @@ The client will normalize each entry and rotate across them for load distributio
38
43
 
39
44
  ### OAuth 2.0 PKCE
40
45
 
41
- | Variable | Type | Default | Description |
42
- | -------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------ |
43
- | `GITLAB_USE_OAUTH` | boolean | `false` | Enable OAuth PKCE flow. |
44
- | `GITLAB_OAUTH_CLIENT_ID` | string | — | **Required** when OAuth is enabled. Application ID from GitLab OAuth settings. |
45
- | `GITLAB_OAUTH_CLIENT_SECRET` | string | — | Optional. Required only for confidential OAuth applications. |
46
- | `GITLAB_OAUTH_GITLAB_URL` | string | derived from `GITLAB_API_URL` | GitLab base URL for OAuth endpoints (e.g. `https://gitlab.com`). |
47
- | `GITLAB_OAUTH_REDIRECT_URI` | string (URL) | `http://127.0.0.1:8765/callback` | Local callback URL for the OAuth flow. |
48
- | `GITLAB_OAUTH_SCOPES` | string | `api` | Space or comma-separated OAuth scopes. |
49
- | `GITLAB_OAUTH_TOKEN_PATH` | string | `~/.gitlab-mcp-oauth-token.json` | File path for persisting OAuth tokens. Stored with `chmod 600`. |
50
- | `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. |
51
56
 
52
57
  ### External Token Script
53
58
 
@@ -73,10 +78,10 @@ The client will normalize each entry and rotate across them for load distributio
73
78
 
74
79
  ### Remote Authorization (HTTP Mode)
75
80
 
76
- | Variable | Type | Default | Description |
77
- | ------------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
78
- | `REMOTE_AUTHORIZATION` | boolean | `false` | Require per-request tokens via `Authorization` (Bearer) or `Private-Token` headers for HTTP requests. Disables fallback auth chain. |
79
- | `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`. |
80
85
 
81
86
  ## Policy
82
87
 
@@ -85,7 +90,7 @@ The client will normalize each entry and rotate across them for load distributio
85
90
  | `GITLAB_READ_ONLY_MODE` | boolean | `false` | Disable all mutating tools (create, update, delete, merge, etc.). |
86
91
  | `GITLAB_ALLOWED_PROJECT_IDS` | string | — | Comma-separated project IDs. If set, only these projects can be accessed. Empty = no restriction. |
87
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. |
88
- | `GITLAB_DENIED_TOOLS_REGEX` | string | — | Regex pattern to deny tools by name (example: `^gitlab_delete_`). |
93
+ | `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. |
89
94
  | `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. |
90
95
 
91
96
  ## Feature Toggles
@@ -99,12 +104,13 @@ The client will normalize each entry and rotate across them for load distributio
99
104
 
100
105
  ## Output
101
106
 
102
- | Variable | Type | Default | Description |
103
- | --------------------------- | ---------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
104
- | `GITLAB_RESPONSE_MODE` | `json` \| `compact-json` \| `yaml` | `json` | Response serialization format. `compact-json` omits indentation. |
105
- | `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. |
106
- | `GITLAB_HTTP_TIMEOUT_MS` | number | `20000` | GitLab API request timeout in milliseconds (1,000–120,000). |
107
- | `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. |
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_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). |
112
+ | `GITLAB_HTTP_TIMEOUT_MS` | number | `20000` | GitLab API request timeout in milliseconds (1,000–120,000). |
113
+ | `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
114
 
109
115
  ## Network
110
116
 
@@ -112,6 +118,7 @@ The client will normalize each entry and rotate across them for load distributio
112
118
  | ------------------------------ | ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
113
119
  | `HTTP_PROXY` | string | — | HTTP proxy URL. |
114
120
  | `HTTPS_PROXY` | string | — | HTTPS proxy URL. Takes precedence over `HTTP_PROXY` for HTTPS requests. |
121
+ | `NO_PROXY` | string | — | Comma-separated host, suffix, wildcard, or `host:port` entries that bypass the configured proxy. |
115
122
  | `GITLAB_CA_CERT_PATH` | string | — | Path to a custom CA certificate file (PEM format). |
116
123
  | `NODE_TLS_REJECT_UNAUTHORIZED` | string | — | Set to `0` to disable TLS verification. **Requires** `GITLAB_ALLOW_INSECURE_TLS=true` as explicit acknowledgment. |
117
124
  | `GITLAB_ALLOW_INSECURE_TLS` | boolean | `false` | Acknowledge insecure TLS. Required when `NODE_TLS_REJECT_UNAUTHORIZED=0`. |
package/docs/deployment.md CHANGED
@@ -250,6 +250,8 @@ GITLAB_DENIED_TOOLS_REGEX=^gitlab_(delete|create)_
250
250
  GITLAB_ALLOWED_PROJECT_IDS=123,456
251
251
  ```
252
252
 
253
+ Unsafe `GITLAB_DENIED_TOOLS_REGEX` patterns are ignored instead of failing startup.
254
+
253
255
  ---
254
256
 
255
257
  ## Multi-Instance Deployment