GitLab MCP Server

Instructions

Implementation Reference

• tools/get_commit_discussions.py:9-106 (handler)

  The main handler function that implements the tool logic: fetches merge request commits and discussions, matches discussions to commits based on head_sha, and formats a detailed markdown report with summaries and per-commit details.
  async def get_commit_discussions(gitlab_url, project_id, access_token, args): """Get discussions/comments on commits within a merge request""" logging.info(f"get_commit_discussions called with args: {args}") mr_iid = args["merge_request_iid"] try: commits_result = await get_merge_request_commits(gitlab_url, project_id, access_token, mr_iid) commits_status, commits_data, commits_error = commits_result if commits_status != 200: logging.error(f"Error fetching merge request commits: " f"{commits_status} - {commits_error}") raise Exception(f"Error fetching merge request commits: {commits_error}") if not commits_data: return [TextContent(type="text", text="No commits found in this merge request.")] logging.info(f"Getting ALL MR discussions for MR #{mr_iid}...") discussions_result = await get_merge_request_discussions_paginated(gitlab_url, project_id, access_token, mr_iid) discussions_status, discussions_data, discussions_error = discussions_result if discussions_status != 200: logging.error(f"Error fetching MR discussions: " f"{discussions_status} - {discussions_error}") discussions_data = [] commit_map = {commit["id"]: commit for commit in commits_data} commits_with_discussions = {} total_discussions = 0 for discussion in discussions_data: notes = discussion.get("notes", []) for note in notes: position = note.get("position") if position and position.get("head_sha"): commit_sha = position["head_sha"] if commit_sha in commit_map: if commit_sha not in commits_with_discussions: commits_with_discussions[commit_sha] = {"commit": commit_map[commit_sha], "discussions": []} commits_with_discussions[commit_sha]["discussions"].append( {"discussion_id": discussion.get("id"), "note": note, "position": position} ) total_discussions += 1 if not commits_with_discussions: summary_text = ( f"## Commit Discussions for MR #{mr_iid}\n\n" f"**Summary:**\n" f"- Total commits: {len(commits_data)}\n" f"- Commits with discussions: 0\n" f"- Total discussions: 0\n\n" f"No line-level discussions found on any commits in this " f"merge request. Found {len(discussions_data)} total MR discussions." ) return [TextContent(type="text", text=summary_text)] response_text = ( f"## Commit Discussions for MR #{mr_iid}\n\n" f"**Summary:**\n" f"- Total commits: {len(commits_data)}\n" f"- Commits with discussions: {len(commits_with_discussions)}\n" f"- Total line-level discussions: {total_discussions}\n" f"- Total MR discussions: {len(discussions_data)}\n\n" ) for _commit_sha, item in commits_with_discussions.items(): commit = item["commit"] discussions = item["discussions"] response_text += f"### 📝 Commit: {commit['short_id']}\n" response_text += f"**Title:** {commit['title']}\n" response_text += f"**Author:** {commit['author_name']}\n" response_text += f"**Date:** {format_date(commit['committed_date'])}\n" response_text += f"**SHA:** `{commit['id']}`\n\n" for discussion_item in discussions: discussion_id = discussion_item["discussion_id"] note = discussion_item["note"] position = discussion_item["position"] author_name = note["author"]["name"] response_text += f"**💬 Comment by {author_name}:**\n" response_text += f"{note['body']}\n" if position.get("new_path"): line_info = position.get("new_line", "N/A") response_text += f"*On file: {position['new_path']} " f"(line {line_info})*\n" created_at = format_date(note["created_at"]) response_text += f"*Posted: {created_at}*\n" response_text += f"*Discussion ID: {discussion_id}*\n\n" response_text += "---\n\n" return [TextContent(type="text", text=response_text)] except Exception as e: logging.error(f"Error in get_commit_discussions: {str(e)}") return [TextContent(type="text", text=f"Error retrieving commit discussions: {str(e)}")]
• main.py:257-272 (schema)

  The tool schema definition including input schema requiring 'merge_request_iid' as input.
  Tool( name="get_commit_discussions", description=("Get discussions and comments on commits within a " "specific merge request"), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), } }, "required": ["merge_request_iid"], "additionalProperties": False, }, ),
• main.py:344-347 (registration)

  The dispatch/registration in the call_tool handler that routes calls to the get_commit_discussions function.
  elif name == "get_commit_discussions": return await get_commit_discussions( self.config["gitlab_url"], self.config["project_id"], self.config["access_token"], arguments )
