mcp-gitlab 0.2.0__tar.gz → 0.3.0__tar.gz

mcp_gitlab-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Report a bug or unexpected behavior
+title: ""
+labels: bug
+assignees: ""
+---
+
+**Tool name**
+Which tool(s) are affected? (e.g. `gitlab_create_mr`, `gitlab_list_pipelines`)
+
+**Describe the bug**
+A clear description of what happened.
+
+**Expected behavior**
+What should have happened instead.
+
+**Error output**
+```
+Paste the error JSON or traceback here
+```
+
+**Environment**
+- mcp-gitlab version: (e.g. 0.2.0)
+- Python version:
+- MCP client: (e.g. Claude Code, Cursor, VS Code)
+- GitLab version: (e.g. 17.x, gitlab.com)
+
+**Additional context**
+Any other relevant details.

mcp_gitlab-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest a new tool or enhancement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+**Is this a new tool or an enhancement to an existing one?**
+New tool / Enhancement
+
+**Describe the feature**
+What GitLab API endpoint or workflow should be supported?
+
+**GitLab API reference**
+Link to the relevant [GitLab REST API docs](https://docs.gitlab.com/api/).
+
+**Use case**
+How would you use this feature?

{mcp_gitlab-0.2.0 → mcp_gitlab-0.3.0}/.gitignore

@@ -32,3 +32,6 @@ Thumbs.db
 .idea/
 .vscode/
 *.iml
+.claude/
+.cursorrules
+.cursor/

mcp_gitlab-0.3.0/AGENTS.md

@@ -0,0 +1,74 @@
+# mcp-gitlab — Agent Context
+
+MCP server providing 76 tools for the GitLab REST API v4.
+
+## Architecture
+
+- **Entry point**: `src/mcp_gitlab/__init__.py` — click CLI, loads env, runs FastMCP server
+- **Client**: `src/mcp_gitlab/client.py` — async httpx client with all GitLab API methods
+- **Tools**: `src/mcp_gitlab/servers/gitlab.py` — all FastMCP tool registrations
+- **Models**: `src/mcp_gitlab/models/` — Pydantic models for typed API responses (unused by tools)
+- **Config**: `src/mcp_gitlab/config.py` — `GitLabConfig` dataclass from env vars
+- **Exceptions**: `src/mcp_gitlab/exceptions.py` — `GitLabApiError`, `GitLabAuthError`, etc.
+
+## Patterns
+
+- All tools are `async def` returning JSON strings
+- Error handling: try/except wrapping every tool, returning `{"error": ...}` JSON
+- Write access control: `_check_write(ctx)` raises `GitLabWriteDisabledError` when `GITLAB_READ_ONLY=true`
+- Tags: every tool tagged with `{"gitlab", "<category>", "read"|"write"}`
+- Parameters use `Annotated[type, Field(description=...)]`
+- Client uses httpx with `PRIVATE-TOKEN` header auth
+- Project/group IDs can be numeric or URL-encoded paths
+
+## MCP Compliance Rules
+
+### Tool Annotations (MANDATORY)
+Every tool MUST have `annotations={}` with at minimum `readOnlyHint`.
+- Read tools: `annotations={"readOnlyHint": True, "idempotentHint": True}`
+- Non-destructive write tools: `annotations={"readOnlyHint": False}`
+- Destructive write tools: `annotations={"destructiveHint": True, "readOnlyHint": False}`
+- Idempotent writes (PUT/update): add `idempotentHint: True`
+
+### Tool Descriptions
+- 1-2 sentences. Front-load what it does AND what it returns.
+- Bad: "This tool gets a merge request."
+- Good: "Get merge request details. Returns title, state, branches, author, diff_refs."
+
+### Error Handling
+- Every tool MUST wrap in try/except and return `_err(e)` — never raise.
+- Error text MUST be actionable: include what went wrong and suggest a fix.
+- Never return concatenated JSON strings — always a single valid JSON object.
+- Never expose stack traces, tokens, or internal paths.
+
+### Parameter Design
+- Use `Annotated[type, Field(description="...")]` on every parameter.
+- Use `Literal[...]` for known value sets instead of plain `str`.
+- Every optional parameter must have a default.
+- Flatten — no nested dicts unless truly necessary.
+
+### Read-Only Mode
+- Every write tool MUST call `_check_write(ctx)` before any mutation.
+
+### Naming Convention
+- Pattern: `gitlab_{verb}_{resource}` (snake_case)
+- Verbs: create, get, list, search, update, delete, merge, rebase, retry, play, cancel, award, remove, share, unshare, compare, add, reply, resolve
+
+## Tool Categories
+
+Projects (4), Approvals (10), Groups (6), Branches (3), Commits (4), Merge Requests (8), MR Notes (6), MR Discussions (4), Pipelines (5), Jobs (4), Tags (4), Releases (5), CI/CD Variables (8), Issues (5)
+
+## Environment Variables
+
+- `GITLAB_URL` (required) — GitLab instance base URL
+- `GITLAB_TOKEN` or `GITLAB_PAT` (required) — Personal access token
+- `GITLAB_READ_ONLY` — disable mutations
+- `GITLAB_TIMEOUT` — request timeout seconds
+- `GITLAB_SSL_VERIFY` — SSL verification toggle
+
+## Known Limitations / Future Work
+
+- 76 tools in one server file (exceeds 5-15 guideline). Consider splitting by category in a future refactor.
+- Pydantic models in `models/` are defined but unused — tools work with raw dicts. Consider removing or wiring up.
+- No tool-level tests. Client tests exist but the MCP registration layer (`servers/gitlab.py`) is untested.
+- Errors are returned as successful tool results with `{"error": ...}` (soft-error pattern). Callers must inspect JSON content.

{mcp_gitlab-0.2.0 → mcp_gitlab-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gitlab
-Version: 0.2.0
+Version: 0.3.0
 Summary: MCP server for GitLab API — projects, MRs, pipelines, CI/CD variables, approvals, and more
 Project-URL: Homepage, https://github.com/vish288/mcp-gitlab
 Project-URL: Repository, https://github.com/vish288/mcp-gitlab
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Version Control :: Git
@@ -43,11 +44,19 @@ Description-Content-Type: text/markdown
 
 Built with [FastMCP](https://github.com/jlowin/fastmcp), [httpx](https://www.python-httpx.org/), and [Pydantic](https://docs.pydantic.dev/).
 
-## Quick Install
+## 1-Click Installation
 
-### Cursor
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://vish288.github.io/mcp-gitlab-cursor-redirect.html?install=cursor)
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=mcp-gitlab&config=eyJtY3BTZXJ2ZXJzIjogeyJnaXRsYWIiOiB7ImNvbW1hbmQiOiAidXZ4IiwgImFyZ3MiOiBbIm1jcC1naXRsYWIiXSwgImVudiI6IHsiR0lUTEFCX1VSTCI6ICJodHRwczovL2dpdGxhYi5leGFtcGxlLmNvbSIsICJHSVRMQUJfVE9LRU4iOiAieW91ci10b2tlbiJ9fX19)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-gitlab-cursor-redirect.html?install=vscode) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-gitlab-cursor-redirect.html?install=vscode-insiders)
+
+> **💡 Tip:** For other AI assistants (Claude Code, Windsurf, IntelliJ), visit the **[GitLab MCP Installation Gateway](https://vish288.github.io/mcp-gitlab-cursor-redirect.html)**.
+
+<details>
+<summary><b>Manual Setup Guides (Click to expand)</b></summary>
+<br/>
+
+> Prerequisite: Install `uv` first (required for all `uvx` install flows). [Install uv](https://docs.astral.sh/uv/getting-started/installation/).
 
 ### Claude Code
 
@@ -55,9 +64,12 @@ Built with [FastMCP](https://github.com/jlowin/fastmcp), [httpx](https://www.pyt
 claude mcp add gitlab -- uvx mcp-gitlab
 ```
 
-### Windsurf / VS Code
+### Windsurf & IntelliJ
 
-Add to your MCP config file:
+**Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`
+**IntelliJ:** Add to `Settings | Tools | MCP Servers`
+
+> **Note:** The actual server config starts at `gitlab` inside the `mcpServers` object.
 
 ```json
 {
@@ -80,15 +92,17 @@ Add to your MCP config file:
 uv pip install mcp-gitlab
 ```
 
+</details>
+
 ## Configuration
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `GITLAB_URL` | Yes | GitLab instance URL (e.g. `https://gitlab.example.com`) |
-| `GITLAB_TOKEN` | Yes | Authentication token (see below) |
-| `GITLAB_READ_ONLY` | No | Set to `true` to disable write operations |
-| `GITLAB_TIMEOUT` | No | Request timeout in seconds (default: 30) |
-| `GITLAB_SSL_VERIFY` | No | Set to `false` to skip SSL verification |
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GITLAB_URL` | **Yes** | - | GitLab instance URL (e.g. `https://gitlab.example.com`) |
+| `GITLAB_TOKEN` | **Yes** | - | Authentication token (see below) |
+| `GITLAB_READ_ONLY` | No | `false` | Set to `true` to disable write operations |
+| `GITLAB_TIMEOUT` | No | `30` | Request timeout in seconds |
+| `GITLAB_SSL_VERIFY` | No | `true` | Set to `false` to skip SSL verification |
 
 ### Supported Token Types
 
@@ -107,8 +121,8 @@ uv pip install mcp-gitlab
 | Claude Desktop | Yes | `claude_desktop_config.json` |
 | Claude Code | Yes | `claude mcp add` |
 | Cursor | Yes | One-click deeplink or `.cursor/mcp.json` |
+| VS Code Copilot | Yes | One-click deeplink or `.vscode/mcp.json` |
 | Windsurf | Yes | `~/.codeium/windsurf/mcp_config.json` |
-| VS Code Copilot | Yes | `.vscode/mcp.json` |
 | Any MCP client | Yes | stdio or HTTP transport |
 
 ## Tools (76)

{mcp_gitlab-0.2.0 → mcp_gitlab-0.3.0}/README.md

@@ -10,11 +10,19 @@
 
 Built with [FastMCP](https://github.com/jlowin/fastmcp), [httpx](https://www.python-httpx.org/), and [Pydantic](https://docs.pydantic.dev/).
 
-## Quick Install
+## 1-Click Installation
 
-### Cursor
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://vish288.github.io/mcp-gitlab-cursor-redirect.html?install=cursor)
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=mcp-gitlab&config=eyJtY3BTZXJ2ZXJzIjogeyJnaXRsYWIiOiB7ImNvbW1hbmQiOiAidXZ4IiwgImFyZ3MiOiBbIm1jcC1naXRsYWIiXSwgImVudiI6IHsiR0lUTEFCX1VSTCI6ICJodHRwczovL2dpdGxhYi5leGFtcGxlLmNvbSIsICJHSVRMQUJfVE9LRU4iOiAieW91ci10b2tlbiJ9fX19)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-gitlab-cursor-redirect.html?install=vscode) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-gitlab-cursor-redirect.html?install=vscode-insiders)
+
+> **💡 Tip:** For other AI assistants (Claude Code, Windsurf, IntelliJ), visit the **[GitLab MCP Installation Gateway](https://vish288.github.io/mcp-gitlab-cursor-redirect.html)**.
+
+<details>
+<summary><b>Manual Setup Guides (Click to expand)</b></summary>
+<br/>
+
+> Prerequisite: Install `uv` first (required for all `uvx` install flows). [Install uv](https://docs.astral.sh/uv/getting-started/installation/).
 
 ### Claude Code
 
@@ -22,9 +30,12 @@ Built with [FastMCP](https://github.com/jlowin/fastmcp), [httpx](https://www.pyt
 claude mcp add gitlab -- uvx mcp-gitlab
 ```
 
-### Windsurf / VS Code
+### Windsurf & IntelliJ
 
-Add to your MCP config file:
+**Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`
+**IntelliJ:** Add to `Settings | Tools | MCP Servers`
+
+> **Note:** The actual server config starts at `gitlab` inside the `mcpServers` object.
 
 ```json
 {
@@ -47,15 +58,17 @@ Add to your MCP config file:
 uv pip install mcp-gitlab
 ```
 
+</details>
+
 ## Configuration
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `GITLAB_URL` | Yes | GitLab instance URL (e.g. `https://gitlab.example.com`) |
-| `GITLAB_TOKEN` | Yes | Authentication token (see below) |
-| `GITLAB_READ_ONLY` | No | Set to `true` to disable write operations |
-| `GITLAB_TIMEOUT` | No | Request timeout in seconds (default: 30) |
-| `GITLAB_SSL_VERIFY` | No | Set to `false` to skip SSL verification |
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GITLAB_URL` | **Yes** | - | GitLab instance URL (e.g. `https://gitlab.example.com`) |
+| `GITLAB_TOKEN` | **Yes** | - | Authentication token (see below) |
+| `GITLAB_READ_ONLY` | No | `false` | Set to `true` to disable write operations |
+| `GITLAB_TIMEOUT` | No | `30` | Request timeout in seconds |
+| `GITLAB_SSL_VERIFY` | No | `true` | Set to `false` to skip SSL verification |
 
 ### Supported Token Types
 
@@ -74,8 +87,8 @@ uv pip install mcp-gitlab
 | Claude Desktop | Yes | `claude_desktop_config.json` |
 | Claude Code | Yes | `claude mcp add` |
 | Cursor | Yes | One-click deeplink or `.cursor/mcp.json` |
+| VS Code Copilot | Yes | One-click deeplink or `.vscode/mcp.json` |
 | Windsurf | Yes | `~/.codeium/windsurf/mcp_config.json` |
-| VS Code Copilot | Yes | `.vscode/mcp.json` |
 | Any MCP client | Yes | stdio or HTTP transport |
 
 ## Tools (76)

{mcp_gitlab-0.2.0 → mcp_gitlab-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-gitlab"
-version = "0.2.0"
+version = "0.3.0"
 description = "MCP server for GitLab API — projects, MRs, pipelines, CI/CD variables, approvals, and more"
 readme = "README.md"
 license = {text = "MIT"}
@@ -34,6 +34,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Software Development :: Version Control :: Git",