mcp-proxy-adapter 3.0.3__tar.gz → 3.1.0__tar.gz

{mcp_proxy_adapter-3.0.3/mcp_proxy_adapter.egg-info → mcp_proxy_adapter-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-proxy-adapter
-Version: 3.0.3
+Version: 3.1.0
 Summary: Reliable microservice with unified JSON-RPC endpoint
 Home-page: https://github.com/yourusername/mcp-proxy-adapter
 Author: MCP Team

mcp_proxy_adapter-3.1.0/docs/EN/development/DEPENDENCY_INJECTION.md

@@ -0,0 +1,176 @@
+# Dependency Injection
+
+MCP Proxy Adapter version 3.1.0 introduces support for Dependency Injection (DI).
+This feature allows creating more flexible and testable commands that can
+use shared services and resources.
+
+## Core Concepts
+
+**Dependency Injection (DI)** is a design pattern where an object receives its
+dependencies from external sources rather than creating them itself. In the context of microservice-command-protocol:
+
+1. **Commands** - classes that receive dependencies through their constructor
+2. **Dependencies** - services, repositories, or other objects needed by commands
+3. **Container** - an object for storing and managing dependencies
+4. **Registration** - the process of adding a command instance to the registry
+
+## Using DI in Commands
+
+### 1. Creating a Command with Dependencies
+
+```python
+from mcp_proxy_adapter.commands import Command, SuccessResult
+
+class DatabaseService:
+    """Service for data operations."""
+    
+    def get_data(self, key):
+        # ... data retrieval logic
+        return {"result": f"Data for {key}"}
+
+
+class DataCommand(Command):
+    """Command using an injected dependency."""
+    
+    name = "get_data"
+    result_class = SuccessResult
+    
+    def __init__(self, db_service: DatabaseService):
+        """
+        Initialize command with dependencies.
+        
+        Args:
+            db_service: Service for data operations
+        """
+        self.db_service = db_service
+    
+    async def execute(self, key: str) -> SuccessResult:
+        """Execute command."""
+        data = self.db_service.get_data(key)
+        return self.result_class(**data)
+```
+
+### 2. Registering a Command with Dependencies
+
+```python
+from mcp_proxy_adapter.commands import registry, container
+
+# Create services
+db_service = DatabaseService()
+
+# Register in container (optional)
+container.register("db_service", db_service)
+
+# Create command instance with dependencies
+data_command = DataCommand(db_service)
+
+# Register the instance
+registry.register(data_command)
+```
+
+### 3. Executing the Command via API
+
+After registering a command with dependencies, it can be called via API just like regular commands. The system will automatically find the registered command instance:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "get_data",
+  "params": {
+    "key": "user_123"
+  },
+  "id": 1
+}
+```
+
+## Registration Types and Lifecycle Management
+
+### 1. Command Instance Registration
+
+```python
+# Create instance
+command = MyCommand(dependency)
+
+# Register instance
+registry.register(command)
+```
+
+### 2. Command Class Registration (for commands without dependencies)
+
+```python
+# Register class
+registry.register(MySimpleCommand)
+```
+
+## Dependency Container
+
+MCP Proxy Adapter includes a simple dependency container (`DependencyContainer`) that can be used for centralized dependency management:
+
+```python
+from mcp_proxy_adapter.commands import container
+
+# Register a simple dependency
+container.register("config", config_service)
+
+# Register a factory (creates a new instance on each request)
+container.register_factory("logger", lambda: create_logger())
+
+# Register a singleton (creates instance only on first request)
+container.register_singleton("db", lambda: create_db_connection())
+
+# Get a dependency
+db = container.get("db")
+```
+
+## Full Integration Example
+
+```python
+import asyncio
+from mcp_proxy_adapter import create_app
+from mcp_proxy_adapter.commands import registry, container
+
+# Create services
+db_service = DatabaseService("sqlite://:memory:")
+config_service = ConfigService("config.json")
+time_service = TimeService()
+
+# Register in container
+container.register("db", db_service)
+container.register("config", config_service)
+container.register("time", time_service)
+
+# Register commands
+registry.register(DataCommand(db_service, time_service))
+registry.register(ConfigCommand(config_service))
+registry.register(StatusCommand(db_service, config_service, time_service))
+
+# Create FastAPI application
+app = create_app()
+
+# Run the server
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+## DI Benefits
+
+1. **Testability** - ability to replace real dependencies with mocks during testing
+2. **Flexibility** - ability to change dependencies without modifying command code
+3. **Lifecycle Management** - centralized resource management
+4. **Reusability** - ability to use the same services across different commands
+
+## Best Practices
+
+1. **Interfaces** - define clear interfaces for services
+2. **Initialization** - initialize dependencies at application startup
+3. **Resource Cleanup** - add handlers for proper resource cleanup
+4. **Grouping** - group logically related dependencies in a single service
+
+## Complete Examples
+
+Complete examples of DI usage can be found in the `examples/di_example/` directory and `examples/commands/echo_command_di.py`.
+
+## Backward Compatibility
+
+The DI implementation is fully backward compatible with previous library versions. Commands without dependencies will continue to work without changes. 

