mcp-proxy-adapter 2.1.13__py3-none-any.whl → 2.1.14__py3-none-any.whl

mcp_proxy_adapter/analyzers/docstring_analyzer.py

@@ -0,0 +1,199 @@
+"""
+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

@@ -0,0 +1,151 @@
+"""
+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/base_dispatcher.py

@@ -0,0 +1,85 @@
+"""
+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

@@ -145,13 +145,14 @@ class JsonRpcDispatcher(BaseDispatcher):
             raise e
 
     async def execute(self, command: str, **kwargs) -> Any:
-        # Check if command exists
+        """
+        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:
-            result = await self._call_handler_always_awaitable(handler, kwargs)
-            return result
+            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())

mcp_proxy_adapter/examples/docstring_and_schema_example.py

@@ -10,7 +10,8 @@ Run:
 """
 import os
 import sys
-sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+import asyncio
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
 from mcp_proxy_adapter.adapter import MCPProxyAdapter
 
 class MyRegistry:
@@ -57,4 +58,12 @@ if __name__ == "__main__":
     # Print OpenAPI schema (simulated)
     schema = adapter.generate_mcp_proxy_config()
     print("=== Tool description from docstring ===")
-    print(schema.tools[0].description) 
+    print(schema.tools[0].description)
+
+    # Call sync handler
+    result_sync = registry.execute('sum', a=10, b=1)
+    print(result_sync)  # 11
+
+    # Call sync handler (ещё раз)
+    result_sync2 = registry.execute('sum', a=10, b=10)
+    print(result_sync2)  # 20 

mcp_proxy_adapter/examples/extension_example.py

@@ -10,7 +10,8 @@ Run:
 """
 import os
 import sys
-sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+import asyncio
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
 from mcp_proxy_adapter.adapter import MCPProxyAdapter
 
 class MyRegistry:
@@ -54,7 +55,18 @@ class MyRegistry:
 if __name__ == "__main__":
     registry = MyRegistry()
     adapter = MCPProxyAdapter(registry)
-    print("[EXT] Ping:", registry.execute("ping"))
-    print("[EXT] Help (all):", registry.execute("help"))
-    print("[EXT] Help (ping):", registry.execute("help", command="ping"))
-    print("[EXT] Help (notfound):", registry.execute("help", command="notfound")) 
+    # Call sync handler
+    result_sync = registry.execute("ping")
+    print(result_sync)  # Ping
+
+    # Call help (all)
+    result_help_all = registry.execute("help")
+    print("Help (all)", result_help_all)
+
+    # Call help (ping)
+    result_help_ping = registry.execute("help", command="ping")
+    print("Help (ping)", result_help_ping)
+
+    # Call help (notfound)
+    result_help_notfound = registry.execute("help", command="notfound")
+    print("Help (notfound)", result_help_notfound) 

mcp_proxy_adapter/examples/testing_example.py

@@ -10,7 +10,8 @@ Run:
 """
 import os
 import sys
-sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+import asyncio
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
 from mcp_proxy_adapter.adapter import MCPProxyAdapter
 
 class MyRegistry:
@@ -48,6 +49,16 @@ def test_echo():
     # Not a real FastAPI call, just for illustration
     print("[TEST] Echo command passed.")
 
+# Call sync handler
+registry = MyRegistry()
+adapter = MCPProxyAdapter(registry)
+result_sync = registry.execute('echo', text='hi')
+print(result_sync)  # hi
+
+# Call async handler
+result_async = asyncio.run(registry.execute('async', x=10))
+print(result_async)  # 20
+
 if __name__ == "__main__":
     test_echo()
     print("All tests passed.") 

mcp_proxy_adapter/models.py

@@ -0,0 +1,47 @@
+"""
+Data models for MCP Proxy Adapter.
+"""
+from typing import Dict, Any, List, Optional, Union
+from pydantic import BaseModel, Field
+
+class JsonRpcRequest(BaseModel):
+    """Base model for JSON-RPC requests."""
+    jsonrpc: str = Field(default="2.0", description="JSON-RPC version")
+    method: str = Field(..., description="Method name to call")
+    params: Dict[str, Any] = Field(default_factory=dict, description="Method parameters")
+    id: Optional[Union[str, int]] = Field(default=None, description="Request identifier")
+
+class JsonRpcResponse(BaseModel):
+    """Base model for JSON-RPC responses."""
+    jsonrpc: str = Field(default="2.0", description="JSON-RPC version")
+    result: Optional[Any] = Field(default=None, description="Method execution result")
+    error: Optional[Dict[str, Any]] = Field(default=None, description="Error information")
+    id: Optional[Union[str, int]] = Field(default=None, description="Request identifier")
+    
+class CommandInfo(BaseModel):
+    """Command information model."""
+    name: str = Field(..., description="Command name")
+    description: str = Field(default="", description="Command description")
+    summary: Optional[str] = Field(default=None, description="Brief description")
+    parameters: Dict[str, Dict[str, Any]] = Field(default_factory=dict, description="Command parameters")
+    returns: Optional[Dict[str, Any]] = Field(default=None, description="Return value information")
+
+class CommandParameter(BaseModel):
+    """Command parameter model."""
+    type: str = Field(..., description="Parameter type")
+    description: str = Field(default="", description="Parameter description")
+    required: bool = Field(default=False, description="Whether the parameter is required")
+    default: Optional[Any] = Field(default=None, description="Default value")
+    enum: Optional[List[Any]] = Field(default=None, description="Possible values for enumeration")
+
+class MCPProxyTool(BaseModel):
+    """Tool model for MCPProxy."""
+    name: str = Field(..., description="Tool name") 
+    description: str = Field(default="", description="Tool description")
+    parameters: Dict[str, Any] = Field(..., description="Tool parameters schema")
+
+class MCPProxyConfig(BaseModel):
+    """Configuration model for MCPProxy."""
+    version: str = Field(default="1.0", description="Configuration version")
+    tools: List[MCPProxyTool] = Field(default_factory=list, description="List of tools")
+    routes: List[Dict[str, Any]] = Field(default_factory=list, description="Routes configuration")