gitlab-mcp 0.1.5 → 1.1.0

package/docs/configuration.md

@@ -0,0 +1,149 @@
+# Configuration Reference
+
+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.
+
+You can set variables in a `.env` file (loaded automatically via `dotenv`) or pass them directly as environment variables.
+
+## Core Settings
+
+| Variable             | Type                                                                     | Default       | Description                                              |
+| -------------------- | ------------------------------------------------------------------------ | ------------- | -------------------------------------------------------- |
+| `NODE_ENV`           | `development` \| `test` \| `production`                                  | `development` | Runtime environment. Affects error detail mode defaults. |
+| `LOG_LEVEL`          | `fatal` \| `error` \| `warn` \| `info` \| `debug` \| `trace` \| `silent` | `info`        | Pino log level.                                          |
+| `MCP_SERVER_NAME`    | string                                                                   | `gitlab-mcp`  | Server name reported in MCP handshake.                   |
+| `MCP_SERVER_VERSION` | string                                                                   | `0.1.0`       | Server version reported in MCP handshake.                |
+
+## GitLab API
+
+| Variable                       | Type   | Default                     | Description                                                                                                                                       |
+| ------------------------------ | ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITLAB_API_URL`               | string | `https://gitlab.com/api/v4` | Base API URL. Supports **comma-separated** URLs for multi-instance rotation. Each URL is automatically normalized to end with `/api/v4`.          |
+| `GITLAB_PERSONAL_ACCESS_TOKEN` | string | —                           | Static default token for requests in default mode (`REMOTE_AUTHORIZATION=false`). If omitted, runtime can still resolve OAuth/script/file tokens. |
+
+### Multi-Instance Example
+
+```bash
+GITLAB_API_URL=https://gitlab.example.com,https://gitlab-mirror.example.com
+```
+
+The client will normalize each entry and rotate across them for load distribution.
+
+## Authentication
+
+### Personal Access Token
+
+| Variable                       | Type   | Default | Description                                                         |
+| ------------------------------ | ------ | ------- | ------------------------------------------------------------------- |
+| `GITLAB_PERSONAL_ACCESS_TOKEN` | string | —       | Token with `api` scope. Used as the default request token when set. |
+
+### OAuth 2.0 PKCE
+
+| Variable                         | Type         | Default                          | Description                                                                    |
+| -------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------ |
+| `GITLAB_USE_OAUTH`               | boolean      | `false`                          | Enable OAuth PKCE flow.                                                        |
+| `GITLAB_OAUTH_CLIENT_ID`         | string       | —                                | **Required** when OAuth is enabled. Application ID from GitLab OAuth settings. |
+| `GITLAB_OAUTH_CLIENT_SECRET`     | string       | —                                | Optional. Required only for confidential OAuth applications.                   |
+| `GITLAB_OAUTH_GITLAB_URL`        | string       | derived from `GITLAB_API_URL`    | GitLab base URL for OAuth endpoints (e.g. `https://gitlab.com`).               |
+| `GITLAB_OAUTH_REDIRECT_URI`      | string (URL) | `http://127.0.0.1:8765/callback` | Local callback URL for the OAuth flow.                                         |
+| `GITLAB_OAUTH_SCOPES`            | string       | `api`                            | Space or comma-separated OAuth scopes.                                         |
+| `GITLAB_OAUTH_TOKEN_PATH`        | string       | `~/.gitlab-mcp-oauth-token.json` | File path for persisting OAuth tokens. Stored with `chmod 600`.                |
+| `GITLAB_OAUTH_AUTO_OPEN_BROWSER` | boolean      | `true`                           | Automatically open the browser for authorization.                              |
+
+### External Token Script
+
+| Variable                         | Type   | Default | Description                                                                                                                                                                |
+| -------------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITLAB_TOKEN_SCRIPT`            | string | —       | Shell command to execute for obtaining a token. Must output either a raw token string or JSON (`{"access_token":"..."}`, `{"token":"..."}`, or `{"private_token":"..."}`). |
+| `GITLAB_TOKEN_SCRIPT_TIMEOUT_MS` | number | `10000` | Script execution timeout (500ms–120s).                                                                                                                                     |
+| `GITLAB_TOKEN_CACHE_SECONDS`     | number | `300`   | How long to cache the resolved token (0–86400s).                                                                                                                           |
+
+### Token File
+
+| Variable                           | Type    | Default | Description                                                                                    |
+| ---------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------- |
+| `GITLAB_TOKEN_FILE`                | string  | —       | Path to a file containing a token. Supports `~/` prefix.                                       |
+| `GITLAB_ALLOW_INSECURE_TOKEN_FILE` | boolean | `false` | Allow token files with group/other read permissions. By default, the file must be `chmod 600`. |
+
+### Cookie-Based Auth
+
+| Variable                    | Type   | Default | Description                                                          |
+| --------------------------- | ------ | ------- | -------------------------------------------------------------------- |
+| `GITLAB_AUTH_COOKIE_PATH`   | string | —       | Path to a Netscape-format cookie file. Auto-reloads on file changes. |
+| `GITLAB_COOKIE_WARMUP_PATH` | string | `/user` | API path used for session warmup when cookies are loaded.            |
+
+### Remote Authorization (HTTP Mode)
+
+| Variable                 | Type    | Default | Description                                                                                                                         |
+| ------------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `REMOTE_AUTHORIZATION`   | boolean | `false` | Require per-request tokens via `Authorization` (Bearer) or `Private-Token` headers for HTTP requests. Disables fallback auth chain. |
+| `ENABLE_DYNAMIC_API_URL` | boolean | `false` | Require per-request API URL via `X-GitLab-API-URL` header. Requires `REMOTE_AUTHORIZATION=true`.                                    |
+
+## Policy
+
+| Variable                                  | Type    | Default | Description                                                                                                                                             |
+| ----------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITLAB_READ_ONLY_MODE`                   | boolean | `false` | Disable all mutating tools (create, update, delete, merge, etc.).                                                                                       |
+| `GITLAB_ALLOWED_PROJECT_IDS`              | string  | —       | Comma-separated project IDs. If set, only these projects can be accessed. Empty = no restriction.                                                       |
+| `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. |
+| `GITLAB_DENIED_TOOLS_REGEX`               | string  | —       | Regex pattern to deny tools by name (example: `^gitlab_delete_`).                                                                                       |
+| `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.                     |
+
+## Feature Toggles
+
+| Variable          | Type    | Default | Description                     |
+| ----------------- | ------- | ------- | ------------------------------- |
+| `USE_GITLAB_WIKI` | boolean | `true`  | Enable wiki-related tools.      |
+| `USE_MILESTONE`   | boolean | `true`  | Enable milestone-related tools. |
+| `USE_PIPELINE`    | boolean | `true`  | Enable pipeline and job tools.  |
+| `USE_RELEASE`     | boolean | `true`  | Enable release-related tools.   |
+
+## Output
+
+| Variable                    | Type                               | Default                                | Description                                                                                                                         |
+| --------------------------- | ---------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `GITLAB_RESPONSE_MODE`      | `json` \| `compact-json` \| `yaml` | `json`                                 | Response serialization format. `compact-json` omits indentation.                                                                    |
+| `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. |
+| `GITLAB_HTTP_TIMEOUT_MS`    | number                             | `20000`                                | GitLab API request timeout in milliseconds (1,000–120,000).                                                                         |
+| `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.                         |
+
+## Network
+
+| Variable                       | Type    | Default          | Description                                                                                                       |
+| ------------------------------ | ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `HTTP_PROXY`                   | string  | —                | HTTP proxy URL.                                                                                                   |
+| `HTTPS_PROXY`                  | string  | —                | HTTPS proxy URL. Takes precedence over `HTTP_PROXY` for HTTPS requests.                                           |
+| `GITLAB_CA_CERT_PATH`          | string  | —                | Path to a custom CA certificate file (PEM format).                                                                |
+| `NODE_TLS_REJECT_UNAUTHORIZED` | string  | —                | Set to `0` to disable TLS verification. **Requires** `GITLAB_ALLOW_INSECURE_TLS=true` as explicit acknowledgment. |
+| `GITLAB_ALLOW_INSECURE_TLS`    | boolean | `false`          | Acknowledge insecure TLS. Required when `NODE_TLS_REJECT_UNAUTHORIZED=0`.                                         |
+| `GITLAB_CLOUDFLARE_BYPASS`     | boolean | `false`          | Add browser-like headers (User-Agent, Accept-Language, Cache-Control) to bypass Cloudflare protection.            |
+| `GITLAB_USER_AGENT`            | string  | —                | Custom User-Agent header. If not set and `GITLAB_CLOUDFLARE_BYPASS` is enabled, a Chrome-like UA is used.         |
+| `GITLAB_ACCEPT_LANGUAGE`       | string  | `en-US,en;q=0.9` | Accept-Language header (used with Cloudflare bypass).                                                             |
+
+## HTTP Server
+
+These settings apply only to the HTTP transport (`dist/http.js`).
+
+| Variable         | Type    | Default     | Description                                                                                                  |
+| ---------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
+| `HTTP_HOST`      | string  | `127.0.0.1` | Bind address. Use `0.0.0.0` to listen on all interfaces.                                                     |
+| `HTTP_PORT`      | number  | `3333`      | Listen port (1–65535).                                                                                       |
+| `HTTP_JSON_ONLY` | boolean | `false`     | Force JSON-only responses (disable streaming).                                                               |
+| `SSE`            | boolean | `false`     | Enable legacy SSE transport (`GET /sse`, `POST /messages`). Cannot be used with `REMOTE_AUTHORIZATION=true`. |
+
+## Session Management (HTTP Mode)
+
+| Variable                  | Type   | Default | Description                                                                      |
+| ------------------------- | ------ | ------- | -------------------------------------------------------------------------------- |
+| `SESSION_TIMEOUT_SECONDS` | number | `3600`  | Idle session TTL in seconds (1–86400). Sessions are garbage-collected every 30s. |
+| `MAX_SESSIONS`            | number | `1000`  | Maximum concurrent sessions (1–10000). Returns HTTP 503 when exceeded.           |
+| `MAX_REQUESTS_PER_MINUTE` | number | `300`   | Per-session rate limit (1–10000). Returns HTTP 429 when exceeded.                |
+
+## Validation Rules
+
+The server enforces these cross-field constraints at startup:
+
+- `GITLAB_API_URL` must contain at least one valid URL
+- `GITLAB_USE_OAUTH=true` requires `GITLAB_OAUTH_CLIENT_ID`
+- `ENABLE_DYNAMIC_API_URL=true` requires `REMOTE_AUTHORIZATION=true`
+- `SSE=true` is not compatible with `REMOTE_AUTHORIZATION=true`
+- `NODE_TLS_REJECT_UNAUTHORIZED=0` requires `GITLAB_ALLOW_INSECURE_TLS=true`

