mcp-proxy-adapter 2.1.0__py3-none-any.whl → 2.1.2__py3-none-any.whl

docs/README.md

@@ -0,0 +1,172 @@
+# Command Registry
+
+## Overview
+
+Command Registry is a high-level system for centralized command management in applications. It provides a unified mechanism for defining, registering, executing, and documenting commands through various interfaces.
+
+## Key Features
+
+- **Single access point** for application commands
+- **Automatic metadata extraction** from Python docstrings and type hints
+- **Integration with various protocols** (REST, JSON-RPC, WebSockets)
+- **API documentation generation** based on command metadata
+- **Input parameters and output values validation**
+- **Metadata compliance verification** with actual function signatures
+- **Extensibility** through interfaces for dispatchers, adapters, and schema generators
+- **AI model integration** via MCP Proxy Adapter
+
+## Getting Started
+
+### Installation
+
+```bash
+pip install command-registry
+```
+
+For MCP Proxy integration, also install:
+
+```bash
+pip install mcp-proxy-adapter
+```
+
+### Simple Example
+
+```python
+from command_registry import CommandRegistry
+
+# Create a command registry instance
+registry = CommandRegistry()
+
+# Define a command
+def add_numbers(a: int, b: int) -> int:
+    """Adds two numbers.
+    
+    Args:
+        a: First number
+        b: Second number
+        
+    Returns:
+        Sum of numbers a and b
+    """
+    return a + b
+
+# Register the command
+registry.register_command("add", add_numbers)
+
+# Execute the command
+result = registry.execute("add", {"a": 5, "b": 3})  # Returns 8
+```
+
+### FastAPI Export
+
+```python
+from fastapi import FastAPI
+from command_registry.adapters import RESTAdapter
+
+app = FastAPI()
+adapter = RESTAdapter(registry)
+adapter.register_endpoints(app)
+```
+
+### MCP Proxy Integration for AI Models
+
+```python
+from fastapi import FastAPI
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+app = FastAPI()
+adapter = MCPProxyAdapter(registry)
+adapter.register_endpoints(app)
+
+# Create configuration for MCP Proxy
+adapter.save_config_to_file("mcp_proxy_config.json")
+```
+
+### Automatic Command Registration from Module
+
+```python
+# Scan module and register all found commands
+registry.scan_module("myapp.commands")
+```
+
+## Documentation
+
+- [Architecture](architecture.md) - detailed component description
+- [Command Development Guide](command_development.md) - best practices
+- [Examples](examples.md) - usage examples for various scenarios
+- [Validation](validation.md) - command validation mechanisms
+- [MCP Proxy Adapter](mcp_proxy_adapter.md) - AI model integration via MCP Proxy
+
+## Project Structure
+
+```
+command_registry/
+  ├── __init__.py            # Main public API
+  ├── core.py                # Core CommandRegistry logic
+  ├── dispatchers/           # Command dispatchers
+  │   ├── __init__.py
+  │   ├── base_dispatcher.py  # Abstract base class
+  │   └── command_dispatcher.py  # Main implementation
+  ├── metadata/              # Metadata extraction
+  │   ├── __init__.py
+  │   ├── docstring_parser.py  # Docstring parser
+  │   └── type_analyzer.py   # Type analyzer
+  ├── validators/            # Validators
+  │   ├── __init__.py
+  │   └── parameter_validator.py  # Parameter validation
+  ├── adapters/              # Protocol adapters
+  │   ├── __init__.py
+  │   ├── rest_adapter.py    # REST API
+  │   └── json_rpc_adapter.py  # JSON-RPC
+  └── schema/                # Schema generators
+      ├── __init__.py
+      ├── openapi_generator.py  # OpenAPI
+      └── json_schema_generator.py  # JSON Schema
+```
+
+## Integration with Existing Systems
+
+Command Registry is designed for easy integration with existing systems and frameworks:
+
+- **FastAPI** - via RESTAdapter
+- **Flask** - via RESTAdapter with modifications
+- **aiohttp** - via WebSockets adapter
+- **Click** - via CLI adapter
+- **GraphQL** - via GraphQL adapter
+- **MCP Proxy** - via MCPProxyAdapter for AI model integration
+
+## Usage Examples
+
+### REST API
+
+```python
+from fastapi import FastAPI
+from command_registry import CommandRegistry
+from command_registry.adapters import RESTAdapter
+
+app = FastAPI()
+registry = CommandRegistry()
+registry.scan_module("myapp.commands")
+
+adapter = RESTAdapter(registry)
+adapter.register_endpoints(app)
+```
+
+### JSON-RPC via MCP Proxy Adapter
+
+```python
+from fastapi import FastAPI
+from command_registry import CommandRegistry
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+app = FastAPI()
+registry = CommandRegistry()
+registry.scan_module("myapp.commands")
+
+adapter = MCPProxyAdapter(registry)
+adapter.register_endpoints(app)
+```
+
+## License
+
+MIT 

