mcp-proxy-adapter 2.0.2__py3-none-any.whl → 2.1.1__py3-none-any.whl

docs/mcp_proxy_adapter.md

@@ -0,0 +1,251 @@
+# MCP Proxy Adapter
+
+## Overview
+
+MCP Proxy Adapter is a specialized adapter for integrating Command Registry with MCP Proxy (Model Control Protocol Proxy). It allows using commands from Command Registry as tools for artificial intelligence models, providing a unified JSON-RPC interface for interacting with commands.
+
+## Key Features
+
+- **JSON-RPC interface** for executing commands from the registry
+- **Automatic configuration generation** for MCPProxy
+- **OpenAPI schema optimization** for working with AI models
+- **Enhanced error handling** with detailed logging
+- **Parameter type validation** to prevent runtime errors
+- **Integration with any FastAPI applications**
+
+## Installation
+
+```bash
+pip install mcp-proxy-adapter
+```
+
+## Quick Start
+
+### Basic Integration
+
+```python
+from fastapi import FastAPI
+from command_registry import CommandRegistry
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+# Create FastAPI application
+app = FastAPI()
+
+# Create command registry
+registry = CommandRegistry()
+
+# Register commands
+registry.register_command("search_by_text", search_function, 
+                          description="Search by text query")
+
+# Create MCP Proxy adapter
+adapter = MCPProxyAdapter(registry)
+
+# Register endpoints in FastAPI application
+adapter.register_endpoints(app)
+
+# Save MCP Proxy configuration to file
+adapter.save_config_to_file("mcp_proxy_config.json")
+```
+
+### Working with External Loggers
+
+```python
+import logging
+from mcp_proxy_adapter.adapter import configure_logger
+
+# Create application logger
+app_logger = logging.getLogger("my_application")
+app_logger.setLevel(logging.DEBUG)
+
+# Configure handler for logger
+handler = logging.StreamHandler()
+handler.setFormatter(logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s'))
+app_logger.addHandler(handler)
+
+# Integrate application logger with adapter
+adapter_logger = configure_logger(app_logger)
+
+# Now all messages from adapter will go through application logger
+```
+
+## Architecture
+
+### Core Components
+
+MCP Proxy Adapter consists of the following components:
+
+1. **MCPProxyAdapter** — main class providing integration with Command Registry and FastAPI
+2. **JsonRpcRequest/JsonRpcResponse** — models for working with JSON-RPC requests and responses
+3. **SchemaOptimizer** — OpenAPI schema optimizer for working with MCP Proxy
+4. **MCPProxyConfig/MCPProxyTool** — models for forming MCP Proxy configuration
+
+### Technical Implementation Details
+
+Based on code analysis, the following was discovered:
+
+1. **Implementation duplication** — MCPProxyAdapter is present in two files:
+   - `src/adapter.py` (394 lines) — main adapter implementation
+   - `src/adapters/mcp_proxy_adapter.py` — specialized version
+
+2. **OpenAPI Schemas** — a significant part of the codebase consists of OpenAPI schemas:
+   - `src/openapi_schema/rest_schema.py` (506 lines)
+   - `src/openapi_schema/rpc_schema.py` (414 lines)
+
+3. **Method Call Chains**:
+   - `__init__` calls `_generate_router` for FastAPI router setup
+   - `save_config_to_file` uses `generate_mcp_proxy_config`
+   - `get_openapi_schema` uses `_generate_basic_schema`
+   - `execute_command` uses `_validate_param_types` for type checking
+
+### Interaction Diagram
+
+```
+┌─────────────────┐      ┌────────────────────┐      ┌─────────────────┐
+│                 │      │                    │      │                 │
+│    MCP Proxy    │      │  MCPProxyAdapter   │      │ CommandRegistry │
+│                 │◄─────┤                    │◄─────┤                 │
+└─────────────────┘      └────────────────────┘      └─────────────────┘
+        ▲                         ▲                          ▲
+        │                         │                          │
+        │                ┌────────┴───────┐                  │
+        │                │                │                  │
+        └────────────────┤  FastAPI App   │──────────────────┘
+                         │                │
+                         └────────────────┘
+```
+
+## Adapter API
+
+### Initialization
+
+```python
+def __init__(
+    self, 
+    registry: CommandRegistry,
+    cmd_endpoint: str = "/cmd",
+    include_schema: bool = True,
+    optimize_schema: bool = True
+)
+```
+
+* **registry** — CommandRegistry instance for integration
+* **cmd_endpoint** — path for command execution endpoint
+* **include_schema** — whether to include OpenAPI schema generation
+* **optimize_schema** — whether to optimize schema for MCP Proxy
+
+### Main Methods
+
+* **register_endpoints(app: FastAPI)** — registers endpoints in FastAPI application
+* **generate_mcp_proxy_config()** — generates configuration for MCP Proxy
+* **save_config_to_file(filename: str)** — saves configuration to file
+* **_generate_router()** — internal method for generating FastAPI router
+* **_validate_param_types(command, params)** — checks parameter types before command execution
+* **_generate_basic_schema()** — creates basic OpenAPI schema when generator is absent
+* **_optimize_schema(schema)** — optimizes OpenAPI schema for MCP Proxy
+
+## Implementation Features
+
+Code analysis revealed the following important implementation aspects:
+
+1. **Parameter Validation** occurs in several stages:
+   - First, command presence in registry is checked
+   - Then, presence of all required parameters is verified
+   - After that, types of all passed parameters are checked
+
+2. **Error Handling** is implemented using an extensive try/except mechanism that:
+   - Catches specific exceptions (TypeError, KeyError)
+   - Handles general exceptions through Exception block
+   - Formats all errors in JSON-RPC format with appropriate codes
+
+3. **Schema Optimization** includes several steps:
+   - Removing redundant information from OpenAPI schema
+   - Adding JSON-RPC components
+   - Preparing schema for use with MCP Proxy
+
+## JSON-RPC Protocol
+
+### Request Format
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "command_name",
+  "params": {
+    "param1": "value1",
+    "param2": "value2"
+  },
+  "id": "request_id"
+}
+```
+
+### Successful Response Format
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    // Command execution result
+  },
+  "id": "request_id"
+}
+```
+
+### Error Response Format
+
+```json
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32603,
+    "message": "Error description"
+  },
+  "id": "request_id"
+}
+```
+
+## Error Handling
+
+The adapter handles and logs the following error types:
+
+1. **Non-existent Command** (-32601) — calling a command not registered in the registry
+2. **Missing Required Parameters** (-32602) — required command parameters not specified
+3. **Parameter Type Errors** (-32602) — parameter type doesn't match expected type
+4. **Command Execution Errors** (-32603) — exceptions occurring during execution
+5. **Internal Server Errors** (-32603) — unexpected errors in adapter operation
+
+## Usage Examples
+
+### Integration with Existing FastAPI Application
+
+```python
+from fastapi import FastAPI
+from command_registry import CommandRegistry
+from mcp_proxy_adapter.adapter import MCPProxyAdapter, configure_logger
+
+# Create main application
+app = FastAPI(title="My Application API")
+
+# Create command registry
+registry = CommandRegistry()
+
+# Register commands from different modules
+registry.scan_module("myapp.commands.search")
+registry.scan_module("myapp.commands.analytics")
+
+# Configure project logger and integrate it with adapter
+logger = logging.getLogger("myapp")
+adapter_logger = configure_logger(logger)
+
+# Create MCP Proxy adapter
+adapter = MCPProxyAdapter(registry)
+
+# Register endpoints in application
+adapter.register_endpoints(app)
+
+# Save configuration for MCP Proxy
+adapter.save_config_to_file("config/mcp_proxy_config.json")
+```
+
+### Parameter Type Validation
+``` 

docs/mcp_proxy_adapter_ru.md

@@ -0,0 +1,405 @@
+# MCP Proxy Adapter
+
+## Обзор
+
+MCP Proxy Adapter — это специализированный адаптер для интеграции Command Registry с MCP Proxy (Model Control Protocol Proxy). Он позволяет использовать команды из Command Registry как инструменты (tools) для моделей искусственного интеллекта, предоставляя унифицированный JSON-RPC интерфейс для взаимодействия с командами.
+
+## Основные возможности
+
+- **JSON-RPC интерфейс** для выполнения команд из реестра
+- **Автоматическая генерация конфигурации** для MCPProxy
+- **Оптимизация OpenAPI схемы** для работы с моделями ИИ
+- **Расширенная обработка ошибок** с детальным логированием
+- **Валидация типов параметров** для предотвращения ошибок во время выполнения
+- **Интеграция с любыми FastAPI приложениями**
+
+## Установка
+
+```bash
+pip install mcp-proxy-adapter
+```
+
+## Быстрый старт
+
+### Базовая интеграция
+
+```python
+from fastapi import FastAPI
+from command_registry import CommandRegistry
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+# Создаем приложение FastAPI
+app = FastAPI()
+
+# Создаем реестр команд
+registry = CommandRegistry()
+
+# Регистрируем команды
+registry.register_command("search_by_text", search_function, 
+                          description="Поиск по текстовому запросу")
+
+# Создаем MCP Proxy адаптер
+adapter = MCPProxyAdapter(registry)
+
+# Регистрируем эндпоинты в FastAPI приложении
+adapter.register_endpoints(app)
+
+# Сохраняем конфигурацию MCP Proxy в файл
+adapter.save_config_to_file("mcp_proxy_config.json")
+```
+
+### Работа с внешними логгерами
+
+```python
+import logging
+from mcp_proxy_adapter.adapter import configure_logger
+
+# Создаем логгер приложения
+app_logger = logging.getLogger("my_application")
+app_logger.setLevel(logging.DEBUG)
+
+# Настраиваем обработчик для логгера
+handler = logging.StreamHandler()
+handler.setFormatter(logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s'))
+app_logger.addHandler(handler)
+
+# Интегрируем логгер приложения с адаптером
+adapter_logger = configure_logger(app_logger)
+
+# Теперь все сообщения от адаптера будут проходить через логгер приложения
+```
+
+## Архитектура
+
+### Основные компоненты
+
+MCP Proxy Adapter состоит из следующих компонентов:
+
+1. **MCPProxyAdapter** — основной класс, обеспечивающий интеграцию с Command Registry и FastAPI
+2. **JsonRpcRequest/JsonRpcResponse** — модели для работы с JSON-RPC запросами и ответами
+3. **SchemaOptimizer** — оптимизатор OpenAPI схемы для работы с MCP Proxy
+4. **MCPProxyConfig/MCPProxyTool** — модели для формирования конфигурации MCP Proxy
+
+### Технические детали реализации
+
+На основании анализа кода было обнаружено:
+
+1. **Дублирование реализации** — MCPProxyAdapter представлен в двух файлах:
+   - `src/adapter.py` (394 строки) — основная реализация адаптера
+   - `src/adapters/mcp_proxy_adapter.py` — специализированная версия
+
+2. **Схемы OpenAPI** — значительную часть кодовой базы составляют схемы OpenAPI:
+   - `src/openapi_schema/rest_schema.py` (506 строк)
+   - `src/openapi_schema/rpc_schema.py` (414 строк)
+
+3. **Цепочки вызовов методов**:
+   - `__init__` вызывает `_generate_router` для настройки FastAPI маршрутизатора
+   - `save_config_to_file` использует `generate_mcp_proxy_config`
+   - `get_openapi_schema` использует `_generate_basic_schema`
+   - `execute_command` использует `_validate_param_types` для проверки типов
+
+### Диаграмма взаимодействия
+
+```
+┌─────────────────┐      ┌────────────────────┐      ┌─────────────────┐
+│                 │      │                    │      │                 │
+│    МСР Proxy    │      │  MCPProxyAdapter   │      │ CommandRegistry │
+│                 │◄─────┤                    │◄─────┤                 │
+└─────────────────┘      └────────────────────┘      └─────────────────┘
+        ▲                         ▲                          ▲
+        │                         │                          │
+        │                ┌────────┴───────┐                  │
+        │                │                │                  │
+        └────────────────┤  FastAPI App   │──────────────────┘
+                         │                │
+                         └────────────────┘
+```
+
+## API адаптера
+
+### Инициализация
+
+```python
+def __init__(
+    self, 
+    registry: CommandRegistry,
+    cmd_endpoint: str = "/cmd",
+    include_schema: bool = True,
+    optimize_schema: bool = True
+)
+```
+
+* **registry** — экземпляр CommandRegistry для интеграции
+* **cmd_endpoint** — путь для эндпоинта выполнения команд 
+* **include_schema** — включить ли генерацию схемы OpenAPI
+* **optimize_schema** — оптимизировать ли схему для MCP Proxy
+
+### Основные методы
+
+* **register_endpoints(app: FastAPI)** — регистрирует эндпоинты в приложении FastAPI
+* **generate_mcp_proxy_config()** — генерирует конфигурацию для MCP Proxy
+* **save_config_to_file(filename: str)** — сохраняет конфигурацию в файл
+* **_generate_router()** — внутренний метод для генерации маршрутизатора FastAPI
+* **_validate_param_types(command, params)** — проверяет типы параметров перед выполнением команды
+* **_generate_basic_schema()** — создает базовую схему OpenAPI при отсутствии генератора
+* **_optimize_schema(schema)** — оптимизирует схему OpenAPI для MCP Proxy
+
+## Особенности реализации
+
+Анализ кода показал следующие важные аспекты реализации:
+
+1. **Валидация параметров** происходит в несколько этапов:
+   - Сначала проверяется наличие команды в реестре
+   - Затем проверяется наличие всех обязательных параметров
+   - После этого проверяются типы всех переданных параметров
+
+2. **Обработка ошибок** реализована с помощью обширного механизма try/except, который:
+   - Перехватывает специфические исключения (TypeError, KeyError)
+   - Обрабатывает общие исключения через блок Exception
+   - Форматирует все ошибки в формат JSON-RPC с соответствующими кодами
+
+3. **Оптимизация схемы** включает несколько шагов:
+   - Удаление избыточной информации из схемы OpenAPI
+   - Добавление JSON-RPC компонентов
+   - Подготовка схемы для использования с MCP Proxy
+
+## JSON-RPC протокол
+
+### Формат запроса
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "имя_команды",
+  "params": {
+    "параметр1": "значение1",
+    "параметр2": "значение2"
+  },
+  "id": "идентификатор_запроса"
+}
+```
+
+### Формат успешного ответа
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    // Результат выполнения команды
+  },
+  "id": "идентификатор_запроса"
+}
+```
+
+### Формат ответа с ошибкой
+
+```json
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32603,
+    "message": "Описание ошибки"
+  },
+  "id": "идентификатор_запроса"
+}
+```
+
+## Обработка ошибок
+
+Адаптер обрабатывает и логирует следующие типы ошибок:
+
+1. **Несуществующая команда** (-32601) — вызов команды, которая не зарегистрирована в реестре
+2. **Отсутствие обязательных параметров** (-32602) — не указаны обязательные параметры команды
+3. **Ошибки типов параметров** (-32602) — тип параметра не соответствует ожидаемому
+4. **Ошибки при выполнении команды** (-32603) — исключения, возникающие в процессе выполнения
+5. **Внутренние ошибки сервера** (-32603) — непредвиденные ошибки в работе адаптера
+
+## Примеры использования
+
+### Интеграция с существующим FastAPI приложением
+
+```python
+from fastapi import FastAPI
+from command_registry import CommandRegistry
+from mcp_proxy_adapter.adapter import MCPProxyAdapter, configure_logger
+
+# Создаем основное приложение
+app = FastAPI(title="My Application API")
+
+# Создаем реестр команд
+registry = CommandRegistry()
+
+# Регистрируем команды из разных модулей
+registry.scan_module("myapp.commands.search")
+registry.scan_module("myapp.commands.analytics")
+
+# Настраиваем логгер проекта и интегрируем его с адаптером
+logger = logging.getLogger("myapp")
+adapter_logger = configure_logger(logger)
+
+# Создаем MCP Proxy адаптер
+adapter = MCPProxyAdapter(registry)
+
+# Регистрируем эндпоинты в приложении
+adapter.register_endpoints(app)
+
+# Сохраняем конфигурацию для MCP Proxy
+adapter.save_config_to_file("config/mcp_proxy_config.json")
+```
+
+### Валидация типов параметров
+
+MCP Proxy Adapter автоматически проверяет типы параметров перед выполнением команды:
+
+```python
+# Определение команды с типизированными параметрами
+def search_documents(query: str, max_results: int = 10, filters: dict = None) -> list:
+    """
+    Поиск документов по запросу.
+    
+    Args:
+        query: Поисковый запрос
+        max_results: Максимальное количество результатов
+        filters: Фильтры для уточнения поиска
+        
+    Returns:
+        Список найденных документов
+    """
+    # Реализация поиска...
+    
+# Пример JSON-RPC запроса с некорректным типом
+# {
+#   "jsonrpc": "2.0",
+#   "method": "search_documents",
+#   "params": {
+#     "query": "test query",
+#     "max_results": "not_a_number"  # Должно быть числом
+#   },
+#   "id": 1
+# }
+#
+# Ответ с ошибкой:
+# {
+#   "jsonrpc": "2.0",
+#   "error": {
+#     "code": -32602,
+#     "message": "Invalid parameter types: Параметр 'max_results' должен быть целым числом"
+#   },
+#   "id": 1
+# }
+```
+
+## Тестирование адаптера
+
+Для тестирования MCP Proxy Adapter рекомендуется использовать следующий подход:
+
+```python
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from command_registry import CommandRegistry
+from mcp_proxy_adapter.adapter import MCPProxyAdapter
+
+# Тестовая команда
+def test_command(value: int = 1) -> dict:
+    """Тестовая команда."""
+    return {"result": value * 2}
+
+@pytest.fixture
+def test_app():
+    """Создает тестовое приложение с настроенным адаптером."""
+    # Создаем реестр команд
+    registry = CommandRegistry()
+    registry.register_command("test", test_command)
+    
+    # Создаем адаптер
+    adapter = MCPProxyAdapter(registry)
+    
+    # Создаем приложение FastAPI
+    app = FastAPI()
+    adapter.register_endpoints(app)
+    
+    # Возвращаем тестовый клиент
+    return TestClient(app)
+
+def test_successful_command_execution(test_app):
+    """Тест успешного выполнения команды."""
+    response = test_app.post("/cmd", json={
+        "jsonrpc": "2.0",
+        "method": "test",
+        "params": {"value": 5},
+        "id": 1
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert data["result"] == {"result": 10}
+    assert data["jsonrpc"] == "2.0"
+    assert data["id"] == 1
+```
+
+## Интеграция с MCP Proxy
+
+### Конфигурация MCP Proxy
+
+MCP Proxy Adapter автоматически генерирует конфигурацию для MCP Proxy:
+
+```json
+{
+  "version": "1.0",
+  "tools": [
+    {
+      "name": "mcp_search_documents",
+      "description": "Поиск документов по запросу",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Поисковый запрос"
+          },
+          "max_results": {
+            "type": "integer",
+            "description": "Максимальное количество результатов"
+          },
+          "filters": {
+            "type": "object",
+            "description": "Фильтры для уточнения поиска"
+          }
+        },
+        "required": ["query"]
+      }
+    }
+  ],
+  "routes": [
+    {
+      "path": "/cmd",
+      "type": "json_rpc",
+      "method_field": "method",
+      "params_field": "params"
+    }
+  ]
+}
+```
+
+### Запуск с MCP Proxy
+
+1. Запустите ваше FastAPI приложение с MCPProxyAdapter
+2. Запустите MCP Proxy с сгенерированной конфигурацией:
+   ```bash
+   mcp-proxy --config mcp_proxy_config.json
+   ```
+3. Настройте модель ИИ для работы с MCP Proxy
+
+## Известные проблемы и ограничения
+
+Анализ кода показал следующие моменты, о которых следует знать:
+
+1. **Дублирование реализации** — адаптер реализован в двух разных файлах, что может привести к несогласованности при обновлениях. Рекомендуется использовать версию из `mcp_proxy_adapter.adapter`.
+
+2. **Большой размер схем** — схемы OpenAPI довольно объемные (более 400 строк), что может повлиять на производительность при обработке большого количества команд.
+
+3. **Ограничения обнаружения типов** — валидация типов работает только с базовыми типами Python и может иметь ограничения при работе со сложными пользовательскими типами.
+
+## Заключение
+
+MCP Proxy Adapter — это мощный инструмент для интеграции Command Registry с моделями искусственного интеллекта через MCP Proxy. Он предоставляет унифицированный JSON-RPC интерфейс, автоматически генерирует конфигурацию для MCP Proxy и обеспечивает надежную обработку ошибок и валидацию параметров.