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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: mcp-proxy-adapter
-Version: 4.0.0
+Version: 4.1.0
 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.0/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.0/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. **Документируйте пользовательские команды** для облегчения поддержки 

{mcp_proxy_adapter-4.0.0 → mcp_proxy_adapter-4.1.0}/mcp_proxy_adapter/commands/command_registry.py

@@ -257,15 +257,20 @@ class CommandRegistry:
                 commands_info[name] = self.get_command_info(name)
         return commands_info
     
-    def discover_commands(self, package_path: str = "mcp_proxy_adapter.commands") -> None:
+    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 commands discovered and registered.
         """
         logger.info(f"Discovering commands in package: {package_path}")
         
+        commands_discovered = 0
+        
         try:
             package = importlib.import_module(package_path)
             package_dir = os.path.dirname(package.__file__ or "")
@@ -273,7 +278,7 @@ class CommandRegistry:
             for _, module_name, is_pkg in pkgutil.iter_modules([package_dir]):
                 if is_pkg:
                     # Recursively traverse subpackages
-                    self.discover_commands(f"{package_path}.{module_name}")
+                    commands_discovered += self.discover_commands(f"{package_path}.{module_name}")
                 elif module_name.endswith("_command"):
                     # Import only command modules
                     module_path = f"{package_path}.{module_name}"
@@ -297,6 +302,8 @@ class CommandRegistry:
                                 # Register the command only if it doesn't exist
                                 if not self.command_exists(command_name):
                                     self.register(cast(Type[Command], obj))
+                                    commands_discovered += 1
+                                    logger.debug(f"Registered command: {command_name}")
                                 else:
                                     logger.debug(f"Command '{command_name}' is already registered, skipping")
                     except ValueError as e:
@@ -307,6 +314,8 @@ class CommandRegistry:
         except Exception as e:
             logger.error(f"Error discovering commands: {e}")
             
+        return commands_discovered
+            
     def register_custom_command(self, command: Union[Type[Command], Command]) -> None:
         """
         Register a custom command with priority over built-in commands.

{mcp_proxy_adapter-4.0.0 → mcp_proxy_adapter-4.1.0}/mcp_proxy_adapter/version.py

@@ -1,3 +1,3 @@
 """Version information for MCP Microservice."""
 
-__version__ = "4.0.0" 
+__version__ = "4.1.0" 

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: mcp-proxy-adapter
-Version: 4.0.0
+Version: 4.1.0
 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.0.0 → mcp_proxy_adapter-4.1.0}/mcp_proxy_adapter.egg-info/SOURCES.txt

@@ -44,6 +44,7 @@ docs/EN/development/OPENAPI_CUSTOMIZATION.md
 docs/EN/development/REMOVE_COMMAND_GUIDE.md
 docs/EN/development/TOOL_INTEGRATION.md
 docs/EN/development/architecture.md
+docs/EN/development/command_auto_discovery.md
 docs/EN/development/settings_management.md
 docs/EN/examples/README.md
 docs/EN/examples/anti_patterns.md
@@ -97,6 +98,7 @@ docs/RU/development/PLAN_REALIZACII_METADATA.md
 docs/RU/development/REMOVE_COMMAND_GUIDE.md
 docs/RU/development/TOOL_INTEGRATION.md
 docs/RU/development/architecture.md
+docs/RU/development/command_auto_discovery.md
 docs/RU/development/settings_management.md
 docs/RU/examples/README.md
 docs/RU/examples/anti_patterns.md

{mcp_proxy_adapter-4.0.0 → mcp_proxy_adapter-4.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcp-proxy-adapter"
-version = "4.0.0"
+version = "4.1.0"
 description = "Reliable microservice with unified JSON-RPC endpoint"
 readme = "README.md"
 requires-python = ">=3.8"

{mcp_proxy_adapter-4.0.0 → mcp_proxy_adapter-4.1.0}/setup.py

@@ -2,13 +2,13 @@ from setuptools import setup, find_packages
 
 setup(
     name="mcp-proxy-adapter",
-    version="3.1.6",
+    version="4.1.0",
     description="Adapter for MCP Proxy JSON-RPC communications",
     long_description=open("README.md").read(),
     long_description_content_type="text/markdown",
-    author="MCP Team",
-    author_email="info@example.com",
-    url="https://github.com/yourusername/mcp-proxy-adapter",
+    author="Vasiliy Zdanovskiy",
+    author_email="vasilyvz@gmail.com",
+    url="https://github.com/maverikod/mcp-proxy-adapter",
     packages=find_packages(exclude=["mcp_sdk*"]) + ['examples', 
                'examples.minimal_example', 
                'examples.basic_example',