chore: use abstract classes instead of Protocol

Author: erfanmirshams

README.md

@@ -68,7 +68,7 @@ Supported backends:
 
 ## Prerequisites
 
-- **Python 3.10+**: Required for running the MCP servers
+- **Python 3.13+**: Required for running the MCP servers
 - **Search Backend**: Either a Sourcegraph instance or Zoekt server
 - **UV** (optional): Modern Python package manager for easier dependency management
 - **Langfuse** (optional): For observability and tracing

src/backends/__init__.py

@@ -1,13 +1,11 @@
 """Search backends for the MCP server."""
 
-from .content_fetcher_factory import ContentFetcherFactory
-from .content_fetcher_protocol import ContentFetcherProtocol
-from .search_factory import SearchClientFactory
-from .search_protocol import SearchClientProtocol
+from .content_fetcher import AbstractContentFetcher, ContentFetcherFactory
+from .search import AbstractSearchClient, SearchClientFactory
 
 __all__ = [
     "ContentFetcherFactory",
-    "ContentFetcherProtocol",
+    "AbstractContentFetcher",
     "SearchClientFactory",
-    "SearchClientProtocol",
+    "AbstractSearchClient",
 ]

src/backends/content_fetcher_factory.py renamed to src/backends/content_fetcher.py

@@ -1,13 +1,37 @@
-from backends.content_fetcher_protocol import ContentFetcherProtocol
-from backends.sourcegraph.fetcher import SourcegraphContentFetcher
-from backends.zoekt.fetcher import ZoektContentFetcher
+from abc import ABC, abstractmethod
+
+MAX_FILE_SIZE = 100_000
+
+
+class AbstractContentFetcher(ABC):
+    """
+    Interface for content fetchers.
+    """
+
+    @abstractmethod
+    def get_content(self, repository: str, path: str = "", depth: int = 2, ref: str = "HEAD") -> str:
+        """Get content from repository.
+
+        Args:
+            repository: Repository path (e.g., "git.divar.cloud/divar/rpc/autogenerated/divar-interface-swift")
+            path: File or directory path (e.g., "Sources/DivarInterfaceClient/divar_interface_sms_sms.grpc.swift")
+            depth: Tree depth for directory listings
+            ref: Git reference (branch, tag, or commit SHA)
+
+        Returns:
+            File content if path is a file, directory tree if path is a directory
+
+        Raises:
+            ValueError: If repository or path does not exist
+        """
+        ...
 
 
 class ContentFetcherFactory:
     """Factory class for creating content fetcher instances based on configuration."""
 
     @staticmethod
-    def create_fetcher(backend: str, **kwargs) -> ContentFetcherProtocol:
+    def create_fetcher(backend: str, **kwargs) -> AbstractContentFetcher:
         """Create a content fetcher based on the specified backend.
 
         Args:
@@ -28,7 +52,7 @@ def create_fetcher(backend: str, **kwargs) -> ContentFetcherProtocol:
             raise ValueError(f"Unsupported content fetcher backend: {backend}")
 
     @staticmethod
-    def _create_sourcegraph_fetcher(**kwargs) -> SourcegraphContentFetcher:
+    def _create_sourcegraph_fetcher(**kwargs) -> "SourcegraphContentFetcher":
         """Create and configure a Sourcegraph content fetcher.
 
         Args:
@@ -40,6 +64,8 @@ def _create_sourcegraph_fetcher(**kwargs) -> SourcegraphContentFetcher:
         Raises:
             ValueError: If required configuration is missing
         """
+        from backends.sourcegraph.fetcher import SourcegraphContentFetcher
+
         endpoint = kwargs.get("endpoint")
         token = kwargs.get("token", "")
 
@@ -49,7 +75,7 @@ def _create_sourcegraph_fetcher(**kwargs) -> SourcegraphContentFetcher:
         return SourcegraphContentFetcher(endpoint=endpoint, token=token)
 
     @staticmethod
-    def _create_zoekt_fetcher(**kwargs) -> ZoektContentFetcher:
+    def _create_zoekt_fetcher(**kwargs) -> "ZoektContentFetcher":
         """Create and configure a Zoekt content fetcher.
 
         Args:
@@ -58,6 +84,8 @@ def _create_zoekt_fetcher(**kwargs) -> ZoektContentFetcher:
         Returns:
             ZoektContentFetcher: Configured Zoekt content fetcher
         """
+        from backends.zoekt.fetcher import ZoektContentFetcher
+
         zoekt_url = kwargs.get("zoekt_url")
 
         if not zoekt_url:

src/backends/content_fetcher_protocol.py

@@ -1,13 +1,46 @@
-from backends.search_protocol import SearchClientProtocol
-from backends.sourcegraph import SourcegraphClient
-from backends.zoekt import Client as ZoektClient
+from abc import ABC, abstractmethod
+from typing import List
+
+from backends.models import FormattedResult
+
+
+class AbstractSearchClient(ABC):
+    """
+    Interface for search clients.
+    """
+
+    @abstractmethod
+    def search(self, query: str, num: int) -> dict:
+        """Execute a search query and return raw results.
+
+        Args:
+            query: The search query string
+            num: Maximum number of results to return
+
+        Returns:
+            Raw search results as a dictionary
+        """
+        ...
+
+    @abstractmethod
+    def format_results(self, results: dict, num: int) -> List[FormattedResult]:
+        """Format raw search results into structured FormattedResult objects.
+
+        Args:
+            results: Raw search results from the search method
+            num: Maximum number of results to format
+
+        Returns:
+            List of formatted results
+        """
+        ...
 
 
 class SearchClientFactory:
     """Factory class for creating search client instances based on configuration."""
 
     @staticmethod
-    def create_client(backend: str, **kwargs) -> SearchClientProtocol:
+    def create_client(backend: str, **kwargs) -> AbstractSearchClient:
         """Create a search client based on the specified backend.
 
         Args:
@@ -28,7 +61,7 @@ def create_client(backend: str, **kwargs) -> SearchClientProtocol:
             raise ValueError(f"Unsupported search backend: {backend}")
 
     @staticmethod
-    def _create_sourcegraph_client(**kwargs) -> SourcegraphClient:
+    def _create_sourcegraph_client(**kwargs) -> "SourcegraphClient":
         """Create and configure a Sourcegraph client.
 
         Args:
@@ -40,6 +73,8 @@ def _create_sourcegraph_client(**kwargs) -> SourcegraphClient:
         Raises:
             ValueError: If required configuration is missing
         """
+        from backends.sourcegraph import SourcegraphClient
+
         endpoint = kwargs.get("endpoint")
         token = kwargs.get("token", "")
 
@@ -54,7 +89,7 @@ def _create_sourcegraph_client(**kwargs) -> SourcegraphClient:
         )
 
     @staticmethod
-    def _create_zoekt_client(**kwargs) -> ZoektClient:
+    def _create_zoekt_client(**kwargs) -> "ZoektClient":
         """Create and configure a Zoekt client.
 
         Args:
@@ -63,6 +98,8 @@ def _create_zoekt_client(**kwargs) -> ZoektClient:
         Returns:
             ZoektClient: Configured Zoekt client
         """
+        from backends.zoekt import Client as ZoektClient
+
         base_url = kwargs.get("base_url")
 
         if not base_url:

src/backends/search_factory.py renamed to src/backends/search.py

@@ -6,7 +6,7 @@
 import requests
 
 from backends.models import FormattedResult, Match
-from backends.search_protocol import SearchClientProtocol
+from backends.search import AbstractSearchClient
 
 logger = logging.getLogger(__name__)
 
@@ -68,9 +68,7 @@ def _parse_event(self, event_text: str) -> Dict[str, str]:
         return {}
 
 
-class SourcegraphClient(SearchClientProtocol):
-    """Sourcegraph search client implementing the SearchClientProtocol interface."""
-
+class SourcegraphClient(AbstractSearchClient):
     def __init__(
         self,
         endpoint: str,

src/backends/search_protocol.py

@@ -6,10 +6,10 @@
 
 import requests
 
-from backends.content_fetcher_protocol import MAX_FILE_SIZE, ContentFetcherProtocol
+from backends.content_fetcher import MAX_FILE_SIZE, AbstractContentFetcher
 
 
-class SourcegraphContentFetcher(ContentFetcherProtocol):
+class SourcegraphContentFetcher(AbstractContentFetcher):
     """Fetches content from Sourcegraph repositories."""
 
     def __init__(self, endpoint: str, token: str = ""):

src/backends/sourcegraph/client.py

@@ -3,10 +3,10 @@
 import requests
 
 from backends.models import FormattedResult, Match
-from backends.search_protocol import SearchClientProtocol
+from backends.search import AbstractSearchClient
 
 
-class Client(SearchClientProtocol):
+class Client(AbstractSearchClient):
     def __init__(
         self,
         base_url: str,

src/backends/sourcegraph/fetcher.py

@@ -5,10 +5,10 @@
 
 import requests
 
-from backends.content_fetcher_protocol import MAX_FILE_SIZE, ContentFetcherProtocol
+from backends.content_fetcher import MAX_FILE_SIZE, AbstractContentFetcher
 
 
-class ZoektContentFetcher(ContentFetcherProtocol):
+class ZoektContentFetcher(AbstractContentFetcher):
     def __init__(self, zoekt_url: str):
         self.zoekt_url = zoekt_url.rstrip("/")