PyGithub MCP Server

Instructions

Implementation Reference

• src/pygithub_mcp_server/tools/repositories/tools.py:173-217 (handler)

  MCP tool handler for search_repositories. Validates input using SearchRepositoriesParams, calls the operations layer, and formats MCP response.
  @tool() def search_repositories(params: Dict) -> Dict: """Search for GitHub repositories. Args: params: Dictionary with search parameters - query: Search query - page: Page number for pagination (optional) - per_page: Results per page (optional) Returns: MCP response with matching repositories """ try: logger.debug(f"search_repositories called with params: {params}") # Convert dict to Pydantic model search_params = SearchRepositoriesParams(**params) # Call operation result = repositories.search_repositories(search_params) logger.debug(f"Got {len(result)} results") 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/operations/repositories.py:128-156 (helper)

  Core implementation performing GitHub API search_repositories call, pagination, and schema conversion.
  def search_repositories(params: SearchRepositoriesParams) -> List[Dict[str, Any]]: """Search for repositories. Args: params: Parameters for searching repositories Returns: List of matching repositories in our schema Raises: GitHubError: If repository search fails """ logger.debug(f"Searching repositories with query: {params.query}") try: client = GitHubClient.get_instance() github = client.github # Search repositories paginated_repos = github.search_repositories(query=params.query) # Handle pagination repos = get_paginated_items(paginated_repos, params.page, params.per_page) # Convert repositories to our schema return [convert_repository(repo) for repo in repos] except GithubException as e: logger.error(f"GitHub exception when searching repositories: {str(e)}") raise client._handle_github_exception(e, resource_hint="repository")
• src/pygithub_mcp_server/schemas/repositories.py:91-128 (schema)

  Pydantic schema for input validation of search_repositories tool parameters.
  class SearchRepositoriesParams(BaseModel): """Parameters for searching repositories.""" model_config = ConfigDict(strict=True) query: str = Field(..., description="Search query") page: Optional[int] = Field(None, description="Page number for pagination") per_page: Optional[int] = Field( None, description="Number of results per page (default: 30, max: 100)" ) @field_validator('query') @classmethod def validate_query(cls, v): """Validate that query is not empty.""" if not v.strip(): raise ValueError("query cannot be empty") return v @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
• src/pygithub_mcp_server/tools/repositories/__init__.py:9-39 (registration)

  Registration of the search_repositories tool along with other repository tools using register_tools.
  def register(mcp: FastMCP) -> None: """Register all repository tools with the MCP server. Args: mcp: The MCP server instance """ from pygithub_mcp_server.tools import register_tools 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 ])