mcp-proxy-adapter 2.1.16__py3-none-any.whl → 3.0.0__py3-none-any.whl

mcp_proxy_adapter/analyzers/__init__.py

@@ -1 +0,0 @@
- 

mcp_proxy_adapter/analyzers/docstring_analyzer.py

@@ -1,199 +0,0 @@
-"""
-Docstring analyzer for extracting information from function documentation.
-"""
-import inspect
-from typing import Dict, Any, Optional, Callable, List, Tuple
-import docstring_parser
-
-class DocstringAnalyzer:
-    """
-    Docstring analyzer for extracting metadata from function documentation.
-    
-    This class is responsible for analyzing command handler function docstrings
-    and extracting function descriptions, parameters, and return values.
-    """
-    
-    def analyze(self, handler: Callable) -> Dict[str, Any]:
-        """
-        Analyzes function docstring and returns metadata.
-        
-        Args:
-            handler: Handler function to analyze
-            
-        Returns:
-            Dict[str, Any]: Metadata extracted from docstring
-        """
-        result = {
-            "description": "",
-            "summary": "",
-            "parameters": {},
-            "returns": {
-                "description": ""
-            }
-        }
-        
-        # Get function signature
-        sig = inspect.signature(handler)
-        
-        # Get docstring
-        docstring = handler.__doc__ or ""
-        
-        # Parse docstring
-        try:
-            parsed_doc = docstring_parser.parse(docstring)
-            
-            # Extract general function description
-            if parsed_doc.short_description:
-                result["summary"] = parsed_doc.short_description
-                result["description"] = parsed_doc.short_description
-                
-            if parsed_doc.long_description:
-                # If both short and long descriptions exist, combine them
-                if result["description"]:
-                    result["description"] = f"{result['description']}\n\n{parsed_doc.long_description}"
-                else:
-                    result["description"] = parsed_doc.long_description
-            
-            # Extract parameter information
-            for param in parsed_doc.params:
-                param_name = param.arg_name
-                param_desc = param.description or f"Parameter {param_name}"
-                param_type = None
-                
-                # If parameter type is specified in docstring, use it
-                if param.type_name:
-                    param_type = self._parse_type_from_docstring(param.type_name)
-                
-                # Add parameter to metadata
-                if param_name not in result["parameters"]:
-                    result["parameters"][param_name] = {}
-                    
-                result["parameters"][param_name]["description"] = param_desc
-                
-                if param_type:
-                    result["parameters"][param_name]["type"] = param_type
-            
-            # Extract return value information
-            if parsed_doc.returns:
-                result["returns"]["description"] = parsed_doc.returns.description or "Return value"
-                
-                if parsed_doc.returns.type_name:
-                    result["returns"]["type"] = self._parse_type_from_docstring(parsed_doc.returns.type_name)
-        
-        except Exception as e:
-            # In case of parsing error, use docstring as is
-            if docstring:
-                result["description"] = docstring.strip()
-        
-        # Fill parameter information from signature if not found in docstring
-        for param_name, param in sig.parameters.items():
-            # Skip self for methods
-            if param_name == 'self':
-                continue
-                
-            # If parameter not yet added to metadata, add it
-            if param_name not in result["parameters"]:
-                result["parameters"][param_name] = {
-                    "description": f"Parameter {param_name}"
-                }
-            
-            # Determine if parameter is required
-            required = param.default == inspect.Parameter.empty
-            result["parameters"][param_name]["required"] = required
-            
-            # Add default value if exists
-            if param.default != inspect.Parameter.empty:
-                # Some default values cannot be serialized to JSON
-                # So we check if the value can be serialized
-                if param.default is None or isinstance(param.default, (str, int, float, bool, list, dict)):
-                    result["parameters"][param_name]["default"] = param.default
-        
-        return result
-    
-    def validate(self, handler: Callable) -> Tuple[bool, List[str]]:
-        """
-        Validates that function docstring matches its formal parameters.
-        
-        Args:
-            handler: Command handler function
-            
-        Returns:
-            Tuple[bool, List[str]]: Validity flag and list of errors
-        """
-        errors = []
-        
-        # Get function formal parameters
-        sig = inspect.signature(handler)
-        formal_params = list(sig.parameters.keys())
-        
-        # Skip self parameter for methods
-        if formal_params and formal_params[0] == 'self':
-            formal_params = formal_params[1:]
-            
-        # Parse docstring
-        docstring = handler.__doc__ or ""
-        parsed_doc = docstring_parser.parse(docstring)
-        
-        # Check for function description
-        if not parsed_doc.short_description and not parsed_doc.long_description:
-            errors.append(f"Missing function description")
-        
-        # Get parameters from docstring
-        doc_params = {param.arg_name: param for param in parsed_doc.params}
-        
-        # Check that all formal parameters are described in docstring
-        for param in formal_params:
-            if param not in doc_params and param != 'params':  # 'params' is special case, can be dictionary of all parameters
-                errors.append(f"Parameter '{param}' not described in function docstring")
-        
-        # Check for returns in docstring
-        if not parsed_doc.returns and not any(t.type_name == 'Returns' for t in parsed_doc.meta):
-            errors.append(f"Missing return value description in function docstring")
-        
-        return len(errors) == 0, errors
-    
-    def _parse_type_from_docstring(self, type_str: str) -> str:
-        """
-        Parses type from string representation in docstring.
-        
-        Args:
-            type_str: String representation of type
-            
-        Returns:
-            str: Type in OpenAPI format
-        """
-        # Simple mapping of string types to OpenAPI types
-        type_map = {
-            "str": "string",
-            "string": "string",
-            "int": "integer",
-            "integer": "integer",
-            "float": "number",
-            "number": "number",
-            "bool": "boolean",
-            "boolean": "boolean",
-            "list": "array",
-            "array": "array",
-            "dict": "object",
-            "object": "object",
-            "none": "null",
-            "null": "null",
-        }
-        
-        # Convert to lowercase and remove spaces
-        cleaned_type = type_str.lower().strip()
-        
-        # Check for simple types
-        if cleaned_type in type_map:
-            return type_map[cleaned_type]
-        
-        # Check for List[X]
-        if cleaned_type.startswith("list[") or cleaned_type.startswith("array["):
-            return "array"
-        
-        # Check for Dict[X, Y]
-        if cleaned_type.startswith("dict[") or cleaned_type.startswith("object["):
-            return "object"
-        
-        # Default to object
-        return "object" 

