napistu 0.2.4.dev4__tar.gz → 0.2.5__tar.gz

{napistu-0.2.4.dev4 → napistu-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napistu
-Version: 0.2.4.dev4
+Version: 0.2.5
 Summary: Connecting high-dimensional data to curated pathways
 Home-page: https://github.com/napistu/napistu-py
 Author: Sean Hackett

{napistu-0.2.4.dev4 → napistu-0.2.5}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = napistu
-version = 0.2.4.dev4
+version = 0.2.5
 description = Connecting high-dimensional data to curated pathways
 long_description = file: README.md
 long_description_content_type = text/markdown

napistu-0.2.5/src/napistu/mcp/__main__.py

@@ -0,0 +1,205 @@
+# src/napistu/mcp/__main__.py
+"""
+MCP (Model Context Protocol) Server CLI for Napistu.
+"""
+
+import asyncio
+import click
+import click_logging
+import logging
+
+import napistu
+from napistu.mcp.server import start_mcp_server
+from napistu.mcp.client import (
+    check_server_health,
+    print_health_status,
+    list_server_resources,
+    read_server_resource,
+)
+
+logger = logging.getLogger(napistu.__name__)
+click_logging.basic_config(logger)
+
+
+@click.group()
+def cli():
+    """The Napistu MCP (Model Context Protocol) Server CLI"""
+    pass
+
+
+@click.group()
+def server():
+    """Start and manage MCP servers."""
+    pass
+
+
+@server.command(name="start")
+@click.option(
+    "--profile", type=click.Choice(["local", "remote", "full"]), default="remote"
+)
+@click.option("--host", type=str, default="127.0.0.1")
+@click.option("--port", type=int, default=8765)
+@click.option("--server-name", type=str)
+@click_logging.simple_verbosity_option(logger)
+def start_server(profile, host, port, server_name):
+    """Start an MCP server with the specified profile."""
+    start_mcp_server(profile, host, port, server_name)
+
+
+@server.command(name="local")
+@click.option("--server-name", type=str, default="napistu-local")
+@click_logging.simple_verbosity_option(logger)
+def start_local(server_name):
+    """Start a local MCP server optimized for function execution."""
+    start_mcp_server("local", "127.0.0.1", 8765, server_name)
+
+
+@server.command(name="full")
+@click.option("--server-name", type=str, default="napistu-full")
+@click_logging.simple_verbosity_option(logger)
+def start_full(server_name):
+    """Start a full MCP server with all components enabled (local debugging)."""
+    start_mcp_server("full", "127.0.0.1", 8765, server_name)
+
+
+@cli.command()
+@click.option("--url", default="http://127.0.0.1:8765", help="Server URL")
+@click_logging.simple_verbosity_option(logger)
+def health(url):
+    """Quick health check of MCP server."""
+
+    async def run_health_check():
+        print("🏥 Napistu MCP Server Health Check")
+        print("=" * 40)
+        print(f"Server URL: {url}")
+        print()
+
+        health = await check_server_health(server_url=url)
+        print_health_status(health)
+
+    asyncio.run(run_health_check())
+
+
+@cli.command()
+@click.option("--url", default="http://127.0.0.1:8765", help="Server URL")
+@click_logging.simple_verbosity_option(logger)
+def resources(url):
+    """List all available resources on the MCP server."""
+
+    async def run_list_resources():
+        print("📋 Napistu MCP Server Resources")
+        print("=" * 40)
+        print(f"Server URL: {url}")
+        print()
+
+        resources = await list_server_resources(server_url=url)
+
+        if resources:
+            print(f"Found {len(resources)} resources:")
+            for resource in resources:
+                print(f"  📄 {resource.uri}")
+                if resource.name != resource.uri:
+                    print(f"      Name: {resource.name}")
+                if hasattr(resource, "description") and resource.description:
+                    print(f"      Description: {resource.description}")
+                print()
+        else:
+            print("❌ Could not retrieve resources")
+
+    asyncio.run(run_list_resources())
+
+
+@cli.command()
+@click.argument("resource_uri")
+@click.option("--url", default="http://127.0.0.1:8765", help="Server URL")
+@click.option(
+    "--output", type=click.File("w"), default="-", help="Output file (default: stdout)"
+)
+@click_logging.simple_verbosity_option(logger)
+def read(resource_uri, url, output):
+    """Read a specific resource from the MCP server."""
+
+    async def run_read_resource():
+        print(
+            f"📖 Reading Resource: {resource_uri}",
+            file=output if output.name != "<stdout>" else None,
+        )
+        print(f"Server URL: {url}", file=output if output.name != "<stdout>" else None)
+        print("=" * 50, file=output if output.name != "<stdout>" else None)
+
+        content = await read_server_resource(resource_uri, server_url=url)
+
+        if content:
+            print(content, file=output)
+        else:
+            print(
+                "❌ Could not read resource",
+                file=output if output.name != "<stdout>" else None,
+            )
+
+    asyncio.run(run_read_resource())
+
+
+@cli.command()
+@click.option("--local-url", default="http://127.0.0.1:8765", help="Local server URL")
+@click.option("--remote-url", required=True, help="Remote server URL")
+@click_logging.simple_verbosity_option(logger)
+def compare(local_url, remote_url):
+    """Compare health between local and remote servers."""
+
+    async def run_comparison():
+        print("🔍 Local vs Remote Server Comparison")
+        print("=" * 50)
+
+        print(f"\n📍 Local Server: {local_url}")
+        local_health = await check_server_health(server_url=local_url)
+        print_health_status(local_health)
+
+        print(f"\n🌐 Remote Server: {remote_url}")
+        remote_health = await check_server_health(server_url=remote_url)
+        print_health_status(remote_health)
+
+        # Compare results
+        print("\n📊 Comparison Summary:")
+        if local_health and remote_health:
+            local_components = local_health.get("components", {})
+            remote_components = remote_health.get("components", {})
+
+            all_components = set(local_components.keys()) | set(
+                remote_components.keys()
+            )
+
+            for component in sorted(all_components):
+                local_status = local_components.get(component, {}).get(
+                    "status", "missing"
+                )
+                remote_status = remote_components.get(component, {}).get(
+                    "status", "missing"
+                )
+
+                if local_status == remote_status == "healthy":
+                    icon = "✅"
+                elif local_status != remote_status:
+                    icon = "⚠️ "
+                else:
+                    icon = "❌"
+
+                print(
+                    f"  {icon} {component}: Local={local_status}, Remote={remote_status}"
+                )
+        else:
+            print("  ❌ Cannot compare - one or both servers unreachable")
+
+    asyncio.run(run_comparison())
+
+
+# Add commands to the CLI
+cli.add_command(server)
+cli.add_command(health)
+cli.add_command(resources)
+cli.add_command(read)
+cli.add_command(compare)
+
+
+if __name__ == "__main__":
+    cli()

napistu-0.2.5/src/napistu/mcp/client.py

@@ -0,0 +1,207 @@
+# src/napistu/mcp/client.py
+"""
+MCP client for testing and interacting with Napistu MCP servers.
+"""
+
+import json
+import logging
+from typing import Optional, Dict, Any, Mapping
+
+from fastmcp import Client
+
+logger = logging.getLogger(__name__)
+
+
+async def check_server_health(
+    server_url: str = "http://127.0.0.1:8765",
+) -> Optional[Dict[str, Any]]:
+    """
+    Health check using FastMCP client.
+
+    Parameters
+    ----------
+    server_url : str, optional
+        Server URL for HTTP transport. Defaults to 'http://127.0.0.1:8765'.
+
+    Returns
+    -------
+    Optional[Dict[str, Any]]
+        Dictionary containing health status information if successful, None if failed.
+        The dictionary contains:
+            - status : str
+                Overall server status ('healthy', 'degraded', or 'unhealthy')
+            - timestamp : str
+                ISO format timestamp of the health check
+            - version : str
+                Version of the Napistu package
+            - components : Dict[str, Dict[str, str]]
+                Status of each component ('healthy', 'inactive', or 'unavailable')
+    """
+
+    try:
+        # FastMCP streamable-http requires the /mcp path
+        mcp_url = server_url.rstrip("/") + "/mcp"
+        logger.info(f"Connecting to MCP server at: {mcp_url}")
+
+        client = Client(mcp_url)
+
+        async with client:
+            logger.info("✅ FastMCP client connected")
+
+            # List all available resources
+            resources = await client.list_resources()
+            logger.info(f"Found {len(resources)} resources")
+
+            # Find health resource
+            health_resource = None
+            for resource in resources:
+                uri_str = str(resource.uri).lower()
+                if "health" in uri_str:
+                    health_resource = resource
+                    logger.info(f"Found health resource: {resource.uri}")
+                    break
+
+            if not health_resource:
+                logger.error("No health resource found")
+                logger.info(f"Available resources: {[str(r.uri) for r in resources]}")
+                return None
+
+            # Read the health resource
+            logger.info(f"Reading health resource: {health_resource.uri}")
+            result = await client.read_resource(str(health_resource.uri))
+
+            if result and len(result) > 0 and hasattr(result[0], "text"):
+                try:
+                    health_data = json.loads(result[0].text)
+                    logger.info("✅ Health check successful")
+                    return health_data
+                except json.JSONDecodeError as e:
+                    logger.error(f"Failed to parse health JSON: {e}")
+                    logger.error(f"Raw response: {result[0].text}")
+                    return None
+            else:
+                logger.error(f"No valid response from health resource: {result}")
+                return None
+
+    except Exception as e:
+        logger.error(f"Health check failed: {str(e)}")
+        if hasattr(e, "__traceback__"):
+            import traceback
+
+            logger.error("Traceback:\n" + "".join(traceback.format_tb(e.__traceback__)))
+        return None
+
+
+def print_health_status(health: Optional[Mapping[str, Any]]) -> None:
+    """
+    Pretty print health status information.
+
+    Parameters
+    ----------
+    health : Optional[Mapping[str, Any]]
+        Health status dictionary from check_server_health, or None if health check failed.
+        Expected to contain:
+            - status : str
+                Overall server status
+            - components : Dict[str, Dict[str, str]]
+                Status of each component
+            - timestamp : str, optional
+                ISO format timestamp
+            - version : str, optional
+                Package version
+
+    Returns
+    -------
+    None
+        Prints health status information to stdout.
+    """
+    if not health:
+        print("❌ Could not get health status")
+        print("Check the logs above for detailed error information")
+        return
+
+    status = health.get("status", "unknown")
+    print(f"\nServer Status: {status}")
+
+    components = health.get("components", {})
+    if components:
+        print("\nComponents:")
+        for name, comp_status in components.items():
+            icon = "✅" if comp_status.get("status") == "healthy" else "❌"
+            print(f"  {icon} {name}: {comp_status.get('status', 'unknown')}")
+
+    # Show additional info if available
+    if "timestamp" in health:
+        print(f"\nTimestamp: {health['timestamp']}")
+    if "version" in health:
+        print(f"Version: {health['version']}")
+
+
+async def list_server_resources(
+    server_url: str = "http://127.0.0.1:8765",
+) -> Optional[list]:
+    """
+    List all available resources on the MCP server.
+
+    Parameters
+    ----------
+    server_url : str, optional
+        Server URL for HTTP transport. Defaults to 'http://127.0.0.1:8765'.
+
+    Returns
+    -------
+    Optional[list]
+        List of available resources, or None if failed.
+    """
+    try:
+        mcp_url = server_url.rstrip("/") + "/mcp"
+        logger.info(f"Listing resources from: {mcp_url}")
+
+        client = Client(mcp_url)
+
+        async with client:
+            resources = await client.list_resources()
+            logger.info(f"Found {len(resources)} resources")
+            return resources
+
+    except Exception as e:
+        logger.error(f"Failed to list resources: {str(e)}")
+        return None
+
+
+async def read_server_resource(
+    resource_uri: str, server_url: str = "http://127.0.0.1:8765"
+) -> Optional[str]:
+    """
+    Read a specific resource from the MCP server.
+
+    Parameters
+    ----------
+    resource_uri : str
+        URI of the resource to read (e.g., 'napistu://health')
+    server_url : str, optional
+        Server URL for HTTP transport. Defaults to 'http://127.0.0.1:8765'.
+
+    Returns
+    -------
+    Optional[str]
+        Resource content as text, or None if failed.
+    """
+    try:
+        mcp_url = server_url.rstrip("/") + "/mcp"
+        logger.info(f"Reading resource {resource_uri} from: {mcp_url}")
+
+        client = Client(mcp_url)
+
+        async with client:
+            result = await client.read_resource(resource_uri)
+
+            if result and len(result) > 0 and hasattr(result[0], "text"):
+                return result[0].text
+            else:
+                logger.error(f"No content found for resource: {resource_uri}")
+                return None
+
+    except Exception as e:
+        logger.error(f"Failed to read resource {resource_uri}: {str(e)}")
+        return None

napistu-0.2.5/src/napistu/mcp/health.py

@@ -0,0 +1,247 @@
+# src/napistu/mcp/health.py
+"""
+Health check endpoint for the MCP server when deployed to Cloud Run.
+"""
+
+import logging
+from typing import Dict, Any, TypeVar
+from datetime import datetime
+from fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+# Type variable for the FastMCP decorator return type
+T = TypeVar("T")
+
+# Global cache for component health status
+_health_cache = {"status": "initializing", "components": {}, "last_check": None}
+
+
+def register_components(mcp: FastMCP) -> None:
+    """
+    Register health check components with the MCP server.
+
+    Parameters
+    ----------
+    mcp : FastMCP
+        FastMCP server instance to register the health endpoint with.
+    """
+
+    @mcp.resource("napistu://health")
+    async def health_check() -> Dict[str, Any]:
+        """
+        Health check endpoint for deployment monitoring.
+        Returns current cached health status.
+        """
+        return _health_cache
+
+    @mcp.tool("napistu://health/check")
+    async def check_current_health() -> Dict[str, Any]:
+        """
+        Tool to actively check current component health.
+        This performs real-time checks and updates the cached status.
+        """
+        global _health_cache
+        try:
+            health_status = {
+                "status": "healthy",
+                "timestamp": datetime.utcnow().isoformat(),
+                "version": _get_version(),
+                "components": await _check_components(),
+            }
+
+            # Check if any components failed
+            failed_components = [
+                name
+                for name, status in health_status["components"].items()
+                if status["status"] == "unavailable"
+            ]
+
+            if failed_components:
+                health_status["status"] = "degraded"
+                health_status["failed_components"] = failed_components
+
+            # Update the global cache with latest status
+            health_status["last_check"] = datetime.utcnow().isoformat()
+            _health_cache.update(health_status)
+            logger.info(f"Updated health cache - Status: {health_status['status']}")
+
+            return health_status
+
+        except Exception as e:
+            logger.error(f"Health check failed: {e}")
+            error_status = {
+                "status": "unhealthy",
+                "error": str(e),
+                "timestamp": datetime.utcnow().isoformat(),
+                "last_check": datetime.utcnow().isoformat(),
+            }
+            # Update cache even on error
+            _health_cache.update(error_status)
+            return error_status
+
+
+async def initialize_components() -> bool:
+    """
+    Initialize health check components.
+    Performs initial health check and caches the result.
+
+    Returns
+    -------
+    bool
+        True if initialization is successful
+    """
+    global _health_cache
+
+    logger.info("Initializing health check components...")
+
+    try:
+        # Check initial component health
+        component_status = await _check_components()
+
+        # Update cache
+        _health_cache.update(
+            {
+                "status": "healthy",
+                "components": component_status,
+                "timestamp": datetime.utcnow().isoformat(),
+                "version": _get_version(),
+                "last_check": datetime.utcnow().isoformat(),
+            }
+        )
+
+        # Check for failed components
+        failed_components = [
+            name
+            for name, status in component_status.items()
+            if status["status"] == "unavailable"
+        ]
+
+        if failed_components:
+            _health_cache["status"] = "degraded"
+            _health_cache["failed_components"] = failed_components
+
+        logger.info(f"Health check initialization complete: {_health_cache['status']}")
+        return True
+
+    except Exception as e:
+        logger.error(f"Health check initialization failed: {e}")
+        _health_cache["status"] = "unhealthy"
+        _health_cache["error"] = str(e)
+        return False
+
+
+def _check_component_health(
+    component_name: str, module_name: str, cache_attr: str
+) -> Dict[str, str]:
+    """
+    Check the health of a single MCP component by verifying its cache is initialized and contains data.
+
+    Parameters
+    ----------
+    component_name : str
+        Name of the component (for importing)
+    module_name : str
+        Full module path for importing
+    cache_attr : str
+        Name of the cache/context attribute to check
+
+    Returns
+    -------
+    Dict[str, str]
+        Dictionary containing component health status:
+            - status : str
+                One of: 'healthy', 'inactive', or 'unavailable'
+            - error : str, optional
+                Error message if status is 'unavailable'
+    """
+    try:
+        module = __import__(module_name, fromlist=[component_name])
+        cache = getattr(module, cache_attr, None)
+        logger.info(
+            f"Checking {component_name} health - Cache exists: {cache is not None}"
+        )
+
+        # Component specific checks for actual data
+        if cache:
+            if component_name == "documentation":
+                # Check if any documentation section has content
+                has_data = any(bool(section) for section in cache.values())
+                logger.info(f"Documentation sections: {list(cache.keys())}")
+            elif component_name == "codebase":
+                # Check if any codebase section has content
+                has_data = any(bool(section) for section in cache.values())
+                logger.info(f"Codebase sections: {list(cache.keys())}")
+            elif component_name == "tutorials":
+                # Check if tutorials section has content
+                has_data = bool(cache.get("tutorials", {}))
+                logger.info(f"Tutorials cache: {bool(cache.get('tutorials', {}))}")
+            elif component_name == "execution":
+                # Check if session context has more than just napistu module
+                has_data = len(cache) > 0
+                logger.info(f"Execution context: {list(cache.keys())}")
+            else:
+                has_data = bool(cache)
+
+            if has_data:
+                logger.info(f"{component_name} is healthy")
+                return {"status": "healthy"}
+
+        logger.info(f"{component_name} is inactive")
+        return {"status": "inactive"}
+    except Exception as e:
+        logger.error(f"{component_name} check failed: {str(e)}")
+        return {"status": "unavailable", "error": str(e)}
+
+
+async def _check_components() -> Dict[str, Dict[str, Any]]:
+    """
+    Check the health of individual MCP components by verifying their caches.
+
+    Returns
+    -------
+    Dict[str, Dict[str, Any]]
+        Dictionary mapping component names to their health status:
+            - {component_name} : Dict[str, str]
+                Health status for each component, containing:
+                    - status : str
+                        One of: 'healthy', 'inactive', or 'unavailable'
+                    - error : str, optional
+                        Error message if status is 'unavailable'
+    """
+    # Define component configurations - cache vars that indicate initialization
+    component_configs = {
+        "documentation": ("napistu.mcp.documentation", "_docs_cache"),
+        "codebase": ("napistu.mcp.codebase", "_codebase_cache"),
+        "tutorials": ("napistu.mcp.tutorials", "_tutorial_cache"),
+        "execution": ("napistu.mcp.execution", "_session_context"),
+    }
+
+    logger.info("Starting component health checks...")
+    logger.info(f"Checking components: {list(component_configs.keys())}")
+
+    # Check each component's cache
+    results = {
+        name: _check_component_health(name, module_path, cache_attr)
+        for name, (module_path, cache_attr) in component_configs.items()
+    }
+
+    logger.info(f"Health check results: {results}")
+    return results
+
+
+def _get_version() -> str:
+    """
+    Get the Napistu version.
+
+    Returns
+    -------
+    str
+        Version string of the Napistu package, or 'unknown' if not available.
+    """
+    try:
+        import napistu
+
+        return getattr(napistu, "__version__", "unknown")
+    except ImportError:
+        return "unknown"