mcp-proxy-adapter 2.0.1__py3-none-any.whl → 6.9.50__py3-none-any.whl

mcp_proxy_adapter/api/schemas.py

@@ -0,0 +1,270 @@
+"""
+Module with API schema definitions.
+"""
+
+from typing import Any, Dict, List, Optional, Union, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ErrorResponse(BaseModel):
+    """
+    Error response model.
+    """
+
+    code: int = Field(..., description="Error code")
+    message: str = Field(..., description="Error message")
+    details: Optional[Dict[str, Any]] = Field(
+        None, description="Additional error details"
+    )
+
+
+class ErrorWrapper(BaseModel):
+    """
+    Wrapper for error response.
+    """
+
+    error: ErrorResponse
+
+
+class JsonRpcRequest(BaseModel):
+    """
+    JSON-RPC request model.
+    """
+
+    jsonrpc: Literal["2.0"] = Field("2.0", description="JSON-RPC version")
+    method: str = Field(..., description="Method name")
+    params: Optional[Union[Dict[str, Any], List[Any]]] = Field(
+        None, description="Method parameters"
+    )
+    id: Optional[Union[str, int]] = Field(None, description="Request ID")
+
+
+class JsonRpcError(BaseModel):
+    """
+    JSON-RPC error model.
+    """
+
+    code: int = Field(..., description="Error code")
+    message: str = Field(..., description="Error message")
+    data: Optional[Dict[str, Any]] = Field(None, description="Additional error data")
+
+
+class JsonRpcSuccessResponse(BaseModel):
+    """
+    JSON-RPC success response model.
+    """
+
+    jsonrpc: Literal["2.0"] = Field("2.0", description="JSON-RPC version")
+    result: Dict[str, Any] = Field(..., description="Method result")
+    id: Optional[Union[str, int]] = Field(None, description="Request ID")
+
+
+class JsonRpcErrorResponse(BaseModel):
+    """
+    JSON-RPC error response model.
+    """
+
+    jsonrpc: Literal["2.0"] = Field("2.0", description="JSON-RPC version")
+    error: JsonRpcError = Field(..., description="Error information")
+    id: Optional[Union[str, int]] = Field(None, description="Request ID")
+
+
+class CommandResponse(BaseModel):
+    """
+    Command response model.
+    """
+
+    success: bool = Field(..., description="Command execution success flag")
+    data: Optional[Dict[str, Any]] = Field(None, description="Result data")
+    message: Optional[str] = Field(None, description="Result message")
+    error: Optional[ErrorResponse] = Field(None, description="Error information")
+
+
+class HealthResponse(BaseModel):
+    """
+    Health response model.
+    """
+
+    status: str = Field(..., description="Server status")
+    version: str = Field(..., description="Server version")
+    uptime: float = Field(..., description="Server uptime in seconds")
+    components: Dict[str, Any] = Field(..., description="Components health")
+
+
+class CommandListResponse(BaseModel):
+    """
+    Command list response model.
+    """
+
+    commands: Dict[str, Dict[str, Any]] = Field(..., description="Available commands")
+
+
+class CommandRequest(BaseModel):
+    """
+    Command request model for /cmd endpoint.
+    """
+
+    command: str = Field(..., description="Command name to execute")
+    params: Optional[Dict[str, Any]] = Field({}, description="Command parameters")
+
+
+class CommandSuccessResponse(BaseModel):
+    """
+    Command success response model for /cmd endpoint.
+    """
+
+    result: Dict[str, Any] = Field(..., description="Command execution result")
+
+
+class CommandErrorResponse(BaseModel):
+    """
+    Command error response model for /cmd endpoint.
+    """
+
+    error: JsonRpcError = Field(..., description="Error information")
+
+
+class APIToolDescription:
+    """
+    Генератор описаний для инструментов API на основе метаданных команд.
+
+    Класс предоставляет функциональность для создания подробных и понятных
+    описаний инструментов API, которые помогают пользователям сразу понять
+    как использовать API.
+    """
+
+    @classmethod
+    def generate_tool_description(cls, name: str, registry) -> Dict[str, Any]:
+        """
+        Генерирует подробное описание инструмента API на основе имени и реестра команд.
+
+        Args:
+            name: Имя инструмента API
+            registry: Реестр команд
+
+        Returns:
+            Словарь с полным описанием инструмента
+        """
+        # Получаем все метаданные из реестра команд
+        all_metadata = registry.get_all_metadata()
+
+        # Базовое описание инструмента
+        description = {
+            "name": name,
+            "description": f"Выполняет команды через JSON-RPC протокол на сервере проекта.",
+            "supported_commands": {},
+            "examples": [],
+        }
+
+        # Добавляем информацию о поддерживаемых командах
+        for cmd_name, metadata in all_metadata.items():
+            command_info = {
+                "summary": metadata["summary"],
+                "description": metadata["description"],
+                "params": {},
+                "required_params": [],
+            }
+
+            # Добавляем информацию о параметрах
+            for param_name, param_info in metadata["params"].items():
+                param_type = param_info.get("type", "any").replace("typing.", "")
+
+                # Определяем тип параметра для документации
+                simple_type = cls._simplify_type(param_type)
+
+                command_info["params"][param_name] = {
+                    "type": simple_type,
+                    "description": cls._extract_param_description(
+                        metadata["description"], param_name
+                    ),
+                    "required": param_info.get("required", False),
+                }
+
+                # Если параметр обязательный, добавляем его в список обязательных
+                if param_info.get("required", False):
+                    command_info["required_params"].append(param_name)
+
+            description["supported_commands"][cmd_name] = command_info
+
+            # Добавляем примеры из метаданных команды
+            for example in metadata.get("examples", []):
+                description["examples"].append(
+                    {
+                        "command": example.get("command", cmd_name),
+                        "params": example.get("params", {}),
+                        "description": example.get(
+                            "description", f"Пример использования команды {cmd_name}"
+                        ),
+                    }
+                )
+
+        return description
+
+    @classmethod
+
+    @classmethod
+    def _simplify_type(cls, type_str: str) -> str:
+        """
+        Упрощает строковое представление типа для документации.
+
+        Args:
+            type_str: Строковое представление типа
+
+        Returns:
+            Упрощенное строковое представление типа
+        """
+        # Удаляем префиксы из строки типа
+        type_str = type_str.replace("<class '", "").replace("'>", "")
+
+        # Преобразование стандартных типов
+        if "str" in type_str:
+            return "строка"
+        elif "int" in type_str:
+            return "целое число"
+        elif "float" in type_str:
+            return "число"
+        elif "bool" in type_str:
+            return "логическое значение"
+        elif "List" in type_str or "list" in type_str:
+            return "список"
+        elif "Dict" in type_str or "dict" in type_str:
+            return "объект"
+        elif "Optional" in type_str:
+            # Извлекаем тип из Optional[X]
+            inner_type = type_str.split("[")[1].split("]")[0]
+            return cls._simplify_type(inner_type)
+        else:
+            return "значение"
+
+    @classmethod
+    def _extract_param_description(cls, doc_string: str, param_name: str) -> str:
+        """
+        Извлекает описание параметра из строки документации.
+
+        Args:
+            doc_string: Строка документации
+            param_name: Имя параметра
+
+        Returns:
+            Описание параметра или пустая строка, если описание не найдено
+        """
+        # Проверяем, есть ли в документации секция Args или Parameters
+        if "Args:" in doc_string:
+            args_section = doc_string.split("Args:")[1].split("\n\n")[0]
+        elif "Parameters:" in doc_string:
+            args_section = doc_string.split("Parameters:")[1].split("\n\n")[0]
+        else:
+            return ""
+
+        # Ищем описание параметра
+        for line in args_section.split("\n"):
+            line = line.strip()
+            if line.startswith(param_name + ":") or line.startswith(param_name + " :"):
+                return line.split(":", 1)[1].strip()
+
+        return ""
+
+
+# Create dictionary mapping command names to their schemas
+command_schemas: Dict[str, Dict[str, Any]] = {}

