chuk-mcp-runtime 0.1.0__py3-none-any.whl

chuk_mcp_runtime/__init__.py

@@ -0,0 +1,11 @@
+# chuk_mcp_runtime/__init__.py
+"""
+CHUK MCP Runtime Package
+
+This package provides a runtime for CHUK MCP (Messaging Control Protocol) servers.
+"""
+
+__version__ = "0.1.0"
+
+# Import main functions for convenience
+from chuk_mcp_runtime.main import run_server, main

chuk_mcp_runtime/common/errors.py

@@ -0,0 +1,32 @@
+# chuk_mcp_runtime/common/errors.py
+"""
+Error classes for the CHUK MCP runtime.
+
+This module defines standard error classes used across the CHUK MCP runtime.
+"""
+
+class ChukMcpRuntimeError(Exception):
+    """Base exception class for all CHUK MCP runtime errors."""
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+class ConfigurationError(ChukMcpRuntimeError):
+    """Exception raised for configuration errors."""
+    pass
+
+class ImportError(ChukMcpRuntimeError):
+    """Exception raised for errors during module importing."""
+    pass
+
+class ToolExecutionError(ChukMcpRuntimeError):
+    """Exception raised for errors during tool execution."""
+    pass
+
+class ServerError(ChukMcpRuntimeError):
+    """Exception raised for server errors."""
+    pass
+
+class ValidationError(ChukMcpRuntimeError):
+    """Exception raised for validation errors."""
+    pass

chuk_mcp_runtime/common/mcp_tool_decorator.py

@@ -0,0 +1,186 @@
+# chuk_mcp_runtime/common/mcp_tool_decorator.py
+"""
+CHUK MCP Tool Decorator Module
+
+This module provides decorators for registering functions as CHUK MCP tools
+with automatic input schema generation based on function signatures.
+"""
+import inspect
+from functools import wraps
+from typing import Dict, Any, Callable, Optional, Type, get_type_hints
+import logging
+
+# We'll try to import pydantic, but provide fallbacks if it's not available
+try:
+    from pydantic import create_model
+    HAS_PYDANTIC = True
+except ImportError:
+    HAS_PYDANTIC = False
+    logging.getLogger("chuk_mcp_runtime.tools").warning(
+        "Pydantic not available, using fallback schema generation"
+    )
+
+# Import MCP types, with fallback if not available
+try:
+    from mcp.types import Tool
+    HAS_MCP_TYPES = True
+except ImportError:
+    HAS_MCP_TYPES = False
+    logging.getLogger("chuk_mcp_runtime.tools").warning(
+        "MCP types not available, using fallback Tool class"
+    )
+    
+    # Fallback Tool class for when MCP types are not available
+    class Tool:
+        def __init__(self, name: str, description: str, inputSchema: Dict[str, Any]):
+            self.name = name
+            self.description = description
+            self.inputSchema = inputSchema
+
+# Global registry for MCP tool functions
+TOOLS_REGISTRY = {}
+
+def _get_type_schema(annotation: Type) -> Dict[str, Any]:
+    """
+    Convert a Python type annotation to a JSON Schema type.
+    
+    Args:
+        annotation: Type annotation to convert.
+        
+    Returns:
+        JSON Schema representation of the type.
+    """
+    # Map Python types to JSON Schema types
+    if annotation == str:
+        return {"type": "string"}
+    elif annotation == int:
+        return {"type": "integer"}
+    elif annotation == float:
+        return {"type": "number"}
+    elif annotation == bool:
+        return {"type": "boolean"}
+    elif annotation == list or getattr(annotation, "__origin__", None) == list:
+        # Handle List[...] type
+        return {"type": "array"}
+    elif annotation == dict or getattr(annotation, "__origin__", None) == dict:
+        # Handle Dict[...] type
+        return {"type": "object"}
+    # Add more type mappings as needed
+    return {"type": "string"}  # Default to string
+
+def create_input_schema(func: Callable) -> Dict[str, Any]:
+    """
+    Create a JSON Schema for the function's parameters.
+    
+    Args:
+        func: The function to create a schema for.
+        
+    Returns:
+        A JSON Schema object representing the function's parameters.
+    """
+    sig = inspect.signature(func)
+    
+    if HAS_PYDANTIC:
+        # Use Pydantic for schema generation if available
+        fields = {}
+        for param in sig.parameters.values():
+            annotation = param.annotation if param.annotation != inspect.Parameter.empty else str
+            fields[param.name] = (annotation, ...)
+        
+        InputModel = create_model(f"{func.__name__.capitalize()}Input", **fields)
+        return InputModel.model_json_schema()
+    else:
+        # Fallback schema generation without Pydantic
+        properties = {}
+        required = []
+        
+        type_hints = get_type_hints(func)
+        
+        for param in sig.parameters.values():
+            if param.name == 'self':
+                continue
+                
+            # Get type annotation if available
+            annotation = type_hints.get(param.name, str)
+            
+            # Add to properties
+            properties[param.name] = _get_type_schema(annotation)
+            
+            # Add required if no default value
+            if param.default == inspect.Parameter.empty:
+                required.append(param.name)
+        
+        return {
+            "type": "object",
+            "properties": properties,
+            "required": required
+        }
+
+def mcp_tool(name: str = None, description: str = None):
+    """
+    Decorator to register an MCP tool function and auto-generate its input JSON schema.
+    
+    Args:
+        name: Name of the tool. If None, uses the function name.
+        description: Description of the tool. If None, uses the function's docstring.
+    
+    Returns:
+        Decorated function with _mcp_tool attribute.
+    """
+    def decorator(func):
+        # Use function name if name not provided
+        tool_name = name or func.__name__
+        
+        # Use docstring if description not provided
+        tool_description = description
+        if tool_description is None and func.__doc__:
+            tool_description = func.__doc__.strip()
+        elif tool_description is None:
+            tool_description = f"Tool: {tool_name}"
+        
+        # Create input schema based on function signature
+        input_schema = create_input_schema(func)
+        
+        # Create Tool instance
+        tool = Tool(
+            name=tool_name,
+            description=tool_description,
+            inputSchema=input_schema
+        )
+        
+        # Register the function in the global registry.
+        TOOLS_REGISTRY[tool_name] = func
+        
+        # Attach the tool metadata to the function for introspection.
+        func._mcp_tool = tool
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+def register_tools_from_module(module):
+    """
+    Scan a module for functions decorated with @mcp_tool and register them.
+    
+    Args:
+        module: The module to scan for tools.
+        
+    Returns:
+        Dictionary of registered tools from the module.
+    """
+    module_tools = {}
+    
+    for name in dir(module):
+        item = getattr(module, name)
+        if callable(item) and hasattr(item, '_mcp_tool'):
+            tool_name = item._mcp_tool.name
+            TOOLS_REGISTRY[tool_name] = item
+            module_tools[tool_name] = item
+            
+    return module_tools
+
+def clear_tools_registry():
+    """Clear the global tools registry."""
+    TOOLS_REGISTRY.clear()

