mcp-proxy-adapter 3.0.0__py3-none-any.whl → 3.0.1__py3-none-any.whl

examples/basic_example/README.md

@@ -1,7 +1,120 @@
-# Базовый пример MCP Microservice
+# Basic MCP Proxy Adapter Example
 
-Этот пример демонстрирует базовую функциональность MCP Microservice с несколькими командами,
-организованными в отдельные файлы.
+This example demonstrates how to use MCP Proxy Adapter to create a microservice with multiple commands organized in separate files.
+
+## English Documentation
+
+### Overview
+
+This example shows:
+- Creating a microservice using MCP Proxy Adapter
+- Configuring the service using JSON configuration file
+- Automatic command discovery from a package
+- Implementing various command types with their result classes
+- Running the service with auto-reload for development
+
+### Setup
+
+1. Make sure you have installed MCP Proxy Adapter package
+2. Install additional dependencies:
+   ```
+   pip install pytz uvicorn
+   ```
+
+### Configuration
+
+The service uses `config.json` for configuration. The key settings are:
+- Server host and port
+- Logging configuration
+- Command discovery settings
+
+### Available Commands
+
+The example includes several commands:
+- `echo` - Echo back a message
+- `time` - Get current time in different formats and timezones
+- `math` - Perform basic math operations
+
+### Running the Example
+
+```bash
+cd examples/basic_example
+python server.py
+```
+
+The service will start on http://localhost:8000 by default, with API documentation available at http://localhost:8000/docs
+
+### Testing Commands
+
+You can test commands using curl:
+
+```bash
+# Echo command
+curl -X POST http://localhost:8000/cmd -H "Content-Type: application/json" -d '{"command": "echo", "params": {"message": "Hello, world!"}}'
+
+# Time command
+curl -X POST http://localhost:8000/cmd -H "Content-Type: application/json" -d '{"command": "time", "params": {"timezone": "Europe/London"}}'
+
+# JSON-RPC style request
+curl -X POST http://localhost:8000/api/jsonrpc -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello RPC!"}, "id": 1}'
+```
+
+## Русская документация
+
+### Обзор
+
+Этот пример демонстрирует:
+- Создание микросервиса с использованием MCP Proxy Adapter
+- Настройку сервиса с использованием JSON-файла конфигурации
+- Автоматическое обнаружение команд из пакета
+- Реализацию различных типов команд с их классами результатов
+- Запуск сервиса с автоперезагрузкой для разработки
+
+### Настройка
+
+1. Убедитесь, что у вас установлен пакет MCP Proxy Adapter
+2. Установите дополнительные зависимости:
+   ```
+   pip install pytz uvicorn
+   ```
+
+### Конфигурация
+
+Сервис использует `config.json` для конфигурации. Основные настройки:
+- Хост и порт сервера
+- Настройки логирования
+- Настройки обнаружения команд
+
+### Доступные команды
+
+Пример включает несколько команд:
+- `echo` - Эхо-ответ сообщения
+- `time` - Получение текущего времени в разных форматах и часовых поясах
+- `math` - Выполнение базовых математических операций
+
+### Запуск примера
+
+```bash
+cd examples/basic_example
+python server.py
+```
+
+Сервис запустится на http://localhost:8000 по умолчанию, документация API доступна по адресу http://localhost:8000/docs
+
+### Тестирование команд
+
+Вы можете тестировать команды с помощью curl:
+
+```bash
+# Команда echo
+curl -X POST http://localhost:8000/cmd -H "Content-Type: application/json" -d '{"command": "echo", "params": {"message": "Привет, мир!"}}'
+
+# Команда time
+curl -X POST http://localhost:8000/cmd -H "Content-Type: application/json" -d '{"command": "time", "params": {"timezone": "Europe/Moscow"}}'
+
+# Запрос в стиле JSON-RPC
+curl -X POST http://localhost:8000/api/jsonrpc -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Привет RPC!"}, "id": 1}'
+```
 
 ## Структура примера
 
@@ -12,7 +125,7 @@ basic_example/
 │   ├── echo_command.py        # Команда эхо
 │   ├── math_command.py        # Математическая команда
 │   └── time_command.py        # Команда времени
