napistu 0.2.5.dev6__py3-none-any.whl → 0.3.1__py3-none-any.whl

napistu/mcp/codebase.py

@@ -2,181 +2,229 @@
 Codebase exploration components for the Napistu MCP server.
 """
 
-from napistu.mcp.constants import NAPISTU_PY_READTHEDOCS_API
-
-from fastmcp import FastMCP
-
 from typing import Dict, Any
 import json
+import logging
 
+from fastmcp import FastMCP
+
+from napistu.mcp.component_base import ComponentState, MCPComponent
+from napistu.mcp.constants import NAPISTU_PY_READTHEDOCS_API
 from napistu.mcp import codebase_utils
 from napistu.mcp import utils as mcp_utils
 
-# Global cache for codebase information
-_codebase_cache = {
-    "modules": {},
-    "classes": {},
-    "functions": {},
-}
+logger = logging.getLogger(__name__)
 
 
-async def initialize_components() -> bool:
-    """
-    Initialize codebase components.
+class CodebaseState(ComponentState):
+    """State management for codebase component."""
 
-    Returns
-    -------
-    bool
-        True if initialization is successful.
-    """
-    global _codebase_cache
-    # Load documentation from the ReadTheDocs API
-    _codebase_cache["modules"] = await codebase_utils.read_read_the_docs(
-        NAPISTU_PY_READTHEDOCS_API
-    )
-    # Extract functions and classes from the modules
-    _codebase_cache["functions"], _codebase_cache["classes"] = (
-        codebase_utils.extract_functions_and_classes_from_modules(
-            _codebase_cache["modules"]
-        )
-    )
-    return True
-
-
-def register_components(mcp: FastMCP):
-    """
-    Register codebase exploration components with the MCP server.
+    def __init__(self):
+        super().__init__()
+        self.codebase_cache: Dict[str, Dict[str, Any]] = {
+            "modules": {},
+            "classes": {},
+            "functions": {},
+        }
 
-    Args:
-        mcp: FastMCP server instance
-    """
-    global _codebase_cache
+    def is_healthy(self) -> bool:
+        """Component is healthy if it has loaded any codebase information."""
+        return any(bool(section) for section in self.codebase_cache.values())
 
-    # Register resources
-    @mcp.resource("napistu://codebase/summary")
-    async def get_codebase_summary() -> Dict[str, Any]:
-        """
-        Get a summary of the Napistu codebase structure.
-        """
+    def get_health_details(self) -> Dict[str, Any]:
+        """Provide codebase-specific health details."""
         return {
-            "modules": list(_codebase_cache["modules"].keys()),
-            "top_level_classes": [
-                class_name
-                for class_name, info in _codebase_cache["classes"].items()
-                if "." not in class_name  # Only include top-level classes
-            ],
-            "top_level_functions": [
-                func_name
-                for func_name, info in _codebase_cache["functions"].items()
-                if "." not in func_name  # Only include top-level functions
-            ],
+            "modules_count": len(self.codebase_cache["modules"]),
+            "classes_count": len(self.codebase_cache["classes"]),
+            "functions_count": len(self.codebase_cache["functions"]),
+            "total_items": sum(
+                len(section) for section in self.codebase_cache.values()
+            ),
         }
 
-    @mcp.resource("napistu://codebase/modules/{module_name}")
-    async def get_module_details(module_name: str) -> Dict[str, Any]:
-        """
-        Get detailed information about a specific module.
 
-        Args:
-            module_name: Name of the module
-        """
-        if module_name not in _codebase_cache["modules"]:
-            return {"error": f"Module {module_name} not found"}
+class CodebaseComponent(MCPComponent):
+    """MCP component for codebase exploration and search."""
 
-        return _codebase_cache["modules"][module_name]
+    def _create_state(self) -> CodebaseState:
+        """Create codebase-specific state."""
+        return CodebaseState()
 
-    # Register tools
-    @mcp.tool()
-    async def search_codebase(query: str) -> Dict[str, Any]:
+    async def initialize(self) -> bool:
         """
-        Search the codebase for a specific query.
+        Initialize codebase component by loading documentation from ReadTheDocs.
 
