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

mcp_proxy_adapter/api/tools.py

@@ -0,0 +1,198 @@
+"""
+Модуль с реализацией инструментов API для внешних систем.
+
+Этот модуль содержит классы инструментов API, которые могут быть
+интегрированы с внешними системами для выполнения команд микросервиса.
+"""
+
+from typing import Any, Dict, Optional, Union, List
+import json
+import logging
+
+from mcp_proxy_adapter.api.tool_integration import ToolIntegration
+from mcp_proxy_adapter.commands.command_registry import registry
+from mcp_proxy_adapter.core.errors import NotFoundError, InvalidParamsError
+
+logger = logging.getLogger(__name__)
+
+
+class TSTCommandExecutor:
+    """
+    Инструмент для выполнения команд через JSON-RPC протокол на сервере проекта.
+    
+    Этот класс предоставляет функциональность для выполнения команд микросервиса
+    через внешний интерфейс TST (Tool-System-Transport).
+    """
+    
+    name = "tst_execute_command"
+    description = "Выполняет команду через JSON-RPC протокол."
+    
+    @classmethod
+    async def execute(cls, command: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Выполняет команду с указанными параметрами.
+        
+        Args:
+            command: Имя команды для выполнения
+            params: Параметры команды (опционально)
+            
+        Returns:
+            Результат выполнения команды
+            
+        Raises:
+            NotFoundError: Если команда не найдена
+            InvalidParamsError: Если переданы некорректные параметры
+        """
+        if not params:
+            params = {}
+            
+        logger.info(f"Executing command via TST: {command}, params: {params}")
+        
+        try:
+            # Проверяем существование команды
+            if not registry.command_exists(command):
+                raise NotFoundError(f"Команда '{command}' не найдена")
+            
+            # Получаем класс команды
+            command_class = registry.get_command(command)
+            
+            # Выполняем команду
+            result = await command_class.run(**params)
+            
+            # Возвращаем результат
+            return result.to_dict()
+        except NotFoundError as e:
+            logger.error(f"Command not found: {command}")
+            raise
+        except Exception as e:
+            logger.exception(f"Error executing command {command}: {e}")
+            raise
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """
+        Возвращает схему инструмента в формате OpenAPI.
+        
+        Returns:
+            Словарь со схемой инструмента
+        """
+        return ToolIntegration.generate_tool_schema(cls.name, registry, cls.description)
+    
+    @classmethod
+    def get_description(cls, format: str = "json") -> Union[Dict[str, Any], str]:
+        """
+        Возвращает полное описание инструмента в указанном формате.
+        
+        Args:
+            format: Формат описания (json, markdown, html)
+            
+        Returns:
+            Описание инструмента в указанном формате
+        """
+        if format.lower() == "json":
+            # Получаем базовое описание инструмента
+            base_description = ToolIntegration.generate_tool_schema(cls.name, registry, cls.description)
+            
+            # Добавляем дополнительную информацию
+            base_description["examples"] = cls._generate_examples()
+            base_description["error_codes"] = cls._generate_error_codes()
+            
+            return base_description
+        elif format.lower() in ["markdown", "text", "html"]:
+            return ToolIntegration.generate_tool_documentation(cls.name, registry, format)
+        else:
+            # По умолчанию возвращаем JSON формат
+            return ToolIntegration.generate_tool_schema(cls.name, registry, cls.description)
+    
+    @classmethod
+    def _generate_examples(cls) -> List[Dict[str, Any]]:
+        """
+        Генерирует примеры использования инструмента.
+        
+        Returns:
+            Список примеров использования
+        """
+        examples = []
+        
+        # Получаем метаданные всех команд
+        all_metadata = registry.get_all_metadata()
+        
+        # Добавляем по одному примеру для каждой команды
+        for cmd_name, metadata in all_metadata.items():
+            if metadata.get("examples"):
+                # Берем первый пример из метаданных
+                example = metadata["examples"][0]
+                
+                # Формируем пример использования инструмента
+                examples.append({
+                    "command": cls.name,
+                    "params": {
+                        "command": example.get("command", cmd_name),
+                        "params": example.get("params", {})
+                    },
+                    "description": f"Выполнение команды {cmd_name}"
+                })
+        
+        return examples
+    
+    @classmethod
+    def _generate_error_codes(cls) -> Dict[str, str]:
+        """
+        Генерирует словарь возможных кодов ошибок.
+        
+        Returns:
+            Словарь с кодами ошибок и их описаниями
+        """
+        return {
+            "-32600": "Некорректный запрос",
+            "-32601": "Команда не найдена",
+            "-32602": "Некорректные параметры",
+            "-32603": "Внутренняя ошибка",
+            "-32000": "Ошибка выполнения команды"
+        }
+
+
+# Экспортируем доступные инструменты API
+available_tools = {
+    TSTCommandExecutor.name: TSTCommandExecutor
+}
+
+
+def get_tool_description(tool_name: str, format: str = "json") -> Union[Dict[str, Any], str]:
+    """
+    Получает описание инструмента API по имени.
+    
+    Args:
+        tool_name: Имя инструмента API
+        format: Формат описания (json, markdown, html)
+        
+    Returns:
+        Описание инструмента в указанном формате
+        
+    Raises:
+        NotFoundError: Если инструмент не найден
+    """
+    if tool_name in available_tools:
+        return available_tools[tool_name].get_description(format)
+    else:
+        raise NotFoundError(f"Инструмент '{tool_name}' не найден")
+
+
+async def execute_tool(tool_name: str, **params) -> Dict[str, Any]:
+    """
+    Выполняет инструмент API с указанными параметрами.
+    
+    Args:
+        tool_name: Имя инструмента API
+        **params: Параметры инструмента
+        
+    Returns:
+        Результат выполнения инструмента
+        
+    Raises:
+        NotFoundError: Если инструмент не найден
+    """
+    if tool_name in available_tools:
+        return await available_tools[tool_name].execute(**params)
+    else:
+        raise NotFoundError(f"Инструмент '{tool_name}' не найден") 

mcp_proxy_adapter/commands/__init__.py

@@ -0,0 +1,19 @@
+"""
+Package with command implementation.
+"""
+
+from mcp_proxy_adapter.commands.base import Command
+from mcp_proxy_adapter.commands.result import CommandResult, SuccessResult, ErrorResult
+from mcp_proxy_adapter.commands.command_registry import registry, CommandRegistry
+
+# Automatically discover and register commands
+registry.discover_commands()
+
+__all__ = [
+    "Command",
+    "CommandResult",
+    "SuccessResult", 
+    "ErrorResult",
+    "registry",
+    "CommandRegistry"
+]

mcp_proxy_adapter/commands/base.py

@@ -0,0 +1,301 @@
+"""
+Module with base command class.
+"""
+
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Dict, List, Optional, Type, TypeVar, Union
+
+from mcp_proxy_adapter.commands.result import CommandResult, ErrorResult, SuccessResult
+from mcp_proxy_adapter.core.errors import (
+    ValidationError, CommandError, InternalError, InvalidParamsError, 
+    NotFoundError, TimeoutError
+)
+from mcp_proxy_adapter.core.logging import logger
+
+T = TypeVar("T", bound=CommandResult)
+
+
+class Command(ABC):
+    """
+    Base abstract class for all commands.
+    """
+    
+    # Command name for registration
+    name: ClassVar[str]
+    # Result class
+    result_class: ClassVar[Type[CommandResult]]
+    
+    @abstractmethod
+    async def execute(self, **kwargs) -> CommandResult:
+        """
+        Executes command with given parameters.
+
+        Args:
+            **kwargs: Command parameters.
+
+        Returns:
+            Command execution result.
+        """
+        pass
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """
+        Returns JSON schema for command parameters validation.
+        This method should be overridden in child classes.
+
+        Returns:
+            Dictionary with JSON schema.
+        """
+        # Default base schema that can be overridden
+        return {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False
+        }
+    
+    @classmethod
+    def get_result_schema(cls) -> Dict[str, Any]:
+        """
+        Returns JSON schema for command result validation.
+
+        Returns:
+            Dictionary with JSON schema.
+        """
+        if hasattr(cls, "result_class") and cls.result_class:
+            return cls.result_class.get_schema()
+        return {}
+    
+    @classmethod
+    def validate_params(cls, params: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Validates command parameters before execution.
+        This method can be overridden in child classes for custom validation.
+
+        Args:
+            params: Parameters to validate.
+
+        Returns:
+            Validated parameters.
+
+        Raises:
+            ValidationError: If parameters failed validation.
+        """
+        # In base implementation, simply return parameters without validation
+        # In real implementation, jsonschema or pydantic will be used here
+        return params
+    
+    @classmethod
+    async def run(cls, **kwargs) -> CommandResult:
+        """
+        Runs command with parameters validation.
+
+        Args:
+            **kwargs: Command parameters.
+
+        Returns:
+            Command execution result.
+        """
+        try:
+            logger.debug(f"Running command {cls.__name__} with params: {kwargs}")
+            
+            # Parameters validation
+            validated_params = cls.validate_params(kwargs)
+            
+            # Create command instance
+            command = cls()
+            
+            # Execute command
+            result = await command.execute(**validated_params)
+            
+            logger.debug(f"Command {cls.__name__} executed successfully")
+            return result
+        except ValidationError as e:
+            # Ошибка валидации параметров
+            logger.error(f"Validation error in command {cls.__name__}: {e}")
+            return ErrorResult(
+                message=str(e), 
+                code=e.code, 
+                details=e.data
+            )
+        except InvalidParamsError as e:
+            # Ошибка в параметрах команды
+            logger.error(f"Invalid parameters error in command {cls.__name__}: {e}")
+            return ErrorResult(
+                message=str(e), 
+                code=e.code, 
+                details=e.data
+            )
+        except NotFoundError as e:
+            # Ресурс не найден
+            logger.error(f"Resource not found error in command {cls.__name__}: {e}")
+            return ErrorResult(
+                message=str(e), 
+                code=e.code, 
+                details=e.data
+            )
+        except TimeoutError as e:
+            # Превышено время ожидания
+            logger.error(f"Timeout error in command {cls.__name__}: {e}")
+            return ErrorResult(
+                message=str(e), 
+                code=e.code, 
+                details=e.data
+            )
+        except CommandError as e:
+            # Ошибка выполнения команды
+            logger.error(f"Command error in {cls.__name__}: {e}")
+            return ErrorResult(
+                message=str(e), 
+                code=e.code, 
+                details=e.data
+            )
+        except Exception as e:
+            # Непредвиденная ошибка
+            logger.exception(f"Unexpected error executing command {cls.__name__}: {e}")
+            internal_error = InternalError(f"Command execution error: {str(e)}")
+            return ErrorResult(
+                message=internal_error.message,
+                code=internal_error.code,
+                details={"original_error": str(e)}
+            )
+    
+    @classmethod
+    def get_param_info(cls) -> Dict[str, Dict[str, Any]]:
+        """
+        Gets information about execute method parameters.
+
+        Returns:
+            Dictionary with parameters information.
+        """
+        signature = inspect.signature(cls.execute)
+        params = {}
+        
+        for name, param in signature.parameters.items():
+            if name == "self":
+                continue
+                
+            param_info = {
+                "name": name,
+                "required": param.default == inspect.Parameter.empty
+            }
+            
+            if param.annotation != inspect.Parameter.empty:
+                param_info["type"] = str(param.annotation)
+            
+            if param.default != inspect.Parameter.empty:
+                param_info["default"] = param.default
+                
+            params[name] = param_info
+            
+        return params
+    
+    @classmethod
+    def get_metadata(cls) -> Dict[str, Any]:
+        """
+        Returns complete metadata about the command.
+        
+        Provides a single access point to all command metadata.
+        
+        Returns:
+            Dict with command metadata
+        """
+        # Get and format docstring
+        doc = cls.__doc__ or ""
+        description = inspect.cleandoc(doc) if doc else ""
+        
+        # Extract first line for summary
+        summary = description.split("\n")[0] if description else ""
+        
+        # Get parameters information
+        param_info = cls.get_param_info()
+        
+        # Generate examples based on parameters
+        examples = cls._generate_examples(param_info)
+        
+        return {
+            "name": cls.name,
+            "summary": summary,
+            "description": description,
+            "params": param_info,
+            "examples": examples,
+            "schema": cls.get_schema(),
+            "result_schema": cls.get_result_schema(),
+            "result_class": cls.result_class.__name__ if hasattr(cls, "result_class") else None,
+        }
+    
+    @classmethod
+    def _generate_examples(cls, params: Dict[str, Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Generates usage examples of the command based on its parameters.
+        
+        Args:
+            params: Information about command parameters
+            
+        Returns:
+            List of examples
+        """
+        examples = []
+        
+        # Simple example without parameters, if all parameters are optional
+        if not any(param.get("required", False) for param in params.values()):
+            examples.append({
+                "command": cls.name,
+                "description": f"Call {cls.name} command without parameters"
+            })
+        
+        # Example with all required parameters
+        required_params = {k: v for k, v in params.items() if v.get("required", False)}
+        if required_params:
+            example_params = {}
+            for param_name, param_info in required_params.items():
+                # Generate suitable example value based on parameter type
+                param_type = param_info.get("type", "")
+                if "str" in param_type.lower():
+                    example_params[param_name] = f"example_{param_name}"
+                elif "int" in param_type.lower():
+                    example_params[param_name] = 123
+                elif "float" in param_type.lower():
+                    example_params[param_name] = 123.45
+                elif "bool" in param_type.lower():
+                    example_params[param_name] = True
+                else:
+                    example_params[param_name] = f"value_for_{param_name}"
+            
+            examples.append({
+                "command": cls.name,
+                "params": example_params,
+                "description": f"Call {cls.name} command with required parameters"
+            })
+        
+        # Add example with all parameters, if there are optional ones
+        optional_params = {k: v for k, v in params.items() if not v.get("required", False)}
+        if optional_params and required_params:
+            full_example_params = dict(example_params) if 'example_params' in locals() else {}
+            
+            for param_name, param_info in optional_params.items():
+                # Get default value or generate suitable example
+                if "default" in param_info:
+                    full_example_params[param_name] = param_info["default"]
+                else:
+                    # Generate suitable example value based on parameter type
+                    param_type = param_info.get("type", "")
+                    if "str" in param_type.lower():
+                        full_example_params[param_name] = f"optional_{param_name}"
+                    elif "int" in param_type.lower():
+                        full_example_params[param_name] = 456
+                    elif "float" in param_type.lower():
+                        full_example_params[param_name] = 45.67
+                    elif "bool" in param_type.lower():
+                        full_example_params[param_name] = False
+                    else:
+                        full_example_params[param_name] = f"optional_value_for_{param_name}"
+            
+            examples.append({
+                "command": cls.name,
+                "params": full_example_params,
+                "description": f"Call {cls.name} command with all parameters"
+            })
+        
+        return examples