-├── config.yaml                # Файл конфигурации
+├── config.json                # Файл конфигурации JSON
 ├── README.md                  # Документация
 └── server.py                  # Файл запуска сервера
 ```
@@ -124,8 +237,9 @@ curl -X POST "http://localhost:8000/api/command/time" \
 
 ## Что демонстрирует этот пример
 
-1. Организация команд в отдельные файлы
-2. Автоматическое обнаружение и регистрация команд
-3. Различные типы команд и параметров
-4. Обработка ошибок
-5. Различные способы вызова команд (JSON-RPC, /cmd, /api/command/{command_name}) 
+1. Прямое использование FastAPI и uvicorn с MCP Proxy Adapter
+2. Организация команд в отдельные файлы
+3. Автоматическое обнаружение и регистрация команд
+4. Различные типы команд и параметров
+5. Обработка ошибок
+6. Различные способы вызова команд (JSON-RPC, /cmd, /api/command/{command_name}) 

examples/basic_example/config.json

@@ -17,5 +17,9 @@
       "max_bytes": 10485760,
       "backup_count": 5
     }
+  },
+  "discovery": {
+    "enabled": true,
+    "package": "commands"
   }
 } 

examples/basic_example/docs/EN/README.md

@@ -12,14 +12,16 @@ basic_example/
 │   ├── echo_command.py        # Echo command
 │   ├── math_command.py        # Math command
 │   └── time_command.py        # Time command
-├── config.yaml                # Configuration file
+├── config.json                # JSON configuration file
 ├── docs/                      # Documentation
 │   ├── EN/                    # English documentation
 │   │   └── README.md          # This file
 │   └── RU/                    # Russian documentation
 │       └── README.md          # Russian version of this file
 ├── logs/                      # Logs directory
-└── server.py                  # Server startup file
+├── server.py                  # Server startup and application logic
+└── tests/                     # Tests directory
+    └── conftest.py            # Test configuration and fixtures
 ```
 
 ## Running the Example
@@ -31,12 +33,48 @@ cd examples/basic_example
 # Create logs directory if it doesn't exist
 mkdir -p logs
 
-# Run the server
+# Run the server with default configuration (config.json)
 python server.py
+
+# Or run with a specific configuration file
+python server.py --config other_config.json
 ```
 
 After starting, the server will be available at [http://localhost:8000](http://localhost:8000).
 
+## Configuration
+
+The server reads configuration from JSON files. By default, it uses `config.json` in the same directory as `server.py`.
+
+You can specify a different configuration file with the `--config` parameter:
+
+```bash
+python server.py --config my_custom_config.json
+```
+
+If the specified configuration file doesn't exist, the server will try to fall back to `config.json`.
+
+The main configuration options are:
+
+```json
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 8000,
+    "debug": true,
+    "log_level": "info"
+  },
+  "logging": {
+    "level": "INFO",
+    "file": "logs/basic_example.log"
+  }
+}
+```
+
+The server can run in two modes:
+- Normal mode: Uses a pre-configured application instance
+- Debug mode: Uses hot reload (when `"debug": true` in config)
+
 ## Available Commands
 
 ### 1. `echo` - Echo Command
@@ -132,5 +170,8 @@ curl -X POST "http://localhost:8000/api/command/time" \
 1. Command organization in separate files
 2. Automatic command discovery and registration
 3. Different command types and parameter handling
-4. Error handling
-5. Different ways to call commands (JSON-RPC, /cmd, /api/command/{command_name}) 
+4. Error handling and automatic command reregistration
+5. Different ways to call commands (JSON-RPC, /cmd, /api/command/{command_name})
+6. Support for debug mode with hot reload
+7. Safe command registration for preventing conflicts
+8. JSON configuration files with command-line options 

examples/basic_example/docs/RU/README.md

@@ -12,14 +12,16 @@ basic_example/
 │   ├── echo_command.py        # Команда эхо
 │   ├── math_command.py        # Математическая команда
 │   └── time_command.py        # Команда времени
-├── config.yaml                # Файл конфигурации
+├── config.json                # Файл конфигурации JSON
 ├── docs/                      # Документация
 │   ├── EN/                    # Английская документация
 │   │   └── README.md          # Английская версия данного файла
 │   └── RU/                    # Русская документация
 │       └── README.md          # Этот файл
 ├── logs/                      # Директория для логов
-└── server.py                  # Файл запуска сервера
+├── server.py                  # Файл запуска сервера и логики приложения
+└── tests/                     # Директория с тестами
+    └── conftest.py            # Конфигурация и фикстуры для тестов
 ```
 
 ## Запуск примера