mcp_proxy_adapter/analyzers/type_analyzer.py

@@ -1,151 +0,0 @@
-"""
-Type analyzer for extracting information from function type annotations.
-"""
-import inspect
-from typing import Dict, Any, List, Optional, Callable, Union, get_origin, get_args, get_type_hints
-
-class TypeAnalyzer:
-    """
-    Type analyzer for extracting information from function type annotations.
-    
-    This class is responsible for analyzing type annotations of command handler functions
-    and converting them to JSON Schema/OpenAPI type format.
-    """
-    
-    def __init__(self):
-        # Mapping Python types to OpenAPI types
-        self.type_map = {
-            str: "string",
-            int: "integer",
-            float: "number",
-            bool: "boolean",
-            list: "array",
-            dict: "object",
-            Any: "object",
-            None: "null",
-        }
-    
-    def analyze(self, handler: Callable) -> Dict[str, Any]:
-        """
-        Analyzes function type annotations and returns metadata.
-        
-        Args:
-            handler: Handler function to analyze
-            
-        Returns:
-            Dict[str, Any]: Metadata about parameter types and return value
-        """
-        result = {
-            "parameters": {},
-            "returns": None
-        }
-        
-        # Get function signature
-        sig = inspect.signature(handler)
-        
-        # Get type annotations
-        type_hints = self._get_type_hints(handler)
-        
-        # Analyze parameters
-        for param_name, param in sig.parameters.items():
-            # Skip self for methods
-            if param_name == 'self':
-                continue
-                
-            # If parameter is named params, assume it's a dictionary of all parameters
-            if param_name == 'params':
-                continue
-                
-            # Determine if parameter is required
-            required = param.default == inspect.Parameter.empty
-            
-            # Determine parameter type
-            param_type = "object"  # Default type
-            
-            if param_name in type_hints:
-                param_type = self._map_type_to_openapi(type_hints[param_name])
-                
-            # Create parameter metadata
-            param_metadata = {
-                "type": param_type,
-                "required": required
-            }
-            
-            # Add default value if exists
-            if param.default != inspect.Parameter.empty:
-                # Some default values cannot be serialized to JSON
-                # So we convert them to string representation for such cases
-                if param.default is None or isinstance(param.default, (str, int, float, bool, list, dict)):
-                    param_metadata["default"] = param.default
-            
-            # Add parameter to metadata
-            result["parameters"][param_name] = param_metadata
-        
-        # Analyze return value
-        if 'return' in type_hints:
-            result["returns"] = self._map_type_to_openapi(type_hints['return'])
-        
-        return result
-    
-    def _get_type_hints(self, handler: Callable) -> Dict[str, Any]:
-        """
-        Gets type annotations of a function.
-        
-        Args:
-            handler: Handler function
-            
-        Returns:
-            Dict[str, Any]: Type annotations
-        """
-        try:
-            return get_type_hints(handler)
-        except Exception:
-            # If failed to get annotations via get_type_hints,
-            # extract them manually from __annotations__
-            return getattr(handler, "__annotations__", {})
-    
-    def _map_type_to_openapi(self, type_hint: Any) -> Union[str, Dict[str, Any]]:
-        """
-        Converts Python type to OpenAPI type.
-        
-        Args:
-            type_hint: Python type
-            
-        Returns:
-            Union[str, Dict[str, Any]]: OpenAPI type string representation or schema
-        """
-        # Check for None
-        if type_hint is None:
-            return "null"
-        
-        # Handle primitive types
-        if type_hint in self.type_map:
-            return self.type_map[type_hint]
-        
-        # Check for generic types
-        origin = get_origin(type_hint)
-        if origin is not None:
-            # Handle List[X], Dict[X, Y], etc.
-            if origin in (list, List):
-                args = get_args(type_hint)
-                if args:
-                    item_type = self._map_type_to_openapi(args[0])
-                    return {
-                        "type": "array",
-                        "items": item_type if isinstance(item_type, dict) else {"type": item_type}
-                    }
-                return "array"
-            elif origin in (dict, Dict):
-                # For dict we just return object, as OpenAPI
-                # doesn't have a direct equivalent for Dict[X, Y]
-                return "object"
-            elif origin is Union:
-                # For Union we take the first type that is not None
-                args = get_args(type_hint)
-                for arg in args:
-                    if arg is not type(None):
-                        return self._map_type_to_openapi(arg)
-                return "object"
-        
-        # Default to object
-        return "object" 