-        Args:
-            query: Search term
-
-        Returns:
-            Dictionary with search results organized by code element type, including snippets for context.
+        Returns
+        -------
+        bool
+            True if codebase information was loaded successfully
         """
-        results = {
-            "modules": [],
-            "classes": [],
-            "functions": [],
-        }
-
-        # Search modules
-        for module_name, info in _codebase_cache["modules"].items():
-            # Use docstring or description for snippet
-            doc = info.get("doc") or info.get("description") or ""
-            module_text = json.dumps(info)
-            if query.lower() in module_text.lower():
-                snippet = mcp_utils.get_snippet(doc, query)
-                results["modules"].append(
-                    {
-                        "name": module_name,
-                        "description": doc,
-                        "snippet": snippet,
-                    }
-                )
-
-        # Search classes
-        for class_name, info in _codebase_cache["classes"].items():
-            doc = info.get("doc") or info.get("description") or ""
-            class_text = json.dumps(info)
-            if query.lower() in class_text.lower():
-                snippet = mcp_utils.get_snippet(doc, query)
-                results["classes"].append(
-                    {
-                        "name": class_name,
-                        "description": doc,
-                        "snippet": snippet,
-                    }
-                )
-
-        # Search functions
-        for func_name, info in _codebase_cache["functions"].items():
-            doc = info.get("doc") or info.get("description") or ""
-            func_text = json.dumps(info)
-            if query.lower() in func_text.lower():
-                snippet = mcp_utils.get_snippet(doc, query)
-                results["functions"].append(
-                    {
-                        "name": func_name,
-                        "description": doc,
-                        "signature": info.get("signature", ""),
-                        "snippet": snippet,
-                    }
-                )
-
-        return results
-
-    @mcp.tool()
-    async def get_function_documentation(function_name: str) -> Dict[str, Any]:
+        try:
+            logger.info("Loading codebase documentation from ReadTheDocs...")
+
+            # Load documentation from the ReadTheDocs API
+            modules = await codebase_utils.read_read_the_docs(
+                NAPISTU_PY_READTHEDOCS_API
+            )
+            self.state.codebase_cache["modules"] = modules
+
+            # Extract functions and classes from the modules
+            functions, classes = (
+                codebase_utils.extract_functions_and_classes_from_modules(modules)
+            )
+            self.state.codebase_cache["functions"] = functions
+            self.state.codebase_cache["classes"] = classes
+
+            logger.info(
+                f"Codebase loading complete: "
+                f"{len(modules)} modules, "
+                f"{len(classes)} classes, "
+                f"{len(functions)} functions"
+            )
+
+            # Consider successful if we loaded any modules
+            return len(modules) > 0
+
+        except Exception as e:
+            logger.error(f"Failed to load codebase documentation: {e}")
+            return False
+
+    def register(self, mcp: FastMCP) -> None:
         """
-        Get detailed documentation for a specific function.
-
-        Args:
-            function_name: Name of the function
+        Register codebase resources and tools with the MCP server.
 
-        Returns:
-            Dictionary with function documentation
+        Parameters
+        ----------
+        mcp : FastMCP
+            FastMCP server instance
         """
-        if function_name not in _codebase_cache["functions"]:
-            return {"error": f"Function {function_name} not found"}
 
-        return _codebase_cache["functions"][function_name]
-
-    @mcp.tool()
-    async def get_class_documentation(class_name: str) -> Dict[str, Any]:
-        """
-        Get detailed documentation for a specific class.
-
-        Args:
-            class_name: Name of the class
-
-        Returns:
-            Dictionary with class documentation
-        """
-        if class_name not in _codebase_cache["classes"]:
-            return {"error": f"Class {class_name} not found"}
+        # Register resources
+        @mcp.resource("napistu://codebase/summary")
+        async def get_codebase_summary():
+            """Get a summary of all available codebase information."""
+            return {
+                "modules": list(self.state.codebase_cache["modules"].keys()),
+                "classes": list(self.state.codebase_cache["classes"].keys()),
+                "functions": list(self.state.codebase_cache["functions"].keys()),
+            }
+
+        @mcp.resource("napistu://codebase/modules/{module_name}")
+        async def get_module_details(module_name: str) -> Dict[str, Any]:
+            """Get detailed information about a specific module."""
+            if module_name not in self.state.codebase_cache["modules"]:
+                return {"error": f"Module {module_name} not found"}
+
+            return self.state.codebase_cache["modules"][module_name]
+
+        # Register tools
+        @mcp.tool()
+        async def search_codebase(query: str) -> Dict[str, Any]:
+            """
+            Search the codebase for a specific query.
+
+            Args:
+                query: Search term
+
+            Returns:
+                Dictionary with search results organized by code element type, including snippets for context.
+            """
+            results = {
+                "modules": [],
+                "classes": [],
+                "functions": [],
+            }
+
+            # Search modules
+            for module_name, info in self.state.codebase_cache["modules"].items():
+                # Use docstring or description for snippet
+                doc = info.get("doc") or info.get("description") or ""
+                module_text = json.dumps(info)
+                if query.lower() in module_text.lower():
+                    snippet = mcp_utils.get_snippet(doc, query)
+                    results["modules"].append(
+                        {
+                            "name": module_name,
+                            "description": doc,
+                            "snippet": snippet,
+                        }
+                    )
+
+            # Search classes
+            for class_name, info in self.state.codebase_cache["classes"].items():
+                doc = info.get("doc") or info.get("description") or ""
+                class_text = json.dumps(info)
+                if query.lower() in class_text.lower():
+                    snippet = mcp_utils.get_snippet(doc, query)
+                    results["classes"].append(
+                        {
+                            "name": class_name,
+                            "description": doc,
+                            "snippet": snippet,
+                        }
+                    )
+
+            # Search functions
+            for func_name, info in self.state.codebase_cache["functions"].items():
+                doc = info.get("doc") or info.get("description") or ""
+                func_text = json.dumps(info)
+                if query.lower() in func_text.lower():
+                    snippet = mcp_utils.get_snippet(doc, query)
+                    results["functions"].append(
+                        {
+                            "name": func_name,
+                            "description": doc,
+                            "signature": info.get("signature", ""),
+                            "snippet": snippet,
+                        }
+                    )
+
+            return results
+
+        @mcp.tool()
+        async def get_function_documentation(function_name: str) -> Dict[str, Any]:
+            """
+            Get detailed documentation for a specific function.
+
+            Args:
+                function_name: Name of the function
+
+            Returns:
+                Dictionary with function documentation
+            """
+            if function_name not in self.state.codebase_cache["functions"]:
+                return {"error": f"Function {function_name} not found"}
+
+            return self.state.codebase_cache["functions"][function_name]
+
+        @mcp.tool()
+        async def get_class_documentation(class_name: str) -> Dict[str, Any]:
+            """
+            Get detailed documentation for a specific class.
+
+            Args:
+                class_name: Name of the class
+
+            Returns:
+                Dictionary with class documentation
+            """
+            if class_name not in self.state.codebase_cache["classes"]:
+                return {"error": f"Class {class_name} not found"}
+
+            return self.state.codebase_cache["classes"][class_name]
+
+
+# Module-level component instance
+_component = CodebaseComponent()
+
+
+def get_component() -> CodebaseComponent:
+    """
+    Get the codebase component instance.
 
