search_ave

Instructions

Implementation Reference

• bawbel_mcp/server.py:402-444 (handler)

  The `search_ave` function is an MCP tool decorated with @mcp.tool(). It accepts a `query` string and optional `limit` (default 10, max 20). It calls the PiranhaDB API at /records/search, formats each result with severity, CVSS-AI score, OWASP MCP categories, and a link to the full record. Returns a human-readable string.

  @mcp.tool()
  def search_ave(
      query: str,
      limit: int = 10,
  ) -> str:
      """
      Search AVE records by keyword.
  
      Searches across AVE ID, title, attack class, description, and
      behavioral fingerprint. Returns matching records with severity,
      CVSS-AI score, and a link to the full record.
  
      Args:
          query: Search term (e.g. "tool poisoning", "credential", "MCP01")
          limit: Maximum number of results to return (default 10, max 20)
      """
      limit = min(limit, 20)
      data = _piranha_get(f"/records/search?q={urllib.parse.quote(query)}&limit={limit}")
  
      if data.get("error"):
          return f"Error: {data['error']}"
  
      records = data.get("records", [])
      total = data.get("total", 0)
  
      if not records:
          return f"No AVE records found for query: {query}"
  
      lines = [f"Found {total} record(s) for '{query}' (showing {len(records)})", ""]
  
      for r in records:
          ave_id = r.get("ave_id", "")
          title = r.get("title", "")
          severity = r.get("severity", "")
          score = r.get("cvss_ai_score", 0)
          owasp_mcp = ", ".join(r.get("owasp_mcp", []))
          lines.append(f"[{severity} {score}] {ave_id}  {title}")
          if owasp_mcp:
              lines.append(f"  OWASP MCP: {owasp_mcp}")
          lines.append(f"  {PIRANHA_API}/records/{ave_id}")
          lines.append("")
  
      return "\n".join(lines)

• bawbel_mcp/server.py:402-402 (registration)

  The tool is registered with the FastMCP server via the @mcp.tool() decorator on line 402, which registers it as the 'search_ave' tool.

  @mcp.tool()

• bawbel_mcp/server.py:122-131 (helper)

  The `_piranha_get` helper function is used by `search_ave` to make HTTP GET requests to the PiranhaDB API.

  def _piranha_get(path: str) -> dict:
      """GET from PiranhaDB API. Returns parsed JSON or error dict."""
      url = f"{PIRANHA_API}{path}"
      content, err = _fetch_url(url)
      if err:
          return {"error": f"PiranhaDB unavailable: {err}"}
      try:
          return json.loads(content)
      except json.JSONDecodeError:
          return {"error": "Invalid response from PiranhaDB"}

• bawbel_mcp/server.py:407-417 (schema)

  The docstring and type annotations define the schema: `query` (str) is required, `limit` (int, default 10) is optional. The return type is str.

  """
  Search AVE records by keyword.
  
  Searches across AVE ID, title, attack class, description, and
  behavioral fingerprint. Returns matching records with severity,
  CVSS-AI score, and a link to the full record.
  
  Args:
      query: Search term (e.g. "tool poisoning", "credential", "MCP01")
      limit: Maximum number of results to return (default 10, max 20)
  """