ZeroPath MCP Server

Instructions

List security scans with optional filtering and pagination.

Args:
    search_query: Optional search term to filter scans
    repository_ids: Optional list of repository IDs to filter by
    scan_type: Optional scan type filter (FullScan, PrScan, SCAScan)
    page: Page number (default: 1)
    page_size: Number of results per page (default: 10)

Implementation Reference

• src/zeropath_mcp_server/server.py:358-404 (handler)

  The primary handler for the 'list_scans' MCP tool. Decorated with @mcp.tool() for registration. Handles input parameters, validates scan_type, constructs payload for ZeroPath API endpoint 'scans/list', processes the response, and returns formatted results or errors.

  @mcp.tool()
  def list_scans(
      search_query: str = None,
      repository_ids: list[str] = None,
      scan_type: str = None,
      page: int = 1,
      page_size: int = 10
  ) -> str:
      """
      List security scans with optional filtering and pagination.
  
      Args:
          search_query: Optional search term to filter scans
          repository_ids: Optional list of repository IDs to filter by
          scan_type: Optional scan type filter (FullScan, PrScan, SCAScan)
          page: Page number (default: 1)
          page_size: Number of results per page (default: 10)
      """
      payload = {
          "page": page,
          "pageSize": page_size
      }
  
      if search_query:
          payload["searchQuery"] = search_query
      if repository_ids:
          payload["repositoryIds"] = repository_ids
      if scan_type:
          valid_types = ["FullScan", "PrScan", "SCAScan"]
          if scan_type not in valid_types:
              return f"Error: Invalid scan type. Must be one of: {', '.join(valid_types)}"
          payload["scanType"] = scan_type
  
      response, error = make_api_request("scans/list", payload)
  
      if error:
          return error
  
      if response.status_code == 200:
          return process_scans_response(response.json())
      elif response.status_code == 401:
          return "Error: Unauthorized - check API credentials"
      elif response.status_code == 400:
          return f"Error: Bad request - {response.text}"
      else:
          return f"Error: API returned status {response.status_code}: {response.text}"

• src/zeropath_mcp_server/server.py:406-443 (helper)

  Supporting helper function used by list_scans to format the raw API response into a readable string, listing scan details including ID, status, type, repository, timestamps, issue counts, and pagination information.

  def process_scans_response(raw_response):
      """Process scans list response into readable format."""
      if "error" in raw_response:
          return f"Error: {raw_response['error']}"
  
      scans = raw_response.get("scans", raw_response.get("items", []))
      if not scans:
          return "No scans found."
  
      total_count = raw_response.get("totalCount", len(scans))
      result = f"Found {total_count} scan(s).\n\n"
  
      for i, scan in enumerate(scans, 1):
          result += f"Scan {i}:\n"
          result += f"  ID: {scan.get('id', 'N/A')}\n"
          result += f"  Status: {scan.get('status', 'N/A')}\n"
          result += f"  Type: {scan.get('scanType', 'N/A')}\n"
          result += f"  Repository: {scan.get('repositoryName', scan.get('repositoryId', 'N/A'))}\n"
          result += f"  Branch: {scan.get('branch', 'N/A')}\n"
          result += f"  Created: {scan.get('createdAt', 'N/A')}\n"
          result += f"  Updated: {scan.get('updatedAt', 'N/A')}\n"
  
          # Issue counts if available
          if scan.get('openIssues') is not None:
              result += f"  Open Issues: {scan.get('openIssues', 0)}\n"
          if scan.get('patchedIssues') is not None:
              result += f"  Patched Issues: {scan.get('patchedIssues', 0)}\n"
          if scan.get('falsePositiveIssues') is not None:
              result += f"  False Positives: {scan.get('falsePositiveIssues', 0)}\n"
  
          result += "\n"
  
      # Pagination info
      if "page" in raw_response or "currentPage" in raw_response:
          result += f"Page: {raw_response.get('page', raw_response.get('currentPage', 1))}\n"
          result += f"Page Size: {raw_response.get('pageSize', len(scans))}\n"
  
      return result