mcp_proxy_adapter-3.1.0/docs/RU/development/DEPENDENCY_INJECTION.md

@@ -0,0 +1,176 @@
+# Внедрение зависимостей (Dependency Injection)
+
+В версии 3.1.0 библиотеки MCP Proxy Adapter добавлена поддержка внедрения зависимостей (DI).
+Эта функциональность позволяет создавать более гибкие и тестируемые команды, которые
+могут использовать общие сервисы и ресурсы.
+
+## Основные понятия
+
+**Dependency Injection (DI)** - это паттерн проектирования, при котором объект получает свои
+зависимости извне, а не создает их самостоятельно. В контексте microservice-command-protocol:
+
+1. **Команды** - классы, которые принимают зависимости через конструктор
+2. **Зависимости** - сервисы, репозитории, другие объекты, необходимые для работы команд
+3. **Контейнер** - объект для хранения и управления зависимостями
+4. **Регистрация** - процесс добавления экземпляра команды в реестр
+
+## Использование DI в командах
+
+### 1. Создание команды с зависимостями
+
+```python
+from mcp_proxy_adapter.commands import Command, SuccessResult
+
+class DatabaseService:
+    """Сервис для работы с данными."""
+    
+    def get_data(self, key):
+        # ... логика получения данных
+        return {"result": f"Data for {key}"}
+
+
+class DataCommand(Command):
+    """Команда, использующая внедренную зависимость."""
+    
+    name = "get_data"
+    result_class = SuccessResult
+    
+    def __init__(self, db_service: DatabaseService):
+        """
+        Инициализация команды с зависимостями.
+        
+        Args:
+            db_service: Сервис для работы с данными
+        """
+        self.db_service = db_service
+    
+    async def execute(self, key: str) -> SuccessResult:
+        """Выполнение команды."""
+        data = self.db_service.get_data(key)
+        return self.result_class(**data)
+```
+
+### 2. Регистрация команды с зависимостями
+
+```python
+from mcp_proxy_adapter.commands import registry, container
+
+# Создание сервисов
+db_service = DatabaseService()
+
+# Регистрация в контейнере (опционально)
+container.register("db_service", db_service)
+
+# Создание экземпляра команды с зависимостями
+data_command = DataCommand(db_service)
+
+# Регистрация экземпляра
+registry.register(data_command)
+```
+
+### 3. Выполнение команды через API
+
+После регистрации команды с зависимостями, её можно вызывать через API точно так же, как и обычные команды. Система автоматически найдет зарегистрированный экземпляр команды:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "get_data",
+  "params": {
+    "key": "user_123"
+  },
+  "id": 1
+}
+```
+
+## Типы регистрации и управление жизненным циклом
+
+### 1. Регистрация экземпляра команды
+
+```python
+# Создание экземпляра
+command = MyCommand(dependency)
+
+# Регистрация экземпляра
+registry.register(command)
+```
+
+### 2. Регистрация класса команды (для команд без зависимостей)
+
+```python
+# Регистрация класса
+registry.register(MySimpleCommand)
+```
+
+## Контейнер зависимостей
+
+MCP Proxy Adapter включает простой контейнер зависимостей (`DependencyContainer`), который можно использовать для централизованного управления зависимостями:
+
+```python
+from mcp_proxy_adapter.commands import container
+
+# Регистрация простой зависимости
+container.register("config", config_service)
+
+# Регистрация фабрики (создает новый экземпляр при каждом запросе)
+container.register_factory("logger", lambda: create_logger())
+
+# Регистрация синглтона (создает экземпляр только при первом запросе)
+container.register_singleton("db", lambda: create_db_connection())
+
+# Получение зависимости
+db = container.get("db")
+```
+
+## Пример полной интеграции
+
+```python
+import asyncio
+from mcp_proxy_adapter import create_app
+from mcp_proxy_adapter.commands import registry, container
+
+# Создание сервисов
+db_service = DatabaseService("sqlite://:memory:")
+config_service = ConfigService("config.json")
+time_service = TimeService()
+
+# Регистрация в контейнере
+container.register("db", db_service)
+container.register("config", config_service)
+container.register("time", time_service)
+
+# Регистрация команд
+registry.register(DataCommand(db_service, time_service))
+registry.register(ConfigCommand(config_service))
+registry.register(StatusCommand(db_service, config_service, time_service))
+
+# Создание FastAPI приложения
+app = create_app()
+
+# Запуск сервера
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+## Преимущества DI
+
+1. **Тестируемость** - возможность подменять реальные зависимости на моки при тестировании
+2. **Гибкость** - возможность изменять зависимости без изменения кода команд
+3. **Управление жизненным циклом** - централизованное управление ресурсами
+4. **Повторное использование** - возможность использовать одни и те же сервисы в разных командах
+
+## Практические рекомендации
+
+1. **Интерфейсы** - определяйте чёткие интерфейсы для сервисов
+2. **Инициализация** - инициализируйте зависимости при запуске приложения
+3. **Освобождение ресурсов** - добавляйте обработчики для корректного освобождения ресурсов
+4. **Группировка** - группируйте логически связанные зависимости в одном сервисе
+
+## Полные примеры
+
+Полные примеры использования DI можно найти в директории `examples/di_example/` и `examples/commands/echo_command_di.py`.
+
+## Совместимость с предыдущими версиями
+
+Реализация DI полностью совместима с предыдущими версиями библиотеки. Команды без зависимостей продолжат работать без изменений. 