docs/README_ru.md

@@ -0,0 +1,172 @@
+# Command Registry
+
+## Обзор
+
+Command Registry - это высокоуровневая система для централизованного управления командами в приложении. Она предоставляет унифицированный механизм определения, регистрации, выполнения и документирования команд через различные интерфейсы.
+
+## Основные возможности
+
+- **Единая точка доступа** к командам приложения
+- **Автоматическое извлечение метаданных** из докстрингов и типизации Python
+- **Интеграция с различными протоколами** (REST, JSON-RPC, WebSockets)
+- **Генерация документации API** на основе метаданных команд
+- **Валидация входных параметров** и выходных значений
+- **Проверка соответствия метаданных** фактической сигнатуре функций
+- **Расширяемость** через интерфейсы для диспетчеров, адаптеров и генераторов схем
+- **Интеграция с моделями ИИ** через MCP Proxy Adapter
+
+## Начало работы
+
+### Установка
+
+```bash
+pip install command-registry
+```
+
+Для работы с MCP Proxy также установите:
+
+```bash
+pip install mcp-proxy-adapter
+```
+
+### Простой пример
+
+```python
+from command_registry import CommandRegistry
+
+# Создание экземпляра реестра команд
+registry = CommandRegistry()
+
+# Определение команды
+def add_numbers(a: int, b: int) -> int:
+    """Складывает два числа.
+    
+    Args:
+        a: Первое число
+        b: Второе число
+        
+    Returns:
+        Сумма чисел a и b
+    """
+    return a + b
+
+# Регистрация команды
+registry.register_command("add", add_numbers)
+
+# Выполнение команды
+result = registry.execute("add", {"a": 5, "b": 3})  # Вернёт 8
+```
+
+### Экспорт через FastAPI
+
+```python
+from fastapi import FastAPI
+from command_registry.adapters import RESTAdapter
+
+app = FastAPI()
+adapter = RESTAdapter(registry)
+adapter.register_endpoints(app)
+```
+
+### Интеграция с MCP Proxy для моделей ИИ
+
+```python
+from fastapi import FastAPI
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+app = FastAPI()
+adapter = MCPProxyAdapter(registry)
+adapter.register_endpoints(app)
+
+# Создание конфигурации для MCP Proxy
+adapter.save_config_to_file("mcp_proxy_config.json")
+```
+
+### Автоматическая регистрация команд из модуля
+
+```python
+# Сканирование модуля и регистрация всех найденных команд
+registry.scan_module("myapp.commands")
+```
+
+## Документация
+
+- [Архитектура](architecture.md) - подробное описание компонентов
+- [Руководство по разработке команд](command_development.md) - лучшие практики
+- [Примеры](examples.md) - примеры использования для различных сценариев
+- [Валидация](validation.md) - механизмы проверки команд
+- [MCP Proxy Adapter](mcp_proxy_adapter.md) - интеграция с моделями ИИ через MCP Proxy
+
+## Структура проекта
+
+```
+command_registry/
+  ├── __init__.py            # Основные публичные API
+  ├── core.py                # Основная логика CommandRegistry
+  ├── dispatchers/           # Диспетчеры команд
+  │   ├── __init__.py
+  │   ├── base_dispatcher.py  # Абстрактный базовый класс
+  │   └── command_dispatcher.py  # Основная реализация
+  ├── metadata/              # Извлечение метаданных
+  │   ├── __init__.py
+  │   ├── docstring_parser.py  # Парсер докстрингов
+  │   └── type_analyzer.py   # Анализатор типов
+  ├── validators/            # Валидаторы
+  │   ├── __init__.py
+  │   └── parameter_validator.py  # Валидация параметров
+  ├── adapters/              # Адаптеры протоколов
+  │   ├── __init__.py
+  │   ├── rest_adapter.py    # REST API
+  │   └── json_rpc_adapter.py  # JSON-RPC
+  └── schema/                # Генераторы схем
+      ├── __init__.py
+      ├── openapi_generator.py  # OpenAPI
+      └── json_schema_generator.py  # JSON Schema
+```
+
+## Интеграция с существующими системами
+
+Command Registry спроектирован для легкой интеграции с существующими системами и фреймворками:
+
+- **FastAPI** - через RESTAdapter
+- **Flask** - через RESTAdapter с модификациями
+- **aiohttp** - через адаптер для WebSockets
+- **Click** - через CLI адаптер
+- **GraphQL** - через GraphQL адаптер
+- **MCP Proxy** - через MCPProxyAdapter для интеграции с моделями ИИ
+
+## Примеры использования
+
+### REST API
+
+```python
+from fastapi import FastAPI
+from command_registry import CommandRegistry
+from command_registry.adapters import RESTAdapter
+
+app = FastAPI()
+registry = CommandRegistry()
+registry.scan_module("myapp.commands")
+
+adapter = RESTAdapter(registry)
+adapter.register_endpoints(app)
+```
+
+### JSON-RPC через MCP Proxy Adapter
+
+```python
+from fastapi import FastAPI
+from command_registry import CommandRegistry
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+app = FastAPI()
+registry = CommandRegistry()
+registry.scan_module("myapp.commands")
+
+adapter = MCPProxyAdapter(registry)
+adapter.register_endpoints(app)
+```
+
+## Лицензия
+
+MIT 

