mcp-proxy-adapter 4.0.0__tar.gz → 4.1.1__tar.gz

{mcp_proxy_adapter-4.0.0/mcp_proxy_adapter.egg-info → mcp_proxy_adapter-4.1.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: mcp-proxy-adapter
-Version: 4.0.0
+Version: 4.1.1
 Summary: Reliable microservice with unified JSON-RPC endpoint
-Home-page: https://github.com/yourusername/mcp-proxy-adapter
-Author: MCP Team
+Home-page: https://github.com/maverikod/mcp-proxy-adapter
+Author: Vasiliy Zdanovskiy
 Author-email: Vasiliy Zubarev <vasiliy.zubarev@example.com>
 License: MIT License
         

mcp_proxy_adapter-4.1.1/docs/EN/development/command_auto_discovery.md

@@ -0,0 +1,277 @@
+# Command Auto-Discovery and Configuration Reload
+
+## Overview
+
+The MCP Proxy Adapter system supports automatic command discovery and the ability to reload configuration without restarting the server. During reload, custom commands are preserved while built-in commands are reloaded fresh.
+
+## Command Auto-Discovery Process
+
+### How It Works
+
+Command auto-discovery works according to the following principles:
+
+1. **Package Scanning**: The system scans specified packages for modules with names ending in `_command`
+2. **Class Analysis**: In each module, it looks for classes that inherit from `Command`
+3. **Automatic Registration**: Found commands are automatically registered in the registry
+
+### Auto-Discovery Configuration
+
+```json
+{
+  "commands": {
+    "auto_discovery": true,
+    "discovery_path": "mcp_proxy_adapter.commands",
+    "custom_commands_path": "./custom_commands"
+  }
+}
+```
+
+### `discover_commands()` Method
+
+```python
+def discover_commands(self, package_path: str = "mcp_proxy_adapter.commands") -> int:
+    """
+    Automatically discovers and registers commands in the specified package.
+    
+    Args:
+        package_path: Path to package with commands
+        
+    Returns:
+        Number of discovered and registered commands
+    """
+```
+
+## Command Types
+
+### 1. Built-in Commands
+
+Commands provided with the framework:
+- `help` - command help
+- `health` - server health check
+- `config` - configuration management
+- `reload` - configuration reload
+- `settings` - settings management
+- `reload_settings` - settings reload
+
+### 2. Auto-Discovered Commands
+
+Commands found automatically in packages:
+- Must be located in modules with names `*_command.py`
+- Must inherit from the base `Command` class
+- Are registered automatically at startup
+
+### 3. Custom Commands
+
+Commands registered manually:
+- Registered via `register_custom_command()`
+- Have priority over built-in commands
+- Are preserved during configuration reload
+
+## Command Priority Hierarchy
+
+1. **Custom Commands** (highest priority)
+2. **Auto-Discovered Commands**
+3. **Built-in Commands** (lowest priority)
+
+## Configuration Reload
+
+### `reload_config_and_commands()` Method
+
+```python
+def reload_config_and_commands(self, package_path: str = "mcp_proxy_adapter.commands") -> Dict[str, Any]:
+    """
+    Reloads configuration and re-discovers commands.
+    
+    Args:
+        package_path: Path to package with commands
+        
+    Returns:
+        Dictionary with reload information:
+        - config_reloaded: Configuration reload success
+        - commands_discovered: Number of discovered commands
+        - custom_commands_preserved: Number of preserved custom commands
+        - total_commands: Total number of commands after reload
+        - built_in_commands: Number of built-in commands
+        - custom_commands: Number of custom commands
+    """
+```
+
+### Reload Process
+
+1. **Preserve Custom Commands**: Create backup of custom commands
+2. **Reload Configuration**: Load new configuration from file
+3. **Reinitialize Logging**: Configure logging with new parameters
+4. **Clear Registry**: Remove all commands except custom ones
+5. **Restore Custom Commands**: Restore saved custom commands
+6. **Re-discover Commands**: Re-discover and register commands
+
+### Custom Command Preservation
+
+Custom commands are preserved during reload thanks to:
+
+```python
+# Preserve custom commands
+custom_commands_backup = self._custom_commands.copy()
+
+# Clear all commands
+self._commands.clear()
+self._instances.clear()
+
+# Restore custom commands
+self._custom_commands = custom_commands_backup
+```
+
+## Usage Examples
+
+### Registering Custom Commands
+
+```python
+from mcp_proxy_adapter.commands.command_registry import registry
+from mcp_proxy_adapter.commands.base import Command
+
+class MyCustomCommand(Command):
+    name = "my_custom"
+    
+    async def execute(self, **kwargs):
+        return SuccessResult(message="Custom command executed")
+
+# Register with priority
+registry.register_custom_command(MyCustomCommand)
+```
+
+### Configuration Reload
+
+```python
+# Reload via command
+result = await reload_command.execute()
+
+# Direct reload
+reload_info = registry.reload_config_and_commands()
+print(f"Discovered commands: {reload_info['commands_discovered']}")
+print(f"Preserved custom: {reload_info['custom_commands_preserved']}")
+```
+
+### Checking Command Types
+
+```python
+# Check custom command existence
+if registry.custom_command_exists("my_custom"):
+    print("Custom command exists")
+
+# Get command with priority
+command = registry.get_command_with_priority("my_custom")
+
+# Get all commands with info
+all_commands = registry.get_all_commands_info()
+```
+
+## Work Demonstration
+
+Create file `demo_reload.py`:
+
+```python
+#!/usr/bin/env python3
+"""
+Demonstration of command auto-discovery and configuration reload.
+"""
+
+from mcp_proxy_adapter.commands.command_registry import registry
+from mcp_proxy_adapter.commands.base import Command
+from mcp_proxy_adapter.commands.result import SuccessResult
+
+class DemoCommand(Command):
+    name = "demo"
+    result_class = SuccessResult
+    
+    async def execute(self, message: str = "Hello!", **kwargs):
+        return SuccessResult(message=f"Demo: {message}")
+
+def main():
+    # Register custom command
+    registry.register_custom_command(DemoCommand)
+    print(f"Before reload: {len(registry.get_all_commands())} commands")
+    
+    # Reload configuration
+    result = registry.reload_config_and_commands()
+    print(f"After reload: {result['total_commands']} commands")
+    print(f"Preserved custom: {result['custom_commands_preserved']}")
+    
+    # Check preservation
+    if registry.custom_command_exists("demo"):
+        print("✅ Custom command preserved!")
+    else:
+        print("❌ Custom command lost!")
+
+if __name__ == "__main__":
+    main()
+```
+
+## System Advantages
+
+1. **Flexibility**: Ability to add commands without code changes
+2. **Reliability**: Preservation of custom commands during reload
+3. **Performance**: Automatic discovery without manual registration
+4. **Prioritization**: Custom commands have priority over built-in ones
+5. **Monitoring**: Detailed information about reload process
+
+## Behavior When Deleting Commands
+
+### What Happens When a Command File is Deleted
+
+1. **Before Reload**: Command remains available as it's already loaded in memory
+2. **After Reload**: Command disappears from registry as the file no longer exists
+
+### Process for Handling Deleted Commands
+
+```python
+# During configuration reload:
+def reload_config_and_commands(self, package_path: str = "mcp_proxy_adapter.commands") -> Dict[str, Any]:
+    # 1. Preserve custom commands
+    custom_commands_backup = self._custom_commands.copy()
+    
+    # 2. Clear all commands (except custom ones)
+    self._commands.clear()
+    self._instances.clear()
+    
+    # 3. Re-discover commands (deleted files are ignored)
+    commands_discovered = self.discover_commands(package_path)
+    
+    # 4. Restore custom commands
+    self._custom_commands = custom_commands_backup
+```
+
+### Import Error Handling
+
+The system correctly handles situations where command files are deleted:
+
+```python
+try:
+    module = importlib.import_module(module_path)
+    # Process command...
+except Exception as e:
+    logger.error(f"Error loading command module {module_path}: {e}")
+    # Module is skipped, error is logged
+```
+
+### Advantages of This Behavior
+
+1. **Safety**: Deleted commands don't remain in the system
+2. **Consistency**: Command registry always matches the file system
+3. **Fault Tolerance**: Import errors don't interrupt system operation
+4. **Flexibility**: Commands can be dynamically added and removed
+
+## Limitations
+
+1. **Naming Requirements**: Modules must end with `_command`
+2. **Inheritance**: Commands must inherit from base `Command` class
+3. **Server Restart**: Some configuration changes may require server restart
+4. **Dependencies**: Custom commands with dependencies must be registered as instances
+5. **Command Deletion**: Configuration reload is required to remove commands from registry
+
+## Recommendations
+
+1. **Use Custom Commands** to override built-in ones
+2. **Group Commands** in separate packages for better organization
+3. **Test Reload** before deploying to production
+4. **Monitor Logs** to track auto-discovery process
+5. **Document Custom Commands** to facilitate maintenance 

mcp_proxy_adapter-4.1.1/docs/EN/user/configuration.md

@@ -0,0 +1,128 @@
+# Configuration
+
+This guide describes how to configure the MCP Proxy service.
+
+## Configuration File
+
+The MCP Proxy service is configured using a JSON configuration file. By default, it looks for a file named `config.json` in the current directory.
+
+You can specify a different configuration file using the `--config` command-line option:
+
+```bash
+mcp-proxy --config /path/to/config.json
+```
+
+## Configuration Options
+
+The configuration is organized into sections. Here are the available options:
+
+### Server Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| server.host | string | "0.0.0.0" | The host to bind the service to |
+| server.port | number | 8000 | The port to listen on |
+| server.debug | boolean | false | Enable debug mode |
+| server.log_level | string | "INFO" | The logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
+
+### Logging Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| logging.level | string | "INFO" | The logging level |
+| logging.log_dir | string | "./logs" | Directory for log files |
+| logging.log_file | string | "mcp_proxy_adapter.log" | Main log file name |
+| logging.error_log_file | string | "mcp_proxy_adapter_error.log" | Error log file name |
+| logging.access_log_file | string | "mcp_proxy_adapter_access.log" | Access log file name |
+| logging.max_file_size | string | "10MB" | Maximum log file size |
+| logging.backup_count | number | 5 | Number of backup log files |
+| logging.console_output | boolean | true | Enable console logging |
+| logging.file_output | boolean | true | Enable file logging |
+
+### Commands Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| commands.auto_discovery | boolean | true | Enable automatic command discovery |
+| commands.discovery_path | string | "mcp_proxy_adapter.commands" | **Path to package with commands** |
+| commands.custom_commands_path | string | null | Path to custom commands (deprecated) |
+
+**Important**: The `commands.discovery_path` parameter specifies the Python package path where your commands are located. For example:
+- `"mcp_proxy_adapter.commands"` - built-in commands
+- `"myproject.commands"` - your project's commands
+- `"custom_commands.commands"` - custom commands package
+
+## Example Configuration
+
+Here's an example configuration file:
+
+```json
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 8000,
+    "debug": false,
+    "log_level": "INFO"
+  },
+  "logging": {
+    "level": "INFO",
+    "log_dir": "./logs",
+    "log_file": "mcp_proxy_adapter.log",
+    "error_log_file": "mcp_proxy_adapter_error.log",
+    "access_log_file": "mcp_proxy_adapter_access.log",
+    "max_file_size": "10MB",
+    "backup_count": 5,
+    "console_output": true,
+    "file_output": true
+  },
+  "commands": {
+    "auto_discovery": true,
+    "discovery_path": "mcp_proxy_adapter.commands",
+    "custom_commands_path": null
+  }
+}
+```
+
+### Example with Custom Commands
+
+If you have your own commands in a package called `myproject.commands`:
+
+```json
+{
+  "server": {
+    "host": "127.0.0.1",
+    "port": 8001,
+    "debug": true,
+    "log_level": "DEBUG"
+  },
+  "logging": {
+    "level": "DEBUG",
+    "log_dir": "./logs",
+    "log_file": "myproject.log"
+  },
+  "commands": {
+    "auto_discovery": true,
+    "discovery_path": "myproject.commands"
+  }
+}
+```
+
+## Environment Variables
+
+You can also configure the service using environment variables. Environment variables take precedence over the configuration file.
+
+The environment variable format is `MCP_UPPERCASE_OPTION_NAME`. For example, to set the port:
+
+```bash
+export MCP_PORT=8000
+```
+
+## Testing the Configuration
+
+To verify your configuration, you can run the service with the `--validate-config` option:
+
+```bash
+mcp-proxy --config /path/to/config.json --validate-config
+```
+
+This will validate the configuration file and exit without starting the service. 

mcp_proxy_adapter-4.1.1/docs/RU/development/command_auto_discovery.md

@@ -0,0 +1,277 @@
+# Автообнаружение команд и перезагрузка конфигурации
+
+## Обзор
+
+Система MCP Proxy Adapter поддерживает автоматическое обнаружение команд и возможность перезагрузки конфигурации без перезапуска сервера. При перезагрузке пользовательские команды сохраняются, а встроенные команды перезагружаются заново.
+
+## Процесс автообнаружения команд
+
+### Принцип работы
+
+Автообнаружение команд работает по следующим принципам:
+
+1. **Сканирование пакетов**: Система сканирует указанные пакеты на наличие модулей с именами, заканчивающимися на `_command`
+2. **Анализ классов**: В каждом модуле ищутся классы, наследующие от `Command`
+3. **Автоматическая регистрация**: Найденные команды автоматически регистрируются в реестре
+
+### Конфигурация автообнаружения
+
+```json
+{
+  "commands": {
+    "auto_discovery": true,
+    "discovery_path": "mcp_proxy_adapter.commands",
+    "custom_commands_path": "./custom_commands"
+  }
+}
+```
+
+### Метод `discover_commands()`
+
+```python
+def discover_commands(self, package_path: str = "mcp_proxy_adapter.commands") -> int:
+    """
+    Автоматически обнаруживает и регистрирует команды в указанном пакете.
+    
+    Args:
+        package_path: Путь к пакету с командами
+        
+    Returns:
+        Количество обнаруженных и зарегистрированных команд
+    """
+```
+
+## Типы команд
+
+### 1. Встроенные команды (Built-in Commands)
+
+Команды, поставляемые с фреймворком:
+- `help` - справка по командам
+- `health` - проверка состояния сервера
+- `config` - управление конфигурацией
+- `reload` - перезагрузка конфигурации
+- `settings` - управление настройками
+- `reload_settings` - перезагрузка настроек
+
+### 2. Автообнаруженные команды (Auto-discovered Commands)
+
+Команды, найденные автоматически в пакетах:
+- Должны находиться в модулях с именами `*_command.py`
+- Должны наследовать от базового класса `Command`
+- Регистрируются автоматически при запуске
+
+### 3. Пользовательские команды (Custom Commands)
+
+Команды, зарегистрированные вручную:
+- Регистрируются через `register_custom_command()`
+- Имеют приоритет над встроенными командами
+- Сохраняются при перезагрузке конфигурации
+
+## Иерархия приоритетов команд
+
+1. **Пользовательские команды** (высший приоритет)
+2. **Автообнаруженные команды**
+3. **Встроенные команды** (низший приоритет)
+
+## Перезагрузка конфигурации
+
+### Метод `reload_config_and_commands()`
+
+```python
+def reload_config_and_commands(self, package_path: str = "mcp_proxy_adapter.commands") -> Dict[str, Any]:
+    """
+    Перезагружает конфигурацию и переобнаруживает команды.
+    
+    Args:
+        package_path: Путь к пакету с командами
+        
+    Returns:
+        Словарь с информацией о перезагрузке:
+        - config_reloaded: Успешность перезагрузки конфигурации
+        - commands_discovered: Количество обнаруженных команд
+        - custom_commands_preserved: Количество сохраненных пользовательских команд
+        - total_commands: Общее количество команд после перезагрузки
+        - built_in_commands: Количество встроенных команд
+        - custom_commands: Количество пользовательских команд
+    """
+```
+
+### Процесс перезагрузки
+
+1. **Сохранение пользовательских команд**: Создается резервная копия пользовательских команд
+2. **Перезагрузка конфигурации**: Загружается новая конфигурация из файла
+3. **Переинициализация логирования**: Настраивается логирование с новыми параметрами
+4. **Очистка реестра**: Удаляются все команды, кроме пользовательских
+5. **Восстановление пользовательских команд**: Восстанавливаются сохраненные пользовательские команды
+6. **Переобнаружение команд**: Заново обнаруживаются и регистрируются команды
+
+### Сохранение пользовательских команд
+
+Пользовательские команды сохраняются при перезагрузке благодаря:
+
+```python
+# Сохранение пользовательских команд
+custom_commands_backup = self._custom_commands.copy()
+
+# Очистка всех команд
+self._commands.clear()
+self._instances.clear()
+
+# Восстановление пользовательских команд
+self._custom_commands = custom_commands_backup
+```
+
+## Примеры использования
+
+### Регистрация пользовательской команды
+
+```python
+from mcp_proxy_adapter.commands.command_registry import registry
+from mcp_proxy_adapter.commands.base import Command
+
+class MyCustomCommand(Command):
+    name = "my_custom"
+    
+    async def execute(self, **kwargs):
+        return SuccessResult(message="Custom command executed")
+
+# Регистрация с приоритетом
+registry.register_custom_command(MyCustomCommand)
+```
+
+### Перезагрузка конфигурации
+
+```python
+# Перезагрузка через команду
+result = await reload_command.execute()
+
+# Прямая перезагрузка
+reload_info = registry.reload_config_and_commands()
+print(f"Обнаружено команд: {reload_info['commands_discovered']}")
+print(f"Сохранено пользовательских: {reload_info['custom_commands_preserved']}")
+```
+
+### Проверка типов команд
+
+```python
+# Проверка существования пользовательской команды
+if registry.custom_command_exists("my_custom"):
+    print("Пользовательская команда существует")
+
+# Получение команды с учетом приоритета
+command = registry.get_command_with_priority("my_custom")
+
+# Получение всех команд с информацией
+all_commands = registry.get_all_commands_info()
+```
+
+## Демонстрация работы
+
+Создайте файл `demo_reload.py`:
+
+```python
+#!/usr/bin/env python3
+"""
+Демонстрация автообнаружения команд и перезагрузки конфигурации.
+"""
+
+from mcp_proxy_adapter.commands.command_registry import registry
+from mcp_proxy_adapter.commands.base import Command
+from mcp_proxy_adapter.commands.result import SuccessResult
+
+class DemoCommand(Command):
+    name = "demo"
+    result_class = SuccessResult
+    
+    async def execute(self, message: str = "Hello!", **kwargs):
+        return SuccessResult(message=f"Demo: {message}")
+
+def main():
+    # Регистрация пользовательской команды
+    registry.register_custom_command(DemoCommand)
+    print(f"До перезагрузки: {len(registry.get_all_commands())} команд")
+    
+    # Перезагрузка конфигурации
+    result = registry.reload_config_and_commands()
+    print(f"После перезагрузки: {result['total_commands']} команд")
+    print(f"Сохранено пользовательских: {result['custom_commands_preserved']}")
+    
+    # Проверка сохранения
+    if registry.custom_command_exists("demo"):
+        print("✅ Пользовательская команда сохранена!")
+    else:
+        print("❌ Пользовательская команда потеряна!")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Преимущества системы
+
+1. **Гибкость**: Возможность добавления команд без изменения кода
+2. **Надежность**: Сохранение пользовательских команд при перезагрузке
+3. **Производительность**: Автоматическое обнаружение без ручной регистрации
+4. **Приоритизация**: Пользовательские команды имеют приоритет над встроенными
+5. **Мониторинг**: Детальная информация о процессе перезагрузки
+
+## Поведение при удалении команд
+
+### Что происходит при удалении файла команды
+
+1. **До перезагрузки**: Команда остается доступной, так как она уже загружена в память
+2. **После перезагрузки**: Команда исчезает из реестра, так как файл больше не существует
+
+### Процесс обработки удаленных команд
+
+```python
+# При перезагрузке конфигурации:
+def reload_config_and_commands(self, package_path: str = "mcp_proxy_adapter.commands") -> Dict[str, Any]:
+    # 1. Сохранение пользовательских команд
+    custom_commands_backup = self._custom_commands.copy()
+    
+    # 2. Очистка всех команд (кроме пользовательских)
+    self._commands.clear()
+    self._instances.clear()
+    
+    # 3. Переобнаружение команд (удаленные файлы игнорируются)
+    commands_discovered = self.discover_commands(package_path)
+    
+    # 4. Восстановление пользовательских команд
+    self._custom_commands = custom_commands_backup
+```
+
+### Обработка ошибок импорта
+
+Система корректно обрабатывает ситуации, когда файлы команд удалены:
+
+```python
+try:
+    module = importlib.import_module(module_path)
+    # Обработка команды...
+except Exception as e:
+    logger.error(f"Error loading command module {module_path}: {e}")
+    # Модуль пропускается, ошибка логируется
+```
+
+### Преимущества такого поведения
+
+1. **Безопасность**: Удаленные команды не остаются в системе
+2. **Консистентность**: Реестр команд всегда соответствует файловой системе
+3. **Отказоустойчивость**: Ошибки импорта не прерывают работу системы
+4. **Гибкость**: Можно динамически добавлять и удалять команды
+
+## Ограничения
+
+1. **Требования к именованию**: Модули должны заканчиваться на `_command`
+2. **Наследование**: Команды должны наследовать от базового класса `Command`
+3. **Перезапуск сервера**: Некоторые изменения конфигурации могут требовать перезапуска
+4. **Зависимости**: Пользовательские команды с зависимостями должны регистрироваться как экземпляры
+5. **Удаление команд**: Требуется перезагрузка конфигурации для удаления команд из реестра
+
+## Рекомендации
+
+1. **Используйте пользовательские команды** для переопределения встроенных
+2. **Группируйте команды** в отдельные пакеты для лучшей организации
+3. **Тестируйте перезагрузку** перед развертыванием в продакшене
+4. **Мониторьте логи** для отслеживания процесса автообнаружения
+5. **Документируйте пользовательские команды** для облегчения поддержки