list_merge_requests
Retrieve merge requests from a GitLab project with filtering options by state, branch, assignee, author, search terms, and scope to manage code review workflows.
Instructions
List merge requests in a project
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| assignee_id | No | Filter by assignee user ID | |
| author_id | No | Filter by author user ID | |
| per_page | No | Number of results per page (max 100) | |
| project_id | Yes | Project ID or path | |
| scope | No | Return merge requests with the given scope (optional) | |
| search | No | Search merge requests by title and description | |
| source_branch | No | Filter by source branch | |
| state | No | Filter by merge request state | opened |
| target_branch | No | Filter by target branch |
Implementation Reference
- src/handlers/merge-requests.ts:78-110 (handler)The main handler function that implements the core logic of the 'list_merge_requests' tool. It constructs URL query parameters from the input args and fetches the list of merge requests from the GitLab API endpoint `/projects/{project_id}/merge_requests`, then returns the JSON-formatted response.async listMergeRequests(args: ListMergeRequestsParams) { const params = new URLSearchParams(); if (args.state) params.append("state", args.state); if (args.target_branch) params.append("target_branch", args.target_branch); if (args.source_branch) params.append("source_branch", args.source_branch); if (args.assignee_id) params.append("assignee_id", String(args.assignee_id)); if (args.author_id) params.append("author_id", String(args.author_id)); if (args.reviewer_id) params.append("reviewer_id", String(args.reviewer_id)); if (args.reviewer_username) params.append("reviewer_username", args.reviewer_username); if (args.search) params.append("search", args.search); // Only add scope if explicitly provided by user if (args.scope) params.append("scope", args.scope); params.append("per_page", String(args.per_page || 20)); const data = await this.client.get( `/projects/${encodeURIComponent( args.project_id )}/merge_requests?${params.toString()}` ); return { content: [ { type: "text", text: JSON.stringify(data, null, 2), }, ], }; }
- src/tools/merge-requests.ts:4-62 (registration)Tool registration in the mergeRequestTools array. Defines the MCP tool name, description, and detailed inputSchema for validation.{ name: 'list_merge_requests', description: 'List merge requests in a project', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID or path', }, state: { type: 'string', enum: ['opened', 'closed', 'merged', 'all'], description: 'Filter by merge request state', default: 'opened', }, target_branch: { type: 'string', description: 'Filter by target branch', }, source_branch: { type: 'string', description: 'Filter by source branch', }, assignee_id: { type: 'number', description: 'Filter by assignee user ID', }, author_id: { type: 'number', description: 'Filter by author user ID', }, reviewer_id: { type: 'number', description: 'Filter by reviewer user ID', }, reviewer_username: { type: 'string', description: 'Filter by reviewer username', }, search: { type: 'string', description: 'Search merge requests by title and description', }, scope: { type: 'string', enum: ['created_by_me', 'assigned_to_me', 'all'], description: 'Return merge requests with the given scope (optional)', }, per_page: { type: 'number', description: 'Number of results per page (max 100)', maximum: 100, default: 20, }, }, required: ['project_id'], }, },
- src/types.ts:240-252 (schema)TypeScript interface defining the input parameters for the listMergeRequests handler function.export interface ListMergeRequestsParams { project_id: string; state?: 'opened' | 'closed' | 'merged' | 'all'; target_branch?: string; source_branch?: string; assignee_id?: number; author_id?: number; reviewer_id?: number; reviewer_username?: string; search?: string; scope?: 'created_by_me' | 'assigned_to_me' | 'all'; per_page?: number; }
- src/server.ts:177-180 (registration)Dispatch logic in the MCP server that handles incoming tool calls for 'list_merge_requests' by invoking the corresponding handler method.case "list_merge_requests": return await this.mergeRequestHandlers.listMergeRequests( args as unknown as ListMergeRequestsParams );