docs/architecture.md

@@ -0,0 +1,251 @@
+# Command Registry Architecture
+
+This document describes the architecture of the Command Registry system, its key components, their interactions, and extension principles.
+
+## Architecture Overview
+
+Command Registry is a modular system built around the concept of centralized command storage and management. The architecture ensures flexibility, extensibility, and adherence to SOLID principles.
+
+Key system capabilities:
+
+1. **Defining commands as Python functions** using type hints and docstrings
+2. **Metadata extraction** from function signatures and their documentation
+3. **Command registration** in a central registry
+4. **Providing a unified interface** for command execution
+5. **API documentation generation** based on command metadata
+6. **Command export** through various protocols (REST, JSON-RPC, CLI, etc.)
+
+## System Components
+
+![Components Diagram](../diagrams/command_registry_components.png)
+
+### Core Components:
+
+1. **Command Definition** - Command definition (Python function with type hints and docstrings)
+2. **Dispatcher Component** - Command dispatcher responsible for registration and execution
+3. **Metadata Extractor** - Extracts metadata from docstrings and function signatures
+4. **Protocol Adapter** - Adapter for exporting commands through various protocols
+
+### CommandRegistry
+
+The central system component that:
+
+- Initializes and configures dispatchers
+- Provides an interface for command registration
+- Manages command metadata
+- Coordinates interaction between components
+
+## Command Lifecycle
+
+### 1. Command Definition
+
+```python
+def calculate_total(
+    prices: List[float], 
+    discount: float = 0.0,
+    tax_rate: float = 0.0
+) -> float:
+    """
+    Calculates total cost including discount and tax.
+    
+    Args:
+        prices: List of item prices
+        discount: Discount percentage (0-100)
+        tax_rate: Tax rate percentage (0-100)
+        
+    Returns:
+        Total cost including discount and tax
+    """
+    subtotal = sum(prices)
+    discounted = subtotal * (1 - discount / 100)
+    total = discounted * (1 + tax_rate / 100)
+    return round(total, 2)
+```
+
+### 2. Command Registration
+
+```python
+from command_registry import CommandRegistry
+from command_registry.dispatchers import CommandDispatcher
+
+# Create command registry
+registry = CommandRegistry(CommandDispatcher())
+
+# Register command
+registry.register_command("calculate_total", calculate_total)
+```
+
+### 3. Command Execution
+
+```python
+# Execute command
+result = registry.execute(
+    "calculate_total", 
+    {
+        "prices": [10.0, 20.0, 30.0],
+        "discount": 10.0,
+        "tax_rate": 7.0
+    }
+)
+print(result)  # 57.33
+```
+
+### 4. API Export
+
+```python
+from fastapi import FastAPI
+from command_registry.adapters import RESTAdapter
+
+app = FastAPI()
+adapter = RESTAdapter(registry)
+adapter.register_endpoints(app)
+```
+
+## Data Flow Diagrams
+
+### Command Registration Process
+
+```
+┌─────────────────┐      ┌────────────────────┐      ┌─────────────────┐
+│                 │      │                    │      │                 │
+│  Python Function├─────►│  Metadata Extractor ├─────►│  Metadata      │
+│                 │      │                    │      │                 │
+└─────────────────┘      └────────────────────┘      └────────┬────────┘
+                                                              │
+                                                              ▼
+┌─────────────────┐      ┌────────────────────┐      ┌─────────────────┐
+│                 │      │                    │      │                 │
+│  CommandRegistry│◄─────┤  Data Validation   │◄─────┤  Parameters    │
+│                 │      │                    │      │                 │
+└────────┬────────┘      └────────────────────┘      └─────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│                 │
+│  Dispatcher     │
+│                 │
+└─────────────────┘
+```
+
+### Command Execution Process
+
+```
+┌─────────────────┐      ┌────────────────────┐      ┌─────────────────┐
+│                 │      │                    │      │                 │
+│  Command Name   │      │                    │      │  Parameter      │
+│  + Parameters   ├─────►│  CommandRegistry   ├─────►│  Validation    │
+│                 │      │                    │      │                 │
+└─────────────────┘      └────────────────────┘      └────────┬────────┘
+                                                              │
+                                                              ▼
+┌─────────────────┐      ┌────────────────────┐      ┌─────────────────┐
+│                 │      │                    │      │                 │
+│  Result         │◄─────┤  Error Handling    │◄─────┤  Dispatcher     │
+│                 │      │                    │      │  (execution)    │
+└─────────────────┘      └────────────────────┘      └─────────────────┘
+```
+
+### API Documentation Generation
+
+```
+┌─────────────────┐      ┌────────────────────┐      ┌─────────────────┐
+│                 │      │                    │      │                 │
+│  Command        │      │  Schema Generator  │      │  OpenAPI/       │
+│  Metadata       ├─────►│                    ├─────►│  JSON Schema    │
+│                 │      │                    │      │                 │
+└─────────────────┘      └────────────────────┘      └────────┬────────┘
+                                                              │
+                                                              ▼
+                                                     ┌─────────────────┐
+                                                     │                 │
+                                                     │  API Docs UI    │
+                                                     │  (Swagger/      │
+                                                     │   ReDoc)        │
+                                                     └─────────────────┘
+```
+
+## System Extension
+
+### Creating a Custom Dispatcher
+
+```python
+from command_registry.dispatchers import BaseDispatcher
+from typing import Dict, Any, List, Optional, Callable
+
+class MyCustomDispatcher(BaseDispatcher):
+    def __init__(self):
+        self._commands = {}
+        self._info = {}
+        
+    def register_handler(
+        self, 
+        command_name: str,
+        handler: Callable,
+        description: str = None,
+        summary: str = None,
+        params: Dict[str, Any] = None
+    ) -> None:
+        self._commands[command_name] = handler
+        self._info[command_name] = {
+            "description": description,
+            "summary": summary,
+            "params": params or {}
+        }
+        
+    def execute(self, command_name: str, params: Dict[str, Any] = None) -> Any:
+        if command_name not in self._commands:
+            raise ValueError(f"Command '{command_name}' not found")
+        
+        handler = self._commands[command_name]
+        return handler(**params or {})
+    
+    def get_valid_commands(self) -> List[str]:
+        return list(self._commands.keys())
+    
+    def get_command_info(self, command_name: str) -> Optional[Dict[str, Any]]:
+        return self._info.get(command_name)
+    
+    def get_commands_info(self) -> Dict[str, Dict[str, Any]]:
+        return self._info
+```
+
+### Creating a Custom Protocol Adapter
+
+```python
+from command_registry import CommandRegistry
+from typing import Dict, Any
+
+class GraphQLAdapter:
+    def __init__(self, registry: CommandRegistry):
+        self.registry = registry
+        
+    def generate_schema(self) -> str:
+        """Generates GraphQL schema based on command metadata."""
+        commands_info = self.registry.get_all_commands_info()
+        schema_types = []
+        query_fields = []
+        
+        for cmd_name, info in commands_info.items():
+            # Generate types for input and output data
+            input_type = self._generate_input_type(cmd_name, info["params"])
+            output_type = self._generate_output_type(cmd_name, info.get("returns"))
+            
+            schema_types.extend([input_type, output_type])
+            
+            # Add field to Query
+            query_fields.append(
+                f"{cmd_name}(input: {cmd_name}Input): {cmd_name}Output"
+            )
+        
+        # Form final schema
+        schema = "\n".join(schema_types)
+        schema += f"\ntype Query {{\n  {chr(10).join(query_fields)}\n}}"
+        
+        return schema
+    
+    def _generate_input_type(self, cmd_name: str, params: Dict[str, Any]) -> str:
+        fields = []
+        for name, param_info in params.items():
+            field_type = self._map_type(param_info.get("type", "String"))
+            required = "!" if param_info.get("required", False) else ""
+```