gitlab-mcp 0.1.5 → 1.1.0

package/docker-compose.yml

@@ -0,0 +1,10 @@
+services:
+  gitlab-mcp:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    env_file:
+      - .env
+    ports:
+      - "3333:3333"
+    restart: unless-stopped

package/docs/architecture.md

@@ -0,0 +1,310 @@
+# Architecture
+
+This document describes the internal design of gitlab-mcp, its module relationships, and key design decisions.
+
+## Overview
+
+gitlab-mcp is structured as a layered MCP server with clear separation between transport, tool registration, API client, and cross-cutting concerns (policy, auth, output formatting).
+
+```
+┌──────────────────────────────────────────────────────┐
+│              Transport Layer                         │
+│  index.ts (stdio)  │  http.ts (HTTP/SSE)            │
+└─────────┬──────────┴──────────┬──────────────────────┘
+          │                     │
+          │    ┌────────────────▼────────────────────┐
+          │    │  Session Management (HTTP only)     │
+          │    │  - Serial request queuing           │
+          │    │  - Rate limiting per session        │
+          │    │  - TTL-based garbage collection     │
+          │    │  - AsyncLocalStorage auth context   │
+          │    └────────────────┬────────────────────┘
+          │                     │
+┌─────────▼─────────────────────▼──────────────────────┐
+│                  MCP Server Factory                   │
+│                  build-server.ts                      │
+│  ┌──────────────────────────────────────────────┐    │
+│  │  registerHealthTool()                         │    │
+│  │  registerGitLabTools() ──▶ Policy filtering   │    │
+│  └──────────────────────────────────────────────┘    │
+└───────────────────────┬──────────────────────────────┘
+                        │
+┌───────────────────────▼──────────────────────────────┐
+│                   AppContext                          │
+│  ┌──────────┐ ┌───────────┐ ┌──────────────────┐    │
+│  │   env    │ │  logger   │ │  gitlab (Client)  │    │
+│  │ (AppEnv) │ │  (Pino)   │ │                   │    │
+│  └──────────┘ └───────────┘ └──────────────────┘    │
+│  ┌──────────────────┐ ┌─────────────────────────┐    │
+│  │ policy (Engine)  │ │ formatter (Output)      │    │
+│  └──────────────────┘ └─────────────────────────┘    │
+└──────────────────────────────────────────────────────┘
+```
+
+## Module Dependency Graph
+
+```
+config/env.ts
+  ▲
+  │ (imported by all entry points)
+  │
+  ├── index.ts (stdio)
+  │     └── lib/gitlab-client.ts
+  │     └── lib/policy.ts
+  │     └── lib/output.ts
+  │     └── lib/network.ts
+  │     └── lib/request-runtime.ts
+  │           └── lib/oauth.ts
+  │     └── server/build-server.ts
+  │           └── tools/gitlab.ts
+  │           │     └── tools/mr-code-context.ts
+  │           └── tools/health.ts
+  │
+  └── http.ts (HTTP)
+        └── (same dependencies as index.ts)
+        └── lib/auth-context.ts (AsyncLocalStorage)
+```
+
+## Key Modules
+
+### `config/env.ts` — Configuration
+
+- Parses and validates all environment variables using Zod schemas
+- Enforces cross-field constraints (e.g. OAuth requires client ID, dynamic API URL requires remote auth)
+- Normalizes API URLs to `/api/v4` suffix
+- Exports a typed `env` singleton and `AppEnv` type
+- Fails fast at startup with descriptive error messages
+
+### `server/build-server.ts` — Server Factory
+
+- Creates an `McpServer` instance with configured name and version
+- Registers the health check tool
+- Registers all GitLab tools after policy filtering
+- Pure factory function — no side effects
+
+### `tools/gitlab.ts` — Tool Definitions
+
+- Defines 80+ tools as a `GitLabToolDefinition[]` array
+- Each definition specifies: `name`, `title`, `description`, `mutating`, optional `requiresFeature`, `inputSchema` (Zod), and `handler`
+- Tools are filtered by the policy engine at registration time
+- Tool execution wraps results through the output formatter
+- Error handling converts `GitLabApiError` to structured MCP error responses
+
+**Tool execution flow:**
+
+```
+Raw args ──▶ stripNullsDeep ──▶ handler(args, context) ──▶ formatter.format() ──▶ MCP response
+                                       │
+                                       └── assertAuthReady()  (check token exists)
+                                       └── resolveProjectId() (apply project allowlist)
+```
+
+### `tools/mr-code-context.ts` — MR Code Context
+
+A specialized tool for AI-assisted code review:
+
+1. Fetches MR diff files
+2. Filters by glob patterns, extensions, or languages
+3. Sorts by changed lines, path, or file size
+4. Retrieves file content within a character budget
+5. Supports three content modes:
+   - **patch** — Raw unified diff
+   - **surrounding** — Changed lines with N lines of context from the full file
+   - **fullfile** — Complete file content
+6. Supports `list_only` mode for two-stage retrieval (list first, then fetch selectively)
+
+### `lib/gitlab-client.ts` — GitLab API Client
+
+- Wraps the GitLab REST API v4 with typed methods
+- Supports multi-instance URL rotation (round-robin)
+- Pre-request hook system (`beforeRequest`) for token/header injection
+- Per-session auth via `AsyncLocalStorage` (checked before each request)
+- Configurable timeout with `AbortSignal`
+- Error wrapping via `GitLabApiError` with status code and details
+
+**Request lifecycle:**
+
+```
+Method call ──▶ Build URL ──▶ Set headers ──▶ beforeRequest hook
+     │                                              │
+     │                          ┌───────────────────┘
+     │                          ▼
+     │                   Apply session auth (if available)
+     │                   Apply token header
+     │                   Apply compatibility headers
+     │                          │
+     └──────────────────────────▼
+                          fetch() with timeout
+                                │
+                          Parse response / throw GitLabApiError
+```
+
+### `lib/policy.ts` — Tool Policy Engine
+
+Controls which tools are available:
+
+1. **Read-only mode** — Blocks all tools marked `mutating: true`
+2. **Feature toggles** — Blocks tools requiring disabled features (wiki, milestone, pipeline, release)
+3. **Allowlist** — If set, only listed tools are available. Tool names are normalized (accepts `get_project` or `gitlab_get_project`)
+4. **Deny regex** — Blocks tools matching a regex pattern
+
+Policy is applied in two places:
+
+- **Registration time** — `filterTools()` removes tools from the MCP server entirely
+- **Execution time** — `assertCanExecute()` double-checks (defense in depth)
+
+### `lib/auth-context.ts` — Session Auth Context
+
+Uses Node.js `AsyncLocalStorage` to provide per-request authentication context:
+
+```typescript
+interface SessionAuth {
+  sessionId?: string;
+  token?: string;
+  apiUrl?: string;
+  header?: "authorization" | "private-token";
+  updatedAt: number;
+}
+```
+
+- In HTTP mode, each request runs within `runWithSessionAuth()` which sets the context
+- The GitLab client reads `getSessionAuth()` to get per-request credentials
+- In stdio mode, session auth is not used (static PAT is the primary method)
+
+### `lib/request-runtime.ts` — Request Preprocessing
+
+Orchestrates authentication and request modifications:
+
+1. **Cookie management** — Loads Netscape cookie files, auto-reloads on changes, creates `fetch-cookie` wrapper
+2. **Session warmup** — Sends a warmup request to establish cookie sessions
+3. **Token resolution** — When no request/session/PAT token is present, tries OAuth, then token script, then token file
+4. **Compatibility headers** — Applies User-Agent, Accept-Language for Cloudflare bypass
+5. **Token caching** — Caches resolved tokens with configurable TTL
+
+### `lib/oauth.ts` — OAuth PKCE Manager
+
+Implements the full OAuth 2.0 PKCE flow:
+
+1. Check stored token → use if not expired
+2. Try refresh token → persist new token
+3. Fall back to interactive flow:
+   - Generate PKCE challenge
+   - Build authorization URL
+   - Start local HTTP callback server
+   - Open browser (optional)
+   - Wait for callback (3 minute timeout)
+   - Exchange code for token
+   - Persist token (chmod 600)
+
+### `lib/network.ts` — Network Runtime
+
+Configures global fetch behavior using `undici`:
+
+- Sets up proxy agent (`ProxyAgent`) if `HTTP_PROXY`/`HTTPS_PROXY` is set
+- Loads custom CA certificates from `GITLAB_CA_CERT_PATH`
+- Controls TLS verification via `rejectUnauthorized`
+- Applied globally via `setGlobalDispatcher()`
+
+### `lib/output.ts` — Response Formatting
+
+- Serializes tool output to JSON (pretty), compact JSON, or YAML
+- Enforces `GITLAB_MAX_RESPONSE_BYTES` limit
+- Truncates oversized responses with a `[truncated N bytes]` marker
+- Returns metadata: `truncated` flag and `bytes` count
+
+### `lib/sanitize.ts` — Null Stripping
+
+`stripNullsDeep()` recursively removes `null` values from objects and arrays before passing them to the GitLab API. This prevents sending `null` in JSON payloads where `undefined` (omission) is the correct behavior.
+
+## HTTP Server Session Management
+
+The HTTP server (`http.ts`) implements a sophisticated session management system:
+
+### Streamable HTTP Sessions
+
+```
+Client POST /mcp (no session-id)
+  └── Create new session
+      ├── Create McpServer instance
+      ├── Create StreamableHTTPServerTransport
+      ├── Add to pending sessions
+      ├── Connect server to transport
+      ├── On session init → move to active sessions
+      └── Return Mcp-Session-Id header
+
+Client POST /mcp (with Mcp-Session-Id)
+  └── Look up existing session
+      ├── Refresh auth from request headers
+      ├── Check rate limit
+      ├── Enqueue request (serial per session)
+      └── Process within session auth context
+```
+
+### Session Lifecycle
+
+1. **Creation** — New session created on first POST without session ID
+2. **Active** — Session receives requests, each queued serially
+3. **Idle timeout** — Garbage collected after `SESSION_TIMEOUT_SECONDS` of inactivity
+4. **Rate limited** — Returns 429 after `MAX_REQUESTS_PER_MINUTE` per session
+5. **Capacity** — Returns 503 when `MAX_SESSIONS` is reached
+6. **Shutdown** — All sessions closed gracefully on SIGINT/SIGTERM
+
+### SSE Sessions (Legacy)
+
+When `SSE=true`:
+
+- Clients connect via `GET /sse` to establish an SSE stream
+- Messages are sent via `POST /messages?sessionId=...`
+- Sessions are cleaned up on client disconnect or idle timeout
+
+## Design Patterns
+
+### Dependency Injection via AppContext
+
+All shared services are bundled into an `AppContext` interface:
+
+```typescript
+interface AppContext {
+  env: AppEnv;
+  logger: Logger;
+  gitlab: GitLabClient;
+  policy: ToolPolicyEngine;
+  formatter: OutputFormatter;
+}
+```
+
+This is created once at startup and passed to tool registration functions. Tools access all services through this context.
+
+### Null Preprocessing in Zod Schemas
+
+Many MCP clients send `null` for optional parameters. The tool schemas use `z.preprocess()` to convert `null` to `undefined`:
+
+```typescript
+const optionalString = z.preprocess(
+  (value) => (value === null ? undefined : value),
+  z.string().optional()
+);
+```
+
+### Backward Compatibility Aliases
+
+Several tools have backward-compatible aliases to support existing integrations:
+
+- `gitlab_mr_discussions` → alias of `gitlab_list_merge_request_discussions`
+- `gitlab_get_merge_request_notes` → alias of `gitlab_list_merge_request_notes`
+- `gitlab_edit_milestone` → alias of `gitlab_update_milestone`
+- `gitlab_execute_graphql` → backward-compatible executor honoring read-only policy
+
+### Structured Content in Responses
+
+Tool responses include both text content (for display) and structured content (for programmatic access):
+
+```typescript
+return {
+  content: [{ type: "text", text: formatted.text }],
+  structuredContent: {
+    result: toStructuredContent(result),
+    meta: { truncated: formatted.truncated, bytes: formatted.bytes }
+  }
+};
+```