mcp_proxy_adapter/dispatchers/__init__.py

@@ -1 +0,0 @@
- 

mcp_proxy_adapter/dispatchers/base_dispatcher.py

@@ -1,85 +0,0 @@
-"""
-Base command dispatcher class.
-"""
-from abc import ABC, abstractmethod
-from typing import Dict, Any, Callable, List, Optional
-
-class BaseDispatcher(ABC):
-    """
-    Abstract base class for command dispatchers.
-    
-    Defines the interface that all command dispatchers must implement.
-    Dispatchers are responsible for registering and executing commands.
-    """
-    
-    @abstractmethod
-    def register_handler(
-        self, 
-        command: str, 
-        handler: Callable, 
-        description: str = "", 
-        summary: str = "", 
-        params: Dict[str, Any] = None
-    ) -> None:
-        """
-        Registers a command handler.
-        
-        Args:
-            command: Command name
-            handler: Command handler function
-            description: Command description
-            summary: Brief command summary
-            params: Command parameters description
-        """
-        pass
-    
-    @abstractmethod
-    def execute(self, command: str, **kwargs) -> Any:
-        """
-        Executes a command with the specified parameters.
-        
-        Args:
-            command: Command name
-            **kwargs: Command parameters
-            
-        Returns:
-            Any: Command execution result
-            
-        Raises:
-            CommandNotFoundError: If command is not found
-            CommandExecutionError: On command execution error
-        """
-        pass
-    
-    @abstractmethod
-    def get_valid_commands(self) -> List[str]:
-        """
-        Returns a list of all registered command names.
-        
-        Returns:
-            List[str]: List of command names
-        """
-        pass
-    
-    @abstractmethod
-    def get_command_info(self, command: str) -> Optional[Dict[str, Any]]:
-        """
-        Returns information about a command.
-        
-        Args:
-            command: Command name
-            
-        Returns:
-            Optional[Dict[str, Any]]: Command information or None if command not found
-        """
-        pass
-    
-    @abstractmethod
-    def get_commands_info(self) -> Dict[str, Dict[str, Any]]:
-        """
-        Returns information about all registered commands.
-        
-        Returns:
-            Dict[str, Dict[str, Any]]: Dictionary {command_name: information}
-        """
-        pass 