chuk_mcp_runtime/main.py

@@ -0,0 +1,76 @@
+# chuk_mcp_runtime/main.py
+import os
+import sys
+import asyncio
+from typing import Dict, Any, Optional, List
+
+from chuk_mcp_runtime.server.config_loader import load_config, find_project_root
+from chuk_mcp_runtime.server.logging_config import get_logger, configure_logging
+from chuk_mcp_runtime.server.server_registry import ServerRegistry
+from chuk_mcp_runtime.server.server import MCPServer
+from chuk_mcp_runtime.common.errors import ChukMcpRuntimeError
+
+async def run_server(config_paths: Optional[List[str]] = None, 
+                    default_config: Optional[Dict[str, Any]] = None) -> None:
+    """
+    Initialize and run an MCP server with the given configuration.
+    
+    Args:
+        config_paths: List of paths to search for configuration files.
+        default_config: Default configuration to use if no config file is found.
+        
+    Raises:
+        ConfigurationError: If there is an error in the configuration.
+    """
+    try:
+        # Load configuration
+        config = load_config(config_paths, default_config)
+        
+        # Configure logging
+        configure_logging(config)
+        logger = get_logger("chuk_mcp_runtime")
+        
+        # Find project root
+        project_root = find_project_root()
+        
+        # Initialize server registry
+        logger.info("Initializing server registry")
+        server_registry = ServerRegistry(project_root, config)
+        
+        # Load server components
+        logger.info("Loading server components")
+        loaded_modules = server_registry.load_server_components()
+        
+        # Initialize MCP server
+        logger.info("Initializing MCP server")
+        mcp_server = MCPServer(config)
+        
+        # Run server
+        logger.info("Starting MCP server")
+        await mcp_server.serve()
+        
+    except Exception as e:
+        logger = get_logger("chuk_mcp_runtime")
+        logger.error(f"Error starting CHUK MCP server: {e}", exc_info=True)
+        raise ChukMcpRuntimeError(f"Error starting CHUK MCP server: {e}")
+
+def main():
+    """
+    Entry point for the MCP runtime command-line script.
+    """
+    try:
+        # Get configuration path from environment or command line
+        config_path = os.environ.get("CHUK_MCP_CONFIG_PATH")
+        if len(sys.argv) > 1:
+            config_path = sys.argv[1]
+            
+        config_paths = [config_path] if config_path else None
+        
+        # Run the server
+        asyncio.run(run_server(config_paths))
+    except Exception as e:
+        print(f"Error starting CHUK MCP server: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

chuk_mcp_runtime/server/config_loader.py

@@ -0,0 +1,132 @@
+# chuk_mcp_runtime/server/config_loader.py
+"""
+Configuration Loader Module
+
+This module provides functionality to load and manage 
+configuration files for CHUK MCP servers from multiple potential locations.
+"""
+import os
+import yaml
+import logging
+from typing import Dict, Any, List, Optional
+
+# logger
+logger = logging.getLogger("chuk_mcp_runtime.config")
+
+def load_config(config_paths: Optional[List[str]] = None, 
+                default_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """
+    Load server configuration from config files.
+    
+    Args:
+        config_paths: List of paths to search for config files. If None, uses default search paths.
+        default_config: Default configuration to use if no config file is found.
+    
+    Returns:
+        A dictionary containing the configuration settings.
+    """
+    if config_paths is None:
+        # Default search paths relative to current working directory
+        config_paths = [
+            os.path.join(os.getcwd(), "config.yaml"),
+            os.path.join(os.getcwd(), "config.yml"),
+            os.environ.get("CHUK_MCP_CONFIG_PATH", ""),
+        ]
+        
+        # Add config in package directory if run from package
+        package_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        config_paths.append(os.path.join(package_dir, "config.yaml"))
+    
+    # Filter out empty paths
+    config_paths = [p for p in config_paths if p]
+    
+    # Try to load from each path
+    for path in config_paths:
+        if os.path.exists(path):
+            logger.info(f"Loading configuration from {path}")
+            try:
+                with open(path, 'r') as f:
+                    config = yaml.safe_load(f)
+                    if config is None:  # Empty YAML file
+                        continue
+                    return config
+            except Exception as e:
+                logger.warning(f"Error loading config from {path}: {e}")
+    
+    # Use default configuration if provided or create a minimal one
+    if default_config is None:
+        logger.warning("No configuration file found, using minimal default configuration")
+        default_config = {
+            "host": {
+                "name": "generic-mcp-server", 
+                "log_level": "INFO"
+            },
+            "mcp_servers": {}
+        }
+    else:
+        logger.warning("No configuration file found, using provided default configuration")
+    
+    return default_config
+
+def find_project_root(start_dir: Optional[str] = None) -> str:
+    """
+    Find the project root directory by looking for markers like config.yaml,
+    pyproject.toml, etc.
+    
+    Args:
+        start_dir: Directory to start the search from. If None, uses current directory.
+    
+    Returns:
+        Absolute path to the project root directory.
+    """
+    if start_dir is None:
+        start_dir = os.getcwd()
+    
+    current_dir = os.path.abspath(start_dir)
+    
+    # Markers that indicate a project root
+    markers = ['config.yaml', 'config.yml', 'pyproject.toml', 'setup.py']
+    
+    # Maximum depth to search up
+    max_depth = 10
+    depth = 0
+    
+    while depth < max_depth:
+        # Check if any markers exist in current directory
+        if any(os.path.exists(os.path.join(current_dir, marker)) for marker in markers):
+            return current_dir
+        
+        # Go up one directory
+        parent_dir = os.path.dirname(current_dir)
+        if parent_dir == current_dir:  # Reached the filesystem root
+            break
+        
+        current_dir = parent_dir
+        depth += 1
+    
+    # If no project root found, return the starting directory
+    logger.warning(f"No project root markers found, using {start_dir} as project root")
+    return os.path.abspath(start_dir)
+
+def get_config_value(config: Dict[str, Any], path: str, default: Any = None) -> Any:
+    """
+    Get a value from a nested configuration dictionary using a dot-separated path.
+    
+    Args:
+        config: Configuration dictionary.
+        path: Dot-separated path to the value (e.g., "host.name").
+        default: Default value to return if the path is not found.
+    
+    Returns:
+        The value at the specified path, or the default value if not found.
+    """
+    keys = path.split('.')
+    result = config
+    
+    for key in keys:
+        if isinstance(result, dict) and key in result:
+            result = result[key]
+        else:
+            return default
+    
+    return result

chuk_mcp_runtime/server/logging_config.py

@@ -0,0 +1,86 @@
+# chuk_mcp_runtime/server/logging_config.py
+"""
+Logging configuration module for CHUK MCP servers.
+
+This module sets up a shared logger with configurable logging levels,
+formats, and output handlers based on configuration.
+"""
+import os
+import sys
+import logging
+from logging import Logger
+from typing import Dict, Any, Optional
+
+def configure_logging(config: Dict[str, Any] = None) -> None:
+    """
+    Configure the root logger based on the provided configuration.
+    
+    Args:
+        config: Configuration dictionary containing logging settings.
+    """
+    # Extract logging configuration
+    log_config = config.get("logging", {}) if config else {}
+    
+    # Determine log level from config or environment
+    log_level_name = log_config.get("level", os.getenv("CHUK_MCP_LOG_LEVEL", "INFO"))
+    log_level = getattr(logging, log_level_name.upper(), logging.INFO)
+    
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level)
+    
+    # Clear existing handlers if requested
+    if log_config.get("reset_handlers", False):
+        for handler in root_logger.handlers[:]:
+            root_logger.removeHandler(handler)
+    
+    # Add handlers if none exist
+    if not root_logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        
+        # Set formatter
+        log_format = log_config.get("format", 
+                                  '%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+        formatter = logging.Formatter(log_format)
+        handler.setFormatter(formatter)
+        
+        root_logger.addHandler(handler)
+    
+    # Set library loggers to higher level to reduce noise
+    if log_config.get("quiet_libraries", True):
+        for lib in ["urllib3", "requests", "asyncio"]:
+            logging.getLogger(lib).setLevel(logging.WARNING)
+
+def get_logger(name: str = None, config: Dict[str, Any] = None) -> Logger:
+    """
+    Get a configured logger with the specified name.
+    
+    Args:
+        name: The name of the logger. If None, uses the calling module's name.
+        config: Optional configuration dictionary.
+        
+    Returns:
+        A logger instance.
+    """
+    # If name is None, try to infer from caller's module
+    if name is None:
+        import inspect
+        frame = inspect.currentframe().f_back
+        module = inspect.getmodule(frame)
+        name = module.__name__ if module else "chuk_mcp_runtime"
+    
+    # Ensure our base prefix is in the name
+    if not name.startswith("chuk_mcp_runtime"):
+        name = f"chuk_mcp_runtime.{name}"
+    
+    # Configure global logging if config is provided
+    if config:
+        configure_logging(config)
+    
+    # Get logger
+    logger = logging.getLogger(name)
+    
+    return logger
+
+# Create a default logger for the module
+logger = get_logger("chuk_mcp_runtime.logging")

chuk_mcp_runtime/server/server.py

@@ -0,0 +1,194 @@
+# chuk_mcp_runtime/server/server.py
+"""
+CHUK MCP Server Module
+
+This module provides the core CHUK MCP server functionality for 
+running tools and managing server operations.
+"""
+import asyncio
+import json
+import importlib
+from typing import Dict, Any, List, Optional, Union, Callable
+
+# MCP imports (assuming these are from an external package)
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent, ImageContent, EmbeddedResource
+
+# Local imports
+from chuk_mcp_runtime.server.logging_config import get_logger
+
+class MCPServer:
+    """
+    Manages the MCP (Messaging Control Protocol) server operations.
+    
+    Handles tool discovery, registration, and execution.
+    """
+    def __init__(self, config: Dict[str, Any], tools_registry: Optional[Dict[str, Callable]] = None):
+        """
+        Initialize the MCP server.
+        
+        Args:
+            config: Configuration dictionary for the server.
+            tools_registry: Optional registry of tools to use instead of importing.
+        """
+        self.config = config
+        
+        # Initialize logger
+        self.logger = get_logger("chuk_mcp_runtime.server", config)
+        
+        # Server name from configuration
+        self.server_name = config.get("host", {}).get("name", "generic-mcp")
+        
+        # Tools registry
+        self.tools_registry = tools_registry or self._import_tools_registry()
+    
+    def _import_tools_registry(self) -> Dict[str, Callable]:
+        """
+        Dynamically import the tools registry.
+        
+        Returns:
+            Dictionary of available tools.
+        """
+        # Get registry module path from config
+        registry_module_path = self.config.get("tools", {}).get(
+            "registry_module", "chuk_mcp_runtime.common.mcp_tool_decorator"
+        )
+        registry_attr = self.config.get("tools", {}).get(
+            "registry_attr", "TOOLS_REGISTRY"
+        )
+        
+        try:
+            tools_decorator_module = importlib.import_module(registry_module_path)
+            tools_registry = getattr(tools_decorator_module, registry_attr, {})
+        except (ImportError, AttributeError) as e:
+            self.logger.error(f"Failed to import TOOLS_REGISTRY from {registry_module_path}: {e}")
+            tools_registry = {}
+        
+        if not tools_registry:
+            self.logger.warning("No tools available")
+        else:
+            self.logger.info(f"Loaded {len(tools_registry)} tools")
+            self.logger.debug(f"Available tools: {', '.join(tools_registry.keys())}")
+        
+        return tools_registry
+    
+    async def serve(self, custom_handlers: Optional[Dict[str, Callable]] = None) -> None:
+        """
+        Run the MCP server with stdio communication.
+        
+        Sets up server, tool listing, and tool execution handlers.
+        
+        Args:
+            custom_handlers: Optional dictionary of custom handlers to add to the server.
+        """
+        # Create MCP server instance
+        server = Server(self.server_name)
+
+        @server.list_tools()
+        async def list_tools() -> List[Tool]:
+            """
+            List available tools.
+            
+            Returns:
+                List of tool descriptions.
+            """
+            if not self.tools_registry:
+                self.logger.warning("No tools available")
+                return []
+            
+            tool_list = []
+            for func in self.tools_registry.values():
+                if hasattr(func, '_mcp_tool'):
+                    tool_list.append(func._mcp_tool)
+            
+            return tool_list
+
+        @server.call_tool()
+        async def call_tool(name: str, arguments: Dict[str, Any]) -> List[Union[TextContent, ImageContent, EmbeddedResource]]:
+            """
+            Execute a specific tool with given arguments.
+            
+            Args:
+                name: Name of the tool to execute.
+                arguments: Arguments for the tool.
+            
+            Returns:
+                List of content resulting from tool execution.
+            
+            Raises:
+                ValueError: If tool is not found or fails to execute.
+            """
+            if name not in self.tools_registry:
+                raise ValueError(f"Tool not found: {name}")
+            
+            func = self.tools_registry[name]
+            try:
+                self.logger.info(f"Executing tool '{name}' with arguments: {arguments}")
+                result = func(**arguments)
+                
+                # If result is already a list of content objects, return as is
+                if isinstance(result, list) and all(isinstance(item, (TextContent, ImageContent, EmbeddedResource)) 
+                                                for item in result):
+                    return result
+                
+                # For simple text results, wrap in TextContent
+                if isinstance(result, str):
+                    return [TextContent(type="text", text=result)]
+                
+                # Otherwise, serialize to JSON
+                return [TextContent(type="text", text=json.dumps(result, indent=2))]
+                
+            except Exception as e:
+                self.logger.error(f"Error processing tool '{name}': {e}", exc_info=True)
+                raise ValueError(f"Error processing tool '{name}': {str(e)}")
+        
+        # Add custom handlers if provided
+        if custom_handlers:
+            for handler_name, handler_func in custom_handlers.items():
+                self.logger.info(f"Adding custom handler: {handler_name}")
+                setattr(server, handler_name, handler_func)
+
+        # Create initialization options
+        options = server.create_initialization_options()
+        
+        # Run server based on configuration
+        server_type = self.config.get("server", {}).get("type", "stdio")
+        
+        if server_type == "stdio":
+            self.logger.info("Starting stdio server")
+            async with stdio_server() as (read_stream, write_stream):
+                await server.run(read_stream, write_stream, options)
+        elif server_type == "websocket":
+            # Example for websocket server - replace with actual implementation
+            ws_host = self.config.get("server", {}).get("host", "localhost")
+            ws_port = self.config.get("server", {}).get("port", 8080)
+            self.logger.info(f"Starting WebSocket server on {ws_host}:{ws_port}")
+            # Implement WebSocket server here
+            raise NotImplementedError("WebSocket server not implemented yet")
+        else:
+            raise ValueError(f"Unknown server type: {server_type}")
+
+    def register_tool(self, name: str, func: Callable) -> None:
+        """
+        Register a tool function with the server.
+        
+        Args:
+            name: Name of the tool.
+            func: Function to register.
+        """
+        if not hasattr(func, '_mcp_tool'):
+            self.logger.warning(f"Function {func.__name__} does not have _mcp_tool attribute")
+            return
+            
+        self.tools_registry[name] = func
+        self.logger.info(f"Registered tool: {name}")
+        
+    def get_tool_names(self) -> List[str]:
+        """
+        Get names of all registered tools.
+        
+        Returns:
+            List of tool names.
+        """
+        return list(self.tools_registry.keys())

chuk_mcp_runtime/server/server_registry.py

@@ -0,0 +1,195 @@
+# chuk_mcp_runtime/server/server_registry.py
+"""
+Server Registry Module for CHUK MCP Tool Servers
+
+This module provides a ServerRegistry class for managing 
+CHUK MCP tool servers and their components.
+"""
+
+import os
+import sys
+import importlib
+from typing import List, Dict, Any, Tuple, Optional
+
+from chuk_mcp_runtime.server.logging_config import get_logger
+
+class ServerRegistry:
+    """Registry for managing MCP tool servers with components"""
+    def __init__(self, project_root: str, config: Dict[str, Any]):
+        """
+        Initialize the server registry.
+        
+        Args:
+            project_root: The root directory of the project.
+            config: Configuration dictionary.
+        """
+        self.project_root = project_root
+        self.config = config
+        
+        # Initialize logger
+        self.logger = get_logger("chuk_mcp_runtime.server_registry", config)
+        
+        self.server_paths, self.components = self._setup_server_paths()
+        self._setup_python_paths()
+        self.loaded_modules = {}
+    
+    def _setup_server_paths(self) -> Tuple[Dict[str, str], Dict[str, List[Dict[str, Any]]]]:
+        """
+        Process server configurations and resolve paths.
+        
+        Returns:
+            Tuple of (server_paths, components) dictionaries.
+        """
+        server_paths = {}
+        components = {}
+        
+        # Add core paths
+        core_paths = self.config.get("core", {})
+        for name, location in core_paths.items():
+            full_path = os.path.join(self.project_root, location)
+            # Always add path, even if it doesn't exist
+            server_paths[name] = full_path
+            
+            if not os.path.exists(full_path):
+                self.logger.warning(f"Core path does not exist: {full_path}")
+        
+        # Process MCP servers
+        mcp_servers = self.config.get("mcp_servers", {})
+        for server_name, server_config in mcp_servers.items():
+            if isinstance(server_config, dict) and server_config.get("enabled", True):
+                location = server_config.get("location")
+                if location:
+                    # Handle both absolute and relative paths
+                    if os.path.isabs(location):
+                        full_path = location
+                    else:
+                        full_path = os.path.join(self.project_root, location)
+                    
+                    # Always add server path
+                    server_paths[server_name] = full_path
+                    components[server_name] = []
+                    
+                    # Process components (tools, resources, prompts)
+                    self._add_component(server_name, server_config, "tools", components)
+                    self._add_component(server_name, server_config, "resources", components)
+                    self._add_component(server_name, server_config, "prompts", components)
+                    
+                    if not os.path.exists(full_path):
+                        self.logger.warning(f"MCP server location does not exist: {full_path}")
+        
+        # Auto-discovery for testing
+        if self.config.get("auto_discover", False):
+            self._auto_discover_servers(server_paths, components)
+        
+        core_servers = [name for name in server_paths.keys() if name in core_paths]
+        mcp_servers_list = [name for name in server_paths.keys() if name not in core_paths]
+        
+        self.logger.info(f"Core paths: {', '.join(core_servers) if core_servers else 'None'}")
+        self.logger.info(f"MCP servers: {', '.join(mcp_servers_list) if mcp_servers_list else 'None'}")
+        
+        return server_paths, components
+    
+    def _auto_discover_servers(self, server_paths: Dict[str, str], 
+                              components: Dict[str, List[Dict[str, Any]]]) -> None:
+        """
+        Automatically discover test servers.
+        
+        Args:
+            server_paths: Dictionary to add server paths to.
+            components: Dictionary to add components to.
+        """
+        # Add known test servers
+        test_servers = self.config.get("auto_discover_servers", [
+            "time_server", 
+            "echo_server", 
+            "test_server"
+        ])
+        
+        for server_name in test_servers:
+            if server_name not in server_paths:
+                # Create a mock path
+                mock_path = os.path.join(self.project_root, "servers", server_name, "src")
+                server_paths[server_name] = mock_path
+                components[server_name] = []
+                
+                # Add a mock tools component
+                components[server_name].append({
+                    "type": "tools",
+                    "module": f"{server_name}.tools",
+                    "auto_discovered": True
+                })
+    
+    def _add_component(self, server_name: str, server_config: Dict[str, Any], 
+                       component_type: str, components: Dict[str, List[Dict[str, Any]]]) -> None:
+        """
+        Add a component (tools, resources, prompts) to the components dictionary.
+        
+        Args:
+            server_name: Name of the server.
+            server_config: Configuration for the server.
+            component_type: Type of component (tools, resources, prompts).
+            components: Dictionary to add the component to.
+        """
+        component_config = server_config.get(component_type, {})
+        if not isinstance(component_config, dict):
+            return
+            
+        enabled = component_config.get("enabled", True)
+        module = component_config.get("module")
+        
+        if enabled and module:
+            components[server_name].append({
+                "type": component_type,
+                "module": module,
+                "auto_discovered": False
+            })
+    
+    def _setup_python_paths(self) -> None:
+        """Add server source directories to Python path"""
+        # Add paths to sys.path in reverse order for correct priority
+        paths = list(self.server_paths.values())
+        for path in reversed(paths):
+            if path not in sys.path:
+                self.logger.debug(f"Adding {path} to sys.path")
+                sys.path.insert(0, path)
+    
+    def load_server_components(self) -> Dict[str, Any]:
+        """
+        Load all enabled components from configured servers.
+        
+        Returns:
+            Dictionary of loaded modules.
+        """
+        for server_name, server_components in self.components.items():
+            for component in server_components:
+                module_name = component["module"]
+                component_type = component["type"]
+                auto_discovered = component.get("auto_discovered", False)
+                
+                # Skip if already loaded
+                if module_name in self.loaded_modules:
+                    self.logger.debug(f"Module {module_name} already loaded")
+                    continue
+                
+                # For testing, always try to import the module
+                try:
+                    self.logger.info(f"Loading {component_type} from {module_name}" + 
+                                   (" (auto-discovered)" if auto_discovered else ""))
+                    self.loaded_modules[module_name] = importlib.import_module(module_name)
+                except ImportError as e:
+                    # If it's for testing, we'll catch the import error but not raise it
+                    if auto_discovered:
+                        self.logger.debug(f"Auto-discovered module {module_name} not found: {e}")
+                    else:
+                        self.logger.warning(f"Failed to import {module_name}: {e}")
+        
+        return self.loaded_modules
+        
+    def get_loaded_modules(self) -> Dict[str, Any]:
+        """
+        Get all loaded modules.
+        
+        Returns:
+            Dictionary of loaded modules.
+        """
+        return self.loaded_modules

chuk_mcp_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: chuk-mcp-runtime
+Version: 0.1.0
+Summary: Generic CHUK MCP Runtime for MCP Servers
+Author-email: Chris Hay <your.email@example.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: mcp>=1.6.0
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: websocket
+Requires-Dist: websockets>=10.0; extra == "websocket"
+Provides-Extra: dev
+Dynamic: license-file
+
+# CHUK MCP Runtime
+A generic framework for creating MCP (Messaging Control Protocol) servers that can be installed as a package on any MCP server.
+
+## Features
+
+- Flexible configuration system with YAML support
+- Automatic tool discovery and registration
+- Configurable logging
+- Server registry for managing multiple MCP servers
+- Runtime for hosting MCP tools
+- Easy-to-use tool decorator for registering functions as MCP tools
+
+## Installation
+
+```bash
+# Install from PyPI
+pip install chuk-mcp-runtime
+
+# Install with optional dependencies
+pip install chuk-mcp-runtime[websocket,dev]
+
+# Install from source
+git clone https://github.com/yourusername/chuk-mcp-runtime.git
+cd chuk-mcp-runtime
+pip install -e .
+```
+
+## Quick Start
+
+### 1. Create a configuration file
+
+Create a `config.yaml` file:
+
+```yaml
+host:
+  name: "my-chuk-mcp-server"
+  log_level: "INFO"
+
+server:
+  type: "stdio"
+
+tools:
+  registry_module: "chuk_mcp_runtime.common.mcp_tool_decorator"
+  registry_attr: "TOOLS_REGISTRY"
+
+mcp_servers:
+  my_server:
+    location: "./my_server"
+    enabled: true
+    tools:
+      module: "my_server.tools"
+      enabled: true
+```
+
+### 2. Create a tools module
+
+Create a file `my_server/tools.py`:
+
+```python
+from chuk_mcp_runtime.common.mcp_tool_decorator import mcp_tool
+
+@mcp_tool(name="greet", description="Generate a greeting")
+def greet(name: str, formal: bool = False) -> str:
+    """
+    Generate a greeting message.
+    
+    Args:
+        name: Name to greet.
+        formal: Whether to use a formal greeting.
+        
+    Returns:
+        Greeting message.
+    """
+    if formal:
+        return f"Good day, {name}. It is a pleasure to meet you."
+    else:
+        return f"Hey {name}! How's it going?"
+```
+
+### 3. Run the server
+
+You can run the server in several ways:
+
+```bash
+# Using the command-line entry point
+chuk-mcp-server
+
+# Using the Python module
+python -m chuk_mcp_runtime
+
+# With a specific config file
+CHUK_MCP_CONFIG_PATH=./my_config.yaml chuk-mcp-server
+```
+
+## Creating a Custom MCP Server
+
+### Basic Server
+
+```python
+import asyncio
+from chuk_mcp_runtime.server.server import MCPServer
+from chuk_mcp_runtime.server.config_loader import load_config
+from chuk_mcp_runtime.common.mcp_tool_decorator import mcp_tool
+
+# Define tools
+@mcp_tool(name="example", description="Example tool")
+def example_tool(param: str) -> dict:
+    return {"result": f"Processed: {param}"}
+
+async def main():
+    # Load config
+    config = load_config()
+    
+    # Create tools registry
+    tools_registry = {"example": example_tool}
+    
+    # Create and run server
+    server = MCPServer(config, tools_registry=tools_registry)
+    await server.serve()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Using Server Registry
+
+For more complex setups with multiple server components:
+
+```python
+import asyncio
+from chuk_mcp_runtime.server.config_loader import load_config, find_project_root
+from chuk_mcp_runtime.server.server_registry import ServerRegistry
+from chuk_mcp_runtime.server.server import MCPServer
+
+async def main():
+    # Load config
+    config = load_config()
+    
+    # Find project root
+    project_root = find_project_root()
+    
+    # Initialize server registry
+    server_registry = ServerRegistry(project_root, config)
+    
+    # Load server components
+    loaded_modules = server_registry.load_server_components()
+    
+    # Create and run server
+    server = MCPServer(config)
+    await server.serve()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration Options
+
+The configuration system supports the following settings:
+
+### Host Configuration
+
+```yaml
+host:
+  name: "my-mcp-server"  # Server name
+  log_level: "INFO"      # Logging level (DEBUG, INFO, WARNING, ERROR)
+```
+
+### Server Configuration
+
+```yaml
+server:
+  type: "stdio"     # Server type (stdio, websocket)
+  host: "localhost" # For websocket server
+  port: 8080        # For websocket server
+```
+
+### Logging Configuration
+
+```yaml
+logging:
+  level: "INFO"  # DEBUG, INFO, WARNING, ERROR
+  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+  reset_handlers: false
+  quiet_libraries: true
+```
+
+### Tool Configuration
+
+```yaml
+tools:
+  registry_module: "mcp_runtime.common.mcp_tool_decorator"
+  registry_attr: "TOOLS_REGISTRY"
+```
+
+### MCP Server Configurations
+
+```yaml
+mcp_servers:
+  example_server:
+    location: "servers/example_server"
+    enabled: true
+    tools:
+      module: "example_server.tools"
+      enabled: true
+    resources:
+      module: "example_server.resources"
+      enabled: true
+    prompts:
+      module: "example_server.prompts"
+      enabled: true
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

chuk_mcp_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+chuk_mcp_runtime/__init__.py,sha256=Lls8OFNHJylYQcWMOS80QA6iK0O--Q6mQXT_TGhD15U,262
+chuk_mcp_runtime/main.py,sha256=f8Mmb8aYVcbk7R7KUbenf7Yqg6myeDJoVX9LeLPDIrs,2621
+chuk_mcp_runtime/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_mcp_runtime/common/errors.py,sha256=N4nuF-Zg5NSF-fmzrmCu4JpAl9qwN34vtj9amBznlAg,908
+chuk_mcp_runtime/common/mcp_tool_decorator.py,sha256=NReZRebT7iqDopko5QiJDCINFI4F5vI2sErLjvVwAws,5978
+chuk_mcp_runtime/server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_mcp_runtime/server/config_loader.py,sha256=Fe1XHOqpXDMGiK-a6v9jHRvplPOayj9lJDeSouvtL04,4455
+chuk_mcp_runtime/server/logging_config.py,sha256=AlAt4xxSOfMVqdIDveY-k1RyM4nqEAuUCWo0OIS4G8Y,2839
+chuk_mcp_runtime/server/server.py,sha256=ce2X2CG4mnrf6j4qRlLjr7D1QbCQBKMh0vPPBRknWkU,7437
+chuk_mcp_runtime/server/server_registry.py,sha256=MSY0Fu7414niECRxTr3gZ-ODhCXmYx7WzJUbHGrrtkI,8001
+chuk_mcp_runtime-0.1.0.dist-info/licenses/LICENSE.md,sha256=HqgRrOv3qCAICv8XxRZLyNAHz1TJg1v9vb34MnE9mcY,1065
+chuk_mcp_runtime-0.1.0.dist-info/METADATA,sha256=to6aM-RPBsm1L1TINwtxMUpqMK-9Eeduuou3Mnbueg4,5327
+chuk_mcp_runtime-0.1.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+chuk_mcp_runtime-0.1.0.dist-info/entry_points.txt,sha256=oJatwTJgNhlcpCK17ohLAy3q154_Ui0jO76aEMIqTVQ,63
+chuk_mcp_runtime-0.1.0.dist-info/top_level.txt,sha256=ljLxbagMOu5eOz634lTmgTFP8lNP5qfSMIdT6rwWQMg,17
+chuk_mcp_runtime-0.1.0.dist-info/RECORD,,

chuk_mcp_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chuk_mcp_runtime-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chuk-mcp-server = chuk_mcp_runtime.main:main

chuk_mcp_runtime-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Hay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chuk_mcp_runtime-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chuk_mcp_runtime