PyGithub MCP Server

Instructions

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

Implementation Reference

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

  The MCP tool handler function decorated with @tool(). It receives parameters as dict, validates using SearchRepositoriesParams, delegates to the repositories operation, handles errors, and returns MCP-formatted 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/schemas/repositories.py:91-128 (schema)

  Pydantic BaseModel defining the input schema for the search_repositories tool, including query (required), page and per_page (optional) with validation rules.

  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-40 (registration)

  Registration function that imports the search_repositories handler and registers it (along with other repository tools) with the MCP server instance 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
      ])

• src/pygithub_mcp_server/operations/repositories.py:128-156 (helper)

  Helper function implementing the core search logic: performs GitHub API search, handles pagination, converts results to internal schema, and raises GitHubError on failure.

  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")