package/docs/deployment.md

@@ -0,0 +1,336 @@
+# Deployment Guide
+
+gitlab-mcp can be deployed in several configurations depending on your use case.
+
+## Transport Modes
+
+| Mode                | Entry Point                         | Best For                                              |
+| ------------------- | ----------------------------------- | ----------------------------------------------------- |
+| **stdio**           | `node dist/index.js`                | Local CLI tools (Claude Desktop, Claude Code, Cursor) |
+| **Streamable HTTP** | `node dist/http.js`                 | Remote deployments, multi-user, shared servers        |
+| **SSE** (legacy)    | `node dist/http.js` with `SSE=true` | Legacy SSE-only clients                               |
+
+---
+
+## Local / stdio Mode
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "node",
+      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
+      "env": {
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "node",
+      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
+      "env": {
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Other MCP Clients
+
+Most MCP clients support stdio transport. Use the same configuration pattern — set the command to `node`, args to the dist entry point, and pass environment variables.
+
+---
+
+## HTTP Server Mode
+
+### Basic Setup
+
+```bash
+# Build
+pnpm build
+
+# Start HTTP server
+HTTP_HOST=127.0.0.1 HTTP_PORT=3333 node dist/http.js
+```
+
+### With Remote Authorization
+
+For multi-user deployments where each client provides their own GitLab token:
+
+```bash
+REMOTE_AUTHORIZATION=true
+HTTP_HOST=0.0.0.0
+HTTP_PORT=3333
+node dist/http.js
+```
+
+Clients connect with their credentials:
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "url": "http://your-server:3333/mcp",
+      "headers": {
+        "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Endpoints
+
+| Endpoint    | Method            | Description                            |
+| ----------- | ----------------- | -------------------------------------- |
+| `/mcp`      | POST, GET, DELETE | Streamable HTTP MCP endpoint           |
+| `/healthz`  | GET               | Health check (session count, status)   |
+| `/sse`      | GET               | SSE connection (when `SSE=true`)       |
+| `/messages` | POST              | SSE message endpoint (when `SSE=true`) |
+
+### Health Check Response
+
+```json
+{
+  "status": "ok",
+  "server": "gitlab-mcp",
+  "activeSessions": 3,
+  "activeSseSessions": 0,
+  "pendingSessions": 0,
+  "maxSessions": 1000,
+  "remoteAuthorization": true,
+  "readOnlyMode": false,
+  "sseEnabled": false
+}
+```
+
+Status is `"degraded"` when session count reaches `MAX_SESSIONS`.
+
+---
+
+## Docker
+
+### Using Docker Compose
+
+1. Create your `.env` file:
+
+```bash
+cp .env.example .env
+# Edit .env with your settings
+```
+
+2. Start the service:
+
+```bash
+docker compose up --build -d
+```
+
+The HTTP server will be available at `http://127.0.0.1:3333`.
+
+### Using Dockerfile Directly
+
+```bash
+# Build
+docker build -t gitlab-mcp .
+
+# Run with environment variables
+docker run -d \
+  --name gitlab-mcp \
+  -p 3333:3333 \
+  -e GITLAB_API_URL=https://gitlab.com/api/v4 \
+  -e GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxx \
+  -e NODE_ENV=production \
+  gitlab-mcp
+
+# Or with .env file
+docker run -d \
+  --name gitlab-mcp \
+  -p 3333:3333 \
+  --env-file .env \
+  gitlab-mcp
+```
+
+### Docker Image Details
+
+The Dockerfile uses a multi-stage build:
+
+1. **deps** — Install all dependencies
+2. **build** — Compile TypeScript
+3. **runtime** — Production image with only production dependencies
+
+Base image: `node:22-alpine`
+Exposed port: `3333`
+Entry point: `node dist/http.js`
+
+---
+
+## Production Considerations
+
+### Session Management
+
+The HTTP server manages sessions with the following controls:
+
+| Setting                   | Default | Description                                                            |
+| ------------------------- | ------- | ---------------------------------------------------------------------- |
+| `SESSION_TIMEOUT_SECONDS` | `3600`  | Idle session timeout. Sessions are garbage-collected every 30 seconds. |
+| `MAX_SESSIONS`            | `1000`  | Maximum concurrent sessions. Returns HTTP 503 when exceeded.           |
+| `MAX_REQUESTS_PER_MINUTE` | `300`   | Per-session rate limit. Returns HTTP 429 when exceeded.                |
+
+### Request Serialization
+
+Each session queues requests serially to prevent race conditions. Concurrent requests to the same session are processed in order.
+
+### Error Handling
+
+In production, set error detail mode to `safe` to prevent leaking upstream error details:
+
+```bash
+NODE_ENV=production
+# Or explicitly:
+GITLAB_ERROR_DETAIL_MODE=safe
+```
+
+### Response Size Limits
+
+Control response sizes to prevent memory issues:
+
+```bash
+GITLAB_MAX_RESPONSE_BYTES=200000   # 200KB default, range: 1KB–2MB
+```
+
+Responses exceeding this limit are truncated with a `[truncated N bytes]` suffix.
+
+### Logging
+
+The server uses [Pino](https://getpino.io/) for structured JSON logging:
+
+```bash
+LOG_LEVEL=info   # Options: fatal, error, warn, info, debug, trace, silent
+```
+
+### Read-Only Mode
+
+For safety in production environments:
+
+```bash
+GITLAB_READ_ONLY_MODE=true
+```
+
+This disables all mutating tools (create, update, delete, merge, etc.) at registration time.
+
+### Tool Restrictions
+
+Limit the available tools:
+
+```bash
+# Only expose specific tools
+GITLAB_ALLOWED_TOOLS=get_project,list_merge_requests,get_merge_request
+
+# Or block tools by pattern
+GITLAB_DENIED_TOOLS_REGEX=^gitlab_(delete|create)_
+
+# Restrict to specific projects
+GITLAB_ALLOWED_PROJECT_IDS=123,456
+```
+
+---
+
+## Multi-Instance Deployment
+
+### Multiple GitLab Instances
+
+The server can rotate across multiple GitLab API URLs:
+
+```bash
+GITLAB_API_URL=https://gitlab-primary.example.com,https://gitlab-secondary.example.com
+```
+
+URLs are normalized to `/api/v4` automatically. The client rotates across them for load distribution.
+
+### Dynamic API URL (Per-Request)
+
+For serving multiple GitLab instances from a single server:
+
+```bash
+REMOTE_AUTHORIZATION=true
+ENABLE_DYNAMIC_API_URL=true
+```
+
+Clients specify the target GitLab instance via header:
+
+```
+X-GitLab-API-URL: https://other-gitlab.example.com/api/v4
+```
+
+---
+
+## Reverse Proxy Setup
+
+When deploying behind a reverse proxy (nginx, Caddy, etc.):
+
+1. Ensure the proxy passes through `Mcp-Session-Id` headers
+2. Configure appropriate timeouts for long-running requests
+3. If using SSE, ensure the proxy supports streaming responses
+
+### nginx Example
+
+```nginx
+location /mcp {
+    proxy_pass http://127.0.0.1:3333;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 120s;
+    proxy_buffering off;
+}
+
+location /healthz {
+    proxy_pass http://127.0.0.1:3333;
+}
+```
+
+---
+
+## Network Configuration
+
+### Proxy
+
+```bash
+HTTP_PROXY=http://proxy.example.com:8080
+HTTPS_PROXY=http://proxy.example.com:8080
+```
+
+### Custom CA Certificate
+
+For internal PKI or self-signed certificates:
+
+```bash
+GITLAB_CA_CERT_PATH=/etc/ssl/certs/internal-ca.pem
+```
+
+### Insecure TLS
+
+Not recommended for production. Requires explicit acknowledgment:
+
+```bash
+NODE_TLS_REJECT_UNAUTHORIZED=0
+GITLAB_ALLOW_INSECURE_TLS=true
+```