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

docs/validation_ru.md

@@ -1,287 +0,0 @@
-# Валидация команд и обработка ошибок
-
-В этом документе описаны процессы валидации команд в 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

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

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

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