package/docs/authentication.md

@@ -0,0 +1,299 @@
+# Authentication Guide
+
+gitlab-mcp supports multiple authentication methods. Token behavior depends on whether remote authorization is enabled.
+
+## Token Resolution
+
+### Default Mode (`REMOTE_AUTHORIZATION=false`)
+
+```
+Static PAT (GITLAB_PERSONAL_ACCESS_TOKEN)
+  └─> OAuth 2.0 PKCE
+      └─> External token script
+          └─> Token file
+```
+
+### Remote Authorization Mode (`REMOTE_AUTHORIZATION=true`, HTTP)
+
+```
+Per-request auth only (required)
+```
+
+In remote authorization mode, each request must include `Authorization: Bearer <token>` or
+`Private-Token: <token>`. If `ENABLE_DYNAMIC_API_URL=true`, each request must also include
+`X-GitLab-API-URL`.
+
+Cookie-based auth (`GITLAB_AUTH_COOKIE_PATH`) is applied independently through a cookie jar and is not part of the token chain.
+
+---
+
+## 1. Personal Access Token (PAT)
+
+The simplest method. Create a token at **GitLab > Settings > Access Tokens** with the `api` scope.
+
+```bash
+GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
+```
+
+This token is the default request token in stdio and HTTP modes when `REMOTE_AUTHORIZATION=false`.
+When `REMOTE_AUTHORIZATION=true`, request headers are required and PAT fallback is disabled.
+
+---
+
+## 2. OAuth 2.0 PKCE
+
+Browser-based OAuth flow for interactive use. The server launches a local callback server and opens the browser for authorization.
+
+### Setup
+
+1. Register an OAuth application in GitLab (**Settings > Applications** or admin area):
+   - **Redirect URI:** `http://127.0.0.1:8765/callback`
+   - **Scopes:** `api`
+   - **Confidential:** No (for PKCE public clients)
+   - Note the **Application ID**
+
+2. Configure environment variables:
+
+```bash
+GITLAB_USE_OAUTH=true
+GITLAB_OAUTH_CLIENT_ID=your-application-id
+GITLAB_OAUTH_REDIRECT_URI=http://127.0.0.1:8765/callback
+GITLAB_OAUTH_SCOPES=api
+```
+
+### Optional Settings
+
+```bash
+# For confidential applications
+GITLAB_OAUTH_CLIENT_SECRET=your-client-secret
+
+# Custom GitLab URL (derived from GITLAB_API_URL if not set)
+GITLAB_OAUTH_GITLAB_URL=https://gitlab.example.com
+
+# Token storage location (default: ~/.gitlab-mcp-oauth-token.json)
+GITLAB_OAUTH_TOKEN_PATH=~/.gitlab-mcp-oauth-token.json
+
+# Disable auto-opening the browser
+GITLAB_OAUTH_AUTO_OPEN_BROWSER=false
+```
+
+### How It Works
+
+1. On first request, the server checks for a stored token at `GITLAB_OAUTH_TOKEN_PATH`
+2. If no valid token exists, it generates a PKCE challenge and opens the browser
+3. The user authorizes the application in GitLab
+4. GitLab redirects back to the local callback server with an authorization code
+5. The server exchanges the code for an access token (with PKCE verifier)
+6. The token is persisted to disk (chmod 600) for future sessions
+7. On subsequent requests, the stored token is reused until it expires
+8. Expired tokens are automatically refreshed using the refresh token
+
+### Notes
+
+- The callback server listens for up to 3 minutes before timing out
+- Token files are stored with `0600` permissions
+- If refresh fails, the server falls back to interactive authorization
+
+---
+
+## 3. External Token Script
+
+Execute a shell command to obtain a token dynamically. Useful for integration with secret managers, vault systems, or custom token providers.
+
+```bash
+GITLAB_TOKEN_SCRIPT=/path/to/get-token.sh
+GITLAB_TOKEN_SCRIPT_TIMEOUT_MS=10000   # 500ms–120s (default: 10s)
+GITLAB_TOKEN_CACHE_SECONDS=300         # 0–86400s (default: 5min)
+```
+
+### Script Output Format
+
+The script must output one of:
+
+1. **Raw token string** (plain text on stdout):
+
+   ```
+   glpat-xxxxxxxxxxxxxxxxxxxx
+   ```
+
+2. **JSON object** with any of these keys:
+   ```json
+   { "access_token": "glpat-xxxxxxxxxxxxxxxxxxxx" }
+   ```
+   ```json
+   { "token": "glpat-xxxxxxxxxxxxxxxxxxxx" }
+   ```
+   ```json
+   { "private_token": "glpat-xxxxxxxxxxxxxxxxxxxx" }
+   ```
+
+### Example Script
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Example: read from environment or secret manager
+if [[ -n "${GITLAB_OAUTH_ACCESS_TOKEN:-}" ]]; then
+  printf '{"access_token":"%s"}\n' "${GITLAB_OAUTH_ACCESS_TOKEN}"
+  exit 0
+fi
+
+echo "Token not available" >&2
+exit 1
+```
+
+The resolved token is cached for `GITLAB_TOKEN_CACHE_SECONDS` to avoid repeated script executions.
+
+---
+
+## 4. Token File
+
+Read a token from a file on disk. The file should contain a raw token string or JSON (same format as the token script output).
+
+```bash
+GITLAB_TOKEN_FILE=~/.gitlab-token
+```
+
+### Security
+
+By default, the server enforces strict file permissions — the token file must be readable only by the owner (`chmod 600`). If the file has group or other permissions, the server rejects it.
+
+To override this check:
+
+```bash
+GITLAB_ALLOW_INSECURE_TOKEN_FILE=true
+```
+
+The token is cached for `GITLAB_TOKEN_CACHE_SECONDS` (default: 300s).
+
+---
+
+## 5. Cookie-Based Auth
+
+Use browser cookies from a Netscape-format cookie file. This is useful when working with GitLab instances that use SSO or other browser-based authentication.
+
+```bash
+GITLAB_AUTH_COOKIE_PATH=~/.gitlab-cookies.txt
+```
+
+### How It Works
+
+1. The server reads cookies from the file in Netscape cookie format
+2. A cookie jar is created and attached to all API requests via `fetch-cookie`
+3. Before the first API call to each GitLab instance, a warmup request is sent to establish the session
+4. If the cookie file changes on disk, it is automatically reloaded
+
+### Warmup Path
+
+The warmup request hits a lightweight endpoint to establish the session:
+
+```bash
+GITLAB_COOKIE_WARMUP_PATH=/user   # default
+```
+
+### Cookie File Format
+
+Standard Netscape cookie format (tab-separated):
+
+```
+# Netscape HTTP Cookie File
+.gitlab.example.com	TRUE	/	TRUE	0	_gitlab_session	abc123...
+```
+
+Lines starting with `#HttpOnly_` are parsed as HttpOnly cookies.
+
+---
+
+## 6. Remote Authorization (HTTP Mode)
+
+In HTTP transport mode, this enables strict per-request credentials. This is the recommended approach for shared/multi-user deployments.
+
+```bash
+REMOTE_AUTHORIZATION=true
+```
+
+`REMOTE_AUTHORIZATION=true` enforces per-request credentials. If a request does not include a token header, the request is rejected.
+
+### Client Headers
+
+The server accepts tokens via:
+
+- **`Authorization: Bearer <token>`** — Standard bearer token
+- **`Private-Token: <token>`** — GitLab private token header
+
+### Dynamic API URL
+
+When serving multiple GitLab instances, enable dynamic API URL per request:
+
+```bash
+REMOTE_AUTHORIZATION=true
+ENABLE_DYNAMIC_API_URL=true
+```
+
+Clients can then send:
+
+```
+X-GitLab-API-URL: https://other-gitlab.example.com/api/v4
+```
+
+### Authentication Flow (HTTP Mode)
+
+1. Client sends a request with auth headers
+2. The server extracts the token and required API URL (when dynamic API URLs are enabled) from headers
+3. Auth context is stored in `AsyncLocalStorage` for the duration of the request
+4. All GitLab API calls within that request use the per-session credentials
+5. Requests missing required headers are rejected before tool execution
+
+---
+
+## Cloudflare Bypass
+
+If your GitLab instance is behind Cloudflare, enable browser-like headers:
+
+```bash
+GITLAB_CLOUDFLARE_BYPASS=true
+```
+
+This adds:
+
+- A Chrome-like `User-Agent` header
+- `Accept-Language: en-US,en;q=0.9`
+- `Cache-Control: no-cache`
+- `Pragma: no-cache`
+
+You can also set a custom User-Agent:
+
+```bash
+GITLAB_USER_AGENT="MyApp/1.0"
+```
+
+---
+
+## TLS & Proxy Configuration
+
+### Custom CA Certificate
+
+For self-signed or internal CA certificates:
+
+```bash
+GITLAB_CA_CERT_PATH=/path/to/ca-bundle.pem
+```
+
+### HTTP Proxy
+
+```bash
+HTTP_PROXY=http://proxy.example.com:8080
+HTTPS_PROXY=http://proxy.example.com:8080
+```
+
+### Insecure TLS (Not Recommended)
+
+To disable TLS certificate verification, you must explicitly acknowledge the risk:
+
+```bash
+NODE_TLS_REJECT_UNAUTHORIZED=0
+GITLAB_ALLOW_INSECURE_TLS=true
+```
+
+Both settings are required — setting only `NODE_TLS_REJECT_UNAUTHORIZED=0` without the acknowledgment flag will cause a startup error.