mcp-proxy-adapter 2.0.2__py3-none-any.whl → 2.1.1__py3-none-any.whl

docs/validation_ru.md

@@ -0,0 +1,287 @@
+# Валидация команд и обработка ошибок
+
+В этом документе описаны процессы валидации команд в Command Registry и способы обработки ошибок.
+
+## Содержание
+
+- [Процесс валидации](#процесс-валидации)
+- [Типы валидаторов](#типы-валидаторов)
+- [Режимы работы](#режимы-работы)
+- [Типы ошибок](#типы-ошибок)
+- [Обработка ошибок](#обработка-ошибок)
+- [Автоматическое исправление](#автоматическое-исправление)
+
+## Процесс валидации
+
+Валидация команд выполняется перед их регистрацией в диспетчере. Процесс включает следующие шаги:
+
+1. **Анализ исходного кода**: извлечение метаданных из докстрингов и аннотаций типов
+2. **Проверка соответствия**: сравнение метаданных с формальными параметрами функции
+3. **Принятие решения**: регистрация команды или вывод ошибок в зависимости от режима работы
+
+```python
+# Основной процесс валидации в методе register_command
+def register_command(self, command_name: str, handler: Callable) -> bool:
+    # Анализ обработчика
+    metadata = self.analyze_handler(command_name, handler)
+    
+    # Валидация метаданных
+    is_valid, errors = self.validate_handler(command_name, handler, metadata)
+    
+    # Вывод ошибок, если они есть
+    if not is_valid:
+        for error in errors:
+            logger.error(f"{command_name}: {error}")
+        
+        # В строгом режиме прерываем регистрацию
+        if self.strict and not self.auto_fix:
+            return False
+    
+    # Регистрация команды
+    self.dispatcher.register_handler(
+        command=command_name,
+        handler=handler,
+        description=metadata["description"],
+        summary=metadata["summary"],
+        params=metadata["parameters"]
+    )
+    
+    return True
+```
+
+## Типы валидаторов
+
+Command Registry включает несколько типов валидаторов для разных аспектов проверки:
+
+### 1. DocstringValidator
+
+Проверяет соответствие докстрингов формальным параметрам функции:
+
+- Наличие описания функции
+- Описание всех параметров в секции Args
+- Наличие секции Returns
+- Соответствие имен параметров в докстринге и сигнатуре функции
+
+```python
+class DocstringValidator:
+    def validate(self, handler: Callable, command_name: str, metadata: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        errors = []
+        
+        # Получаем формальные параметры функции
+        sig = inspect.signature(handler)
+        formal_params = list(sig.parameters.keys())
+        
+        # Парсим докстринг
+        docstring = handler.__doc__ or ""
+        parsed_doc = docstring_parser.parse(docstring)
+        
+        # Проверяем наличие описания функции
+        if not parsed_doc.short_description and not parsed_doc.long_description:
+            errors.append(f"Отсутствует описание функции")
+        
+        # Получаем параметры из докстринга
+        doc_params = {param.arg_name: param for param in parsed_doc.params}
+        
+        # Проверяем, что все формальные параметры описаны в докстринге
+        for param in formal_params:
+            if param not in doc_params and param != 'params':
+                errors.append(f"Параметр '{param}' не описан в докстринге функции")
+        
+        # Проверяем наличие returns в докстринге
+        if not parsed_doc.returns:
+            errors.append(f"Отсутствует описание возвращаемого значения в докстринге функции")
+        
+        return len(errors) == 0, errors
+```
+
+### 2. MetadataValidator
+
+Проверяет соответствие метаданных команды её сигнатуре:
+
+- Наличие всех обязательных параметров в метаданных
+- Соответствие типов параметров в метаданных и аннотациях
+- Отсутствие лишних параметров в метаданных
+
+```python
+class MetadataValidator:
+    def validate(self, handler: Callable, command_name: str, metadata: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        errors = []
+        
+        # Получаем формальные параметры функции
+        sig = inspect.signature(handler)
+        
+        # Проверяем соответствие метаданных и формальных параметров
+        if "parameters" in metadata:
+            for param_name, param_info in metadata["parameters"].items():
+                # Проверяем наличие параметра в сигнатуре функции
+                if param_name not in sig.parameters:
+                    errors.append(f"Параметр '{param_name}' указан в метаданных, но отсутствует в сигнатуре функции")
+            
+            # Проверяем, что все обязательные параметры указаны в метаданных
+            for param_name, param in sig.parameters.items():
+                if param.default == inspect.Parameter.empty and param_name != 'self':
+                    if param_name not in metadata["parameters"]:
+                        errors.append(f"Обязательный параметр '{param_name}' не указан в метаданных")
+        
+        return len(errors) == 0, errors
+```
+
+## Режимы работы
+
+Command Registry поддерживает несколько режимов валидации, которые определяют поведение при обнаружении ошибок:
+
+### 1. Строгий режим (strict=True)
+
+В строгом режиме система отказывается регистрировать команды с ошибками в документации:
+
+- При обнаружении любой ошибки в документации команда не регистрируется
+- Выводятся подробные сообщения об ошибках для каждой команды
+- Рекомендуется использовать в CI/CD и продакшене для обеспечения качества кода
+
+```python
+# Пример использования строгого режима
+registry = CommandRegistry(strict=True, auto_fix=False)
+registry.register_all_commands()  # Команды с ошибками не будут зарегистрированы
+```
+
+### 2. Нестрогий режим (strict=False)
+
+В нестрогом режиме система регистрирует все команды, даже с ошибками:
+
+- При обнаружении ошибок выводятся предупреждения, но команда регистрируется
+- Может привести к неточностям в документации API
+- Полезен для быстрого прототипирования и отладки
+
+```python
+# Пример использования нестрогого режима
+registry = CommandRegistry(strict=False, auto_fix=False)
+registry.register_all_commands()  # Все команды будут зарегистрированы
+```
+
+### 3. Режим автоисправления (auto_fix=True)
+
+В режиме автоисправления система пытается автоматически исправить ошибки:
+
+- Недостающие метаданные извлекаются из аннотаций типов
+- Улучшается документация на основе имеющейся информации
+- Полезен при разработке, когда документация еще не полностью оформлена
+
+```python
+# Пример использования режима автоисправления
+registry = CommandRegistry(strict=True, auto_fix=True)
+registry.register_all_commands()  # Система попытается исправить ошибки
+```
+
+## Типы ошибок
+
+Валидаторы могут обнаруживать различные типы ошибок:
+
+### 1. Ошибки докстрингов
+
+- **Отсутствие описания функции**: докстринг пуст или содержит только код
+- **Отсутствие описания параметра**: параметр функции не описан в докстринге
+- **Отсутствие описания возвращаемого значения**: нет секции Returns
+- **Лишние параметры в докстринге**: в докстринге описаны параметры, которых нет в функции
+
+### 2. Ошибки метаданных
+
+- **Несоответствие типов**: тип в метаданных не соответствует аннотации типа
+- **Отсутствие обязательного параметра**: обязательный параметр не описан в метаданных
+- **Лишние параметры в метаданных**: в метаданных указаны параметры, которых нет в функции
+- **Некорректное описание**: отсутствует или неполное описание команды или параметра
+
+### 3. Ошибки аннотаций типов
+
+- **Отсутствие аннотации типа**: параметр не имеет аннотации типа
+- **Отсутствие аннотации возвращаемого значения**: функция не имеет аннотации возвращаемого значения
+- **Несоответствие типов в аннотациях и метаданных**: тип в аннотации не соответствует типу в метаданных
+
+## Обработка ошибок
+
+При обнаружении ошибок Command Registry предоставляет подробную информацию для их исправления:
+
+```
+🚫 Ошибки в команде 'search_by_vector':
+   - Параметр 'top_k' не описан в докстринге функции
+   - Отсутствует описание возвращаемого значения в докстринге функции
+   - Обязательный параметр 'vector' не указан в метаданных команды
+```
+
+В зависимости от режима работы, система может:
+
+1. **Отказаться регистрировать команду** (strict=True, auto_fix=False)
+2. **Зарегистрировать команду с предупреждениями** (strict=False)
+3. **Попытаться исправить ошибки автоматически** (auto_fix=True)
+
+### Рекомендуемый подход к обработке ошибок
+
+1. **В разработке**:
+   - Использовать auto_fix=True для автоматического исправления ошибок
+   - Регулярно запускать валидацию в строгом режиме для выявления проблем
+
+2. **В CI/CD**:
+   - Использовать strict=True для блокирования PR с ошибками в документации
+   - Добавить проверку валидации команд в процесс тестирования
+
+3. **В продакшене**:
+   - Всегда использовать strict=True для гарантии качества документации
+   - Никогда не использовать auto_fix=True в продакшен-среде
+
+## Автоматическое исправление
+
+Когда включен режим auto_fix=True, система пытается исправить ошибки автоматически:
+
+### 1. Дополнение метаданных
+
+Если метаданные неполные, система дополняет их на основе:
+
+- Аннотаций типов для определения типов параметров
+- Сигнатуры функции для определения обязательных параметров
+- Значений по умолчанию для определения default значений
+
+```python
+# Дополнение метаданных на основе аннотаций типов
+type_hints = get_type_hints(handler)
+for param_name, param_type in type_hints.items():
+    if param_name == 'return':
+        continue
+        
+    if param_name not in metadata["parameters"]:
+        metadata["parameters"][param_name] = {
+            "type": map_type_to_openapi(param_type),
+            "description": f"Параметр {param_name}",
+            "required": param_name in required_params
+        }
+```
+
+### 2. Извлечение описаний из докстрингов
+
+Если докстринги есть, но метаданные неполные, система извлекает описания из докстрингов:
+
+```python
+# Извлечение описаний из докстрингов
+parsed_doc = docstring_parser.parse(handler.__doc__ or "")
+for param in parsed_doc.params:
+    param_name = param.arg_name
+    if param_name in metadata["parameters"]:
+        metadata["parameters"][param_name]["description"] = param.description
+```
+
+### 3. Генерация базовых описаний
+
+Если описания отсутствуют, система генерирует базовые описания:
+
+```python
+# Генерация базовых описаний
+if not metadata.get("description"):
+    metadata["description"] = f"Команда {command_name}"
+
+if not metadata.get("summary"):
+    metadata["summary"] = command_name.replace("_", " ").title()
+```
+
+## Заключение
+
+Система валидации Command Registry помогает обеспечить высокое качество документации API за счет строгой проверки соответствия докстрингов, метаданных и сигнатур функций. 
+
+Рекомендуется использовать строгий режим валидации (strict=True) для гарантии качества документации, особенно в процессе CI/CD и в продакшен-среде. Режим автоисправления (auto_fix=True) полезен на ранних этапах разработки, когда документация еще не полностью оформлена. 

examples/analyze_config.py

@@ -0,0 +1,141 @@
+"""
+Analysis of MCP Proxy configuration generated by the adapter.
+
+This script loads and analyzes the MCP Proxy configuration file
+that was created by MCPProxyAdapter, and outputs structured
+information about routes and tools.
+
+Usage:
+    python examples/analyze_config.py
+"""
+import os
+import json
+import sys
+from typing import Dict, Any, List
+
+
+def load_config_file(config_path: str) -> Dict[str, Any]:
+    """
+    Loads MCP Proxy configuration file.
+    
+    Args:
+        config_path (str): Path to configuration file
+        
+    Returns:
+        Dict[str, Any]: Loaded configuration
+        
+    Raises:
+        FileNotFoundError: If file is not found
+        json.JSONDecodeError: If file is not valid JSON
+    """
+    try:
+        with open(config_path, 'r', encoding='utf-8') as f:
+            return json.load(f)
+    except FileNotFoundError:
+        print(f"Error: Configuration file not found: {config_path}")
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"Error: File is not valid JSON: {e}")
+        sys.exit(1)
+
+
+def print_routes(config: Dict[str, Any]) -> None:
+    """
+    Prints route information from configuration.
+    
+    Args:
+        config (Dict[str, Any]): MCP Proxy configuration
+    """
+    if "routes" not in config:
+        print("No routes in configuration")
+        return
+    
+    routes = config["routes"]
+    print(f"=== Routes ({len(routes)}) ===")
+    
+    for i, route in enumerate(routes, 1):
+        print(f"\n{i}. Route:")
+        print(f"   Endpoint: {route.get('endpoint', 'Not specified')}")
+        print(f"   Method: {route.get('method', 'Not specified')}")
+        
+        if "json_rpc" in route:
+            print("   Type: JSON-RPC")
+            if "params" in route["json_rpc"]:
+                print(f"   Parameters: {route['json_rpc'].get('params', 'Not specified')}")
+        else:
+            print("   Type: Regular HTTP")
+
+
+def print_tools(config: Dict[str, Any]) -> None:
+    """
+    Prints tool information from configuration.
+    
+    Args:
+        config (Dict[str, Any]): MCP Proxy configuration
+    """
+    if "tools" not in config:
+        print("No tools in configuration")
+        return
+    
+    tools = config["tools"]
+    print(f"\n=== Tools ({len(tools)}) ===")
+    
+    for i, tool in enumerate(tools, 1):
+        print(f"\n{i}. Tool:")
+        print(f"   Name: {tool.get('name', 'Not specified')}")
+        print(f"   Description: {tool.get('description', 'Not specified')}")
+        
+        if "parameters" in tool:
+            params = tool["parameters"]
+            required_params = params.get("required", [])
+            properties = params.get("properties", {})
+            
+            print(f"   Parameters ({len(properties)}):") 
+            for param_name, param_info in properties.items():
+                required = "Required" if param_name in required_params else "Optional"
+                param_type = param_info.get("type", "Not specified")
+                description = param_info.get("description", "Not specified")
+                
+                print(f"     - {param_name} ({param_type}, {required}):")
+                print(f"       {description}")
+
+
+def analyze_config(config_path: str) -> None:
+    """
+    Analyzes MCP Proxy configuration.
+    
+    Args:
+        config_path (str): Path to configuration file
+    """
+    config = load_config_file(config_path)
+    
+    print("\n=== MCP Proxy Configuration Analysis ===")
+    print(f"File: {config_path}")
+    print(f"Version: {config.get('version', 'Not specified')}")
+    
+    print_routes(config)
+    print_tools(config)
+    
+    print("\n=== Summary ===")
+    num_routes = len(config.get("routes", []))
+    num_tools = len(config.get("tools", []))
+    
+    print(f"Configuration contains {num_routes} routes and {num_tools} tools.")
+    
+    if num_tools > 0 and num_routes > 0:
+        print("MCP Proxy is configured correctly and ready to use.")
+    else:
+        print("WARNING: Configuration may be incomplete or incorrect.")
+
+
+def main():
+    """Main script function."""
+    # Define path to configuration file
+    config_path = os.path.join(os.path.dirname(__file__), "mcp_proxy_config.json")
+    
+    # Analyze configuration
+    analyze_config(config_path)
+
+
+if __name__ == "__main__":
+    main() 

examples/basic_integration.py

@@ -0,0 +1,161 @@
+"""
+Example of basic MCPProxyAdapter integration with an existing FastAPI application.
+"""
+import logging
+import os
+import sys
+from typing import Dict, Any, List, Optional
+
+# Add parent directory to import path
+current_dir = os.path.dirname(os.path.abspath(__file__))
+parent_dir = os.path.dirname(current_dir)
+if parent_dir not in sys.path:
+    sys.path.insert(0, parent_dir)
+
+from fastapi import FastAPI, HTTPException, APIRouter
+from pydantic import BaseModel
+
+# Import from installed package or local file
+try:
+    from mcp_proxy_adapter.adapter import MCPProxyAdapter, configure_logger
+    from mcp_proxy_adapter.registry import CommandRegistry
+except ImportError:
+    from src.adapter import MCPProxyAdapter, configure_logger
+    from src.registry import CommandRegistry
+
+# Configure project logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+# Create project logger
+project_logger = logging.getLogger("my_project")
+project_logger.setLevel(logging.DEBUG)
+
+# Configure adapter logger using project logger
+adapter_logger = configure_logger(project_logger)
+
+# Create FastAPI application
+app = FastAPI(
+    title="My API with MCP Proxy Integration",
+    description="API with Command Registry integration, supporting MCP Proxy",
+    version="1.0.0"
+)
+
+# Define existing endpoints
+router = APIRouter()
+
+class Item(BaseModel):
+    name: str
+    price: float
+    is_active: bool = True
+
+@router.get("/items", response_model=List[Item])
+async def get_items():
+    """Returns list of items."""
+    return [
+        {"name": "Item 1", "price": 10.5, "is_active": True},
+        {"name": "Item 2", "price": 20.0, "is_active": False},
+        {"name": "Item 3", "price": 30.0, "is_active": True},
+    ]
+
+@router.get("/items/{item_id}", response_model=Item)
+async def get_item(item_id: int):
+    """Returns item information by ID."""
+    items = [
+        {"name": "Item 1", "price": 10.5, "is_active": True},
+        {"name": "Item 2", "price": 20.0, "is_active": False},
+        {"name": "Item 3", "price": 30.0, "is_active": True},
+    ]
+    
+    if item_id < 1 or item_id > len(items):
+        raise HTTPException(status_code=404, detail="Item not found")
+    
+    return items[item_id - 1]
+
+# Add existing endpoints to application
+app.include_router(router)
+
+# Define commands for Command Registry
+def list_items() -> List[Dict[str, Any]]:
+    """
+    Returns list of all items.
+    
+    Returns:
+        List[Dict[str, Any]]: List of items
+    """
+    return [
+        {"name": "Item 1", "price": 10.5, "is_active": True},
+        {"name": "Item 2", "price": 20.0, "is_active": False},
+        {"name": "Item 3", "price": 30.0, "is_active": True},
+    ]
+
+def get_item_by_id(item_id: int) -> Dict[str, Any]:
+    """
+    Returns item information by ID.
+    
+    Args:
+        item_id: Item ID
+        
+    Returns:
+        Dict[str, Any]: Item information
+        
+    Raises:
+        ValueError: If item is not found
+    """
+    items = list_items()
+    
+    if item_id < 1 or item_id > len(items):
+        raise ValueError(f"Item with ID {item_id} not found")
+    
+    return items[item_id - 1]
+
+def search_items(query: str, min_price: Optional[float] = None, max_price: Optional[float] = None) -> List[Dict[str, Any]]:
+    """
+    Searches for items by name and price range.
+    
+    Args:
+        query: Search query for name
+        min_price: Minimum price (optional)
+        max_price: Maximum price (optional)
+        
+    Returns:
+        List[Dict[str, Any]]: List of found items
+    """
+    items = list_items()
+    
+    # Filter by name
+    filtered_items = [item for item in items if query.lower() in item["name"].lower()]
+    
+    # Filter by minimum price
+    if min_price is not None:
+        filtered_items = [item for item in filtered_items if item["price"] >= min_price]
+    
+    # Filter by maximum price
+    if max_price is not None:
+        filtered_items = [item for item in filtered_items if item["price"] <= max_price]
+    
+    return filtered_items
+
+# Create CommandRegistry instance
+registry = CommandRegistry()
+
+# Register commands
+registry.register_command("list_items", list_items)
+registry.register_command("get_item", get_item_by_id)
+registry.register_command("search_items", search_items)
+
+# Create MCP Proxy adapter
+adapter = MCPProxyAdapter(registry)
+
+# Register endpoints in existing application
+adapter.register_endpoints(app)
+
+# Save configuration for MCP Proxy
+adapter.save_config_to_file("mcp_proxy_config.json")
+
+# Entry point for running the application
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000) 

examples/docstring_and_schema_example.py

@@ -0,0 +1,60 @@
+"""
+Docstring and Schema Example for MCPProxyAdapter
+
+- How to write docstrings for commands
+- How docstrings are used in OpenAPI/schema
+- Best practices for documenting parameters and return values
+
+Run:
+    python examples/docstring_and_schema_example.py
+"""
+import os
+import sys
+sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+class MyRegistry:
+    def __init__(self):
+        self.dispatcher = self
+        self.commands = {"sum": self.sum_numbers}
+        self.commands_info = {
+            "sum": {
+                "description": self.sum_numbers.__doc__,
+                "params": {
+                    "a": {"type": "integer", "description": "First number", "required": True},
+                    "b": {"type": "integer", "description": "Second number", "required": True}
+                }
+            }
+        }
+    def get_valid_commands(self):
+        return list(self.commands.keys())
+    def get_command_info(self, command):
+        return self.commands_info.get(command)
+    def get_commands_info(self):
+        return self.commands_info
+    def execute(self, command, **params):
+        if command == "sum":
+            return self.sum_numbers(**params)
+        raise KeyError(f"Unknown command: {command}")
+    def add_generator(self, generator):
+        pass
+    def sum_numbers(self, a: int, b: int) -> int:
+        """
+        Returns the sum of two numbers.
+        
+        Args:
+            a (int): First number
+            b (int): Second number
+        
+        Returns:
+            int: The sum of a and b
+        """
+        return a + b
+
+if __name__ == "__main__":
+    registry = MyRegistry()
+    adapter = MCPProxyAdapter(registry)
+    # Print OpenAPI schema (simulated)
+    schema = adapter.generate_mcp_proxy_config()
+    print("=== Tool description from docstring ===")
+    print(schema.tools[0].description)