Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This MCP server has severe structural deficiencies across all 18 tools. The source code provided contains only Dockerfile and pyproject.toml excerpts; the actual tool definitions in gitlab_api/mcp_server.py are not visible. Based on the tool metadata provided (which appears to be inferred), the schemas are minimal or missing entirely, descriptions are generic, and parameters lack proper type definitions and constraints. The tool definitions appear to bundle multiple unrelated actions into single tools with a free-form 'action' parameter, violating the single-responsibility principle. No input validation guidance, no error recovery hints, and no output schema documentation are evident. The architecture pattern of a single 'action' string parameter that accepts 10+ different values (e.g., gitlab_branches with actions: get, create, delete, delete_merged, protect) is a major anti-pattern, LLMs cannot reliably route between many action modes, and this increases hallucination risk. Tools like gitlab_issues, gitlab_projects, gitlab_commits lack specific action enums and detailed parameter descriptions. This is a D-grade server with fundamental design issues.
Single-responsibility violation: All 18 tools use a free-form 'action' parameter accepting 10+ enum values instead of separate tools. gitlab_branches has actions: get, create, delete, delete_merged, protect. gitlab_commits has 12+ action modes. This forces LLMs to reason about which action mode to use, increases hallucination risk, and violates the core tool design principle.
Missing schema documentation: Input schemas provided are incomplete. Parameters like 'action' lack enum constraints; parameters like 'branch', 'tag_name', 'environment_id' lack type definitions (should be 'string' with minLength/maxLength/pattern where applicable). Output schemas are not documented at all, LLMs cannot plan downstream calls without knowing what fields are returned.
Recommendations
REFACTOR: Split each tool into separate, single-responsibility functions. Instead of gitlab_branches with action='get'|'create'|'delete', create: get_branches, create_branch, delete_branch, protect_branch. This allows LLMs to directly call the intended action without mode-switching logic and reduces hallucination.
DEFINE OUTPUT SCHEMAS: Document the exact fields returned by each tool. Example for get_branches: '{"type": "object", "properties": {"branches": {"type": "array", "items": {"type": "object", "properties": {"name": {"type": "string"}, "protected": {"type": "boolean"}, "merged": {"type": "boolean"}, "default": {"type": "boolean"}}}}}'.
ENHANCE DESCRIPTIONS: Rewrite each tool description to be task-oriented. Example: 'Get the list of branches in a GitLab project. Use this to discover available branches before merging or protecting. Returns branch names, protection status, and whether they are merged. Limited to 20 results per page.'
ADD PARAMETER CONSTRAINTS: For every parameter, specify format and validation rules inline. Example: 'branch: A string 1-255 characters matching GitLab branch naming (alphanumeric, -, _). Case-sensitive. E.g., main, feature/api-auth, or release-v1.0.'
ADD ENUM CONSTRAINTS: Convert free-form 'action' strings to explicit enums. Example input schema for create_branch: '{"type": "object", "required": ["project_id", "branch_name", "ref"], "properties": {"project_id": {"type": "string", "description": "GitLab project ID or slug"}, "branch_name": {"type": "string", "description": "Name of the new branch"}, "ref": {"type": "string", "description": "Reference (branch, tag, or commit SHA) to branch from. E.g., main or a41d6cf"}}}' (no action enum needed, this is a dedicated create_branch tool).
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 13 points across a rubric change (v1 → v2)
43/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-21
F
43
<=2025-11-25
v2
2026-03-09
F
30
-
v1
writeauthsource verified34/100
Manage CI/CD jobs: get, get logs, cancel, retry, erase, run, and get pipeline jobs
Generic, non-actionable descriptions: Tool descriptions like 'Manage project branches: get, create, delete, delete merged branches, and protect branches' are inventory lists, not task-oriented guidance. They do not explain WHEN to use this tool vs similar tools, what prerequisites exist, or what the expected output is. When should I call it? What do I get back?
Parameter descriptions are insufficient: Parameters like 'ref' in gitlab_branches is described as 'Reference to create branch from', what format is this? A commit SHA? A tag name? A branch name? This ambiguity forces LLMs to guess. Example: 'A Git reference (branch, tag, or commit SHA) to branch from. E.g., main, v1.0.0, or a41d6cf.'
No error handling or recovery guidance: Tool descriptions and schemas contain no information on failure modes, retryability, or recovery steps. If gitlab_merge_requests fails to accept a merge request, does the tool say 'Merge already merged' (retryable? no) or 'User lacks permission' (ask for escalation?) or 'Branch has conflicts' (manual resolution needed?). Per pattern:recovery-guide, error responses must tell the LLM what to do next.
No parameter validation rules documented: Parameters like 'project_id', 'group_id', 'user_id' lack documented constraints. Are these numeric IDs? Slug strings? What is the max length? Can they be names instead? PROJ)' is actionable; 'project_id' alone invites invalid input.
No output schema documentation: The provided metadata does not include output schemas for any tool. LLMs need to know: Does get_branches return a list or a single branch? What fields does each branch object contain (name, protected, default)? Can the agent chain the output of one tool into another (e.g., get branch names, then protect them)? Without documented output schemas, LLMs resort to guessing and hallucination.
Source code not visible: The provided code snippets include only Dockerfile and pyproject.toml. The actual tool registration code in gitlab_api/mcp_server.py is not present. Per HARD SCORING RULES, if tool definitions cannot be seen in source (only inferred from metadata), that tool's overall score is capped at 50. This applies to all 18 tools, we are inferring their existence and structure from the metadata provided, not from direct code inspection.
No write/read distinction in tool names: Tools that modify state (create, delete, update, protect) and tools that only read have the same naming style. Compare gitlab_branches (which can delete) vs gitlab_groups (which is read-only per metadata). Tool names should hint at destructiveness. Convention: prefix dangerous tools with 'delete_', 'update_', 'create_', but also ensure descriptions explicitly state 'This tool MODIFIES/DELETES/SENDS...' so LLMs understand irreversible consequences.
ERROR HANDLING: Add error recovery hints to descriptions. Example: 'If the merge request cannot be accepted due to conflicts, the error will state "Conflicting changes". Use get_merge_request_diff first to inspect conflicts, then ask the user to resolve manually or rebase.'
ADD PAGINATION: For list tools (get_branches, get_merge_requests), add 'page' and 'per_page' or 'limit' and 'offset' parameters with documented defaults. Example: 'limit: Max results to return (1-100, default 20). Use with offset to iterate through large result sets.'
DOCUMENT IDEMPOTENCY: For create/update/delete operations, clarify if they are idempotent. Example: 'Idempotent: Calling this multiple times with the same parameters will not create duplicates. If the branch already exists, a 200 OK is returned with the existing branch details.'
ADD TOOL ANNOTATIONS: Use MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint) to mark which tools are safe vs dangerous. Example: destructiveHint for delete_branch, readOnlyHint for get_branches.
PROVIDE SAMPLE CALLS: Include in-tool documentation (comments in the tool handler code, not in descriptions sent to LLM) showing example invocations. Example: '# Create a feature branch from main: create_branch(project_id="123", branch_name="feature/new-api", ref="main")'.
VALIDATION ON INPUT: Implement server-side validation of all parameters before calling GitLab API. Return clear, actionable errors. Example: 'Invalid project_id "xyz": must be numeric (e.g., 123) or a valid project slug (e.g., group/project). Use search_projects() to find your project ID.'
PERMISSION CHECKS: Add permission declarations and pre-flight checks. Example: '# Requires GitLab scopes: api (for most operations), read_repository (for read-only), write_repository (for create/delete). If you lack permission, ask a project maintainer to grant access.'
BATCH VARIANTS: For tools that agents likely call in loops (e.g., protect multiple branches), offer batch versions. Example: protect_branches(project_id, branch_names=[...]) in addition to protect_branch(project_id, branch_name).