mcp_proxy_adapter/dispatchers/json_rpc_dispatcher.py

@@ -1,235 +0,0 @@
-"""
-Implementation of a JSON-RPC based command dispatcher.
-
-CHANGELOG:
-- 2024-06-13: execute() now always returns awaitable. If handler is sync and for any reason result is not awaitable, it is wrapped in an async function and awaited. This guarantees await-safety for all handler types and fixes 'object ... can't be used in await expression' errors in all environments.
-"""
-from typing import Dict, Any, Callable, List, Optional, Union
-import inspect
-import logging
-import traceback
-from .base_dispatcher import BaseDispatcher
-import asyncio
-
-logger = logging.getLogger("command_registry")
-
-print('[DEBUG] LOADED json_rpc_dispatcher.py')
-
-class CommandError(Exception):
-    """Base class for command errors"""
-    pass
-
-class CommandNotFoundError(CommandError):
-    """Error raised when attempting to execute a non-existent command"""
-    pass
-
-class CommandExecutionError(CommandError):
-    """Error raised during command execution"""
-    pass
-
-class JsonRpcDispatcher(BaseDispatcher):
-    """
-    JSON-RPC based command dispatcher.
-    
-    Implements the BaseDispatcher interface for handling commands in JSON-RPC 2.0 format.
-    Supports registration, execution, and retrieval of command information.
-
-    Best practice:
-    ----------------
-    Register handlers explicitly using register_handler (no decorators!).
-    Both sync and async handlers are supported.
-
-    Example:
-        import asyncio
-        from mcp_proxy_adapter.dispatchers.json_rpc_dispatcher import JsonRpcDispatcher
-
-        def sync_handler(x):
-            return x + 1
-
-        async def async_handler(x):
-            await asyncio.sleep(0.1)
-            return x * 2
-
-        dispatcher = JsonRpcDispatcher()
-        dispatcher.register_handler('sync', sync_handler, description='Sync handler')
-        dispatcher.register_handler('async', async_handler, description='Async handler')
-
-        # Call sync handler
-        result_sync = asyncio.run(dispatcher.execute('sync', x=10))
-        print(result_sync)  # 11
-
-        # Call async handler
-        result_async = asyncio.run(dispatcher.execute('async', x=10))
-        print(result_async)  # 20
-    """
-    
-    def __init__(self):
-        """Initializes a new dispatcher instance"""
-        self._handlers = {}
-        self._metadata = {}
-        
-        # Register the built-in help command
-        self.register_handler(
-            command="help",
-            handler=self._help_command,
-            description=(
-                "Returns information about available commands.\n"
-                "Best practice: Register handlers explicitly using register_handler (no decorators).\n"
-                "Example: dispatcher.register_handler('mycmd', my_handler, description='...')"
-            ),
-            summary="Command help",
-            params={
-                "cmdname": {
-                    "type": "string",
-                    "description": "Command name for detailed information",
-                    "required": False
-                }
-            }
-        )
-    
-    def register_handler(
-        self, 
-        command: str, 
-        handler: Callable, 
-        description: str = "", 
-        summary: str = "", 
-        params: Dict[str, Any] = None
-    ) -> None:
-        """
-        Registers a command handler.
-        
-        Args:
-            command: Command name
-            handler: Command handler function
-            description: Command description
-            summary: Brief command summary
-            params: Command parameters description
-        """
-        if not params:
-            params = {}
-            
-        # Save the handler
-        self._handlers[command] = handler
-        
-        # Save metadata
-        self._metadata[command] = {
-            "description": description,
-            "summary": summary or command.replace("_", " ").title(),
-            "params": params
-        }
-        
-        logger.debug(f"Registered command: {command}")
-    
-    async def _call_handler_always_awaitable(self, handler, kwargs):
-        loop = asyncio.get_running_loop()
-        sig = inspect.signature(handler)
-        params = sig.parameters
-        try:
-            if inspect.iscoroutinefunction(handler):
-                if len(params) == 1 and 'params' in params:
-                    result = handler(params=kwargs)
-                else:
-                    result = handler(**kwargs)
-            else:
-                if len(params) == 1 and 'params' in params:
-                    result = loop.run_in_executor(None, lambda: handler(params=kwargs))
-                else:
-                    result = loop.run_in_executor(None, lambda: handler(**kwargs))
-            if inspect.isawaitable(result):
-                return await result
-            else:
-                async def _return_sync():
-                    return result
-                return await _return_sync()
-        except Exception as e:
-            raise e
-
-    async def execute(self, command: str, **kwargs) -> Any:
-        """
-        Executes a command with the specified parameters.
-        """
-        if command not in self._handlers:
-            raise CommandNotFoundError(f"Command '{command}' not found")
-        handler = self._handlers[command]
-        try:
-            return await self._call_handler_always_awaitable(handler, kwargs)
-        except Exception as e:
-            logger.error(f"Error executing command '{command}': {str(e)}")
-            logger.debug(traceback.format_exc())
-            raise CommandExecutionError(f"Error executing command '{command}': {str(e)}")
-    
-    def get_valid_commands(self) -> List[str]:
-        """
-        Returns a list of all registered command names.
-        
-        Returns:
-            List[str]: List of command names
-        """
-        return list(self._handlers.keys())
-    
-    def get_command_info(self, command: str) -> Optional[Dict[str, Any]]:
-        """
-        Returns information about a command.
-        
-        Args:
-            command: Command name
-            
-        Returns:
-            Optional[Dict[str, Any]]: Command information or None if command not found
-        """
-        if command not in self._metadata:
-            return None
-        
-        return self._metadata[command]
-    
-    def get_commands_info(self) -> Dict[str, Dict[str, Any]]:
-        """
-        Returns information about all registered commands.
-        
-        Returns:
-            Dict[str, Dict[str, Any]]: Dictionary {command_name: information}
-        """
-        return self._metadata.copy()
-    
-    def _help_command(self, params: Dict[str, Any] = None) -> Dict[str, Any]:
-        """
-        Built-in help command for getting command information.
-        
-        Args:
-            params: Command parameters
-                cmdname: Command name for detailed information
-                
-        Returns:
-            Dict[str, Any]: Command help information
-        """
-        if not params:
-            params = {}
-            
-        # If specific command is specified, return information only about it
-        if "cmdname" in params and params["cmdname"]:
-            command = params["cmdname"]
-            if command not in self._metadata:
-                return {
-                    "error": f"Command '{command}' not found",
-                    "available_commands": list(self._metadata.keys())
-                }
-            
-            return {
-                "command": command,
-                "info": self._metadata[command]
-            }
-        
-        # Otherwise return brief information about all commands
-        commands_info = {}
-        for cmd, info in self._metadata.items():
-            commands_info[cmd] = {
-                "summary": info["summary"],
-                "description": info["description"],
-                "params_count": len(info["params"])
-            }
-        
-        return {
-            "commands": commands_info,
-            "total": len(commands_info),
-            "note": "Use the 'cmdname' parameter to get detailed information about a specific command"
-        }