refactor: consolidate tools into single search_tools.py file

- Merge pia_search.py and pia_search_facets.py into search_tools.py
- Update imports in __init__.py and test files
- Remove duplicate code and improve maintainability
- All tests pass (14/14) with 74% coverage maintained
- Clean separation of tool definitions and handlers in single module

Author: dividor

src/pia_mcp_server/tools/__init__.py

@@ -5,8 +5,12 @@
 This module provides tools for interacting with the Program Integrity Alliance API.
 """
 
-from .pia_search import handle_pia_search, pia_search_tool
-from .pia_search_facets import handle_pia_search_facets, pia_search_facets_tool
+from .search_tools import (
+    handle_pia_search,
+    pia_search_tool,
+    handle_pia_search_facets,
+    pia_search_facets_tool,
+)
 
 __all__ = [
     "handle_pia_search",

src/pia_mcp_server/tools/pia_search_facets.py

@@ -1,4 +1,4 @@
-"""PIA Search tool for comprehensive database searches."""
+"""PIA Search tools for database searches and facets discovery."""
 
 import httpx
 import mcp.types as types
@@ -10,7 +10,7 @@
 logger = logging.getLogger(__name__)
 settings = Settings()
 
-# Tool definition based on the API response
+# Tool definitions based on the API response
 pia_search_tool = types.Tool(
     name="pia_search",
     description="Search the Program Integrity Alliance (PIA) database for documents and recommendations. Returns comprehensive results with full citation information and clickable links for proper attribution. Each result includes corresponding citations with data source attribution (GAO, OIG, etc.). Supports structured filtering using index field names with operators like eq, ne, in, not_in, gte, lte, etc.",
@@ -48,6 +48,21 @@
     },
 )
 
+pia_search_facets_tool = types.Tool(
+    name="pia_search_facets",
+    description="Get available facets (filter values) for the PIA database. This can help understand what filter values are available before performing searches.",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Optional query to get facets for",
+                "default": "",
+            }
+        },
+    },
+)
+
 
 async def handle_pia_search(arguments: Dict[str, Any]) -> List[types.TextContent]:
     """Handle PIA search requests."""
@@ -107,3 +122,63 @@ async def handle_pia_search(arguments: Dict[str, Any]) -> List[types.TextContent
     except Exception as e:
         logger.error(f"Error during PIA search: {e}")
         return [types.TextContent(type="text", text=f"Error: {str(e)}")]
+
+
+async def handle_pia_search_facets(
+    arguments: Dict[str, Any],
+) -> List[types.TextContent]:
+    """Handle PIA search facets requests."""
+    try:
+        # Prepare the request payload
+        payload = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {"name": "pia_search_facets", "arguments": arguments},
+        }
+
+        try:
+            api_key = settings.API_KEY
+        except ValueError as e:
+            return [
+                types.TextContent(
+                    type="text",
+                    text=f"Error: {str(e)} Configure API key in MCP server settings.",
+                )
+            ]
+
+        headers = {"Content-Type": "application/json", "x-api-key": api_key}
+
+        async with httpx.AsyncClient(timeout=settings.REQUEST_TIMEOUT) as client:
+            response = await client.post(
+                settings.PIA_API_URL, json=payload, headers=headers
+            )
+            response.raise_for_status()
+
+            result = response.json()
+
+            if "error" in result:
+                error_msg = result["error"].get("message", "Unknown error")
+                return [types.TextContent(type="text", text=f"API Error: {error_msg}")]
+
+            if "result" in result:
+                # Format the facets nicely
+                facets = result["result"]
+                formatted_result = json.dumps(facets, indent=2, ensure_ascii=False)
+                return [types.TextContent(type="text", text=formatted_result)]
+            else:
+                return [
+                    types.TextContent(type="text", text="No facets returned from API")
+                ]
+
+    except httpx.HTTPStatusError as e:
+        logger.error(f"HTTP error during PIA search facets: {e}")
+        return [
+            types.TextContent(
+                type="text",
+                text=f"HTTP Error {e.response.status_code}: {e.response.text}",
+            )
+        ]
+    except Exception as e:
+        logger.error(f"Error during PIA search facets: {e}")
+        return [types.TextContent(type="text", text=f"Error: {str(e)}")]

src/pia_mcp_server/tools/pia_search.py renamed to src/pia_mcp_server/tools/search_tools.py

@@ -3,8 +3,10 @@
 import pytest
 from unittest.mock import AsyncMock, patch, PropertyMock, Mock
 import httpx
-from pia_mcp_server.tools.pia_search import handle_pia_search
-from pia_mcp_server.tools.pia_search_facets import handle_pia_search_facets
+from pia_mcp_server.tools.search_tools import (
+    handle_pia_search,
+    handle_pia_search_facets,
+)
 from pia_mcp_server.config import Settings
 
 settings = Settings()