mcp-gitlab 0.9.2__tar.gz → 0.9.4__tar.gz

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/.gitignore

@@ -35,3 +35,6 @@ Thumbs.db
 .claude/
 .cursorrules
 .cursor/
+
+# 1Password shell-plugin config: local tool state, not project config.
+.op/

mcp_gitlab-0.9.4/AGENTS.md

@@ -0,0 +1,184 @@
+# mcp-gitlab — Agent Context
+
+MCP server exposing 83 tools, 7 resources, and 6 prompts over the GitLab REST API v4. Covers the
+full project lifecycle: code, reviews, CI/CD, releases, and issue tracking. Works against
+GitLab.com and self-hosted instances.
+
+## Architecture
+
+- **Entry point**: `src/mcp_gitlab/__init__.py` — click CLI, loads `.env` via python-dotenv, runs the FastMCP server
+- **Client**: `src/mcp_gitlab/client.py` — async httpx client with all GitLab API methods
+- **Tools**: `src/mcp_gitlab/servers/gitlab.py` — all 83 FastMCP tool registrations
+- **Resources**: `src/mcp_gitlab/servers/resources.py` — 7 MCP resources (4 `resource://rules/*`, 3 `resource://guides/*`), content in `src/mcp_gitlab/resources/*.md`
+- **Prompts**: `src/mcp_gitlab/servers/prompts.py` — 6 MCP prompts (multi-tool workflows)
+- **Helpers**: `src/mcp_gitlab/servers/_helpers.py` — cached file loader with path-traversal guard, plus GitLab URL parsers. Most tools accept a project ID, a path, *or* a full GitLab URL for `project_id`; MR and pipeline URLs also yield the iid/id
+- **Config**: `src/mcp_gitlab/config.py` — `GitLabConfig` dataclass built from env vars
+- **Exceptions**: `src/mcp_gitlab/exceptions.py` — `GitLabError` base; `GitLabApiError`, `GitLabAuthError`, `GitLabNotFoundError`, `GitLabWriteDisabledError`
+- **Tests**: `tests/` — `unit/test_tools.py` (143 tool-level tests via the FastMCP in-memory client), plus `test_client.py`, `test_config.py`, `test_exceptions.py`, `test_prompts.py`, `test_resources.py`, and `tests/test_links.py`. Shared fixtures (`config`, `client`, `mock_api` via respx) live in `tests/conftest.py`
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest --cov
+uv run ruff check .
+uv run ruff format --check .   # CI runs --check; formatting drift fails the build
+```
+
+`pytest` uses `asyncio_mode = "auto"` — async tests need no marker. Ruff line length is 100,
+target py310; lint rules include `S` (bandit), `EM`, `N`, `UP`. `tests/**` waives `S101`,
+`S105`, `S106`.
+
+## Patterns
+
+- All tools are `async def` returning JSON strings
+- `_ok(data)` for success, `_err(e)` for failure; `_paginated(items)` for list responses
+- Pipeline and job payloads are trimmed by `_slim_pipeline` / `_slim_job`; tools expose `slim=True` by default
+- 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
+- `gitlab_list_variables` / `gitlab_list_group_variables` return `***MASKED***` for variables GitLab marks as masked
+
+## MCP Compliance Rules
+
+### Tool annotations (mandatory)
+Every tool MUST have `annotations={}` with at minimum `readOnlyHint`.
+- Read tools: `annotations={"readOnlyHint": True, "idempotentHint": True}`
+- Non-destructive writes: `annotations={"readOnlyHint": False}`
+- Destructive writes: `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: what went wrong plus a suggested fix.
+- Never return concatenated JSON strings — always a single valid JSON object.
+- Never expose stack traces, tokens, or internal paths.
+
+### Parameter design
+- `Annotated[type, Field(description="...")]` on every parameter.
+- `Literal[...]` for known value sets instead of plain `str`.
+- Every optional parameter has 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, approve, unapprove, subscribe, unsubscribe
+
+## Tool Categories (83)
+
+| Category | Count | Operations |
+|---|---|---|
+| Projects | 4 | get, create, delete, update merge settings |
+| Approvals | 10 | project-level approval settings; project and MR approval rules (list, create, update, delete) |
+| Groups | 6 | list, get groups; share/unshare project with group; share/unshare group with group |
+| Branches | 3 | list, create, delete |
+| Commits | 4 | list, get, create, compare refs |
+| Merge Requests | 15 | list, get, create, update, merge, merge sequence, rebase, changes/diffs, approve, unapprove, get approvals, list pipelines, list commits, subscribe, unsubscribe |
+| MR Notes | 6 | list, add, update, delete notes; award/remove emoji |
+| MR Discussions | 4 | list, create, reply, resolve |
+| Pipelines | 5 | list, get, create, retry, cancel |
+| Jobs | 4 | retry, play, cancel, get job log |
+| Tags | 4 | list, get, create, delete |
+| Releases | 5 | list, get, create, update, delete |
+| CI/CD Variables | 8 | project and group variables (list, create, update, delete) |
+| Issues | 5 | list, get, create, update, add comment |
+
+Share/unshare tools are counted under Groups, not Projects. There is no `gitlab_list_jobs` —
+get job IDs from `gitlab_get_pipeline(..., include_jobs=True)`.
+
+## Common Workflows
+
+- **Code review**: `gitlab_list_mrs` → `gitlab_mr_changes` → `gitlab_list_mr_discussions` → `gitlab_add_mr_note` or `gitlab_create_mr_discussion` → `gitlab_resolve_discussion`
+- **Pipeline debugging**: `gitlab_list_pipelines` → `gitlab_get_pipeline` (`include_jobs=True`) → `gitlab_get_job_log` → `gitlab_retry_job`
+- **Release**: `gitlab_list_commits` → `gitlab_compare` → `gitlab_create_tag` → `gitlab_create_release`
+- **Branch protection**: `gitlab_list_project_approval_rules` → `gitlab_create_project_approval_rule` → `gitlab_update_project_merge_settings`
+- **Issue triage**: `gitlab_list_issues` → `gitlab_get_issue` → `gitlab_update_issue` → `gitlab_add_issue_comment`
+
+## Prompts
+
+Prompt content lives as `.md` files in `src/mcp_gitlab/resources/prompts/`, loaded by
+`servers/prompts.py` via `_load_prompt()` (`string.Template.safe_substitute` for parameters) and
+registered with `@mcp.prompt()`. Each returns `list[Message]`: a user message (workflow template)
+plus an assistant acknowledgment.
+
+| Prompt | Purpose | Tags |
+|---|---|---|
+| `review_mr` | MR review workflow | gitlab, review |
+| `approve_mr` | MR approval workflow | gitlab, review, approvals |
+| `diagnose_pipeline` | CI debug workflow | gitlab, ci |
+| `prepare_release` | Release preparation | gitlab, release |
+| `setup_branch_protection` | Branch protection setup | gitlab, settings |
+| `triage_issues` | Issue triage workflow | gitlab, issues |
+
+## Environment Variables
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `GITLAB_URL` | yes | — | Instance base URL; trailing slash stripped, `/api/v4` appended |
+| token (see below) | yes | — | Personal access token, OAuth2 token, or `$CI_JOB_TOKEN` |
+| `GITLAB_READ_ONLY` | no | `false` | `true`/`1`/`yes` disables all writes and deletes, enforced before any API call |
+| `GITLAB_TIMEOUT` | no | `30` | Request timeout in seconds |
+| `GITLAB_SSL_VERIFY` | no | `true` | `false`/`0`/`no` skips verification — self-signed certs only |
+
+Token is read from the first of `GITLAB_TOKEN`, `GITLAB_PAT`, `GITLAB_PERSONAL_ACCESS_TOKEN`,
+`GITLAB_API_TOKEN` that is set. Scope `api` for full access, `read_api` for read-only deployments.
+Tokens are never persisted — they are read from the environment at startup.
+
+CLI flags override env: `--gitlab-url`, `--gitlab-token`, `--read-only`, plus
+`--transport {stdio,sse,streamable-http}` with `--host` (default `127.0.0.1`) and `--port`
+(default `8000`); host/port apply only to non-stdio transports.
+
+## Release Workflow
+
+Releases run through GitHub Actions — never bump versions manually.
+
+```bash
+gh workflow run release.yml -f bump=minor                  # 0.9.0 → 0.10.0
+gh workflow run release.yml -f bump=patch                  # 0.9.0 → 0.9.1
+gh workflow run release.yml -f bump=major                  # 0.9.0 → 1.0.0
+gh workflow run release.yml -f bump=minor -f dry_run=true  # preview changelog, no push
+```
+
+1. `release.yml` (workflow_dispatch) — bumps the version in `pyproject.toml`, `llms.txt`,
+   `llms-full.txt`, `server.json`, `gemini-extension.json`; regenerates `uv.lock`; prepends a
+   CHANGELOG.md entry; creates the release commit and tag via the GitHub API.
+2. `publish.yml` (triggered by a `v*` tag push) — builds the wheel, publishes to PyPI, creates the
+   GitHub Release with auto-generated notes, then publishes to the MCP Registry.
+
+Rules:
+- Never edit the `pyproject.toml` version directly — the workflow owns it.
+- Never create tags manually — the workflow creates them.
+- Commit messages must follow Conventional Commits (`feat:`, `fix:`, `docs:`, …) for changelog generation.
+- The release commit is authored by `github-actions[bot]` with message `chore(release): X.Y.Z`.
+
+## Documentation Freshness (mandatory)
+
+When a changeset adds, removes, or modifies tools, resources, or prompts, update ALL of these in
+the same commit:
+
+- `README.md` — counts in heading and intro, tool table, full tool reference, usage examples, permissions table
+- `llms.txt` — count in tagline and documentation link
+- `llms-full.txt` — count in tagline, documentation link, full tool reference section
+- `AGENTS.md` — counts in intro, tool category table
+- `GEMINI.md` — count in intro, tool categories, common workflows
+- `server.json` — description field (≤100 chars)
+
+Checklist: counts match the actual registered tools/resources/prompts; the category list is
+complete; new entries appear in the right sections with parameters and annotations.
+
+## Known Limitations
+
+- 83 tools in one server file, well past the 5-15 guideline. Split by category if it is refactored.
+- Errors come back as successful tool results carrying `{"error": ...}` (soft-error pattern);
+  callers must inspect the JSON content rather than relying on protocol-level errors.

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.9.4] - 2026-09-20
+
+### Bug Fixes
+- fix: correct error masking in merge sequence, tighten docs and messages (7b43094)
+
+### Documentation
+- docs: consolidate GEMINI.md into AGENTS.md (bcfb75f)
+
+### Chores
+- chore: ignore local 1Password plugin state (8d0b554)
+
+
+## [0.9.3] - 2026-08-22
+
+### Chores
+- chore(deps): bump mcp in the uv group across 1 directory (fcf3ec8)
+
+
 ## [0.9.2] - 2026-07-08
 
 ### Chores

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mcp-gitlab
-Version: 0.9.2
+Version: 0.9.4
 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
@@ -156,7 +156,7 @@ These accept any of the following token types:
 | **Groups** | 6 | list, get, share/unshare project, share/unshare group |
 | **Branches** | 3 | list, create, delete |
 | **Commits** | 4 | list, get (with diff), create, compare |
-| **Merge Requests** | 16 | list, get, create, update, merge, merge-sequence, rebase, changes, approve, unapprove, get approvals, list reviewers, list pipelines, list commits, subscribe, unsubscribe |
+| **Merge Requests** | 15 | list, get, create, update, merge, merge-sequence, rebase, changes, approve, unapprove, get approvals, list pipelines, list commits, subscribe, unsubscribe |
 | **MR Notes** | 6 | list, add, delete, update, award emoji, remove emoji |
 | **MR Discussions** | 4 | list, create (inline + multi-line), reply, resolve |
 | **Pipelines** | 5 | list, get (with jobs), create, retry, cancel |
@@ -268,7 +268,7 @@ These accept any of the following token types:
 | `gitlab_retry_job` | Retry a job |
 | `gitlab_play_job` | Trigger manual job |
 | `gitlab_cancel_job` | Cancel a job |
-| `gitlab_get_job_log` | Get job log output |
+| `gitlab_get_job_log` | Get job log output (last 200 lines by default; `tail_lines=0` for all) |
 
 ### Tags
 | Tool | Description |

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/README.md

@@ -120,7 +120,7 @@ These accept any of the following token types:
 | **Groups** | 6 | list, get, share/unshare project, share/unshare group |
 | **Branches** | 3 | list, create, delete |
 | **Commits** | 4 | list, get (with diff), create, compare |
-| **Merge Requests** | 16 | list, get, create, update, merge, merge-sequence, rebase, changes, approve, unapprove, get approvals, list reviewers, list pipelines, list commits, subscribe, unsubscribe |
+| **Merge Requests** | 15 | list, get, create, update, merge, merge-sequence, rebase, changes, approve, unapprove, get approvals, list pipelines, list commits, subscribe, unsubscribe |
 | **MR Notes** | 6 | list, add, delete, update, award emoji, remove emoji |
 | **MR Discussions** | 4 | list, create (inline + multi-line), reply, resolve |
 | **Pipelines** | 5 | list, get (with jobs), create, retry, cancel |
@@ -232,7 +232,7 @@ These accept any of the following token types:
 | `gitlab_retry_job` | Retry a job |
 | `gitlab_play_job` | Trigger manual job |
 | `gitlab_cancel_job` | Cancel a job |
-| `gitlab_get_job_log` | Get job log output |
+| `gitlab_get_job_log` | Get job log output (last 200 lines by default; `tail_lines=0` for all) |
 
 ### Tags
 | Tool | Description |

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-gitlab",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "MCP server for GitLab API \u2014 projects, MRs, pipelines, CI/CD variables, approvals, and more",
   "mcpServers": {
     "mcp-gitlab": {

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/llms-full.txt

@@ -5,7 +5,7 @@
 MCP server that wraps the GitLab REST API. Works with GitLab.com and self-hosted instances (CE/EE). No GitLab Duo or Premium required. Built with FastMCP, httpx, and Pydantic.
 
 - **Install**: `uvx mcp-gitlab`
-- **Version**: 0.9.2
+- **Version**: 0.9.4
 - **Python**: >=3.10
 - **License**: MIT
 - **Transport**: stdio (default), SSE, streamable-http
@@ -133,7 +133,7 @@ uvx mcp-gitlab --gitlab-url https://gitlab.example.com --gitlab-token glpat-xxx
 | `gitlab_create_commit` | Create a commit with multiple file actions |
 | `gitlab_compare` | Compare two branches, tags, or commits |
 
-### Merge Requests (16)
+### Merge Requests (15)
 
 | Tool | Description |
 |------|-------------|
@@ -190,7 +190,7 @@ uvx mcp-gitlab --gitlab-url https://gitlab.example.com --gitlab-token glpat-xxx
 | `gitlab_retry_job` | Retry a failed job |
 | `gitlab_play_job` | Trigger a manual job |
 | `gitlab_cancel_job` | Cancel a running job |
-| `gitlab_get_job_log` | Get the log (trace) output of a job |
+| `gitlab_get_job_log` | Get the log (trace) output of a job — last 200 lines by default, `tail_lines=0` for the whole log |
 
 ### Tags (4)
 
@@ -234,7 +234,7 @@ uvx mcp-gitlab --gitlab-url https://gitlab.example.com --gitlab-token glpat-xxx
 | `gitlab_update_issue` | Update an existing issue |
 | `gitlab_add_issue_comment` | Add a comment to an issue |
 
-## Resources (6)
+## Resources (7)
 
 The server exposes curated workflow guides as MCP resources that clients can read on demand.
 

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/llms.txt

@@ -5,7 +5,7 @@
 MCP server that wraps the GitLab REST API. Works with GitLab.com and self-hosted instances (CE/EE). No GitLab Duo or Premium required. Built with FastMCP, httpx, and Pydantic.
 
 - **Install**: `uvx mcp-gitlab`
-- **Version**: 0.9.2
+- **Version**: 0.9.4
 - **Python**: >=3.10
 - **License**: MIT
 - **Transport**: stdio (default), SSE, streamable-http

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-gitlab"
-version = "0.9.2"
+version = "0.9.4"
 description = "MCP server for GitLab API — projects, MRs, pipelines, CI/CD variables, approvals, and more"
 readme = "README.md"
 license = {text = "MIT"}

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/server.json

@@ -6,19 +6,19 @@
     "url": "https://github.com/vish288/mcp-gitlab",
     "source": "github"
   },
-  "version": "0.9.2",
+  "version": "0.9.4",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "mcp-gitlab",
-      "version": "0.9.2",
+      "version": "0.9.4",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
           "name": "GITLAB_TOKEN",
-          "description": "GitLab personal access token (also accepts GITLAB_PAT or GITLAB_API_TOKEN)",
+          "description": "GitLab personal access token (also accepts GITLAB_PAT, GITLAB_PERSONAL_ACCESS_TOKEN, or GITLAB_API_TOKEN)",
           "isRequired": true,
           "format": "string",
           "isSecret": true

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/src/mcp_gitlab/servers/gitlab.py

@@ -726,7 +726,9 @@ async def gitlab_share_group_with_group(
         _check_write(ctx)
         level = ACCESS_LEVELS.get(access_level.lower())
         if level is None:
-            return _ok({"error": f"Invalid access level: {access_level}"})
+            return _ok(
+                {"error": f"Invalid access level: {access_level}. Use: {', '.join(ACCESS_LEVELS)}"}
+            )
         await _get_client(ctx).share_group_with_group(target_group_id, source_group_id, level)
         return _ok({"status": "shared"})
     except Exception as e:
@@ -1031,10 +1033,7 @@ async def gitlab_get_mr(
 ) -> str:
     """Get merge request details.
 
-
-
     Returns title, state, source/target branches, author, diff_refs, and merge status.
-
     """
     try:
         data = await _get_client(ctx).get_merge_request(project_id, mr_iid)
@@ -1111,7 +1110,7 @@ async def gitlab_update_mr(
     draft: Annotated[bool | None, Field(description="Set draft status")] = None,
     state_event: Annotated[str | None, Field(description="close or reopen")] = None,
 ) -> str:
-    """Update an MR's title, description, labels, assignees, milestone, or state event.
+    """Update an MR's title, description, target branch, labels, squash/draft flags, or state.
 
     Returns the updated MR object.
     """
@@ -1210,10 +1209,10 @@ async def gitlab_merge_mr_sequence(
 
     Returns a per-MR result list with merged/failed status and any error.
     """
+    merged: list[int] = []
     try:
         _check_write(ctx)
         client = _get_client(ctx)
-        merged: list[int] = []
         params: dict[str, Any] = {}
         if squash is not None:
             params["squash"] = squash
@@ -1238,13 +1237,9 @@ async def gitlab_merge_mr_sequence(
 
         return _ok({"status": "all_merged", "merged": merged})
     except Exception as e:
-        detail: dict[str, Any] = {"error": str(e), "merged_so_far": merged}
-        from ..exceptions import GitLabApiError
-
-        if isinstance(e, GitLabApiError):
-            detail["status_code"] = e.status_code
-            detail["body"] = e.body
-        return json.dumps(detail, indent=2, ensure_ascii=False)
+        detail = json.loads(_err(e))
+        detail["merged_so_far"] = merged
+        return _ok(detail)
 
 
 @mcp.tool(
@@ -1455,10 +1450,7 @@ async def gitlab_list_mr_discussions(
 ) -> str:
     """List discussions on a merge request.
 
-
-
-    Returns discussion threads with notes, excluding system notes.
-
+    Returns discussion threads with notes, excluding system-only threads.
     """
     try:
         data = await _get_client(ctx).list_mr_discussions(project_id, mr_iid)
@@ -1818,11 +1810,8 @@ async def gitlab_get_pipeline(
 ) -> str:
     """Get pipeline details, optionally with jobs.
 
-
-
     Returns id, status, ref, timing, web_url.
     Jobs include id, name, stage, status, timing, failure_reason, web_url.
-
     """
     try:
         client = _get_client(ctx)
@@ -1989,9 +1978,15 @@ async def gitlab_get_job_log(
         str, Field(description="Project ID, path, or full GitLab URL", min_length=1)
     ],
     job_id: Annotated[int, Field(description="Job ID")],
-    tail_lines: Annotated[int, Field(description="Number of lines from the end to return")] = 200,
+    tail_lines: Annotated[
+        int,
+        Field(description="Lines to return from the end of the log; 0 returns the whole log", ge=0),
+    ] = 200,
 ) -> str:
-    """Get a job's full log trace as text."""
+    """Get a job's log trace, truncated to the last tail_lines lines (default 200).
+
+    Returns {log, total_lines, shown_lines}. Pass tail_lines=0 for the whole log.
+    """
     try:
         log_text = await _get_client(ctx).get_job_log(project_id, job_id)
         lines = log_text.splitlines()
@@ -2107,7 +2102,7 @@ async def gitlab_delete_tag(
     ],
     tag_name: Annotated[str, Field(description="Tag name to delete", min_length=1)],
 ) -> str:
-    """Delete a tag. Returns a {status: deleted, tag_name} confirmation."""
+    """Delete a tag. Returns a {status: deleted, tag} confirmation."""
     try:
         _check_write(ctx)
         await _get_client(ctx).delete_tag(project_id, tag_name)
@@ -2226,7 +2221,7 @@ async def gitlab_update_release(
     description: Annotated[str | None, Field(description="New release description")] = None,
     released_at: Annotated[str | None, Field(description="New release date (ISO 8601)")] = None,
 ) -> str:
-    """Update a release's name, description, or milestones. Returns the updated release object."""
+    """Update a release's name, description, or release date. Returns the updated release."""
     try:
         _check_write(ctx)
         params: dict[str, Any] = {}
@@ -2255,7 +2250,7 @@ async def gitlab_delete_release(
 ) -> str:
     """Delete a release (the underlying tag is preserved).
 
-    Returns the deleted release's metadata.
+    Returns a {status: deleted, tag_name} confirmation.
     """
     try:
         _check_write(ctx)
@@ -2358,10 +2353,16 @@ async def gitlab_update_variable(
     protected: Annotated[bool | None, Field(description="Protected branches only")] = None,
     masked: Annotated[bool | None, Field(description="Mask in logs")] = None,
     raw: Annotated[bool | None, Field(description="Do not expand references")] = None,
-    environment_scope: Annotated[str | None, Field(description="Environment scope")] = None,
+    environment_scope: Annotated[
+        str | None,
+        Field(description="Environment scope filter — selects which scoped variable to update"),
+    ] = None,
     description: Annotated[str | None, Field(description="Variable description")] = None,
 ) -> str:
-    """Update a project CI/CD variable. Returns the updated variable object."""
+    """Update a project CI/CD variable. Returns the updated variable object.
+
+    environment_scope selects which scoped variable to update; it does not change the scope.
+    """
     try:
         _check_write(ctx)
         params: dict[str, Any] = {"value": value}
@@ -2652,7 +2653,7 @@ async def gitlab_update_issue(
     state_event: Annotated[str | None, Field(description="close or reopen")] = None,
     weight: Annotated[int | None, Field(description="Issue weight")] = None,
 ) -> str:
-    """Update an issue's title, description, labels, assignees, milestone, or state event.
+    """Update an issue's title, description, labels, assignees, weight, or state event.
 
     Returns the updated issue object.
     """

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/tests/unit/test_tools.py

@@ -2329,3 +2329,115 @@ class TestOptionalParams:
         )
         parsed = _parse(result)
         assert parsed["title"] == "Updated"
+
+
+# ═══════════════════════════════════════════════════════
+# Regression tests — defects found by audit
+# ═══════════════════════════════════════════════════════
+
+
+class TestDocstringContracts:
+    """Tools whose docstrings promise a specific return shape must deliver it."""
+
+    async def test_merge_mr_sequence_readonly_blocked(self, readonly_client):
+        """Read-only mode must return a JSON error, not blow up on an unbound local."""
+        client, router = readonly_client
+        result = await client.call_tool(
+            "gitlab_merge_mr_sequence",
+            {"project_id": "123", "mr_iids": [1, 2]},
+        )
+        parsed = _parse(result)
+        assert "error" in parsed
+        assert "read-only" in parsed["hint"].lower()
+        assert parsed["merged_so_far"] == []
+
+    async def test_merge_mr_sequence_partial_failure_reports_progress(self, tool_client):
+        """A mid-sequence API failure still reports which MRs already merged, plus a hint."""
+        client, router = tool_client
+        router.get("/projects/123/merge_requests/1").mock(
+            return_value=Response(200, json={"iid": 1, "detailed_merge_status": "mergeable"})
+        )
+        router.put("/projects/123/merge_requests/1/merge").mock(
+            return_value=Response(200, json={"iid": 1, "state": "merged"})
+        )
+        router.get("/projects/123/merge_requests/2").mock(
+            return_value=Response(404, json={"message": "404 Not found"})
+        )
+        result = await client.call_tool(
+            "gitlab_merge_mr_sequence",
+            {"project_id": "123", "mr_iids": [1, 2]},
+        )
+        parsed = _parse(result)
+        assert parsed["merged_so_far"] == [1]
+        assert parsed["status_code"] == 404
+        assert "hint" in parsed
+
+    async def test_delete_tag_returns_tag_key(self, tool_client):
+        """Docstring promises {status: deleted, tag} — not tag_name."""
+        client, router = tool_client
+        router.delete("/projects/123/repository/tags/v1.0").mock(return_value=Response(204))
+        result = await client.call_tool(
+            "gitlab_delete_tag", {"project_id": "123", "tag_name": "v1.0"}
+        )
+        parsed = _parse(result)
+        assert parsed == {"status": "deleted", "tag": "v1.0"}
+
+    async def test_delete_release_returns_confirmation_not_metadata(self, tool_client):
+        """Docstring promises {status: deleted, tag_name}, not the release object."""
+        client, router = tool_client
+        router.delete("/projects/123/releases/v1.0").mock(return_value=Response(204))
+        result = await client.call_tool(
+            "gitlab_delete_release", {"project_id": "123", "tag_name": "v1.0"}
+        )
+        parsed = _parse(result)
+        assert parsed == {"status": "deleted", "tag_name": "v1.0"}
+
+    async def test_get_job_log_zero_tail_returns_whole_log(self, tool_client):
+        """Docstring promises tail_lines=0 returns the whole log."""
+        client, router = tool_client
+        lines = "\n".join(f"line {i}" for i in range(300))
+        router.get("/projects/123/jobs/1/trace").mock(return_value=Response(200, text=lines))
+        result = await client.call_tool(
+            "gitlab_get_job_log",
+            {"project_id": "123", "job_id": 1, "tail_lines": 0},
+        )
+        parsed = _parse(result)
+        assert parsed["shown_lines"] == 300
+        assert parsed["total_lines"] == 300
+
+    async def test_get_job_log_rejects_negative_tail(self, tool_client):
+        """Negative tail_lines used to silently drop lines off the front; now rejected."""
+        client, router = tool_client
+        with pytest.raises(Exception, match="tail_lines"):
+            await client.call_tool(
+                "gitlab_get_job_log",
+                {"project_id": "123", "job_id": 1, "tail_lines": -5},
+            )
+
+    async def test_share_group_with_group_invalid_level_lists_valid_levels(self, tool_client):
+        """Error message must list the valid levels, matching its project-share sibling."""
+        client, router = tool_client
+        result = await client.call_tool(
+            "gitlab_share_group_with_group",
+            {"target_group_id": "9", "source_group_id": 1, "access_level": "bogus"},
+        )
+        parsed = _parse(result)
+        assert "bogus" in parsed["error"]
+        assert "maintainer" in parsed["error"]
+
+    async def test_tool_descriptions_have_no_blank_line_runs(self, tool_client):
+        """Docstrings ship verbatim as MCP tool descriptions — no stray blank-line runs."""
+        client, router = tool_client
+        tools = await client.list_tools()
+        offenders = [t.name for t in tools if t.description and "\n\n\n" in t.description]
+        assert offenders == []
+
+    async def test_update_docstrings_only_name_real_params(self, tool_client):
+        """Docstrings must not advertise parameters the tool does not accept."""
+        client, router = tool_client
+        tools = {t.name: t for t in await client.list_tools()}
+        for name in ("gitlab_update_mr", "gitlab_update_issue", "gitlab_update_release"):
+            desc = tools[name].description.lower()
+            params = tools[name].inputSchema["properties"]
+            assert "milestone" not in desc or any("milestone" in p for p in params)
+            assert "assignee" not in desc or any("assignee" in p for p in params)

{mcp_gitlab-0.9.2 → mcp_gitlab-0.9.4}/uv.lock

@@ -1,6 +1,12 @@
 version = 1
 revision = 3
 requires-python = ">=3.10"
+resolution-markers = [
+    "python_full_version >= '3.14' and sys_platform == 'win32'",
+    "python_full_version >= '3.14' and sys_platform != 'win32'",
+    "python_full_version < '3.14' and sys_platform == 'win32'",
+    "python_full_version < '3.14' and sys_platform != 'win32'",
+]
 
 [[package]]
 name = "aiofile"
@@ -802,7 +808,7 @@ wheels = [
 
 [[package]]
 name = "mcp"
-version = "1.26.0"
+version = "1.28.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -820,14 +826,14 @@ dependencies = [
     { name = "typing-inspection" },
     { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/fc/6d/62e76bbb8144d6ed86e202b5edd8a4cb631e7c8130f3f4893c3f90262b10/mcp-1.26.0.tar.gz", hash = "sha256:db6e2ef491eecc1a0d93711a76f28dec2e05999f93afd48795da1c1137142c66", size = 608005, upload-time = "2026-01-24T19:40:32.468Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/6e/77/9450b8f251a13affb6281997d0523c4615f8a8b35d0b21ff30db3a5aac9d/mcp-1.28.1.tar.gz", hash = "sha256:d51e36a5f5644faea4f85ea649bfffa6bc6c26770d42798ad6a3de3d2ba69683", size = 638501, upload-time = "2026-06-26T12:57:29.093Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/fd/d9/eaa1f80170d2b7c5ba23f3b59f766f3a0bb41155fbc32a69adfa1adaaef9/mcp-1.26.0-py3-none-any.whl", hash = "sha256:904a21c33c25aa98ddbeb47273033c435e595bbacfdb177f4bd87f6dceebe1ca", size = 233615, upload-time = "2026-01-24T19:40:30.652Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/5e/d118fce19f87a2e7d8101c35c8ae0ec289098a4df0ff244cec23e415aca0/mcp-1.28.1-py3-none-any.whl", hash = "sha256:2726bca5e7193f61c5dde8b12500a6de2d9acf6d1a1c0be9e8c2e706437991df", size = 222620, upload-time = "2026-06-26T12:57:27.218Z" },
 ]
 
 [[package]]
 name = "mcp-gitlab"
-version = "0.9.2"
+version = "0.9.4"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -1593,8 +1599,8 @@ name = "secretstorage"
 version = "3.5.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "cryptography" },
-    { name = "jeepney" },
+    { name = "cryptography", marker = "sys_platform != 'win32'" },
+    { name = "jeepney", marker = "sys_platform != 'win32'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/1c/03/e834bcd866f2f8a49a85eaff47340affa3bfa391ee9912a952a1faa68c7b/secretstorage-3.5.0.tar.gz", hash = "sha256:f04b8e4689cbce351744d5537bf6b1329c6fc68f91fa666f60a380edddcd11be", size = 19884, upload-time = "2025-11-23T19:02:53.191Z" }
 wheels = [

mcp_gitlab-0.9.2/AGENTS.md

@@ -1,124 +0,0 @@
-# mcp-gitlab — Agent Context
-
-MCP server providing 83 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
-- **Resources**: `src/mcp_gitlab/servers/resources.py` — 6 MCP resources (workflow guides)
-- **Prompts**: `src/mcp_gitlab/servers/prompts.py` — 5 MCP prompts (multi-tool workflows)
-- **Config**: `src/mcp_gitlab/config.py` — `GitLabConfig` dataclass from env vars
-- **Exceptions**: `src/mcp_gitlab/exceptions.py` — `GitLabApiError`, `GitLabAuthError`, etc.
-- **Tests**: `tests/unit/test_tools.py` — 120+ tool-level tests via FastMCP test client
-
-## 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, approve, unapprove, subscribe, unsubscribe
-
-## Tool Categories
-
-Projects (4), Approvals (10), Groups (6), Branches (3), Commits (4), Merge Requests (15), 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
-
-## Release Workflow
-
-Releases are handled via GitHub Actions — never bump versions manually.
-
-### How to release
-
-```bash
-# From the repo directory:
-gh workflow run release.yml -f bump=minor      # 0.4.0 → 0.5.0
-gh workflow run release.yml -f bump=patch      # 0.5.0 → 0.5.1
-gh workflow run release.yml -f bump=major      # 0.5.0 → 1.0.0
-
-# Dry run (preview changelog, no push):
-gh workflow run release.yml -f bump=minor -f dry_run=true
-```
-
-### What happens
-
-1. `release.yml` (workflow_dispatch) — bumps the version in `pyproject.toml`, `llms.txt`, `llms-full.txt`, `server.json`, `gemini-extension.json`; regenerates `uv.lock`; prepends a CHANGELOG.md entry; creates the release commit + tag via the GitHub API
-2. `publish.yml` (triggered by `v*` tag push) — builds wheel, publishes to PyPI, creates GitHub Release with auto-generated notes, then publishes to the MCP Registry
-
-### Rules
-- Never edit `pyproject.toml` version directly — the workflow owns it
-- Never create tags manually — the workflow creates them
-- Commit messages must follow conventional commits (`feat:`, `fix:`, `docs:`, etc.) for changelog generation
-- The release commit is authored by `github-actions[bot]` with message `chore(release): X.Y.Z`
-
-## Prompts
-
-Prompts follow the resources pattern: prompt content lives as `.md` files in `src/mcp_gitlab/resources/prompts/`, loaded by `servers/prompts.py` via `_load_prompt()`, registered with `@mcp.prompt()`. Each prompt returns `list[Message]` with a user message (workflow template) and an assistant message (acknowledgment).
-
-- `review_mr` — MR review workflow (tags: gitlab, review)
-- `diagnose_pipeline` — CI debug workflow (tags: gitlab, ci)
-- `prepare_release` — Release preparation (tags: gitlab, release)
-- `setup_branch_protection` — Branch protection setup (tags: gitlab, settings)
-- `triage_issues` — Issue triage workflow (tags: gitlab, issues)
-
-## Documentation Freshness (MANDATORY)
-
-When any changeset adds, removes, or modifies tools, resources, or prompts, ALL documentation files MUST be updated in the same commit:
-
-- `README.md` — tool count in heading + intro, tool table, full tool reference, usage examples, permissions table
-- `llms.txt` — tool count in tagline and documentation link
-- `llms-full.txt` — tool count in tagline, documentation link, full tool reference section
-- `AGENTS.md` — tool count in intro, tool categories list
-- `GEMINI.md` — tool count in intro, tool categories, common workflows
-- `server.json` — description field (<=100 chars)
-
-Checklist: verify tool count matches actual registered tools, verify category list is complete, verify new tools appear in correct sections with parameters and annotations.
-
-## Known Limitations / Future Work
-
-- 83 tools in one server file (exceeds 5-15 guideline). Consider splitting by category in a future refactor.
-- Errors are returned as successful tool results with `{"error": ...}` (soft-error pattern). Callers must inspect JSON content.

mcp_gitlab-0.9.2/GEMINI.md

@@ -1,33 +0,0 @@
-# mcp-gitlab — Gemini CLI Extension Context
-
-MCP server providing 83 tools, 7 resources, and 6 prompts for interacting with the GitLab API. Covers the full lifecycle of GitLab projects: code, reviews, CI/CD, releases, and issue tracking.
-
-## Tool Categories
-
-- **Projects** — get, create, delete, update merge settings, share/unshare with groups
-- **Merge Requests** — list, get, create, update, merge, rebase, view changes and diffs, approve, unapprove, get approvals, list pipelines, list commits, subscribe, unsubscribe
-- **MR Reviews** — list/add/update/delete notes, list/create discussions, reply to and resolve discussions, award/remove emoji
-- **MR Approvals** — project-level and MR-level approval rules (list, create, update, delete)
-- **Pipelines & Jobs** — list/get/create/retry/cancel pipelines, retry/play/cancel jobs, get job logs
-- **Branches** — list, create, delete
-- **Commits** — list, get, create, compare refs
-- **Tags & Releases** — list/get/create/delete tags, list/get/create/update/delete releases
-- **CI/CD Variables** — project and group variables (list, create, update, delete)
-- **Issues** — list, get, create, update, add comments
-- **Groups** — list, get, share/unshare groups
-
-## Common Workflows
-
-- **Code review**: `list_mrs` -> `mr_changes` -> `list_mr_discussions` -> `add_mr_note` or `create_mr_discussion` -> `resolve_discussion`
-- **Pipeline debugging**: `list_pipelines` -> `get_pipeline` -> `get_job_log` -> `retry_job`
-- **Release process**: `list_commits` -> `compare` -> `create_tag` -> `create_release`
-- **Branch protection**: `list_project_approval_rules` -> `create_project_approval_rule` -> `update_project_merge_settings`
-- **Issue triage**: `list_issues` -> `get_issue` -> `update_issue` -> `add_issue_comment`
-
-## Notes
-
-- Set `GITLAB_READ_ONLY=true` to restrict all operations to read-only (no writes, no deletes).
-- Token requires appropriate GitLab scopes: `api` for full access, `read_api` for read-only.
-- Default request timeout is 30 seconds; override with `GITLAB_TIMEOUT`.
-- SSL verification is on by default; disable with `GITLAB_SSL_VERIFY=false` for self-signed certs.
-- Works with GitLab.com and self-hosted GitLab instances.