@zereight/mcp-gitlab 2.0.18 → 2.0.19

package/README.md

@@ -28,6 +28,7 @@ The server supports two authentication methods:
 #### Using OAuth2 Authentication
 
 OAuth2 provides a more secure authentication flow using browser-based authentication. When enabled, the server will:
+
 1. Open your browser to GitLab's authorization page
 2. Wait for you to approve the access
 3. Store the token securely for future use
@@ -55,6 +56,7 @@ Then configure the MCP server with OAuth:
       "env": {
         "GITLAB_USE_OAUTH": "true",
         "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
+        "GITLAB_OAUTH_CLIENT_SECRET": "your_oauth_client_secret", // Required for Confidential apps only
         "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
         "GITLAB_API_URL": "your_gitlab_api_url",
         "GITLAB_PROJECT_ID": "your_project_id", // Optional: default project
@@ -94,13 +96,69 @@ Then configure the MCP server with OAuth:
 
 #### vscode .vscode/mcp.json
 
+**Using OAuth2 (Non-Confidential - Recommended):**
+
+```json
+{
+  "servers": {
+    "GitLab-MCP": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@zereight/mcp-gitlab"],
+      "env": {
+        "GITLAB_USE_OAUTH": "true",
+        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
+        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
+        "GITLAB_READ_ONLY_MODE": "false",
+        "USE_GITLAB_WIKI": "false",
+        "USE_MILESTONE": "false",
+        "USE_PIPELINE": "false"
+      }
+    }
+  }
+}
+```
+
+**Using OAuth2 (Confidential):**
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "gitlab-oauth-secret",
+      "description": "GitLab OAuth Client Secret",
+      "password": true
+    }
+  ],
+  "servers": {
+    "GitLab-MCP": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@zereight/mcp-gitlab"],
+      "env": {
+        "GITLAB_USE_OAUTH": "true",
+        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
+        "GITLAB_OAUTH_CLIENT_SECRET": "${input:gitlab-oauth-secret}",
+        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
+        "GITLAB_READ_ONLY_MODE": "false"
+      }
+    }
+  }
+}
+```
+
+**Using Personal Access Token:**
+
 ```json
 {
   "inputs": [
     {
       "type": "promptString",
       "id": "gitlab-token",
-      "description": "Gitlab Token to read API",
+      "description": "GitLab Personal Access Token",
       "password": true
     }
   ],
@@ -111,9 +169,11 @@ Then configure the MCP server with OAuth:
       "args": ["-y", "@zereight/mcp-gitlab"],
       "env": {
         "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab-token}",
-        "GITLAB_API_URL": "your-fancy-gitlab-url",
-        "GITLAB_READ_ONLY_MODE": "true",
-        ...
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
+        "GITLAB_READ_ONLY_MODE": "false",
+        "USE_GITLAB_WIKI": "false",
+        "USE_MILESTONE": "false",
+        "USE_PIPELINE": "false"
       }
     }
   }
