Repology MCP Server

Instructions

Args:
    start_from: Project name to start listing from
    limit: Maximum number of results (default: 10, max: 200)
    maintainer: Filter by maintainer email
    category: Filter by category
    inrepo: Filter by repository presence
    notinrepo: Filter by repository absence
    repos: Filter by number of repositories (e.g., "1", "5-", "-5", "2-7")
    families: Filter by number of repository families
    newest: Show only newest projects
    outdated: Show only outdated projects
    problematic: Show only problematic projects

Returns:
    JSON formatted dictionary of projects and their packages

Implementation Reference

• src/repology_mcp/server.py:186-267 (handler)

  The MCP tool handler function for 'list_projects'. It enforces limits, builds filters, calls RepologyClient.list_projects, applies client-side repo filtering if needed, formats output as JSON, and handles errors.

  @mcp.tool()
  async def list_projects(
      start_from: Optional[str] = None,
      limit: int = 10,
      maintainer: Optional[str] = None,
      category: Optional[str] = None,
      inrepo: Optional[str] = None,
      notinrepo: Optional[str] = None,
      repos: Optional[str] = None,
      families: Optional[str] = None,
      newest: Optional[bool] = None,
      outdated: Optional[bool] = None,
      problematic: Optional[bool] = None,
      ctx: Context[ServerSession, AppContext] = None,
  ) -> str:
      """List projects with optional filtering.
  
      Args:
          start_from: Project name to start listing from
          limit: Maximum number of results (default: 10, max: 200)
          maintainer: Filter by maintainer email
          category: Filter by category
          inrepo: Filter by repository presence
          notinrepo: Filter by repository absence
          repos: Filter by number of repositories (e.g., "1", "5-", "-5", "2-7")
          families: Filter by number of repository families
          newest: Show only newest projects
          outdated: Show only outdated projects
          problematic: Show only problematic projects
  
      Returns:
          JSON formatted dictionary of projects and their packages
      """
      if limit > 200:
          limit = 200
  
      try:
          client = ctx.request_context.lifespan_context.repology_client
  
          # Build filters
          filters = {}
          if maintainer:
              filters["maintainer"] = maintainer
          if category:
              filters["category"] = category
          if inrepo:
              filters["inrepo"] = inrepo
          if notinrepo:
              filters["notinrepo"] = notinrepo
          if repos:
              filters["repos"] = repos
          if families:
              filters["families"] = families
          if newest:
              filters["newest"] = "1"
          if outdated:
              filters["outdated"] = "1"
          if problematic:
              filters["problematic"] = "1"
  
          project_packages = await client.list_projects(
              start_from=start_from, limit=limit, **filters
          )
  
          # Apply client-side repository filtering if inrepo is specified
          if inrepo and project_packages:
              project_packages = _filter_project_packages_by_repo(
                  project_packages, inrepo
              )
  
          if not project_packages:
              return json.dumps({"message": "No projects found matching the criteria"})
  
          return _project_packages_to_json(project_packages)
  
      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 listing projects: {e}")
          return json.dumps({"error": f"Unexpected error: {e}"})

• src/repology_mcp/server.py:186-186 (registration)

  The @mcp.tool() decorator registers the list_projects function as an MCP tool on the FastMCP server instance.

  @mcp.tool()

• src/repology_mcp/client.py:212-267 (helper)

  RepologyClient.list_projects method: Fetches project list from Repology API with pagination and filters, validates packages with Pydantic models.

  async def list_projects(
      self,
      start_from: Optional[str] = None,
      end_at: Optional[str] = None,
      limit: int = 200,
      **filters: Any,
  ) -> ProjectPackages:
      """List projects with optional filtering.
  
      Args:
          start_from: Project name to start from (inclusive)
          end_at: Project name to end at (inclusive)
          limit: Maximum number of projects (max 200)
          **filters: Additional filters (maintainer, category, inrepo, etc.)
  
      Returns:
          Dictionary mapping project names to package lists
      """
      # Build endpoint path
      if start_from and end_at:
          endpoint = f"projects/{quote(start_from)}/..{quote(end_at)}/"
      elif start_from:
          endpoint = f"projects/{quote(start_from)}/"
      elif end_at:
          endpoint = f"projects/..{quote(end_at)}/"
      else:
          endpoint = "projects/"
  
      # Add query parameters for filters
      params = {}
      for key, value in filters.items():
          if value is not None:
              params[key] = value
  
      try:
          data = await self._make_request(endpoint, params)
  
          if not isinstance(data, dict):
              raise RepologyAPIError(f"Expected dict, got {type(data)}")
  
          result = {}
          for project_name, packages_data in data.items():
              packages = []
              for item in packages_data:
                  try:
                      packages.append(Package.model_validate(item))
                  except ValidationError as e:
                      print(f"Warning: Failed to validate package data: {e}")
                      continue
              result[project_name] = packages
  
          return result
  
      except Exception as e:
          raise RepologyAPIError(f"Failed to list projects: {e}")

• src/repology_mcp/server.py:69-75 (helper)

  Helper function to convert the project packages dictionary to indented JSON string for the tool response.

  def _project_packages_to_json(project_packages: Dict[str, List[Package]]) -> str:
      """Convert project packages dict to formatted JSON string."""
      result = {}
      for project_name, packages in project_packages.items():
          result[project_name] = [pkg.model_dump() for pkg in packages]
      return json.dumps(result, indent=2)

• src/repology_mcp/server.py:55-67 (helper)

  Helper function for client-side filtering of project packages by repository after API call.

  def _filter_project_packages_by_repo(
      project_packages: Dict[str, List[Package]], repo: str
  ) -> Dict[str, List[Package]]:
      """Filter project packages to only include those from a specific repository."""
      filtered = {}
      for project_name, packages in project_packages.items():
          filtered_packages = _filter_packages_by_repo(packages, repo)
          if (
              filtered_packages
          ):  # Only include projects that have packages in the specified repo
              filtered[project_name] = filtered_packages
      return filtered

• src/repology_mcp/models.py:7-34 (schema)

  Pydantic model for Package data structure used in list_projects output validation and serialization.

  class Package(BaseModel):
      """A package in a repository."""
  
      repo: str = Field(description="Repository name")
      subrepo: Optional[str] = Field(None, description="Subrepository name")
      srcname: Optional[str] = Field(None, description="Source package name")
      binname: Optional[str] = Field(None, description="Binary package name")
      binnames: Optional[List[str]] = Field(None, description="All binary package names")
      visiblename: str = Field(description="Package name as shown by Repology")
      version: str = Field(description="Package version (sanitized)")
      origversion: Optional[str] = Field(None, description="Original package version")
      status: Literal[
          "newest",
          "devel",
          "unique",
          "outdated",
          "legacy",
          "rolling",
          "noscheme",
          "incorrect",
          "untrusted",
          "ignored",
      ] = Field(description="Package status")
      summary: Optional[str] = Field(None, description="Package description")
      categories: Optional[List[str]] = Field(None, description="Package categories")
      licenses: Optional[List[str]] = Field(None, description="Package licenses")
      maintainers: Optional[List[str]] = Field(None, description="Package maintainers")