gitlab-mcp 0.1.5 → 1.0.0

package/README.md

@@ -1,276 +1,441 @@
-# GitLab MCP Server
+# gitlab-mcp
 
-Model Context Protocol (MCP) server for GitLab integration. This server allows communication between GitLab and MCP-compatible AI assistants.
+![Node CI](https://github.com/mcpland/gitlab-mcp/workflows/Node%20CI/badge.svg)
+[![npm](https://img.shields.io/npm/v/gitlab-mcp.svg)](https://www.npmjs.com/package/gitlab-mcp)
+![license](https://img.shields.io/npm/l/gitlab-mcp)
+
+A production-ready [MCP](https://modelcontextprotocol.io/) server for GitLab. Provides **80+ tools** that let AI assistants read and manage GitLab projects, merge requests, issues, pipelines, wikis, releases, and more through a unified, policy-controlled interface.
+
+## Highlights
+
+- **Comprehensive GitLab coverage** — projects, merge requests (with code-context analysis), issues, pipelines, wikis, milestones, releases, labels, commits, branches, GraphQL, and file management
+- **Multiple transports** — stdio for local CLI usage, Streamable HTTP for remote deployments, optional SSE
+- **Flexible authentication** — personal access tokens, OAuth 2.0 PKCE, external token scripts, token files, cookie-based auth, and per-request remote authorization
+- **Policy engine** — read-only mode, tool allowlist/denylist, feature toggles, and project-scoped restrictions
+- **Enterprise networking** — HTTP/HTTPS proxy, custom CA certificates, Cloudflare bypass, multi-instance API rotation
+- **Output control** — JSON, compact JSON, or YAML formatting with configurable response size limits
 
 ## Usage
 
-### Using with Claude App, Cline, Roo Code, Cursor
+### Supported clients
+
+Claude Desktop, Claude Code, VS Code, GitHub Copilot Chat (VS Code), Cursor, JetBrains AI Assistant, GitLab Duo, and any MCP client that supports stdio or streamable HTTP.
+
+Current client format references:
+
+- [MCP transports and protocol](https://modelcontextprotocol.io/docs/concepts/transports)
+- [Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp)
+- [VS Code MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+- [Cursor MCP](https://docs.cursor.com/context/model-context-protocol)
+- [JetBrains AI Assistant MCP](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html)
+
+### Authentication methods
+
+The server supports three auth patterns:
+
+1. Personal Access Token (PAT)
+2. OAuth 2.0 PKCE (recommended for local interactive use)
+3. Remote per-request auth (`REMOTE_AUTHORIZATION=true`, HTTP mode)
 
-When using with the Claude App, you need to set up your API key and URLs directly.
+### OAuth2 setup (stdio, recommended for local interactive use)
+
+1. Create a GitLab OAuth application in `Settings -> Applications`.
+2. Set redirect URI to `http://127.0.0.1:8765/callback` (or your custom callback).
+3. Set scope to `api`.
+4. Copy the Application ID as `GITLAB_OAUTH_CLIENT_ID`.
 
 ```json
 {
   "mcpServers": {
-    "GitLab communication server": {
+    "gitlab": {
       "command": "npx",
-      "args": ["-y", "mcp-gitlab"],
+      "args": ["-y", "gitlab-mcp@latest"],
+      "env": {
+        "GITLAB_USE_OAUTH": "true",
+        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
+        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
+        "GITLAB_ALLOWED_PROJECT_IDS": "",
+        "GITLAB_READ_ONLY_MODE": "false",
+        "USE_GITLAB_WIKI": "true",
+        "USE_MILESTONE": "true",
+        "USE_PIPELINE": "true"
+      }
+    }
+  }
+}
+```
+
+If your OAuth app is confidential, also set `GITLAB_OAUTH_CLIENT_SECRET`.
+
+### Personal Access Token setup (stdio)
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "npx",
+      "args": ["-y", "gitlab-mcp@latest"],
+      "env": {
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
+        "GITLAB_ALLOWED_PROJECT_IDS": "",
+        "GITLAB_READ_ONLY_MODE": "false",
+        "USE_GITLAB_WIKI": "true",
+        "USE_MILESTONE": "true",
+        "USE_PIPELINE": "true"
+      }
+    }
+  }
+}
+```
+
+### VS Code `.vscode/mcp.json` examples
+
+PAT with secure prompt input:
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "gitlab_token",
+      "description": "GitLab Personal Access Token",
+      "password": true
+    }
+  ],
+  "servers": {
+    "gitlab": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
       "env": {
-        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
-        "GITLAB_API_URL": "your_gitlab_api_url",
-        "GITLAB_READ_ONLY_MODE": "true"
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4",
+        "GITLAB_READ_ONLY_MODE": "false"
       }
     }
   }
 }
 ```
 
-### Environment Variables
-
-- `GITLAB_PERSONAL_ACCESS_TOKEN`: Your GitLab personal access token.
-- `GITLAB_API_URL`: Your GitLab API URL. (Default: `https://gitlab.com/api/v4`)
-- `GITLAB_READ_ONLY_MODE`: When set to 'true', restricts the server to only expose read-only operations. Useful for enhanced security or when write access is not needed. Also useful for using with Cursor and it's 40 tool limit.
-
-## Tools 🛠️
-
-1. `create_or_update_file`
-
-   - Create or update a single file in a GitLab project. 📝
-   - Inputs:
-     - `project_id` (string): Project ID or namespace/project_path
-     - `file_path` (string): Path to create/update the file
-     - `content` (string): File content
-     - `commit_message` (string): Commit message
-     - `branch` (string): Branch to create/update the file in
-     - `previous_path` (optional string): Previous file path when renaming a file
-   - Returns: File content and commit details
-
-2. `push_files`
-
-   - Push multiple files in a single commit. 📤
-   - Inputs:
-     - `project_id` (string): Project ID or namespace/project_path
-     - `branch` (string): Branch to push to
-     - `files` (array): Array of files to push, each with `file_path` and `content` properties
-     - `commit_message` (string): Commit message
-   - Returns: Updated branch reference
-
-3. `search_repositories`
-
-   - Search for GitLab projects. 🔍
-   - Inputs:
-     - `search` (string): Search query
-     - `page` (optional number): Page number (default: 1)
-     - `per_page` (optional number): Results per page (default: 20, max: 100)
-   - Returns: Project search results
-
-4. `create_repository`
-
-   - Create a new GitLab project. ➕
-   - Inputs:
-     - `name` (string): Project name
-     - `description` (optional string): Project description
-     - `visibility` (optional string): Project visibility level (public, private, internal)
-     - `initialize_with_readme` (optional boolean): Initialize with README
-   - Returns: Details of the created project
-
-5. `get_file_contents`
-
-   - Get the contents of a file or directory. 📂
-   - Inputs:
-     - `project_id` (string): Project ID or namespace/project_path
-     - `file_path` (string): Path to the file/directory
-     - `ref` (optional string): Branch, tag, or commit SHA (default: default branch)
-   - Returns: File/directory content
-
-6. `create_issue`
-
-   - Create a new issue. 🐛
-   - Inputs:
-     - `project_id` (string): Project ID or namespace/project_path
-     - `title` (string): Issue title
-     - `description` (string): Issue description
-     - `assignee_ids` (optional number[]): Array of assignee IDs
-     - `milestone_id` (optional number): Milestone ID
-     - `labels` (optional string[]): Array of labels
-   - Returns: Details of the created issue
-
-7. `create_merge_request`
-
-   - Create a new merge request. 🚀
-   - Inputs:
-     - `project_id` (string): Project ID or namespace/project_path
-     - `title` (string): Merge request title
-     - `description` (string): Merge request description
-     - `source_branch` (string): Branch with changes
-     - `target_branch` (string): Branch to merge into
-     - `allow_collaboration` (optional boolean): Allow collaborators to push commits to the source branch
-     - `draft` (optional boolean): Create as a draft merge request
-   - Returns: Details of the created merge request
-
-8. `fork_repository`
-
-   - Fork a project. 🍴
-   - Inputs:
-     - `project_id` (string): Project ID or namespace/project_path to fork
-     - `namespace` (optional string): Namespace to fork into (default: user namespace)
-   - Returns: Details of the forked project
-
-9. `create_branch`
-
-   - Create a new branch. 🌿
-   - Inputs:
-     - `project_id` (string): Project ID or namespace/project_path
-     - `name` (string): New branch name
-     - `ref` (optional string): Ref to create the branch from (branch, tag, commit SHA, default: default branch)
-   - Returns: Created branch reference
-
-10. `get_merge_request`
-
-    - Get details of a merge request. ℹ️
-    - Inputs:
-      - `project_id` (string): Project ID or namespace/project_path
-      - `merge_request_iid` (number): Merge request IID
-    - Returns: Merge request details
-
-11. `get_merge_request_diffs`
-
-    - Get changes (diffs) of a merge request. diff
-    - Inputs:
-      - `project_id` (string): Project ID or namespace/project_path
-      - `merge_request_iid` (number): Merge request IID
-      - `view` (optional string): Diff view type ('inline' or 'parallel')
-    - Returns: Array of merge request diff information
-
-12. `update_merge_request`
-
-    - Update a merge request. 🔄
-    - Inputs:
-      - `project_id` (string): Project ID or namespace/project_path
-      - `merge_request_iid` (number): Merge request IID
-      - `title` (optional string): New title
-      - `description` (string): New description
-      - `target_branch` (optional string): New target branch
-      - `state_event` (optional string): Merge request state change event ('close', 'reopen')
-      - `remove_source_branch` (optional boolean): Remove source branch after merge
-      - `allow_collaboration` (optional boolean): Allow collaborators to push commits to the source branch
-    - Returns: Updated merge request details
-
-13. `create_note`
-
-    - Create a new note (comment) to an issue or merge request. 💬
-    - Inputs:
-      - `project_id` (string): Project ID or namespace/project_path
-      - `noteable_type` (string): Type of noteable ("issue" or "merge_request")
-      - `noteable_iid` (number): IID of the issue or merge request
-      - `body` (string): Note content
-    - Returns: Details of the created note
-
-14. `list_projects`
-    - List accessible projects with rich filtering options 📊
-    - Inputs:
-      - Search/filtering:
-        - `search`
-        - `owned`
-        - `membership`
-        - `archived`
-        - `visibility`
-      - Features filtering:
-        - `with_issues_enabled`
-        - `with_merge_requests_enabled`
-      - Sorting:
-        - `order_by`
-        - `sort`
-      - Access control:
-        - `min_access_level`
-      - Pagination:
-        - `page`
-        - `per_page`
-        - `simple`
-    - Returns: Array of projects
-15. `list_labels`
-    - List all labels for a project with filtering options 🏷️
-    - Inputs:
-      - `project_id` (string): Project ID or path
-      - `with_counts` (optional): Include issue and merge request counts
-      - `include_ancestor_groups` (optional): Include ancestor groups
-      - `search` (optional): Filter labels by keyword
-    - Returns: Array of labels
-16. `get_label`
-    - Get a single label from a project
-    - Inputs:
-      - `project_id` (string): Project ID or path
-      - `label_id` (number/string): Label ID or name
-      - `include_ancestor_groups` (optional): Include ancestor groups
-    - Returns: label details
-17. `create_label`
-    - Create a new label in an object 🏷️➕
-    - Inputs:
-      - `project_id` (string): Project ID or path
-      - `name` (string): Label name
-      - `color` (string): Color in hex format (e.g., "#FF0000")
-      - `description` (optional): Label description
-      - `priority` (optional): Label priority
-    - Returns: Created label details
-18. `update_label`
-    - Update an existing label in a project 🏷️✏️
-    - Inputs:
-      - `project_id` (string): Project ID or path
-      - `label_id` (number/string): Label ID or name
-      - `new_name` (optional): New label name
-      - `color` (optional): New color in hex format
-      - `description` (optional): New description
-      - `priority` (optional): New priority
-    - Returns: Updated label details
-19. `delete_label`
-
-    - Delete a label from a project 🏷️❌
-    - Inputs:
-      - `project_id` (string): Project ID or path
-      - `label_id` (number/string): Label ID or name
-    - Returns: Success message
-
-20. `list_group_projects`
-
-    - List all projects in a GitLab group. 📂
-    - Inputs:
-      - `group_id` (string): Project ID or namespace/project_path
-      - Filtering options:
-        - `include_subgroups` (optional boolean): Include projects from subgroups
-        - `search` (optional string): Search term to filter projects
-        - `archived` (optional boolean): Filter for archived projects
-        - `visibility` (optional string): Filter by project visibility (public/internal/private)
-        - `with_programming_language` (optional string): Filter by programming language
-        - `starred` (optional boolean): Filter by starred projects
-      - Feature filtering:
-        - `with_issues_enabled` (optional boolean): Filter projects with issues feature enabled
-        - `with_merge_requests_enabled` (optional boolean): Filter projects with merge requests feature enabled
-        - `min_access_level` (optional number): Filter by minimum access level
-      - Pagination:
-        - `page` (optional number): Page number
-        - `per_page` (optional number): Results per page
-      - Sorting:
-        - `order_by` (optional string): Field to sort by
-        - `sort` (optional string): Sort direction (asc/desc)
-      - Additional data:
-        - `statistics` (optional boolean): Include project statistics
-        - `with_custom_attributes` (optional boolean): Include custom attributes
-        - `with_security_reports` (optional boolean): Include security reports
-    - Returns: List of projects
-
-## Environment Variable Configuration
-
-Before running the server, you need to set the following environment variables:
+OAuth (confidential app) with secure prompt input:
 
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "gitlab_oauth_secret",
+      "description": "GitLab OAuth Client Secret",
+      "password": true
+    }
+  ],
+  "servers": {
+    "gitlab": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
+      "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:8765/callback",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      }
+    }
+  }
+}
 ```
-GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token
-GITLAB_API_URL=your_gitlab_api_url  # Default: https://gitlab.com/api/v4
-GITLAB_READ_ONLY_MODE=true          # Optional: Enable read-only mode
+
+GitHub Copilot Chat in VS Code uses the same `.vscode/mcp.json` format.
+
+### Claude Desktop / Claude Code / Cursor
+
+Claude Desktop reads `claude_desktop_config.json`.
+Claude Code supports project-level `.mcp.json` and `claude mcp add-json`.
+Cursor uses `.cursor/mcp.json`.
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "node",
+      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
+      "env": {
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      }
+    }
+  }
+}
+```
+
+### GitLab Duo (`~/.gitlab/duo/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "node",
+      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
+      "env": {
+        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      }
+    }
+  },
+  "approvedTools": ["gitlab_get_project", "gitlab_list_merge_requests"]
+}
 ```
 
-## Credits
+### JetBrains AI Assistant
+
+JetBrains can import an existing MCP JSON config or register the server manually.
+Use stdio command `node /absolute/path/to/gitlab-mcp/dist/index.js`, or HTTP endpoint `http://127.0.0.1:3333/mcp` with required headers.
+
+### Remote authorization (multi-user HTTP)
+
+Start server:
+
+```bash
+REMOTE_AUTHORIZATION=true \
+HTTP_HOST=0.0.0.0 \
+HTTP_PORT=3333 \
+node dist/http.js
+```
+
+Client config:
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "url": "http://127.0.0.1:3333/mcp",
+      "headers": {
+        "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+Dynamic per-request API URL:
+
+```bash
+REMOTE_AUTHORIZATION=true \
+ENABLE_DYNAMIC_API_URL=true \
+HTTP_HOST=0.0.0.0 \
+HTTP_PORT=3333 \
+node dist/http.js
+```
+
+Add header in client requests:
+
+```json
+{
+  "headers": {
+    "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx",
+    "X-GitLab-API-URL": "https://gitlab.example.com/api/v4"
+  }
+}
+```
+
+Remote auth behavior matrix:
+
+| Server Mode                                                 | Required Request Headers                                                        | Token Fallback Chain |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------- |
+| `REMOTE_AUTHORIZATION=false`                                | none                                                                            | enabled              |
+| `REMOTE_AUTHORIZATION=true`                                 | `Authorization: Bearer <token>` or `Private-Token: <token>`                     | disabled             |
+| `REMOTE_AUTHORIZATION=true` + `ENABLE_DYNAMIC_API_URL=true` | `Authorization` or `Private-Token`, and `X-GitLab-API-URL: https://host/api/v4` | disabled             |
+
+### Docker
+
+For containerized deployments, PAT or remote auth is recommended.
+OAuth interactive callback flow is usually less convenient in containers.
+
+```bash
+docker compose up --build -d
+```
+
+or:
+
+```bash
+docker build -t gitlab-mcp .
+
+docker run -d \
+  --name gitlab-mcp \
+  -p 3333:3333 \
+  -e GITLAB_API_URL=https://gitlab.com/api/v4 \
+  -e GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
+  gitlab-mcp
+```
+
+### Compatibility notes
+
+- `GITLAB_PROJECT_ID` is not a supported environment variable in this repository.
+- To set an effective default project, use `GITLAB_ALLOWED_PROJECT_IDS` with one project ID, or pass `project_id` in tool arguments.
+- CLI argument overrides such as `--token` or `--api-url` are not implemented.
+- JSON config files do not support comments (`//`).
+
+## MCP Server Configuration
+
+## HTTP server
+
+```bash
+pnpm install
+cp .env.example .env
+pnpm build
+
+# stdio (local MCP)
+pnpm start
+
+# streamable HTTP server (http://127.0.0.1:3333/mcp)
+pnpm start:http
+```
+
+### Transport and entrypoint
+
+| Transport           | Entry Point          | Endpoint                     | Best For                             |
+| ------------------- | -------------------- | ---------------------------- | ------------------------------------ |
+| **stdio**           | `node dist/index.js` | stdin/stdout                 | Local single-user MCP clients        |
+| **Streamable HTTP** | `node dist/http.js`  | `POST/GET/DELETE /mcp`       | Remote/shared deployments            |
+| **SSE (legacy)**    | `node dist/http.js`  | `GET /sse`, `POST /messages` | Legacy SSE-only clients (`SSE=true`) |
+| **Health**          | `node dist/http.js`  | `GET /healthz`               | Liveness/readiness checks            |
+
+`SSE=true` is not compatible with `REMOTE_AUTHORIZATION=true`.
+
+## Tool Categories
+
+Tools are organized into these categories. All GitLab tools use the `gitlab_` prefix, except `health_check`.
+
+| Category            | Examples                                                                  | Count |
+| ------------------- | ------------------------------------------------------------------------- | ----- |
+| **Projects**        | `get_project`, `list_projects`, `create_repository`, `fork_repository`    | 8     |
+| **Repository**      | `get_repository_tree`, `get_file_contents`, `push_files`, `create_branch` | 7     |
+| **Merge Requests**  | `list_merge_requests`, `create_merge_request`, `merge_merge_request`      | 12    |
+| **MR Code Context** | `get_merge_request_code_context` (advanced code review)                   | 1     |
+| **MR Discussions**  | `list_merge_request_discussions`, `create_merge_request_thread`           | 7     |
+| **MR Notes**        | `list_merge_request_notes`, `create_merge_request_note`                   | 7     |
+| **Draft Notes**     | `list_draft_notes`, `create_draft_note`, `bulk_publish_draft_notes`       | 7     |
+| **Issues**          | `list_issues`, `create_issue`, `update_issue`, issue links                | 13    |
+| **Pipelines**       | `list_pipelines`, `get_pipeline_job_output`, `create_pipeline`            | 12    |
+| **Commits**         | `list_commits`, `get_commit`, `get_commit_diff`                           | 3     |
+| **Labels**          | `list_labels`, `create_label`, `update_label`                             | 5     |
+| **Milestones**      | `list_milestones`, `create_milestone`, burndown events                    | 10    |
+| **Releases**        | `list_releases`, `create_release`, `download_release_asset`               | 7     |
+| **Wiki**            | `list_wiki_pages`, `create_wiki_page`, `update_wiki_page`                 | 5     |
+| **Uploads**         | `upload_markdown`, `download_attachment`                                  | 2     |
+| **GraphQL**         | `execute_graphql_query`, `execute_graphql_mutation`                       | 3     |
+| **Users & Groups**  | `get_users`, `list_namespaces`, `list_events`                             | 6     |
+| **Health**          | `health_check`                                                            | 1     |
+
+See [docs/tools.md](docs/tools.md) for the complete reference.
+
+## Policy & Security
+
+The policy engine controls which tools are available at registration time:
+
+```bash
+# Read-only mode — disables all mutating tools
+GITLAB_READ_ONLY_MODE=true
+
+# Only expose specific tools (supports with or without gitlab_ prefix)
+GITLAB_ALLOWED_TOOLS=get_project,list_merge_requests,get_merge_request
+
+# Block tools by regex pattern
+GITLAB_DENIED_TOOLS_REGEX=^gitlab_(delete|create)_
+
+# Restrict to specific projects
+GITLAB_ALLOWED_PROJECT_IDS=123,456,789
+
+# Keep GraphQL tools enabled in project-scoped mode (disabled by default)
+GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE=true
+
+# Disable feature groups
+USE_PIPELINE=false
+USE_GITLAB_WIKI=false
+```
+
+## Configuration
+
+All configuration is done through environment variables. Key settings:
+
+| Area            | Variable                                  | Default                     | Description                                                                         |
+| --------------- | ----------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------- |
+| GitLab API      | `GITLAB_API_URL`                          | `https://gitlab.com/api/v4` | Base API URL. Supports comma-separated multi-instance URLs.                         |
+| GitLab API      | `GITLAB_PERSONAL_ACCESS_TOKEN`            | —                           | Static default token used when `REMOTE_AUTHORIZATION=false`.                        |
+| Remote Auth     | `REMOTE_AUTHORIZATION`                    | `false`                     | Require per-request token headers in HTTP mode (disables fallback token chain).     |
+| Remote Auth     | `ENABLE_DYNAMIC_API_URL`                  | `false`                     | Require `X-GitLab-API-URL` per request. Requires `REMOTE_AUTHORIZATION=true`.       |
+| HTTP Server     | `HTTP_HOST`                               | `127.0.0.1`                 | HTTP bind host (`0.0.0.0` for external access).                                     |
+| HTTP Server     | `HTTP_PORT`                               | `3333`                      | HTTP server port.                                                                   |
+| HTTP Server     | `HTTP_JSON_ONLY`                          | `false`                     | Force JSON-only responses (no streaming framing).                                   |
+| HTTP Server     | `SSE`                                     | `false`                     | Enable legacy SSE endpoints (`/sse`, `/messages`). Not compatible with remote auth. |
+| Sessions        | `SESSION_TIMEOUT_SECONDS`                 | `3600`                      | Idle session timeout in HTTP mode.                                                  |
+| Sessions        | `MAX_SESSIONS`                            | `1000`                      | Maximum concurrent sessions (`503` when reached).                                   |
+| Sessions        | `MAX_REQUESTS_PER_MINUTE`                 | `300`                       | Per-session rate limit (`429` when exceeded).                                       |
+| Policy          | `GITLAB_READ_ONLY_MODE`                   | `false`                     | Disable mutating tools at registration time.                                        |
+| Policy          | `GITLAB_ALLOWED_PROJECT_IDS`              | —                           | Restrict access to specific GitLab project IDs.                                     |
+| Policy          | `GITLAB_ALLOWED_TOOLS`                    | —                           | Tool allowlist (supports names with or without `gitlab_` prefix).                   |
+| Policy          | `GITLAB_DENIED_TOOLS_REGEX`               | —                           | Regex denylist for tool names.                                                      |
+| Policy          | `GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE` | `false`                     | Keep GraphQL tools enabled when project scope restriction is active.                |
+| Auth Extensions | `GITLAB_USE_OAUTH`                        | `false`                     | Enable OAuth 2.0 PKCE flow.                                                         |
+| Auth Extensions | `GITLAB_TOKEN_SCRIPT`                     | —                           | Resolve token from an external script.                                              |
+| Auth Extensions | `GITLAB_TOKEN_FILE`                       | —                           | Resolve token from a local file.                                                    |
+| Auth Extensions | `GITLAB_AUTH_COOKIE_PATH`                 | —                           | Enable cookie-jar based session auth from Netscape cookie file.                     |
+| Output          | `GITLAB_RESPONSE_MODE`                    | `json`                      | Response format: `json`, `compact-json`, `yaml`.                                    |
+| Output          | `GITLAB_MAX_RESPONSE_BYTES`               | `200000`                    | Max response payload (1KB–2MB), oversized payloads are truncated safely.            |
+| Output          | `GITLAB_HTTP_TIMEOUT_MS`                  | `20000`                     | Upstream GitLab HTTP timeout (1s–120s).                                             |
+| Output          | `GITLAB_ERROR_DETAIL_MODE`                | `safe/full`                 | Error verbosity (`safe` by default in production, `full` otherwise).                |
+| Network/TLS     | `HTTP_PROXY`, `HTTPS_PROXY`               | —                           | Proxy settings for outbound GitLab requests.                                        |
+| Network/TLS     | `GITLAB_CA_CERT_PATH`                     | —                           | Custom CA certificate path (PEM).                                                   |
+| Network/TLS     | `GITLAB_CLOUDFLARE_BYPASS`                | `false`                     | Add browser-like headers for Cloudflare-protected instances.                        |
+| Network/TLS     | `GITLAB_USER_AGENT`                       | —                           | Custom User-Agent for GitLab requests.                                              |
+
+See [docs/configuration.md](docs/configuration.md) for the complete reference.
+
+## Authentication Methods
+
+Authentication behavior depends on mode:
+
+1. **`REMOTE_AUTHORIZATION=true` (HTTP strong mode)**
+   Each request must include `Authorization: Bearer <token>` or `Private-Token: <token>`.
+   When `ENABLE_DYNAMIC_API_URL=true`, each request must also include `X-GitLab-API-URL`.
+2. **`REMOTE_AUTHORIZATION=false` (default mode)**
+   The server resolves credentials in this order:
+   `GITLAB_PERSONAL_ACCESS_TOKEN` -> OAuth PKCE (`GITLAB_USE_OAUTH=true`) -> `GITLAB_TOKEN_SCRIPT` -> `GITLAB_TOKEN_FILE`.
+
+Cookie-based auth (`GITLAB_AUTH_COOKIE_PATH`) is applied independently via a cookie jar and can work with or without a token.
+
+See [docs/authentication.md](docs/authentication.md) for setup guides.
+
+## Development
+
+```bash
+pnpm dev           # stdio mode with hot-reload
+pnpm dev:http      # HTTP mode with hot-reload
+pnpm test          # Run tests
+pnpm test:watch    # Run tests in watch mode
+pnpm lint          # Lint
+pnpm typecheck     # Type check
+pnpm inspector     # Launch MCP Inspector
+```
+
+### Project Structure
+
+See [docs/architecture.md](docs/architecture.md) for detailed design documentation.
+
+## Documentation
+
+- [Configuration Reference](docs/configuration.md) — All environment variables
+- [Tools Reference](docs/tools.md) — Complete list of MCP tools
+- [Authentication Guide](docs/authentication.md) — Auth methods and setup
+- [Deployment Guide](docs/deployment.md) — Docker, production, and multi-instance
+- [Architecture](docs/architecture.md) — Internal design and patterns
+
+## Acknowledgements
 
-- [Model Context Protocol](https://modelcontextprotocol.io/)
-- [GitLab MCP](https://github.com/zereight/gitlab-mcp)
+This repository references and learns from parts of the implementation in [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp). Thanks to the maintainers and contributors for their work.
 
 ## License