• main.py:41-277 (registration)

  The list_tools decorator registration where the tool is listed and described for the MCP server.
  @self.server.list_tools() async def list_tools() -> List[Tool]: logging.info("list_tools called") tools = [ Tool( name="list_merge_requests", description="List merge requests for the GitLab project", inputSchema={ "type": "object", "properties": { "state": { "type": "string", "enum": ["opened", "closed", "merged", "all"], "default": "opened", "description": "Filter by merge request state", }, "target_branch": {"type": "string", "description": ("Filter by target branch (optional)")}, "limit": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100, "description": "Maximum number of results", }, }, "additionalProperties": False, }, ), Tool( name="get_merge_request_reviews", description=("Get reviews and discussions for a specific " "merge request"), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), } }, "required": ["merge_request_iid"], "additionalProperties": False, }, ), Tool( name="get_merge_request_details", description=("Get detailed information about a specific " "merge request"), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), } }, "required": ["merge_request_iid"], "additionalProperties": False, }, ), Tool( name="get_merge_request_pipeline", description=( "Get the last pipeline data for a specific merge " "request, including all jobs and their statuses. " "Returns job IDs that can be used with get_job_log " "to fetch detailed output." ), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), } }, "required": ["merge_request_iid"], "additionalProperties": False, }, ), Tool( name="get_merge_request_test_report", description=( "Get structured test report for a merge request " "with specific test failures, error messages, and " "stack traces. Shows the same test data visible on " "the GitLab MR page. Best for debugging test failures." ), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), } }, "required": ["merge_request_iid"], "additionalProperties": False, }, ), Tool( name="get_pipeline_test_summary", description=( "Get test summary for a merge request - a " "lightweight overview showing pass/fail counts " "per test suite. Faster than full test report. " "Great for quick status checks." ), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), } }, "required": ["merge_request_iid"], "additionalProperties": False, }, ), Tool( name="get_job_log", description=( "Get the trace/log output for a specific pipeline " "job. Perfect for debugging failed tests and " "understanding CI/CD failures." ), inputSchema={ "type": "object", "properties": { "job_id": { "type": "integer", "minimum": 1, "description": ("ID of the pipeline job (obtained from " "get_merge_request_pipeline)"), } }, "required": ["job_id"], "additionalProperties": False, }, ), Tool( name="get_branch_merge_requests", description=("Get all merge requests for a specific branch"), inputSchema={ "type": "object", "properties": {"branch_name": {"type": "string", "description": "Name of the branch"}}, "required": ["branch_name"], "additionalProperties": False, }, ), Tool( name="reply_to_review_comment", description=("Reply to a specific discussion thread in a " "merge request review"), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), }, "discussion_id": { "type": "string", "description": ("ID of the discussion thread to reply to"), }, "body": {"type": "string", "description": "Content of the reply comment"}, }, "required": ["merge_request_iid", "discussion_id", "body"], "additionalProperties": False, }, ), Tool( name="create_review_comment", description=("Create a new discussion thread in a " "merge request review"), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), }, "body": {"type": "string", "description": ("Content of the new discussion comment")}, }, "required": ["merge_request_iid", "body"], "additionalProperties": False, }, ), Tool( name="resolve_review_discussion", description=("Resolve or unresolve a discussion thread in a " "merge request review"), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), }, "discussion_id": { "type": "string", "description": ("ID of the discussion thread to " "resolve/unresolve"), }, "resolved": { "type": "boolean", "default": True, "description": ("Whether to resolve (true) or unresolve " "(false) the discussion"), }, }, "required": ["merge_request_iid", "discussion_id"], "additionalProperties": False, }, ), Tool( name="get_commit_discussions", description=("Get discussions and comments on commits within a " "specific merge request"), inputSchema={ "type": "object", "properties": { "merge_request_iid": { "type": "integer", "minimum": 1, "description": ("Internal ID of the merge request"), } }, "required": ["merge_request_iid"], "additionalProperties": False, }, ), ] tool_names = [t.name for t in tools] logging.info(f"Returning {len(tools)} tools: {tool_names}") return tools
• gitlab_api.py:159-187 (helper)

  Helper function used by the handler to fetch all commits in the merge request with pagination.
  async def get_merge_request_commits(gitlab_url, project_id, access_token, mr_iid): """Get all commits in a merge request (handles pagination)""" base_url = f"{gitlab_url}/api/v4/projects/{project_id}/" f"merge_requests/{mr_iid}/commits" headers = _headers(access_token) all_commits = [] page = 1 per_page = 100 # Maximum allowed per page async with aiohttp.ClientSession() as session: while True: params = {"page": page, "per_page": per_page} async with session.get(base_url, headers=headers, params=params) as response: if response.status != 200: return (response.status, await response.json(), await response.text()) page_data = await response.json() if not page_data: # No more results break all_commits.extend(page_data) # If we got fewer results than per_page, we're done if len(page_data) < per_page: break page += 1 return (200, all_commits, "Success")