@zereight/mcp-gitlab 2.0.13 → 2.0.19

package/README.md

@@ -1,5 +1,7 @@
 # GitLab MCP Server
 
+> **New Feature**: Dynamic GitLab API URL support with connection pooling! See [Dynamic API URL Documentation](docs/dynamic-api-url.md) for details.
+
 [![Star History Chart](https://api.star-history.com/svg?repos=zereight/gitlab-mcp&type=Date)](https://www.star-history.com/#zereight/gitlab-mcp&Date)
 
 ## @zereight/mcp-gitlab
@@ -26,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
@@ -53,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
@@ -92,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
     }
   ],
@@ -109,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"
       }
     }
   }
@@ -125,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(
@@ -139,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
 {
@@ -169,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",
@@ -239,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:
@@ -288,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
 
@@ -337,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/gitlab-client-pool.js

@@ -0,0 +1,113 @@
+import { Agent } from "http";
+import { Agent as HttpsAgent } from "https";
+import { HttpProxyAgent } from "http-proxy-agent";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { SocksProxyAgent } from "socks-proxy-agent";
+import fs from "fs";
+/**
+ * Manages a pool of HTTP/HTTPS agents for different GitLab API URLs.
+ * This allows the server to efficiently handle requests to multiple GitLab instances
+ * by reusing agents and their underlying TCP connections.
+ */
+export class GitLabClientPool {
+    clients = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+        // Initialization is now done on-demand
+    }
+    /**
+     * Creates a pair of HTTP and HTTPS agents for a specific API URL,
+     * considering proxy and SSL/TLS settings.
+     * @param apiUrl The base URL for which to create the agents.
+     * @returns A `ClientAgents` object containing the configured agents.
+     */
+    createAgentsForUrl(apiUrl) {
+        const { httpProxy, httpsProxy, rejectUnauthorized, caCertPath } = this.options;
+        const url = new URL(apiUrl);
+        let sslOptions = {};
+        if (rejectUnauthorized === false) {
+            sslOptions.rejectUnauthorized = false;
+        }
+        else if (caCertPath) {
+            try {
+                sslOptions.ca = fs.readFileSync(caCertPath);
+            }
+            catch (error) {
+                console.error(`Failed to read CA certificate from ${caCertPath}:`, error);
+                throw new Error(`Failed to read CA certificate: ${caCertPath}`);
+            }
+        }
+        let httpAgent;
+        let httpsAgent;
+        // Configure HTTP agent with proxy if specified
+        if (httpProxy) {
+            httpAgent = httpProxy.startsWith("socks")
+                ? new SocksProxyAgent(httpProxy)
+                : new HttpProxyAgent(httpProxy);
+        }
+        else {
+            httpAgent = new Agent({ keepAlive: true });
+        }
+        // Configure HTTPS agent with proxy and SSL options if specified
+        if (httpsProxy) {
+            httpsAgent = httpsProxy.startsWith("socks")
+                // The `as any` cast is used here to bypass a TypeScript type mismatch error.
+                // The `socks-proxy-agent` documentation indicates that TLS options like
+                // `rejectUnauthorized` and `ca` are valid in the constructor's options
+                // object, but the type definitions in this environment seem to disagree.
+                // This cast ensures the options are passed through at runtime.
+                ? new SocksProxyAgent(httpsProxy, sslOptions)
+                : new HttpsProxyAgent(httpsProxy, { ...sslOptions });
+        }
+        else {
+            httpsAgent = new HttpsAgent({ ...sslOptions, keepAlive: true });
+        }
+        return { httpAgent, httpsAgent };
+    }
+    /**
+     * Retrieves the appropriate agent (HTTP or HTTPS) for a given API URL.
+     * If an agent for the URL does not exist, it creates and caches one.
+     * @param apiUrl The full URL of the request.
+     * @returns The corresponding `Agent` for the URL's protocol.
+     */
+    getOrCreateAgentForUrl(apiUrl) {
+        const url = new URL(apiUrl);
+        const baseUrl = `${url.protocol}//${url.host}${url.pathname.substring(0, url.pathname.lastIndexOf('/api/v4') + '/api/v4'.length)}`;
+        if (!this.clients.has(baseUrl)) {
+            // Check pool size limit
+            if (this.options.poolMaxSize !== undefined && this.clients.size >= this.options.poolMaxSize) {
+                throw new Error(`Server capacity reached: Connection pool is full (max ${this.options.poolMaxSize} instances). Please try again later.`);
+            }
+            this.clients.set(baseUrl, this.createAgentsForUrl(baseUrl));
+        }
+        const agents = this.clients.get(baseUrl);
+        if (!agents) {
+            // This should not happen given the logic above, but it satisfies TypeScript
+            throw new Error(`Failed to create or get client for URL: ${baseUrl}`);
+        }
+        return url.protocol === "https:" ? agents.httpsAgent : agents.httpAgent;
+    }
+    /**
+     * Retrieves the client agents for a specific base API URL.
+     * @param apiUrl The base API URL (e.g., "https://gitlab.com/api/v4").
+     * @returns The `ClientAgents` object or undefined if not found.
+     */
+    getClient(apiUrl) {
+        return this.clients.get(apiUrl);
+    }
+    /**
+     * Returns the default client agents, which corresponds to the first URL in the list.
+     * @returns The default `ClientAgents`.
+     */
+    getDefaultClient() {
+        const defaultUrl = this.options.apiUrls?.[0];
+        if (!defaultUrl) {
+            throw new Error("No default API URL configured.");
+        }
+        if (!this.clients.has(defaultUrl)) {
+            this.clients.set(defaultUrl, this.createAgentsForUrl(defaultUrl));
+        }
+        return this.clients.get(defaultUrl);
+    }
+}