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

examples/basic_example/docs/EN/README.md

@@ -0,0 +1,136 @@
+# 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.yaml                # 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
+```
+
+## 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
+python server.py
+```
+
+After starting, the server will be available at [http://localhost:8000](http://localhost:8000).
+
+## 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
+5. Different ways to call commands (JSON-RPC, /cmd, /api/command/{command_name}) 

examples/basic_example/docs/RU/README.md

@@ -0,0 +1,136 @@
+# Базовый пример MCP Microservice
+
+Этот пример демонстрирует базовую функциональность MCP Microservice с несколькими командами,
+организованными в отдельные файлы.
+
+## Структура
+
+```
+basic_example/
+├── commands/                   # Директория с командами
+│   ├── __init__.py            # Инициализация пакета
+│   ├── echo_command.py        # Команда эхо
+│   ├── math_command.py        # Математическая команда
+│   └── time_command.py        # Команда времени
+├── config.yaml                # Файл конфигурации
+├── docs/                      # Документация
+│   ├── EN/                    # Английская документация
+│   │   └── README.md          # Английская версия данного файла
+│   └── RU/                    # Русская документация
+│       └── README.md          # Этот файл
+├── logs/                      # Директория для логов
+└── server.py                  # Файл запуска сервера
+```
+
+## Запуск примера
+
+```bash
+# Перейти в директорию проекта
+cd examples/basic_example
+
+# Создать директорию для логов, если она не существует
+mkdir -p logs
+
+# Запустить сервер
+python server.py
+```
+
+После запуска сервер будет доступен по адресу [http://localhost:8000](http://localhost:8000).
+
+## Доступные команды
+
+### 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}) 

examples/basic_example/main.py

@@ -0,0 +1,50 @@
+"""
+Пример запуска сервера mcp-proxy-adapter с базовыми командами.
+"""
+
+import os
+import sys
+import uvicorn
+import logging
+
+from mcp_proxy_adapter.api.app import create_app
+from mcp_proxy_adapter.config import config
+from mcp_proxy_adapter.core.logging import setup_logging
+
+# Импортируем команды из примера
+from commands.echo_command import EchoCommand
+from commands.math_command import MathCommand
+
+def main():
+    """
+    Основная функция запуска сервера.
+    """
+    try:
+        # Настраиваем логирование
+        log_level = config.get("logging.level", "INFO")
+        setup_logging(log_level)
+        
+        # Получаем настройки сервера
+        host = config.get("server.host", "0.0.0.0")
+        port = int(config.get("server.port", 8000))
+        
+        # Регистрируем команды
+        app = create_app()
+        
+        # Запускаем сервер
+        print(f"Запуск сервера на http://{host}:{port}")
+        print(f"Документация доступна по адресу: http://{host}:{port}/docs")
+        
+        uvicorn.run(
+            app,
+            host=host,
+            port=port,
+            reload=True if os.environ.get("DEBUG") else False,
+            log_level=log_level.lower()
+        )
+    except Exception as e:
+        print(f"Ошибка при запуске приложения: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

examples/basic_example/server.py

@@ -0,0 +1,45 @@
+"""
+Basic MCP Microservice example.
+
+This example demonstrates a microservice with multiple commands
+organized in separate files.
+"""
+
+import os
+import sys
+from typing import Dict, Any
+
+import mcp_proxy_adapter as mcp
+from mcp_proxy_adapter import MicroService
+
+# 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."""
+    # Get absolute paths
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    config_path = os.path.join(current_dir, "config.yaml")
+    
+    # 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
+    )
+    
+    # Discover and register commands from the commands directory
+    package_path = "commands"  # Relative import path
+    service.discover_commands(package_path)
+    
+    # Run server
+    service.run(reload=True)
+
+
+if __name__ == "__main__":
+    main() 

examples/basic_example/tests/conftest.py

@@ -0,0 +1,243 @@
+"""
+Pytest configuration and fixtures for basic example tests.
+
+This module provides fixtures for testing the basic microservice example,
+including running an actual server instance for integration tests.
+All commands in the microservice are implemented as asynchronous functions.
+"""
+
+import os
+import sys
+import time
+import socket
+import asyncio
+import threading
+import multiprocessing
+from typing import Callable, Dict, Any, List
+
+import pytest
+import requests
+
+# Add parent directory to path for imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# Import the server module from the parent directory
+import server as server_module
+from commands.echo_command import EchoCommand
+from commands.math_command import MathCommand
+from commands.time_command import TimeCommand
+
+
+def find_free_port() -> int:
+    """
+    Find a free port on localhost.
+    
+    Returns:
+        Free port number
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(('localhost', 0))
+        return sock.getsockname()[1]
+
+
+class ServerProcess:
+    """Helper class to manage server process."""
+    
+    def __init__(self, port: int):
+        """
+        Initialize server process with a specified port.
+        
+        Args:
+            port: Port number to use
+        """
+        self.port = port
+        self.process = None
+        
+    def start(self) -> None:
+        """Start the server in a separate process."""
+        def run_server():
+            # Mock the configuration to use the test port
+            os.environ["TEST_SERVER_PORT"] = str(self.port)
+            server_module.main()
+            
+        self.process = multiprocessing.Process(target=run_server)
+        self.process.daemon = True
+        self.process.start()
+        
+        # Wait for server to start
+        self._wait_for_server()
+        
+    def stop(self) -> None:
+        """Stop the server process."""
+        if self.process and self.process.is_alive():
+            self.process.terminate()
+            self.process.join(timeout=2)
+            
+    def _wait_for_server(self, max_attempts: int = 10) -> None:
+        """
+        Wait for the server to become available.
+        
+        Args:
+            max_attempts: Maximum number of connection attempts
+        """
+        for i in range(max_attempts):
+            try:
+                response = requests.get(f"http://localhost:{self.port}/health")
+                if response.status_code == 200:
+                    return
+            except requests.ConnectionError:
+                pass
+            
+            time.sleep(0.5)
+            
+        raise TimeoutError(f"Server did not start within {max_attempts * 0.5} seconds")
+
+
+@pytest.fixture
+def server_port() -> int:
+    """
+    Fixture that provides a free port for the test server.
+    
+    Returns:
+        Port number
+    """
+    return find_free_port()
+
+
+@pytest.fixture
+def server(server_port: int) -> ServerProcess:
+    """
+    Fixture that provides a running server instance.
+    
+    Args:
+        server_port: Port to run the server on
+    
+    Returns:
+        Server process object
+    """
+    server_process = ServerProcess(server_port)
+    server_process.start()
+    
+    yield server_process
+    
+    server_process.stop()
+
+
+@pytest.fixture
+def api_url(server_port: int) -> str:
+    """
+    Fixture that provides the base API URL.
+    
+    Args:
+        server_port: Server port
+        
+    Returns:
+        Base API URL
+    """
+    return f"http://localhost:{server_port}"
+
+
+@pytest.fixture
+def jsonrpc_client(api_url: str) -> Callable:
+    """
+    Fixture that provides a JSON-RPC client function.
+    
+    Args:
+        api_url: Base API URL
+        
+    Returns:
+        Function to make JSON-RPC requests
+    """
+    def make_request(method: str, params: Dict[str, Any], request_id: int = 1) -> Dict[str, Any]:
+        """
+        Make a JSON-RPC request.
+        
+        Args:
+            method: Method name
+            params: Method parameters
+            request_id: Request ID
+            
+        Returns:
+            JSON-RPC response
+        """
+        payload = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params,
+            "id": request_id
+        }
+        
+        response = requests.post(
+            f"{api_url}/api/jsonrpc",
+            json=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        
+        return response.json()
+    
+    return make_request
+
+
+@pytest.fixture
+def batch_jsonrpc_client(api_url: str) -> Callable:
+    """
+    Fixture that provides a batch JSON-RPC client function.
+    
+    Args:
+        api_url: Base API URL
+        
+    Returns:
+        Function to make batch JSON-RPC requests
+    """
+    def make_batch_request(requests_data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Make a batch JSON-RPC request.
+        
+        Args:
+            requests_data: List of request objects
+            
+        Returns:
+            List of JSON-RPC responses
+        """
+        response = requests.post(
+            f"{api_url}/api/jsonrpc",
+            json=requests_data,
+            headers={"Content-Type": "application/json"}
+        )
+        
+        return response.json()
+    
+    return make_batch_request
+
+
+@pytest.fixture
+def echo_command() -> EchoCommand:
+    """
+    Fixture that provides an instance of EchoCommand.
+    
+    Returns:
+        EchoCommand instance
+    """
+    return EchoCommand()
+
+
+@pytest.fixture
+def math_command() -> MathCommand:
+    """
+    Fixture that provides an instance of MathCommand.
+    
+    Returns:
+        MathCommand instance
+    """
+    return MathCommand()
+
+
+@pytest.fixture
+def time_command() -> TimeCommand:
+    """
+    Fixture that provides an instance of TimeCommand.
+    
+    Returns:
+        TimeCommand instance
+    """
+    return TimeCommand() 

examples/commands/echo_command.py

@@ -0,0 +1,52 @@
+"""
+Module with echo command implementation.
+"""
+
+from typing import Any, Dict, Optional, ClassVar, Type
+
+from pydantic import BaseModel, Field, ValidationError as PydanticValidationError
+
+from mcp_proxy_adapter.commands.base import Command
+from examples.commands.echo_result import EchoResult
+from mcp_proxy_adapter.core.errors import ValidationError
+from mcp_proxy_adapter.core.logging import logger
+
+
+class EchoCommand(Command):
+    """
+    Command that echoes back the parameters it receives.
+    
+    This command is useful for testing parameter passing and debugging.
+    """
+    
+    name: ClassVar[str] = "echo"
+    result_class: ClassVar[Type[EchoResult]] = EchoResult
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """
+        Returns JSON schema for command parameters validation.
+        
+        Returns:
+            Dictionary with JSON schema.
+        """
+        return {
+            "type": "object",
+            "additionalProperties": True,
+            "description": "Any parameters will be echoed back in the response"
+        }
+    
+    async def execute(self, **kwargs) -> EchoResult:
+        """
+        Executes echo command and returns the parameters back.
+        
+        Args:
+            **kwargs: Any parameters to echo back.
+            
+        Returns:
+            EchoResult: Command execution result with the parameters.
+        """
+        logger.debug(f"Echo command received parameters: {kwargs}")
+        
+        # Simply return the parameters that were passed
+        return EchoResult(params=kwargs)