mcp-proxy-adapter 2.1.0__py3-none-any.whl → 2.1.2__py3-none-any.whl

docs/quickstart.md

@@ -0,0 +1,251 @@
+# Command Registry Quick Start
+
+This guide will help you quickly get started with the Command Registry system and integrate it into your application.
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install command-registry
+```
+
+## Basic Usage
+
+### 1. Defining a Command
+
+Create a `commands.py` file with your commands:
+
+```python
+from typing import List, Dict, Any, Optional
+
+def add_item(
+    item_name: str,
+    quantity: int = 1,
+    properties: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Adds a new item to the system.
+    
+    Args:
+        item_name: Name of the item
+        quantity: Item quantity (default 1)
+        properties: Additional item properties
+        
+    Returns:
+        Information about the created item
+    """
+    # In a real application, this would be code for
+    # saving the item to a database
+    item_id = "item_" + str(hash(item_name))
+    item = {
+        "id": item_id,
+        "name": item_name,
+        "quantity": quantity,
+        "properties": properties or {}
+    }
+    return item
+
+def get_items(
+    search_term: Optional[str] = None,
+    limit: int = 10,
+    offset: int = 0
+) -> List[Dict[str, Any]]:
+    """
+    Gets a list of items with search and pagination capabilities.
+    
+    Args:
+        search_term: String to search by name (optional)
+        limit: Maximum number of items to return
+        offset: Offset for result pagination
+        
+    Returns:
+        List of items matching search criteria
+    """
+    # In a real application, this would be code for
+    # retrieving items from a database
+    items = [
+        {"id": f"item_{i}", "name": f"Item {i}", "quantity": i % 10}
+        for i in range(offset, offset + limit)
+    ]
+    
+    if search_term:
+        items = [item for item in items if search_term.lower() in item["name"].lower()]
+        
+    return items
+```
+
+### 2. Creating Command Registry
+
+Create an `app.py` file with Command Registry initialization:
+
+```python
+from command_registry import CommandRegistry
+from command_registry.dispatchers import CommandDispatcher
+import commands
+
+# Create dispatcher instance
+dispatcher = CommandDispatcher()
+
+# Create command registry
+registry = CommandRegistry(dispatcher)
+
+# Register commands
+registry.register_command("add_item", commands.add_item)
+registry.register_command("get_items", commands.get_items)
+
+# Automatic registration of all commands from module (alternative way)
+# registry.scan_module(commands)
+```
+
+### 3. Executing Commands
+
+Add code to `app.py` for executing commands:
+
+```python
+# Execute add_item command
+result = registry.execute(
+    "add_item", 
+    {
+        "item_name": "Laptop",
+        "quantity": 5,
+        "properties": {"brand": "SuperLaptop", "color": "silver"}
+    }
+)
+print("add_item result:", result)
+
+# Execute get_items command
+items = registry.execute(
+    "get_items", 
+    {
+        "search_term": "Item",
+        "limit": 5
+    }
+)
+print(f"Found {len(items)} items:")
+for item in items:
+    print(f"- {item['name']} (ID: {item['id']}, Quantity: {item['quantity']})")
+```
+
+### 4. Command Information
+
+```python
+# Get list of available commands
+commands = registry.get_valid_commands()
+print("Available commands:", commands)
+
+# Get information about specific command
+info = registry.get_command_info("add_item")
+print("Information about add_item command:")
+print(f"- Description: {info['description']}")
+print(f"- Parameters: {list(info['params'].keys())}")
+```
+
+## Web Framework Integration
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from command_registry.adapters import RESTAdapter
+
+app = FastAPI(title="Command Registry API")
+
+# Create REST adapter
+rest_adapter = RESTAdapter(registry)
+
+# Register endpoints in FastAPI
+rest_adapter.register_endpoints(app)
+
+# Run application
+# uvicorn app:app --reload
+```
+
+### Flask
+
+```python
+from flask import Flask
+from command_registry.adapters import FlaskRESTAdapter
+
+app = Flask(__name__)
+
+# Create REST adapter for Flask
+flask_adapter = FlaskRESTAdapter(registry)
+
+# Register endpoints in Flask
+flask_adapter.register_endpoints(app)
+
+# Run application
+# app.run(debug=True)
+```
+
+### aiohttp
+
+```python
+from aiohttp import web
+from command_registry.adapters import AioHttpAdapter
+
+app = web.Application()
+
+# Create aiohttp adapter
+aiohttp_adapter = AioHttpAdapter(registry)
+
+# Register endpoints
+aiohttp_adapter.register_endpoints(app)
+
+# Run application
+# web.run_app(app)
+```
+
+## Using JSON-RPC
+
+```python
+from fastapi import FastAPI
+from command_registry.adapters import JSONRPCAdapter
+
+app = FastAPI(title="Command Registry JSON-RPC API")
+
+# Create JSON-RPC adapter
+jsonrpc_adapter = JSONRPCAdapter(registry)
+
+# Register JSON-RPC endpoint
+jsonrpc_adapter.register_endpoint(app, "/api/jsonrpc")
+
+# Run application
+# uvicorn app:app --reload
+```
+
+## Command Line Integration
+
+```python
+from command_registry.adapters import ClickAdapter
+import click
+
+# Create adapter for Click
+cli_adapter = ClickAdapter(registry)
+
+# Create CLI application
+cli = click.Group()
+
+# Register commands
+cli_adapter.register_commands(cli)
+
+# Run CLI
+if __name__ == "__main__":
+    cli()
+```
+
+## Error Handling
+
+```python
+from command_registry.exceptions import (
+    CommandNotFoundError,
+    ValidationError,
+    CommandExecutionError
+)
+
+try:
+    result = registry.execute("non_existent_command", {})
+except CommandNotFoundError as e:
+    print(f"Error: Command not found - {e}")
+``` 

docs/quickstart_ru.md

@@ -0,0 +1,397 @@
+# Быстрый старт Command Registry
+
+Это руководство поможет вам быстро начать работу с системой Command Registry и интегрировать её в ваше приложение.
+
+## Установка
+
+Установите пакет с помощью pip:
+
+```bash
+pip install command-registry
+```
+
+## Базовое использование
+
+### 1. Определение команды
+
+Создайте файл `commands.py` с вашими командами:
+
+```python
+from typing import List, Dict, Any, Optional
+
+def add_item(
+    item_name: str,
+    quantity: int = 1,
+    properties: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Добавляет новый товар в систему.
+    
+    Args:
+        item_name: Название товара
+        quantity: Количество товара (по умолчанию 1)
+        properties: Дополнительные свойства товара
+        
+    Returns:
+        Информация о созданном товаре
+    """
+    # В реальном приложении здесь был бы код для
+    # сохранения товара в базе данных
+    item_id = "item_" + str(hash(item_name))
+    item = {
+        "id": item_id,
+        "name": item_name,
+        "quantity": quantity,
+        "properties": properties or {}
+    }
+    return item
+
+def get_items(
+    search_term: Optional[str] = None,
+    limit: int = 10,
+    offset: int = 0
+) -> List[Dict[str, Any]]:
+    """
+    Получает список товаров с возможностью поиска и пагинации.
+    
+    Args:
+        search_term: Строка для поиска по названию (опционально)
+        limit: Максимальное количество возвращаемых товаров
+        offset: Смещение для пагинации результатов
+        
+    Returns:
+        Список товаров, соответствующих критериям поиска
+    """
+    # В реальном приложении здесь был бы код для
+    # получения товаров из базы данных
+    items = [
+        {"id": f"item_{i}", "name": f"Товар {i}", "quantity": i % 10}
+        for i in range(offset, offset + limit)
+    ]
+    
+    if search_term:
+        items = [item for item in items if search_term.lower() in item["name"].lower()]
+        
+    return items
+```
+
+### 2. Создание Command Registry
+
+Создайте файл `app.py` с инициализацией Command Registry:
+
+```python
+from command_registry import CommandRegistry
+from command_registry.dispatchers import CommandDispatcher
+import commands
+
+# Создание экземпляра диспетчера
+dispatcher = CommandDispatcher()
+
+# Создание реестра команд
+registry = CommandRegistry(dispatcher)
+
+# Регистрация команд
+registry.register_command("add_item", commands.add_item)
+registry.register_command("get_items", commands.get_items)
+
+# Автоматическая регистрация всех команд из модуля (альтернативный способ)
+# registry.scan_module(commands)
+```
+
+### 3. Выполнение команд
+
+Добавьте в `app.py` код для выполнения команд:
+
+```python
+# Выполнение команды add_item
+result = registry.execute(
+    "add_item", 
+    {
+        "item_name": "Ноутбук",
+        "quantity": 5,
+        "properties": {"brand": "SuperLaptop", "color": "silver"}
+    }
+)
+print("Результат add_item:", result)
+
+# Выполнение команды get_items
+items = registry.execute(
+    "get_items", 
+    {
+        "search_term": "Товар",
+        "limit": 5
+    }
+)
+print(f"Найдено {len(items)} товаров:")
+for item in items:
+    print(f"- {item['name']} (ID: {item['id']}, Количество: {item['quantity']})")
+```
+
+### 4. Информация о командах
+
+```python
+# Получение списка доступных команд
+commands = registry.get_valid_commands()
+print("Доступные команды:", commands)
+
+# Получение информации о конкретной команде
+info = registry.get_command_info("add_item")
+print("Информация о команде add_item:")
+print(f"- Описание: {info['description']}")
+print(f"- Параметры: {list(info['params'].keys())}")
+```
+
+## Интеграция с веб-фреймворками
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from command_registry.adapters import RESTAdapter
+
+app = FastAPI(title="Command Registry API")
+
+# Создание адаптера REST
+rest_adapter = RESTAdapter(registry)
+
+# Регистрация эндпоинтов в FastAPI
+rest_adapter.register_endpoints(app)
+
+# Запуск приложения
+# uvicorn app:app --reload
+```
+
+### Flask
+
+```python
+from flask import Flask
+from command_registry.adapters import FlaskRESTAdapter
+
+app = Flask(__name__)
+
+# Создание адаптера REST для Flask
+flask_adapter = FlaskRESTAdapter(registry)
+
+# Регистрация эндпоинтов в Flask
+flask_adapter.register_endpoints(app)
+
+# Запуск приложения
+# app.run(debug=True)
+```
+
+### aiohttp
+
+```python
+from aiohttp import web
+from command_registry.adapters import AioHttpAdapter
+
+app = web.Application()
+
+# Создание адаптера aiohttp
+aiohttp_adapter = AioHttpAdapter(registry)
+
+# Регистрация эндпоинтов
+aiohttp_adapter.register_endpoints(app)
+
+# Запуск приложения
+# web.run_app(app)
+```
+
+## Использование JSON-RPC
+
+```python
+from fastapi import FastAPI
+from command_registry.adapters import JSONRPCAdapter
+
+app = FastAPI(title="Command Registry JSON-RPC API")
+
+# Создание адаптера JSON-RPC
+jsonrpc_adapter = JSONRPCAdapter(registry)
+
+# Регистрация эндпоинта JSON-RPC
+jsonrpc_adapter.register_endpoint(app, "/api/jsonrpc")
+
+# Запуск приложения
+# uvicorn app:app --reload
+```
+
+## Интеграция с командной строкой
+
+```python
+from command_registry.adapters import ClickAdapter
+import click
+
+# Создание адаптера для Click
+cli_adapter = ClickAdapter(registry)
+
+# Создание CLI приложения
+cli = click.Group()
+
+# Регистрация команд
+cli_adapter.register_commands(cli)
+
+# Запуск CLI
+if __name__ == "__main__":
+    cli()
+```
+
+## Обработка ошибок
+
+```python
+from command_registry.exceptions import (
+    CommandNotFoundError,
+    ValidationError,
+    CommandExecutionError
+)
+
+try:
+    result = registry.execute("non_existent_command", {})
+except CommandNotFoundError as e:
+    print(f"Ошибка: Команда не найдена - {e}")
+    
+try:
+    result = registry.execute("add_item", {"wrong_param": "value"})
+except ValidationError as e:
+    print(f"Ошибка валидации: {e}")
+    print(f"Детали: {e.errors()}")
+    
+try:
+    result = registry.execute("add_item", {"item_name": None})
+except CommandExecutionError as e:
+    print(f"Ошибка выполнения: {e}")
+    print(f"Исходное исключение: {e.__cause__}")
+```
+
+## Валидация параметров
+
+Включение проверки типов и валидации:
+
+```python
+# При создании диспетчера
+dispatcher = CommandDispatcher(validate_types=True)
+
+# Или при создании реестра
+registry = CommandRegistry(dispatcher, validate_types=True)
+```
+
+## Генерация документации
+
+```python
+from command_registry.generators import OpenAPIGenerator
+
+# Создание генератора OpenAPI
+generator = OpenAPIGenerator(registry)
+
+# Генерация документа OpenAPI
+openapi_schema = generator.generate_schema(
+    title="Command Registry API",
+    version="1.0.0",
+    description="API для управления товарами"
+)
+
+# Сохранение схемы в файл
+import json
+with open("openapi.json", "w") as f:
+    json.dump(openapi_schema, f, indent=2)
+```
+
+## Полное демо-приложение
+
+```python
+from command_registry import CommandRegistry
+from command_registry.dispatchers import CommandDispatcher
+from command_registry.adapters import RESTAdapter
+from fastapi import FastAPI
+import uvicorn
+from typing import Dict, Any, List, Optional
+
+# Определение команд
+def add_item(
+    item_name: str,
+    quantity: int = 1,
+    properties: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Добавляет новый товар в систему.
+    
+    Args:
+        item_name: Название товара
+        quantity: Количество товара (по умолчанию 1)
+        properties: Дополнительные свойства товара
+        
+    Returns:
+        Информация о созданном товаре
+    """
+    item_id = "item_" + str(hash(item_name))
+    item = {
+        "id": item_id,
+        "name": item_name,
+        "quantity": quantity,
+        "properties": properties or {}
+    }
+    return item
+
+def get_items(
+    search_term: Optional[str] = None,
+    limit: int = 10,
+    offset: int = 0
+) -> List[Dict[str, Any]]:
+    """
+    Получает список товаров с возможностью поиска и пагинации.
+    
+    Args:
+        search_term: Строка для поиска по названию (опционально)
+        limit: Максимальное количество возвращаемых товаров
+        offset: Смещение для пагинации результатов
+        
+    Returns:
+        Список товаров, соответствующих критериям поиска
+    """
+    items = [
+        {"id": f"item_{i}", "name": f"Товар {i}", "quantity": i % 10}
+        for i in range(offset, offset + limit)
+    ]
+    
+    if search_term:
+        items = [item for item in items if search_term.lower() in item["name"].lower()]
+        
+    return items
+
+# Создание реестра команд
+dispatcher = CommandDispatcher(validate_types=True)
+registry = CommandRegistry(dispatcher)
+
+# Регистрация команд
+registry.register_command("add_item", add_item)
+registry.register_command("get_items", get_items)
+
+# Создание FastAPI приложения
+app = FastAPI(title="Inventory API")
+
+# Создание REST адаптера и регистрация эндпоинтов
+rest_adapter = RESTAdapter(registry)
+rest_adapter.register_endpoints(app)
+
+# Запуск приложения
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+Запустите приложение:
+
+```bash
+python app.py
+```
+
+После запуска вы можете:
+
+1. Открыть документацию API по адресу: http://localhost:8000/docs
+2. Тестировать эндпоинты через Swagger UI
+3. Отправлять запросы к API с помощью curl или Postman
+
+## Что дальше?
+
+- Изучите [архитектуру системы](architecture.md) для лучшего понимания её компонентов
+- Прочитайте [руководство по разработке команд](command_development.md) для изучения лучших практик
+- Познакомьтесь с возможностями [валидации](validation.md)
+- Изучите [примеры использования](examples.md) для различных сценариев