ZeroPath MCP Server

Instructions

Implementation Reference

• src/zeropath_mcp_server/server.py:532-550 (handler)

  The main tool handler function for 'get_issues_by_vuln_class', decorated with @mcp.tool() for registration. It calls the ZeroPath API endpoint 'stats/issuesByVulnClass' and formats the response.

  @mcp.tool()
  def get_issues_by_vuln_class() -> str:
      """
      Get issue statistics grouped by vulnerability class/type.
      Shows distribution of vulnerabilities by category (XSS, SQLi, etc.).
      """
      response, error = make_api_request("stats/issuesByVulnClass")
  
      if error:
          return error
  
      if response.status_code == 200:
          return process_stats_response(response.json(), "Issues by Vulnerability Class")
      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:574-621 (helper)

  Helper function used by the tool to process and format the API response into a human-readable string, handling nested dicts and lists.

  def process_stats_response(raw_response, title):
      """Process stats response into readable format."""
      # Handle list response directly
      if isinstance(raw_response, list):
          result = f"=== {title} ===\n\n"
          for i, item in enumerate(raw_response, 1):
              if isinstance(item, dict):
                  result += f"Item {i}:\n"
                  for k, v in item.items():
                      formatted_key = ''.join(' ' + c if c.isupper() else c for c in str(k)).strip().title()
                      result += f"  {formatted_key}: {v}\n"
                  result += "\n"
              else:
                  result += f"  - {item}\n"
          return result
  
      if isinstance(raw_response, dict) and "error" in raw_response:
          return f"Error: {raw_response['error']}"
  
      result = f"=== {title} ===\n\n"
  
      def format_value(key, value, indent=0):
          """Format a key-value pair with proper indentation."""
          prefix = "  " * indent
          if isinstance(value, dict):
              output = f"{prefix}{key}:\n"
              for k, v in value.items():
                  output += format_value(k, v, indent + 1)
              return output
          elif isinstance(value, list):
              output = f"{prefix}{key}:\n"
              for i, item in enumerate(value):
                  if isinstance(item, dict):
                      output += f"{prefix}  Item {i + 1}:\n"
                      for k, v in item.items():
                          output += format_value(k, v, indent + 2)
                  else:
                      output += f"{prefix}  - {item}\n"
              return output
          else:
              # Format the key nicely (camelCase to Title Case)
              formatted_key = ''.join(' ' + c if c.isupper() else c for c in key).strip().title()
              return f"{prefix}{formatted_key}: {value}\n"
  
      for key, value in raw_response.items():
          result += format_value(key, value)
  
      return result

• src/zeropath_mcp_server/server.py:21-47 (helper)

  General helper function used by the tool to make authenticated POST requests to the ZeroPath API.

  def make_api_request(endpoint, payload=None, include_org=True):
      """Make authenticated API request to ZeroPath."""
      if not token_id or not token_secret:
          return None, "Error: Zeropath API credentials not found in environment variables"
  
      headers = {
          "X-ZeroPath-API-Token-Id": token_id,
          "X-ZeroPath-API-Token-Secret": token_secret,
          "Content-Type": "application/json"
      }
  
      if payload is None:
          payload = {}
  
      if include_org and org_id:
          payload["organizationId"] = org_id
  
      try:
          response = requests.post(
              f"{API_BASE_URL}/{endpoint}",
              headers=headers,
              json=payload
          )
          return response, None
      except Exception as e:
          return None, f"Error: {str(e)}"