-        return _codebase_cache["classes"][class_name]
+    Returns
+    -------
+    CodebaseComponent
+        The codebase component instance
+    """
+    return _component

napistu/mcp/component_base.py

@@ -0,0 +1,170 @@
+"""
+Base classes for MCP server components.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any
+import logging
+
+from fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+
+class ComponentState(ABC):
+    """
+    Base class for component state management.
+
+    Provides standard interface for health checking and initialization tracking.
+    """
+
+    def __init__(self):
+        self.initialized = False
+        self.initialization_error = None
+
+    @abstractmethod
+    def is_healthy(self) -> bool:
+        """
+        Check if component has successfully loaded data and is functioning.
+
+        Returns
+        -------
+        bool
+            True if component is healthy (has data and no errors)
+        """
+        pass
+
+    def is_available(self) -> bool:
+        """
+        Check if component is available (initialized without critical errors).
+
+        Returns
+        -------
+        bool
+            True if component initialized successfully, regardless of data status
+        """
+        return self.initialized and self.initialization_error is None
+
+    def get_health_status(self) -> Dict[str, Any]:
+        """
+        Get standardized health status for health checks.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Health status dictionary with standard format:
+            - status: 'initializing', 'unavailable', 'inactive', or 'healthy'
+            - error: error message if unavailable
+            - additional component-specific details if healthy
+        """
+        if not self.initialized:
+            return {"status": "initializing"}
+        elif self.initialization_error:
+            return {"status": "unavailable", "error": str(self.initialization_error)}
+        elif not self.is_healthy():
+            return {"status": "inactive"}
+        else:
+            return {"status": "healthy", **self.get_health_details()}
+
+    def get_health_details(self) -> Dict[str, Any]:
+        """
+        Get component-specific health details.
+
+        Override in subclasses to provide additional health information.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Component-specific health details
+        """
+        return {}
+
+
+class MCPComponent(ABC):
+    """
+    Base class for MCP server components.
+
+    Provides standard interface for initialization and registration.
+    """
+
+    def __init__(self):
+        self.state = self._create_state()
+
+    @abstractmethod
+    def _create_state(self) -> ComponentState:
+        """
+        Create the component state object.
+
+        Returns
+        -------
+        ComponentState
+            Component-specific state instance
+        """
+        pass
+
+    @abstractmethod
+    async def initialize(self) -> bool:
+        """
+        Initialize the component asynchronously.
+
+        Should populate component state and handle any external data loading.
+
+        Returns
+        -------
+        bool
+            True if initialization successful
+        """
+        pass
+
+    @abstractmethod
+    def register(self, mcp: FastMCP) -> None:
+        """
+        Register component resources and tools with the MCP server.
+
+        Parameters
+        ----------
+        mcp : FastMCP
+            FastMCP server instance to register with
+        """
+        pass
+
+    def get_state(self) -> ComponentState:
+        """
+        Get the component state for health checks and testing.
+
+        Returns
+        -------
+        ComponentState
+            Current component state
+        """
+        return self.state
+
+    async def safe_initialize(self) -> bool:
+        """
+        Initialize with error handling and state tracking.
+
+        Returns
+        -------
+        bool
+            True if initialization successful
+        """
+        try:
+            logger.info(f"Initializing {self.__class__.__name__}...")
+
+            result = await self.initialize()
+
+            self.state.initialized = True
+            self.state.initialization_error = None
+
+            if result:
+                logger.info(f"✅ {self.__class__.__name__} initialized successfully")
+            else:
+                logger.warning(f"⚠️ {self.__class__.__name__} initialized with issues")
+
+            return result
+
+        except Exception as e:
+            logger.error(f"❌ {self.__class__.__name__} failed to initialize: {e}")
+            self.state.initialized = True
+            self.state.initialization_error = e
+            return False