list_commits
Retrieve commit history for a GitLab project with options to filter by path, date range, SHA, and pagination. Supports detailed commit stats and first-parent history.
Instructions
Get commit history for a GitLab project
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | ||
| first_parent | No | ||
| page | No | ||
| path | No | ||
| per_page | No | ||
| project_id | No | ||
| sha | No | ||
| since | No | ||
| until | No | ||
| with_stats | No |
Implementation Reference
- src/gitlab-api.ts:482-533 (handler)Core handler function in GitLabApi class that fetches and returns commits for a project using the GitLab API.
async listCommits( projectId: string, options: { sha?: string; since?: string; until?: string; path?: string; all?: boolean; with_stats?: boolean; first_parent?: boolean; page?: number; per_page?: number; } = {} ): Promise<GitLabCommitsResponse> { const url = new URL( `${this.apiUrl}/projects/${encodeURIComponent( projectId )}/repository/commits` ); // Add query parameters for filtering and pagination Object.entries(options).forEach(([key, value]) => { if (value !== undefined) { url.searchParams.append(key, value.toString()); } }); const response = await fetch(url.toString(), { headers: { Authorization: `Bearer ${this.token}`, }, }); if (!response.ok) { throw new McpError( ErrorCode.InternalError, `GitLab API error: ${response.statusText}` ); } // Parse the response JSON const commits = await response.json(); // Get the total count from the headers const totalCount = parseInt(response.headers.get("X-Total") || "0"); // Validate and return the response return GitLabCommitsResponseSchema.parse({ count: totalCount, items: commits, }); } - src/index.ts:445-479 (handler)MCP server tool handler case for 'list_commits' that validates input, calls GitLabApi.listCommits, and formats the response.
case "list_commits": { // Parse and validate the arguments const args = ListCommitsSchema.parse(request.params.arguments); // Additional validation for pagination parameters if (args.per_page && (args.per_page < 1 || args.per_page > 100)) { throw new Error("per_page must be between 1 and 100"); } if (args.page && args.page < 1) { throw new Error("page must be greater than 0"); } // Validate date formats if provided if (args.since && !isValidISODate(args.since)) { throw new Error( "since must be a valid ISO 8601 date (YYYY-MM-DDTHH:MM:SSZ)" ); } if (args.until && !isValidISODate(args.until)) { throw new Error( "until must be a valid ISO 8601 date (YYYY-MM-DDTHH:MM:SSZ)" ); } // Extract project_id and options const { project_id, ...options } = args; // Call the API function const commits = await gitlabApi.listCommits(project_id, options); // Format and return the response return formatCommitsResponse(commits); } - src/schemas.ts:465-476 (schema)Zod schema defining the input parameters for the list_commits tool.
export const ListCommitsSchema = z.object({ project_id: z.string(), sha: z.string().optional(), since: z.string().optional(), until: z.string().optional(), path: z.string().optional(), all: z.boolean().optional(), with_stats: z.boolean().optional(), first_parent: z.boolean().optional(), page: z.number().optional(), per_page: z.number().optional() }); - src/index.ts:175-178 (registration)Tool registration in the ALL_TOOLS array, including name, description, input schema, and read-only flag.
name: "list_commits", description: "Get commit history for a GitLab project", inputSchema: createJsonSchema(ListCommitsSchema), readOnly: true