get_project_commits
Retrieve and filter commits from GitLab projects by date, author, file path, or branch to track code changes and review history.
Instructions
List repository commits with filtering options
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID or path | |
| ref_name | No | Branch, tag, or commit SHA | main |
| since | No | ISO 8601 date format (YYYY-MM-DDTHH:MM:SSZ) - commits after this date | |
| until | No | ISO 8601 date format (YYYY-MM-DDTHH:MM:SSZ) - commits before this date | |
| author | No | Filter commits by author name | |
| path | No | Filter commits by file path | |
| all | No | Retrieve every commit from the repository | |
| with_stats | No | Include commit stats (additions, deletions) | |
| first_parent | No | Follow only the first parent commit on merge commits | |
| order | No | List commits in order (default or topological) | |
| trailers | No | Parse and include Git trailers for every commit | |
| page | No | Page number for pagination (default: 1) | |
| per_page | No | Number of results per page (max 100) |
Implementation Reference
- src/handlers/repository.ts:34-67 (handler)The main handler function in RepositoryHandlers class that constructs GitLab API query parameters and fetches the list of commits for the specified project.async getProjectCommits(args: GetProjectCommitsParams) { const params = new URLSearchParams(); if (args.ref_name) params.append("ref_name", args.ref_name); if (args.since) params.append("since", args.since); if (args.until) params.append("until", args.until); if (args.author) params.append("author", args.author); if (args.path) params.append("path", args.path); if (args.all !== undefined) params.append("all", String(args.all)); if (args.with_stats !== undefined) params.append("with_stats", String(args.with_stats)); if (args.first_parent !== undefined) params.append("first_parent", String(args.first_parent)); if (args.order) params.append("order", args.order); if (args.trailers !== undefined) params.append("trailers", String(args.trailers)); if (args.page) params.append("page", String(args.page)); params.append("per_page", String(args.per_page || 20)); const data = await this.client.get( `/projects/${encodeURIComponent( args.project_id )}/repository/commits?${params.toString()}` ); return { content: [ { type: "text", text: JSON.stringify(data, null, 2), }, ], }; }
- src/types.ts:320-334 (schema)TypeScript interface defining the input parameters for the get_project_commits tool handler.export interface GetProjectCommitsParams { project_id: string; ref_name?: string; since?: string; until?: string; author?: string; path?: string; all?: boolean; with_stats?: boolean; first_parent?: boolean; order?: 'default' | 'topo'; trailers?: boolean; page?: number; per_page?: number; }
- src/tools/repository.ts:29-95 (schema)MCP Tool definition including the inputSchema for the get_project_commits tool, used for listing tools and validation.name: "get_project_commits", description: "List repository commits with filtering options", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "Project ID or path", }, ref_name: { type: "string", description: "Branch, tag, or commit SHA", default: "main", }, since: { type: "string", description: "ISO 8601 date format (YYYY-MM-DDTHH:MM:SSZ) - commits after this date", }, until: { type: "string", description: "ISO 8601 date format (YYYY-MM-DDTHH:MM:SSZ) - commits before this date", }, author: { type: "string", description: "Filter commits by author name", }, path: { type: "string", description: "Filter commits by file path", }, all: { type: "boolean", description: "Retrieve every commit from the repository", }, with_stats: { type: "boolean", description: "Include commit stats (additions, deletions)", }, first_parent: { type: "boolean", description: "Follow only the first parent commit on merge commits", }, order: { type: "string", enum: ["default", "topo"], description: "List commits in order (default or topological)", }, trailers: { type: "boolean", description: "Parse and include Git trailers for every commit", }, page: { type: "number", description: "Page number for pagination (default: 1)", }, per_page: { type: "number", description: "Number of results per page (max 100)", maximum: 100, default: 20, }, }, required: ["project_id"], }, },
- src/server.ts:273-276 (registration)Registration in the MCP server's CallToolRequestSchema handler switch statement, dispatching to the repository handler.case "get_project_commits": return await this.repositoryHandlers.getProjectCommits( args as unknown as GetProjectCommitsParams );