mcp-gitlab AGENTS.md

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.