MCP Vulnerability Checker Server

Instructions

Implementation Reference

• mcp_simple_tool/tools/package_vulnerability.py:175-244 (handler)

  The primary handler function that executes the tool's logic: normalizes package name, fetches metadata from PyPI, queries OSV.dev for vulnerabilities, generates formatted report, and returns MCP TextContent or error messages.

  async def check_package_vulnerabilities(
      package_name: str, version: Optional[str] = None
  ) -> List[types.TextContent | types.ImageContent | types.EmbeddedResource]:
      """
      Check for known vulnerabilities in a Python package.
  
      Args:
          package_name: Name of the Python package to check
          version: Specific version to check (optional, checks all versions if not provided)
  
      Returns:
          List of content containing vulnerability report or error messages
      """
      # Clean up package name
      package_name = package_name.lower().strip().replace("_", "-")
  
      if not package_name:
          return [
              types.TextContent(type="text", text="Error: Package name cannot be empty.")
          ]
  
      try:
          # Get package info from PyPI
          package_info = await get_package_info(package_name)
  
          if not package_info:
              return [
                  types.TextContent(
                      type="text",
                      text=f"Error: Package '{package_name}' not found on PyPI. Please check the package name.",
                  )
              ]
  
          # Query OSV for vulnerabilities
          vulns = await query_osv_vulnerabilities(package_name, version)
  
          # Format the report
          report = format_vulnerability_report(vulns, package_name, package_info)
  
          return [types.TextContent(type="text", text=report)]
  
      except httpx.TimeoutException:
          return [
              types.TextContent(
                  type="text",
                  text="Error: Request timed out while checking package vulnerabilities.",
              )
          ]
      except httpx.HTTPStatusError as e:
          return [
              types.TextContent(
                  type="text",
                  text=f"Error: HTTP {e.response.status_code} error while fetching vulnerability data.",
              )
          ]
      except json.JSONDecodeError:
          return [
              types.TextContent(
                  type="text",
                  text="Error: Invalid JSON response from vulnerability database.",
              )
          ]
      except Exception as e:
          return [
              types.TextContent(
                  type="text",
                  text=f"Error: Failed to check package vulnerabilities: {str(e)}",
              )
          ]

• mcp_simple_tool/server.py:180-193 (schema)

  JSON schema defining the tool's input parameters: required 'package_name' string and optional 'version' string.

  inputSchema={
      "type": "object",
      "required": ["package_name"],
      "properties": {
          "package_name": {
              "type": "string",
              "description": "Name of the Python package to check for vulnerabilities (e.g., 'requests', 'django', 'flask')",
          },
          "version": {
              "type": "string",
              "description": "Specific version to check (optional). If not provided, checks all known versions.",
          },
      },
  },

• mcp_simple_tool/server.py:177-194 (registration)

  Registration of the 'package_vulnerability_check' tool in the server's list_tools() method, providing name, description, and input schema.

  types.Tool(
      name="package_vulnerability_check",
      description="Check for known vulnerabilities in Python packages using OSV database",
      inputSchema={
          "type": "object",
          "required": ["package_name"],
          "properties": {
              "package_name": {
                  "type": "string",
                  "description": "Name of the Python package to check for vulnerabilities (e.g., 'requests', 'django', 'flask')",
              },
              "version": {
                  "type": "string",
                  "description": "Specific version to check (optional). If not provided, checks all known versions.",
              },
          },
      },
  ),

• mcp_simple_tool/tools/package_vulnerability.py:35-70 (helper)

  Helper function that constructs and sends POST request to OSV.dev API to retrieve vulnerability data for the specified PyPI package and optional version.

  async def query_osv_vulnerabilities(
      package_name: str, version: Optional[str] = None
  ) -> List[Dict[str, Any]]:
      """
      Query OSV database for vulnerabilities in a Python package.
  
      Args:
          package_name: Name of the Python package
          version: Specific version to check (optional)
  
      Returns:
          List of vulnerability records
      """
      osv_query = {"package": {"name": package_name, "ecosystem": "PyPI"}}
  
      if version:
          osv_query["version"] = version
  
      headers = {
          "User-Agent": "MCP Package Vulnerability Checker v1.0",
          "Content-Type": "application/json",
      }
  
      try:
          timeout = httpx.Timeout(15.0, connect=10.0)
          async with httpx.AsyncClient(headers=headers, timeout=timeout) as client:
              response = await client.post("https://api.osv.dev/v1/query", json=osv_query)
              response.raise_for_status()
  
              data = response.json()
              return data.get("vulns", [])
  
      except Exception:
          # Return empty list but don't print error - let caller handle it
          return []

• mcp_simple_tool/tools/package_vulnerability.py:15-33 (helper)

  Helper function that fetches package metadata (including latest version) from PyPI JSON API.

  async def get_package_info(package_name: str) -> Optional[Dict[str, Any]]:
      """
      Get package information from PyPI to find the latest version.
  
      Args:
          package_name: Name of the Python package
  
      Returns:
          Dictionary containing package info or None if not found
      """
      try:
          timeout = httpx.Timeout(10.0, connect=5.0)
          async with httpx.AsyncClient(timeout=timeout) as client:
              response = await client.get(f"https://pypi.org/pypi/{package_name}/json")
              response.raise_for_status()
              return response.json()
      except Exception:
          return None