mcp_proxy_adapter/api/tool_integration.py

@@ -0,0 +1,131 @@
+"""
+Модуль для интеграции метаданных команд с внешними API инструментами.
+
+Этот модуль обеспечивает преобразование метаданных команд микросервиса 
+в форматы, понятные для внешних систем, таких как OpenAPI, JSON-RPC,
+и других API интерфейсов.
+"""
+
+import json
+import logging
+
+from mcp_proxy_adapter.api.schemas import APIToolDescription
+from mcp_proxy_adapter.commands.command_registry import CommandRegistry
+
+from mcp_proxy_adapter.core.logging import get_global_logger
+logger = logging.getLogger(__name__)
+
+
+class ToolIntegration:
+    """
+    Класс для интеграции метаданных команд с внешними инструментами API.
+
+    Обеспечивает генерацию описаний инструментов API для различных систем
+    на основе метаданных команд микросервиса.
+    """
+
+    @classmethod
+    def generate_tool_schema(
+        cls,
+        tool_name: str,
+        registry: CommandRegistry,
+        description: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Генерирует схему инструмента API для использования в OpenAPI и других системах.
+
+        Args:
+            tool_name: Имя инструмента API
+            registry: Реестр команд
+            description: Дополнительное описание инструмента (опционально)
+
+        Returns:
+            Словарь с описанием инструмента в формате OpenAPI
+        """
+        # Получаем базовое описание инструмента
+        base_description = APIToolDescription.generate_tool_description(
+            tool_name, registry
+        )
+
+        # Получаем типы параметров
+        parameter_types = cls._extract_parameter_types(
+            base_description["supported_commands"]
+        )
+
+        # Формируем схему инструмента
+        schema = {
+            "name": tool_name,
+            "description": description or base_description["description"],
+            "parameters": {
+                "properties": {
+                    "command": {
+                        "description": "Команда для выполнения",
+                        "type": "string",
+                        "enum": list(base_description["supported_commands"].keys()),
+                    },
+                    "params": {
+                        "description": "Параметры команды",
+                        "type": "object",
+                        "additionalProperties": True,
+                        "properties": parameter_types,
+                    },
+                },
+                "required": ["command"],
+                "type": "object",
+            },
+        }
+
+        return schema
+
+    @classmethod
+
+    @classmethod
+
+    @classmethod
+    def _extract_parameter_types(
+        cls, commands: Dict[str, Dict[str, Any]]
+    ) -> Dict[str, Dict[str, Any]]:
+        """
+        Извлекает типы параметров из описания команд для формирования схемы.
+
+        Args:
+            commands: Словарь с описанием команд
+
+        Returns:
+            Словарь с типами параметров для схемы OpenAPI
+        """
+        parameter_types = {}
+
+        # Формируем словарь типов для всех параметров всех команд
+        for cmd_name, cmd_info in commands.items():
+            params = cmd_info.get("params", {})
+            if params is None:
+                continue
+            for param_name, param_info in params.items():
+                param_type = param_info.get("type", "значение")
+
+                # Преобразуем русские типы в типы JSON Schema
+                if param_type == "строка":
+                    json_type = "string"
+                elif param_type == "целое число":
+                    json_type = "integer"
+                elif param_type == "число":
+                    json_type = "number"
+                elif param_type == "логическое значение":
+                    json_type = "boolean"
+                elif param_type == "список":
+                    json_type = "array"
+                elif param_type == "объект":
+                    json_type = "object"
+                else:
+                    json_type = "string"
+
+                # Добавляем тип в общий словарь
+                parameter_types[param_name] = {
+                    "type": json_type,
+                    "description": param_info.get("description", ""),
+                }
+
+        return parameter_types
+
+

mcp_proxy_adapter/api/tools.py

@@ -0,0 +1,163 @@
+"""
+Модуль с реализацией инструментов 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
+
+from mcp_proxy_adapter.core.logging import get_global_logger
+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 = {}
+
+        get_global_logger().info(f"Executing command via TST: {command}, params: {params}")
+
+        try:
+            # Проверяем существование команды
+            if not registry.command_exists_with_priority(command):
+                raise NotFoundError(f"Команда '{command}' не найдена")
+
+            # Получаем класс команды
+            command_class = registry.get_command_with_priority(command)
+
+            # Выполняем команду
+            result = await command_class.execute(**params)
+
+            # Возвращаем результат
+            return result.to_dict()
+        except NotFoundError as e:
+            get_global_logger().error(f"Command not found: {command}")
+            raise
+        except Exception as e:
+            get_global_logger().exception(f"Error executing command {command}: {e}")
+            raise
+
+    @classmethod
+
+    @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}
+
+
+
+