@@ -31,12 +33,48 @@ cd examples/basic_example
 # Создать директорию для логов, если она не существует
 mkdir -p logs
 
-# Запустить сервер
+# Запустить сервер с конфигурацией по умолчанию (config.json)
 python server.py
+
+# Или запустить с указанием другого файла конфигурации
+python server.py --config другой_конфиг.json
 ```
 
 После запуска сервер будет доступен по адресу [http://localhost:8000](http://localhost:8000).
 
+## Конфигурация
+
+Сервер считывает конфигурацию из JSON-файлов. По умолчанию используется `config.json` в том же каталоге, где находится `server.py`.
+
+Вы можете указать другой файл конфигурации с помощью параметра `--config`:
+
+```bash
+python server.py --config мой_конфиг.json
+```
+
+Если указанный файл конфигурации не существует, сервер попытается использовать `config.json`.
+
+Основные параметры конфигурации:
+
+```json
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 8000,
+    "debug": true,
+    "log_level": "info"
+  },
+  "logging": {
+    "level": "INFO",
+    "file": "logs/basic_example.log"
+  }
+}
+```
+
+Сервер может работать в двух режимах:
+- Обычный режим: использует предварительно настроенный экземпляр приложения
+- Режим отладки: использует горячую перезагрузку (когда `"debug": true` в конфигурации)
+
 ## Доступные команды
 
 ### 1. `echo` - Эхо-команда
@@ -132,5 +170,8 @@ curl -X POST "http://localhost:8000/api/command/time" \
 1. Организация команд в отдельные файлы
 2. Автоматическое обнаружение и регистрация команд
 3. Различные типы команд и параметров
-4. Обработка ошибок
-5. Различные способы вызова команд (JSON-RPC, /cmd, /api/command/{command_name}) 
+4. Обработка ошибок и автоматическая перерегистрация команд
+5. Различные способы вызова команд (JSON-RPC, /cmd, /api/command/{command_name})
+6. Поддержка режима отладки с горячей перезагрузкой
+7. Безопасная регистрация команд для предотвращения конфликтов
+8. JSON-файлы конфигурации с опциями командной строки 

examples/basic_example/server.py

@@ -1,44 +1,150 @@
 """
-Basic MCP Microservice example.
+Basic MCP Proxy Adapter example.
 
-This example demonstrates a microservice with multiple commands
-organized in separate files.
+This example demonstrates how to use MCP Proxy Adapter to create
+a microservice with multiple commands organized in separate files.
 """
 
 import os
 import sys
+import json
+import argparse
+import uvicorn
 from typing import Dict, Any
+from pathlib import Path
 
-import mcp_proxy_adapter as mcp
-from mcp_proxy_adapter import MicroService
+from mcp_proxy_adapter import Command, CommandResult, registry
+from mcp_proxy_adapter.api.app import create_app
+from mcp_proxy_adapter.config import config
+from mcp_proxy_adapter.core.logging import logger, setup_logging
 
 # Add commands directory to path for local imports
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 
-def main():
-    """Run microservice with command discovery."""
+def parse_args():
+    """
+    Parse command line arguments.
+    
+    Returns:
+        Parsed arguments
+    """
+    parser = argparse.ArgumentParser(description="Basic MCP Microservice Example")
+    parser.add_argument(
+        "--config", 
+        default="config.json",
+        help="Path to configuration file (default: config.json)"
+    )
+    return parser.parse_args()
+
+
+def setup_application(config_file=None):
+    """
+    Настраивает и возвращает FastAPI приложение.
+    """
+    # Get config file path
+    if config_file is None:
+        args = parse_args()
+        config_file = args.config
+    
     # Get absolute paths
-    current_dir = os.path.dirname(os.path.abspath(__file__))
-    config_path = os.path.join(current_dir, "config.yaml")
+    current_dir = Path(__file__).parent.absolute()
+    config_path = current_dir / config_file
+    
+    # Try alternative config file if specified one doesn't exist
+    if not config_path.exists() and config_file != "config.json":
+        fallback_path = current_dir / "config.json"
+        if fallback_path.exists():
+            logger.warning(f"Config file {config_path} not found, using {fallback_path} instead")
+            config_path = fallback_path
     
     # Create log directory if it doesn't exist
-    os.makedirs(os.path.join(current_dir, "logs"), exist_ok=True)
-    
-    # Create microservice
-    service = MicroService(
-        title="Basic MCP Microservice Example",
-        description="Example microservice with multiple commands",
-        version="1.0.0",
-        config_path=config_path
-    )
+    logs_dir = current_dir / "logs"
+    logs_dir.mkdir(exist_ok=True)
+    
+    # Load configuration if config file exists
+    if config_path.exists():
+        # Make sure we're only loading JSON files
+        if not str(config_path).lower().endswith('.json'):
+            logger.warning(f"Config file {config_path} is not a JSON file, only JSON format is supported")
+            config_path = current_dir / "config.json"
+            if not config_path.exists():
+                logger.warning(f"Default config.json not found, using default values")
+        
+        if config_path.exists():
+            config.load_from_file(str(config_path))
+            logger.info(f"Loaded configuration from {config_path}")
+    else:
+        logger.warning(f"Configuration file {config_path} not found, using defaults")
+    
+    # Create FastAPI app
+    app = create_app()
+    app.title = "Basic MCP Proxy Adapter Example"
+    app.description = "Example microservice with multiple commands using MCP Proxy Adapter"
+    app.version = "1.0.0"
     
     # Discover and register commands from the commands directory
-    package_path = "commands"  # Relative import path
-    service.discover_commands(package_path)
+    package_path = "commands"
+    try:
+        # Clear existing commands to prevent conflicts in test environment
+        registered_commands = registry.get_all_commands()
+        for cmd_name in list(registered_commands.keys()):
+            try:
+                registry.unregister(cmd_name)
+            except Exception as e:
+                logger.debug(f"Error unregistering command {cmd_name}: {e}")
+        
+        # Discover and register commands
+        registry.discover_commands(package_path)
+        logger.info(f"Discovered commands from package: {package_path}")
+    except Exception as e:
+        logger.error(f"Error discovering commands: {e}")
+    
+    return app
+
+
+def main():
+    """Run microservice with command discovery."""
+    # Setup logging
+    log_level = config.get("logging.level", "INFO")
+    setup_logging(log_level)
+    
+    # Initialize application
+    app = setup_application()
+    
+    # Get server configuration
+    host = config.get("server.host", "localhost")
+    port = config.get("server.port", 8000)
+    
+    # Check if port is overridden by environment variable (for testing)
+    if "TEST_SERVER_PORT" in os.environ:
+        port = int(os.environ["TEST_SERVER_PORT"])
+        logger.info(f"Using test port from environment: {port}")
     
     # Run server
-    service.run(reload=True)
+    logger.info(f"Starting server on {host}:{port}")
+    
+    debug = config.get("server.debug", False)
+    
+    if debug:
+        # In debug mode, run with hot reload using import string
+        uvicorn.run(
+            "server:setup_application",
+            host=host,
+            port=port,
+            reload=True,
+            factory=True,
+            log_level=config.get("logging.level", "info").lower()
+        )
+    else:
+        # In normal mode, run with app instance
+        uvicorn.run(
+            app,
+            host=host,
+            port=port,
+            reload=False,
+            log_level=config.get("logging.level", "info").lower()
+        )
 
 
 if __name__ == "__main__":

examples/complete_example/commands/system_command.py

@@ -6,6 +6,7 @@ This module contains a command that returns detailed information about the syste
 
 import os
 import sys
+import socket
 import platform
 import datetime
 from typing import Dict, Any, Optional, List

examples/complete_example/server.py

@@ -9,9 +9,13 @@ import os
 import sys
 import argparse
 from typing import Dict, Any
+from pathlib import Path
 
 import mcp_proxy_adapter as mcp
 from mcp_proxy_adapter import MicroService
+from mcp_proxy_adapter.commands.command_registry import registry
+from mcp_proxy_adapter.core.logging import logger
+from mcp_proxy_adapter.config import config
 
 # Add commands directory to path for local imports
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -53,29 +57,79 @@ def ensure_directories(config_path: str):
     os.makedirs(os.path.join(base_dir, "data"), exist_ok=True)
 
 
-def main():
-    """Run microservice with command discovery."""
-    # Parse command line arguments
-    args = parse_args()
+def setup_application(config_file=None):
+    """
+    Setup and configure the microservice application.
+    
+    Args:
+        config_file: Path to configuration file (optional)
+        
+    Returns:
+        Configured microservice object
+    """
+    # Parse command line arguments if config_file not provided
+    if config_file is None:
+        args = parse_args()
+        config_file = args.config
     
     # Get absolute path to config file
-    current_dir = os.path.dirname(os.path.abspath(__file__))
-    config_path = os.path.join(current_dir, args.config)
+    current_dir = Path(__file__).parent.absolute()
+    config_path = current_dir / config_file
+    
+    # Fall back to config.json if specified file doesn't exist
+    if not config_path.exists():
+        config_path = current_dir / "config.json"
     
     # Create necessary directories
-    ensure_directories(config_path)
+    ensure_directories(str(config_path))
+    
+    # Load configuration if exists
+    if config_path.exists():
+        config.load_from_file(str(config_path))
+        logger.info(f"Loaded configuration from {config_path}")
+    else:
+        logger.warning(f"Configuration file {config_path} not found, using defaults")
     
     # Create microservice
     service = MicroService(
         title="Complete MCP Microservice Example",
         description="Full-featured microservice with Docker support",
         version="1.0.0",
-        config_path=config_path
+        config_path=str(config_path) if config_path.exists() else None
     )
     
-    # Discover and register commands
-    package_path = "commands"
-    service.discover_commands(package_path)
+    # Safely register commands from package
+    try:
+        # Clear any existing registrations to prevent conflicts
+        package_path = "commands"
+        
+        # Get currently registered commands
+        commands = registry.get_all_commands()
+        for cmd_name in list(commands.keys()):
+            try:
+                registry.unregister(cmd_name)
+            except Exception as e:
+                logger.debug(f"Error unregistering command {cmd_name}: {e}")
+        
+        # Discover and register commands
+        service.discover_commands(package_path)
+        logger.info(f"Discovered and registered commands from package: {package_path}")
+    except Exception as e:
+        logger.error(f"Error discovering commands: {e}")
+    
+    return service
+
+
+def main():
+    """Run microservice with command discovery."""
+    # Setup application
+    service = setup_application()
+    
+    # Check if port is overridden by environment variable (for testing)
+    if "TEST_SERVER_PORT" in os.environ:
+        port = int(os.environ["TEST_SERVER_PORT"])
+        service.port = port
+        logger.info(f"Using test port from environment: {port}")
     
     # Run server with parameters from configuration
     service.run()

examples/minimal_example/README.md

@@ -1,4 +1,4 @@
-# Минимальный пример MCP Microservice
+# Минимальный пример MCP Proxy Adapter
 
 Данный пример демонстрирует минимальную конфигурацию для запуска микросервиса с одной простой командой.
 
@@ -6,9 +6,12 @@
 
 ```
 minimal_example/