@@ -127,7 +187,7 @@ env_vars = {
         "GITLAB_PERSONAL_ACCESS_TOKEN": gitlab_access_token,
         "GITLAB_API_URL": gitlab_api_url,
         "USE_GITLAB_WIKI": use_gitlab_wiki
-        # ......the rest of the optional parameters 
+        # ......the rest of the optional parameters
 }
 
 stdio_gitlab_mcp_client = MCPClient(
@@ -141,10 +201,11 @@ stdio_gitlab_mcp_client = MCPClient(
     )
 ```
 
-
 #### Docker
 
-- stdio mcp.json
+> **Note**: For Docker deployments, **Personal Access Token is recommended**. OAuth requires browser-based authentication and a local callback server, which does not work properly in containerized environments.
+
+**Using Personal Access Token (stdio) - Recommended:**
 
 ```json
 {
@@ -171,7 +232,7 @@ stdio_gitlab_mcp_client = MCPClient(
       ],
       "env": {
         "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
-        "GITLAB_API_URL": "https://gitlab.com/api/v4", // Optional, for self-hosted GitLab
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
         "GITLAB_READ_ONLY_MODE": "false",
         "USE_GITLAB_WIKI": "true",
         "USE_MILESTONE": "true",
@@ -241,6 +302,7 @@ docker run -i --rm \
 - `GITLAB_PERSONAL_ACCESS_TOKEN`: Your GitLab personal access token. **Required in standard mode**; not used when `REMOTE_AUTHORIZATION=true` or when using OAuth.
 - `GITLAB_USE_OAUTH`: Set to `true` to enable OAuth2 authentication instead of personal access token.
 - `GITLAB_OAUTH_CLIENT_ID`: The Client ID from your GitLab OAuth application. Required when using OAuth.
+- `GITLAB_OAUTH_CLIENT_SECRET`: The Client Secret from your GitLab OAuth application. Required only for Confidential applications.
 - `GITLAB_OAUTH_REDIRECT_URI`: The OAuth callback URL. Default: `http://127.0.0.1:8888/callback`
 - `GITLAB_OAUTH_TOKEN_PATH`: Custom path to store the OAuth token. Default: `~/.gitlab-mcp-token.json`
 - `REMOTE_AUTHORIZATION`: When set to 'true', enables remote per-session authorization via HTTP headers. In this mode:
@@ -290,6 +352,7 @@ When using Streamable HTTP transport, the following endpoints are available:
 ### Remote Authorization Setup (Multi-User Support)
 
 When using `REMOTE_AUTHORIZATION=true`, the MCP server can support multiple users, each with their own GitLab token passed via HTTP headers. This is useful for:
+
 - Shared MCP server instances where each user needs their own GitLab access
 - IDE integrations that can inject user-specific tokens into MCP requests
 
@@ -339,9 +402,10 @@ The token is stored per session (identified by `mcp-session-id` header) and reus
 ```
 
 **Important Notes:**
+
 - Remote authorization **only works with Streamable HTTP transport**
 - Each session is isolated - tokens from one session cannot access another session's data
- Tokens are automatically cleaned up when sessions close
+  Tokens are automatically cleaned up when sessions close
 - **Session timeout:** Auth tokens expire after `SESSION_TIMEOUT_SECONDS` (default 1 hour) of inactivity. After timeout, the client must send auth headers again. The transport session remains active.
 - Each request resets the timeout timer for that session
 - **Rate limiting:** Each session is limited to `MAX_REQUESTS_PER_MINUTE` requests per minute (default 60)

package/build/oauth.js

@@ -16,7 +16,7 @@ const pendingAuthRequests = new Map();
  * Check if a port is already in use
  */
 async function isPortInUse(port) {
-    return new Promise((resolve) => {
+    return new Promise(resolve => {
         const server = net.createServer();
         server.once("error", (err) => {
             if (err.code === "EADDRINUSE") {
@@ -44,9 +44,9 @@ async function requestAuthFromExistingServer(port, requestId) {
             path: `/auth-request?requestId=${requestId}`,
             method: "GET",
         };
-        const req = http.request(options, (res) => {
+        const req = http.request(options, res => {
             let data = "";
-            res.on("data", (chunk) => {
+            res.on("data", chunk => {
                 data += chunk;
             });
             res.on("end", () => {
@@ -64,7 +64,7 @@ async function requestAuthFromExistingServer(port, requestId) {
                 }
             });
         });
-        req.on("error", (error) => {
+        req.on("error", error => {
             reject(new Error(`Failed to connect to existing OAuth server: ${error.message}`));
         });
         req.setTimeout(5 * 60 * 1000, () => {
@@ -82,8 +82,7 @@ export class GitLabOAuth {
     constructor(config) {
         this.config = config;
         this.tokenStoragePath =
-            config.tokenStoragePath ||
-                path.join(process.env.HOME || "", ".gitlab-mcp-token.json");
+            config.tokenStoragePath || path.join(process.env.HOME || "", ".gitlab-mcp-token.json");
     }
     /**
      * Get the authorization URL for OAuth flow
@@ -119,6 +118,10 @@ export class GitLabOAuth {
             redirect_uri: this.config.redirectUri,
             code_verifier: this.codeVerifier,
         });
+        // Add client_secret for Confidential applications
+        if (this.config.clientSecret) {
+            params.append("client_secret", this.config.clientSecret);
+        }
         const response = await fetch(tokenUrl, {
             method: "POST",
             headers: {
@@ -130,7 +133,7 @@ export class GitLabOAuth {
             const errorText = await response.text();
             throw new Error(`Token exchange failed: ${response.status} ${errorText}`);
         }
-        const data = await response.json();
+        const data = (await response.json());
         return {
             access_token: data.access_token,
             refresh_token: data.refresh_token,
@@ -150,6 +153,10 @@ export class GitLabOAuth {
             grant_type: "refresh_token",
             redirect_uri: this.config.redirectUri,
         });
+        // Add client_secret for Confidential applications
+        if (this.config.clientSecret) {
+            params.append("client_secret", this.config.clientSecret);
+        }
         const response = await fetch(tokenUrl, {
             method: "POST",
             headers: {
@@ -161,7 +168,7 @@ export class GitLabOAuth {
             const errorText = await response.text();
             throw new Error(`Token refresh failed: ${response.status} ${errorText}`);
         }
-        const data = await response.json();
+        const data = (await response.json());
         return {
             access_token: data.access_token,
             refresh_token: data.refresh_token || refreshToken,
@@ -271,7 +278,7 @@ export class GitLabOAuth {
                         const authUrl = await this.getAuthorizationUrl(newState);
                         logger.info("Opening browser for new authentication request...");
                         logger.info(`If browser doesn't open, visit: ${authUrl}`);
-                        open(authUrl).catch((err) => {
+                        open(authUrl).catch(err => {
                             logger.error("Failed to open browser:", err);
                             logger.info(`Please manually open: ${authUrl}`);
                         });
@@ -427,12 +434,12 @@ export class GitLabOAuth {
                 const authUrl = await this.getAuthorizationUrl(state);
                 logger.info("Opening browser for authentication...");
                 logger.info(`If browser doesn't open, visit: ${authUrl}`);
-                open(authUrl).catch((err) => {
+                open(authUrl).catch(err => {
                     logger.error("Failed to open browser:", err);
                     logger.info(`Please manually open: ${authUrl}`);
                 });
             });
-            server.on("error", (error) => {
+            server.on("error", error => {
                 logger.error("OAuth server error:", error);
                 const pending = pendingAuthRequests.get(initialRequestId);
                 if (pending) {
@@ -502,6 +509,7 @@ export class GitLabOAuth {
  */
 export async function initializeOAuth(gitlabUrl = "https://gitlab.com") {
     const clientId = process.env.GITLAB_OAUTH_CLIENT_ID;
+    const clientSecret = process.env.GITLAB_OAUTH_CLIENT_SECRET;
     const redirectUri = process.env.GITLAB_OAUTH_REDIRECT_URI || "http://127.0.0.1:8888/callback";
     const tokenStoragePath = process.env.GITLAB_OAUTH_TOKEN_PATH;
     if (!clientId) {
@@ -509,6 +517,7 @@ export async function initializeOAuth(gitlabUrl = "https://gitlab.com") {
     }
     const oauth = new GitLabOAuth({
         clientId,
+        clientSecret,
         redirectUri,
         gitlabUrl,
         scopes: ["api"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.0.18",
+  "version": "2.0.19",
   "description": "MCP server for using the GitLab API",
   "license": "MIT",
   "author": "zereight",