mcp_proxy_adapter/cli/__init__.py

@@ -0,0 +1,12 @@
+"""
+MCP Proxy Adapter CLI Module
+
+This module provides command-line interface for MCP Proxy Adapter framework.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from .main import main
+
+__all__ = ['main']

mcp_proxy_adapter/cli/commands/__init__.py

@@ -0,0 +1,15 @@
+"""
+CLI Commands Module
+
+This module contains all CLI commands for MCP Proxy Adapter.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from .generate import GenerateCommand
+from .testconfig import TestConfigCommand
+from .server import ServerCommand
+from .sets import SetsCommand
+
+__all__ = ['GenerateCommand', 'TestConfigCommand', 'ServerCommand', 'SetsCommand']

mcp_proxy_adapter/cli/commands/client.py

@@ -0,0 +1,100 @@
+"""
+MCP Client Command
+
+Client CLI for calling health and JSON-RPC endpoints in various modes.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import requests
+from mcp_proxy_adapter.client.proxy import ProxyClient
+
+
+def _build_base_url(protocol: str, host: str, port: int) -> str:
+    scheme = "https" if protocol == "https" else "http"
+    return f"{scheme}://{host}:{port}"
+
+
+def _request_kwargs(protocol: str, token_header: Optional[str], token: Optional[str],
+                    cert: Optional[str], key: Optional[str], ca: Optional[str]) -> Dict[str, Any]:
+    headers: Dict[str, str] = {"Content-Type": "application/json"}
+    if token_header and token:
+        headers[token_header] = token
+
+    kwargs: Dict[str, Any] = {"headers": headers, "timeout": 10}
+
+    if protocol == "https":
+        if cert and key:
+            kwargs["cert"] = (cert, key)
+        # For examples we allow self-signed; if CA provided, use it, otherwise disable verification
+        if ca:
+            kwargs["verify"] = str(Path(ca))
+        else:
+            kwargs["verify"] = False
+
+    return kwargs
+
+
+def client_command(args) -> int:
+    """Dispatch client subcommands."""
+    protocol = args.protocol
+    host = args.host
+    port = args.port
+    base = _build_base_url(protocol, host, port)
+    kwargs = _request_kwargs(
+        protocol,
+        getattr(args, "token_header", None),
+        getattr(args, "token", None),
+        getattr(args, "cert", None),
+        getattr(args, "key", None),
+        getattr(args, "ca", None),
+    )
+
+    try:
+        if args.client_command == "health":
+            resp = requests.get(f"{base}/health", **kwargs)
+            print(json.dumps(resp.json(), ensure_ascii=False))
+            return 0 if resp.ok else 1
+
+        if args.client_command == "jsonrpc":
+            payload: Dict[str, Any] = {
+                "jsonrpc": "2.0",
+                "method": args.method,
+                "params": json.loads(args.params) if args.params else {},
+                "id": args.id,
+            }
+            resp = requests.post(f"{base}/api/jsonrpc", data=json.dumps(payload), **kwargs)
+            print(json.dumps(resp.json(), ensure_ascii=False))
+            return 0 if resp.ok else 1
+
+        if args.client_command == "proxy-register":
+            pc = ProxyClient(args.proxy_url)
+            res = pc.register(args.name, args.url, capabilities=args.capabilities or [], metadata=None)
+            print(json.dumps(res, ensure_ascii=False))
+            return 0
+
+        if args.client_command == "proxy-unregister":
+            pc = ProxyClient(args.proxy_url)
+            res = pc.unregister(args.name)
+            print(json.dumps(res, ensure_ascii=False))
+            return 0
+
+        if args.client_command == "proxy-list":
+            pc = ProxyClient(args.proxy_url)
+            res = pc.list_servers()
+            print(json.dumps(res, ensure_ascii=False))
+            return 0
+
+        print("Available: client health|jsonrpc")
+        return 1
+
+    except Exception as exc:  # noqa: BLE001 (keep simple CLI handling)
+        print(f"❌ Client error: {exc}")
+        return 1
+
+