Repology MCP Server

Instructions

Implementation Reference

• src/repology_mcp/server.py:307-346 (handler)

  The main MCP tool handler function that orchestrates fetching maintainer problems from Repology API via client, handles errors, and returns formatted JSON response.
  @mcp.tool() async def get_maintainer_problems( maintainer: str, repository: Optional[str] = None, start_from: Optional[str] = None, ctx: Context[ServerSession, AppContext] = None, ) -> str: """Get problems reported for packages maintained by a specific person. Args: maintainer: Maintainer email address repository: Optional repository to limit results to start_from: Project name to start from for pagination Returns: JSON formatted list of problems for the maintainer """ try: client = ctx.request_context.lifespan_context.repology_client problems = await client.get_maintainer_problems( maintainer=maintainer, repository=repository, start_from=start_from ) if not problems: msg = f"No problems found for maintainer '{maintainer}'" if repository: msg += f" in repository '{repository}'" return json.dumps({"message": msg}) return _problems_to_json(problems) except RepologyNotFoundError: return json.dumps({"error": f"Maintainer '{maintainer}' not found"}) except RepologyAPIError as e: await ctx.error(f"Repology API error: {e}") return json.dumps({"error": str(e)}) except Exception as e: await ctx.error(f"Unexpected error getting maintainer problems: {e}") return json.dumps({"error": f"Unexpected error: {e}"})
• src/repology_mcp/client.py:321-365 (helper)

  Helper function in RepologyClient that makes the actual HTTP request to Repology API for maintainer problems and validates response using Problem models.
  async def get_maintainer_problems( self, maintainer: str, repository: Optional[str] = None, start_from: Optional[str] = None, ) -> ProblemsData: """Get problems for packages maintained by a specific person. Args: maintainer: Maintainer email address repository: Optional repository to limit results to start_from: Project name to start from for pagination Returns: List of problems """ if repository: endpoint = ( f"maintainer/{quote(maintainer)}/problems-for-repo/{quote(repository)}" ) else: endpoint = f"maintainer/{quote(maintainer)}/problems" params = {} if start_from: params["start"] = start_from try: data = await self._make_request(endpoint, params) if not isinstance(data, list): raise RepologyAPIError(f"Expected list, got {type(data)}") problems = [] for item in data: try: problems.append(Problem.model_validate(item)) except ValidationError as e: print(f"Warning: Failed to validate problem data: {e}") continue return problems except Exception as e: raise RepologyAPIError(f"Failed to get maintainer problems: {e}")
• src/repology_mcp/models.py:36-66 (schema)

  Pydantic models defining the structure of Problem data and ProblemsData type alias used for input/output validation in the client and handler.
  class Problem(BaseModel): """A problem reported for a package.""" type: str = Field(description="Problem type") data: Dict[str, Any] = Field(description="Additional problem details") project_name: str = Field(description="Repology project name") version: str = Field(description="Package version") srcname: Optional[str] = Field(None, description="Source package name") binname: Optional[str] = Field(None, description="Binary package name") rawversion: Optional[str] = Field(None, description="Raw package version") class ProjectSummary(BaseModel): """Summary information about a project.""" name: str = Field(description="Project name") newest_version: Optional[str] = Field(None, description="Newest version") outdated_repos: int = Field(0, description="Number of outdated repositories") total_repos: int = Field(0, description="Total number of repositories") categories: List[str] = Field( default_factory=list, description="Project categories" ) maintainers: List[str] = Field( default_factory=list, description="Project maintainers" ) # Type aliases for API responses ProjectPackages = Dict[str, List[Package]] ProjectData = List[Package] ProblemsData = List[Problem]
• src/repology_mcp/server.py:45-47 (helper)

  Utility helper function to convert list of Problem objects to indented JSON string for the tool response.
  def _problems_to_json(problems: List[Problem]) -> str: """Convert problems list to formatted JSON string.""" return json.dumps([prob.model_dump() for prob in problems], indent=2)
• src/repology_mcp/server.py:37-37 (registration)

  Creation of the FastMCP server instance where tools like get_maintainer_problems are registered via @mcp.tool() decorators.
  mcp = FastMCP("Repology API Server", lifespan=app_lifespan)