-├── config.yaml            # Файл конфигурации
+├── config.json            # Файл конфигурации в JSON формате
 ├── README.md              # Документация
-└── simple_server.py       # Пример сервера с одной командой
+├── simple_server.py       # Пример сервера с одной командой
+└── tests/                 # Директория с интеграционными тестами
+    ├── conftest.py        # Настройка тестов
+    └── test_integration.py # Интеграционные тесты
 ```
 
 ## Запуск примера
@@ -43,9 +46,20 @@ curl -X POST "http://localhost:8000/cmd" \
   -d '{"command": "hello", "params": {"name": "User"}}'
 ```
 
+### Запуск интеграционных тестов
+
+```bash
+# Запуск всех тестов
+pytest tests/test_integration.py -v
+
+# Запуск конкретного теста
+pytest tests/test_integration.py::TestHelloCommandIntegration::test_jsonrpc_hello_default -v
+```
+
 ## Что демонстрирует этот пример
 
-1. Создание минимального микросервиса
-2. Определение простой команды
+1. Создание минимального сервиса с MCP Proxy Adapter
+2. Определение простой команды с метаданными
 3. Основные эндпоинты API
-4. Работа с JSON-RPC 
+4. Работа с JSON-RPC
+5. Тестирование API через интеграционные тесты 

examples/minimal_example/config.json

@@ -1,21 +1,14 @@
 {
-  "service": {
-    "name": "Minimal Example",
-    "version": "1.0.0"
-  },
   "server": {
     "host": "0.0.0.0",
     "port": 8000,
     "debug": true,
-    "log_level": "info"
+    "log_level": "INFO"
   },
   "logging": {
-    "level": "INFO",
-    "file": "logs/minimal_example.log",
-    "rotation": {
-      "type": "size",
-      "max_bytes": 10485760,
-      "backup_count": 5
-    }
-  }
-} 
+    "level": "info",
+    "file": null,
+    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+  },
+  "debug": true
+}