list_commits
Retrieve commit history from GitHub repositories to track changes, review code evolution, and analyze development activity by specifying repository details and optional pagination or branch parameters.
Instructions
List commits in a GitHub repository.
Args:
params: Dictionary with commit parameters
- owner: Repository owner (username or organization)
- repo: Repository name
- page: Page number (optional)
- per_page: Results per page (optional)
- sha: Branch name or commit SHA (optional)
Returns:
MCP response with list of commitsInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Implementation Reference
- MCP tool handler for 'list_commits'. Validates input parameters using ListCommitsParams and delegates to the internal repositories.list_commits operation, formatting the response for MCP.
@tool() def list_commits(params: Dict) -> Dict: """List commits in a GitHub repository. Args: params: Dictionary with commit parameters - owner: Repository owner (username or organization) - repo: Repository name - page: Page number (optional) - per_page: Results per page (optional) - sha: Branch name or commit SHA (optional) Returns: MCP response with list of commits """ try: logger.debug(f"list_commits called with params: {params}") # Convert dict to Pydantic model commits_params = ListCommitsParams(**params) # Call operation result = repositories.list_commits(commits_params) logger.debug(f"Got {len(result)} commits") return { "content": [{"type": "text", "text": json.dumps(result, indent=2)}] } except ValidationError as e: logger.error(f"Validation error: {e}") return { "content": [{"type": "error", "text": f"Validation error: {str(e)}"}], "is_error": True } except GitHubError as e: logger.error(f"GitHub error: {e}") return { "content": [{"type": "error", "text": format_github_error(e)}], "is_error": True } except Exception as e: logger.error(f"Unexpected error: {e}") logger.error(traceback.format_exc()) error_msg = str(e) if str(e) else "An unexpected error occurred" return { "content": [{"type": "error", "text": f"Internal server error: {error_msg}"}], "is_error": True } - src/pygithub_mcp_server/tools/repositories/__init__.py:16-39 (registration)Registration of the 'list_commits' tool along with other repository tools using register_tools in the MCP server.
from .tools import ( get_repository, create_repository, fork_repository, search_repositories, get_file_contents, create_or_update_file, push_files, create_branch, list_commits ) # Register all repository tools register_tools(mcp, [ get_repository, create_repository, fork_repository, search_repositories, get_file_contents, create_or_update_file, push_files, create_branch, list_commits ]) - Pydantic schema for ListCommitsParams, extending RepositoryRef, with validation for pagination parameters.
class ListCommitsParams(RepositoryRef): """Parameters for listing commits.""" model_config = ConfigDict(strict=True) page: Optional[int] = Field(None, description="Page number") per_page: Optional[int] = Field(None, description="Results per page") sha: Optional[str] = Field(None, description="Branch name or commit SHA") @field_validator('page') @classmethod def validate_page(cls, v): """Validate that page is a positive integer.""" if v is not None and v < 1: raise ValueError("page must be a positive integer") return v @field_validator('per_page') @classmethod def validate_per_page(cls, v): """Validate that per_page is within allowed range.""" if v is not None: if v < 1: raise ValueError("per_page must be a positive integer") if v > 100: raise ValueError("per_page cannot exceed 100") return v - Internal helper function that performs the actual GitHub API call to list commits, handles pagination and conversion to schema.
def list_commits(params: ListCommitsParams) -> List[Dict[str, Any]]: """List commits in a repository. Args: params: Parameters for listing commits Returns: List of commits in our schema Raises: GitHubError: If commit listing fails """ logger.debug(f"Listing commits for {params.owner}/{params.repo}") try: client = GitHubClient.get_instance() repository = client.get_repo(f"{params.owner}/{params.repo}") # Build kwargs from Pydantic model kwargs = {} if params.sha: kwargs["sha"] = params.sha # Get commits paginated_commits = repository.get_commits(**kwargs) # Handle pagination commits = get_paginated_items(paginated_commits, params.page, params.per_page) # Convert commits to our schema return [{ "sha": commit.sha, "message": commit.commit.message, "author": { "name": commit.commit.author.name, "email": commit.commit.author.email, "date": commit.commit.author.date.isoformat() }, "html_url": commit.html_url } for commit in commits] except GithubException as e: logger.error(f"GitHub exception when listing commits: {str(e)}") raise client._handle_github_exception(e, resource_hint="commit")