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

examples/basic_example/docs/EN/README.md

@@ -0,0 +1,177 @@
+# Basic MCP Microservice Example
+
+This example demonstrates the basic functionality of MCP Microservice with multiple commands
+organized in separate files.
+
+## Structure
+
+```
+basic_example/
+├── commands/                   # Commands directory
+│   ├── __init__.py            # Package initialization
+│   ├── echo_command.py        # Echo command
+│   ├── math_command.py        # Math command
+│   └── time_command.py        # Time command
+├── 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 and application logic
+└── tests/                     # Tests directory
+    └── conftest.py            # Test configuration and fixtures
+```
+
+## Running the Example
+
+```bash
+# Navigate to the project directory
+cd examples/basic_example
+
+# Create logs directory if it doesn't exist
+mkdir -p logs
+
+# 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
+
+Returns the provided message.
+
+**Parameters:**
+- `message` (string) - Message to echo back
+
+**Example request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "echo",
+  "params": {
+    "message": "Hello, World!"
+  },
+  "id": 1
+}
+```
+
+### 2. `math` - Math Command
+
+Performs a math operation on two numbers.
+
+**Parameters:**
+- `a` (number) - First number
+- `b` (number) - Second number
+- `operation` (string) - Operation (add, subtract, multiply, divide)
+
+**Example request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "math",
+  "params": {
+    "a": 10,
+    "b": 5,
+    "operation": "add"
+  },
+  "id": 1
+}
+```
+
+### 3. `time` - Time Command
+
+Returns the current time and date.
+
+**Parameters:**
+- `format` (string, optional) - Time format (default: "%Y-%m-%d %H:%M:%S")
+- `timezone` (string, optional) - Timezone (default: "UTC")
+
+**Example request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "time",
+  "params": {
+    "format": "%d.%m.%Y %H:%M:%S",
+    "timezone": "Europe/London"
+  },
+  "id": 1
+}
+```
+
+## Testing the API
+
+### Via Web Interface
+
+Open [http://localhost:8000/docs](http://localhost:8000/docs) in your browser to access the Swagger UI interactive documentation.
+
+### Via Command Line
+
+```bash
+# Call echo command via JSON-RPC
+curl -X POST "http://localhost:8000/api/jsonrpc" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello!"}, "id": 1}'
+
+# Call math command via simplified endpoint
+curl -X POST "http://localhost:8000/cmd" \
+  -H "Content-Type: application/json" \
+  -d '{"command": "math", "params": {"a": 10, "b": 5, "operation": "add"}}'
+
+# Call time command via endpoint /api/command/{command_name}
+curl -X POST "http://localhost:8000/api/command/time" \
+  -H "Content-Type: application/json" \
+  -d '{"format": "%d.%m.%Y %H:%M:%S", "timezone": "UTC"}'
+```
+
+## Key Features Demonstrated
+
+1. Command organization in separate files
+2. Automatic command discovery and registration
+3. Different command types and parameter handling
+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

@@ -0,0 +1,177 @@
+# Базовый пример MCP Microservice
+
+Этот пример демонстрирует базовую функциональность MCP Microservice с несколькими командами,
+организованными в отдельные файлы.
+
+## Структура
+
+```
+basic_example/
+├── commands/                   # Директория с командами
+│   ├── __init__.py            # Инициализация пакета
+│   ├── echo_command.py        # Команда эхо
+│   ├── math_command.py        # Математическая команда
+│   └── time_command.py        # Команда времени
+├── config.json                # Файл конфигурации JSON
+├── docs/                      # Документация
+│   ├── EN/                    # Английская документация
+│   │   └── README.md          # Английская версия данного файла
+│   └── RU/                    # Русская документация
+│       └── README.md          # Этот файл
+├── logs/                      # Директория для логов
+├── server.py                  # Файл запуска сервера и логики приложения
+└── tests/                     # Директория с тестами
+    └── conftest.py            # Конфигурация и фикстуры для тестов
+```
+
+## Запуск примера
+
+```bash
+# Перейти в директорию проекта
+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` - Эхо-команда
+
+Возвращает переданное сообщение.
+
+**Параметры:**
+- `message` (string) - Сообщение для эхо
+
+**Пример запроса:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "echo",
+  "params": {
+    "message": "Hello, World!"
+  },
+  "id": 1
+}
+```
+
+### 2. `math` - Математическая команда
+
+Выполняет математическую операцию над двумя числами.
+
+**Параметры:**
+- `a` (number) - Первое число
+- `b` (number) - Второе число
+- `operation` (string) - Операция (add, subtract, multiply, divide)
+
+**Пример запроса:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "math",
+  "params": {
+    "a": 10,
+    "b": 5,
+    "operation": "add"
+  },
+  "id": 1
+}
+```
+
+### 3. `time` - Команда времени
+
+Возвращает текущее время и дату.
+
+**Параметры:**
+- `format` (string, опционально) - Формат времени (по умолчанию: "%Y-%m-%d %H:%M:%S")
+- `timezone` (string, опционально) - Часовой пояс (по умолчанию: "UTC")
+
+**Пример запроса:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "time",
+  "params": {
+    "format": "%d.%m.%Y %H:%M:%S",
+    "timezone": "Europe/Moscow"
+  },
+  "id": 1
+}
+```
+
+## Тестирование API
+
+### Через веб-интерфейс
+
+Откройте в браузере [http://localhost:8000/docs](http://localhost:8000/docs) для доступа к интерактивной документации Swagger UI.
+
+### Через командную строку
+
+```bash
+# Вызов команды echo через JSON-RPC
+curl -X POST "http://localhost:8000/api/jsonrpc" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello!"}, "id": 1}'
+
+# Вызов команды math через упрощенный эндпоинт
+curl -X POST "http://localhost:8000/cmd" \
+  -H "Content-Type: application/json" \
+  -d '{"command": "math", "params": {"a": 10, "b": 5, "operation": "add"}}'
+
+# Вызов команды time через endpoint /api/command/{command_name}
+curl -X POST "http://localhost:8000/api/command/time" \
+  -H "Content-Type: application/json" \
+  -d '{"format": "%d.%m.%Y %H:%M:%S", "timezone": "UTC"}'
+```
+
+## Ключевые особенности, демонстрируемые примером
+
+1. Организация команд в отдельные файлы
+2. Автоматическое обнаружение и регистрация команд
+3. Различные типы команд и параметров
+4. Обработка ошибок и автоматическая перерегистрация команд
+5. Различные способы вызова команд (JSON-RPC, /cmd, /api/command/{command_name})
+6. Поддержка режима отладки с горячей перезагрузкой
+7. Безопасная регистрация команд для предотвращения конфликтов
+8. JSON-файлы конфигурации с опциями командной строки 

examples/basic_example/server.py

@@ -0,0 +1,151 @@
+"""
+Basic MCP Proxy Adapter example.
+
+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
+
+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 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 = 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
+    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"
+    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
+    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__":
+    main()