mcp_proxy_adapter-3.1.0/examples/commands/echo_command_di.py

@@ -0,0 +1,152 @@
+"""
+Example command with dependency injection.
+
+This module demonstrates how to use dependency injection in commands.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from mcp_proxy_adapter.commands import Command, SuccessResult
+from mcp_proxy_adapter.commands.result import CommandResult
+
+
+class EchoCommandResult(SuccessResult):
+    """
+    Result of echo command execution.
+    """
+    
+    def __init__(self, message: str, timestamp: str, **kwargs):
+        """
+        Initializes echo command result.
+        
+        Args:
+            message: Echoed message
+            timestamp: Time of execution
+            **kwargs: Additional parameters
+        """
+        data = {"message": message, "timestamp": timestamp}
+        data.update(kwargs)
+        super().__init__(data=data, message=f"Echo response: {message}")
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """
+        Returns JSON schema for result validation.
+        
+        Returns:
+            Dictionary with JSON schema
+        """
+        return {
+            "type": "object",
+            "properties": {
+                "success": {"type": "boolean"},
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "message": {"type": "string"},
+                        "timestamp": {"type": "string", "format": "date-time"}
+                    },
+                    "required": ["message", "timestamp"]
+                },
+                "message": {"type": "string"}
+            },
+            "required": ["success", "data"]
+        }
+
+
+class TimeService:
+    """
+    Service for time-related operations.
+    
+    This is a dependency that will be injected into the EchoCommand.
+    """
+    
+    def get_current_time(self) -> str:
+        """
+        Get current time formatted as ISO string.
+        
+        Returns:
+            Current time as ISO formatted string
+        """
+        from datetime import datetime
+        return datetime.now().isoformat()
+
+
+class EchoCommand(Command):
+    """
+    Command that echoes back a message with timestamp.
+    
+    This command demonstrates how to use dependency injection in commands
+    by accepting a service dependency in the constructor.
+    """
+    
+    # Command name for JSON-RPC endpoint
+    name = "echo_di"
+    # Command result class
+    result_class = EchoCommandResult
+    
+    def __init__(self, time_service: TimeService):
+        """
+        Initialize command with dependencies.
+        
+        Args:
+            time_service: Service for getting the current time
+        """
+        self.time_service = time_service
+    
+    async def execute(self, message: str = "Hello, World!") -> CommandResult:
+        """
+        Executes echo command.
+        
+        Args:
+            message: Message to echo back
+            
+        Returns:
+            Command execution result with message and timestamp
+        """
+        timestamp = self.time_service.get_current_time()
+        return EchoCommandResult(message=message, timestamp=timestamp)
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """
+        Returns JSON schema for command parameters validation.
+        
+        Returns:
+            Dictionary with JSON schema
+        """
+        return {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "Message to echo back"
+                }
+            },
+            "additionalProperties": False
+        }
+
+
+# Example of registering the command with dependency injection
+def register_echo_command():
+    """
+    Register echo command with dependencies.
+    
+    This function shows how to:
+    1. Create a service dependency
+    2. Create a command instance with the dependency
+    3. Register the command instance in the registry
+    """
+    from mcp_proxy_adapter.commands import registry, container
+    
+    # Create and register service in the container
+    time_service = TimeService()
+    container.register("time_service", time_service)
+    
+    # Create command with dependencies
+    echo_command = EchoCommand(time_service)
+    
+    # Register command instance
+    registry.register(echo_command)
+    
+    return echo_command 

mcp_proxy_adapter-3.1.0/examples/di_example/.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.