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

docs/validation_ru.md

@@ -1,287 +0,0 @@
-# Валидация команд и обработка ошибок
-
-В этом документе описаны процессы валидации команд в Command Registry и способы обработки ошибок.
-
-## Содержание
-
-- [Процесс валидации](#процесс-валидации)
-- [Типы валидаторов](#типы-валидаторов)
-- [Режимы работы](#режимы-работы)
-- [Типы ошибок](#типы-ошибок)
-- [Обработка ошибок](#обработка-ошибок)
-- [Автоматическое исправление](#автоматическое-исправление)
-
-## Процесс валидации
-
-Валидация команд выполняется перед их регистрацией в диспетчере. Процесс включает следующие шаги:
-
-1. **Анализ исходного кода**: извлечение метаданных из докстрингов и аннотаций типов
-2. **Проверка соответствия**: сравнение метаданных с формальными параметрами функции
-3. **Принятие решения**: регистрация команды или вывод ошибок в зависимости от режима работы
-
-```python
-# Основной процесс валидации в методе register_command
-def register_command(self, command_name: str, handler: Callable) -> bool:
-    # Анализ обработчика
-    metadata = self.analyze_handler(command_name, handler)
-    
-    # Валидация метаданных
-    is_valid, errors = self.validate_handler(command_name, handler, metadata)
-    
-    # Вывод ошибок, если они есть
-    if not is_valid:
-        for error in errors:
-            logger.error(f"{command_name}: {error}")
-        
-        # В строгом режиме прерываем регистрацию
-        if self.strict and not self.auto_fix:
-            return False
-    
-    # Регистрация команды
-    self.dispatcher.register_handler(
-        command=command_name,
-        handler=handler,
-        description=metadata["description"],
-        summary=metadata["summary"],
-        params=metadata["parameters"]
-    )
-    
-    return True
-```
-
-## Типы валидаторов
-
-Command Registry включает несколько типов валидаторов для разных аспектов проверки:
-
-### 1. DocstringValidator
-
-Проверяет соответствие докстрингов формальным параметрам функции:
-
-- Наличие описания функции
-- Описание всех параметров в секции Args
-- Наличие секции Returns
-- Соответствие имен параметров в докстринге и сигнатуре функции
-
-```python
-class DocstringValidator:
-    def validate(self, handler: Callable, command_name: str, metadata: Dict[str, Any]) -> Tuple[bool, List[str]]:
-        errors = []
-        
-        # Получаем формальные параметры функции
-        sig = inspect.signature(handler)
-        formal_params = list(sig.parameters.keys())
-        
-        # Парсим докстринг
-        docstring = handler.__doc__ or ""
-        parsed_doc = docstring_parser.parse(docstring)
-        
-        # Проверяем наличие описания функции
-        if not parsed_doc.short_description and not parsed_doc.long_description:
-            errors.append(f"Отсутствует описание функции")
-        
-        # Получаем параметры из докстринга
-        doc_params = {param.arg_name: param for param in parsed_doc.params}
-        
-        # Проверяем, что все формальные параметры описаны в докстринге
-        for param in formal_params:
-            if param not in doc_params and param != 'params':
-                errors.append(f"Параметр '{param}' не описан в докстринге функции")
-        
-        # Проверяем наличие returns в докстринге
-        if not parsed_doc.returns:
-            errors.append(f"Отсутствует описание возвращаемого значения в докстринге функции")
-        
-        return len(errors) == 0, errors
-```
-
-### 2. MetadataValidator
-
-Проверяет соответствие метаданных команды её сигнатуре:
-
-- Наличие всех обязательных параметров в метаданных
-- Соответствие типов параметров в метаданных и аннотациях
-- Отсутствие лишних параметров в метаданных
-
-```python
-class MetadataValidator:
-    def validate(self, handler: Callable, command_name: str, metadata: Dict[str, Any]) -> Tuple[bool, List[str]]:
-        errors = []
-        
-        # Получаем формальные параметры функции
-        sig = inspect.signature(handler)
-        
-        # Проверяем соответствие метаданных и формальных параметров
-        if "parameters" in metadata:
-            for param_name, param_info in metadata["parameters"].items():
-                # Проверяем наличие параметра в сигнатуре функции
-                if param_name not in sig.parameters:
-                    errors.append(f"Параметр '{param_name}' указан в метаданных, но отсутствует в сигнатуре функции")
-            
-            # Проверяем, что все обязательные параметры указаны в метаданных
-            for param_name, param in sig.parameters.items():
-                if param.default == inspect.Parameter.empty and param_name != 'self':
-                    if param_name not in metadata["parameters"]:
-                        errors.append(f"Обязательный параметр '{param_name}' не указан в метаданных")
-        
-        return len(errors) == 0, errors
-```
-
-## Режимы работы
-
-Command Registry поддерживает несколько режимов валидации, которые определяют поведение при обнаружении ошибок:
-
-### 1. Строгий режим (strict=True)
-
-В строгом режиме система отказывается регистрировать команды с ошибками в документации:
-
-- При обнаружении любой ошибки в документации команда не регистрируется
-- Выводятся подробные сообщения об ошибках для каждой команды
-- Рекомендуется использовать в CI/CD и продакшене для обеспечения качества кода
-
-```python
-# Пример использования строгого режима
-registry = CommandRegistry(strict=True, auto_fix=False)
-registry.register_all_commands()  # Команды с ошибками не будут зарегистрированы
-```
-
-### 2. Нестрогий режим (strict=False)
-
-В нестрогом режиме система регистрирует все команды, даже с ошибками:
-
-- При обнаружении ошибок выводятся предупреждения, но команда регистрируется
-- Может привести к неточностям в документации API
-- Полезен для быстрого прототипирования и отладки
-
-```python
-# Пример использования нестрогого режима
-registry = CommandRegistry(strict=False, auto_fix=False)
-registry.register_all_commands()  # Все команды будут зарегистрированы
-```
-
-### 3. Режим автоисправления (auto_fix=True)
-
-В режиме автоисправления система пытается автоматически исправить ошибки:
-
-- Недостающие метаданные извлекаются из аннотаций типов
-- Улучшается документация на основе имеющейся информации
-- Полезен при разработке, когда документация еще не полностью оформлена
-
-```python
-# Пример использования режима автоисправления
-registry = CommandRegistry(strict=True, auto_fix=True)
-registry.register_all_commands()  # Система попытается исправить ошибки
-```
-
-## Типы ошибок
-
-Валидаторы могут обнаруживать различные типы ошибок:
-
-### 1. Ошибки докстрингов
-
-- **Отсутствие описания функции**: докстринг пуст или содержит только код
-- **Отсутствие описания параметра**: параметр функции не описан в докстринге
-- **Отсутствие описания возвращаемого значения**: нет секции Returns
-- **Лишние параметры в докстринге**: в докстринге описаны параметры, которых нет в функции
-
-### 2. Ошибки метаданных
-
-- **Несоответствие типов**: тип в метаданных не соответствует аннотации типа
-- **Отсутствие обязательного параметра**: обязательный параметр не описан в метаданных
-- **Лишние параметры в метаданных**: в метаданных указаны параметры, которых нет в функции
-- **Некорректное описание**: отсутствует или неполное описание команды или параметра
-
-### 3. Ошибки аннотаций типов
-
-- **Отсутствие аннотации типа**: параметр не имеет аннотации типа
-- **Отсутствие аннотации возвращаемого значения**: функция не имеет аннотации возвращаемого значения
-- **Несоответствие типов в аннотациях и метаданных**: тип в аннотации не соответствует типу в метаданных
-
-## Обработка ошибок
-
-При обнаружении ошибок Command Registry предоставляет подробную информацию для их исправления:
-
-```
-🚫 Ошибки в команде 'search_by_vector':
-   - Параметр 'top_k' не описан в докстринге функции
-   - Отсутствует описание возвращаемого значения в докстринге функции
-   - Обязательный параметр 'vector' не указан в метаданных команды
-```
-
-В зависимости от режима работы, система может:
-
-1. **Отказаться регистрировать команду** (strict=True, auto_fix=False)
-2. **Зарегистрировать команду с предупреждениями** (strict=False)
-3. **Попытаться исправить ошибки автоматически** (auto_fix=True)
-
-### Рекомендуемый подход к обработке ошибок
-
-1. **В разработке**:
-   - Использовать auto_fix=True для автоматического исправления ошибок
-   - Регулярно запускать валидацию в строгом режиме для выявления проблем
-
-2. **В CI/CD**:
-   - Использовать strict=True для блокирования PR с ошибками в документации
-   - Добавить проверку валидации команд в процесс тестирования
-
-3. **В продакшене**:
-   - Всегда использовать strict=True для гарантии качества документации
-   - Никогда не использовать auto_fix=True в продакшен-среде
-
-## Автоматическое исправление
-
-Когда включен режим auto_fix=True, система пытается исправить ошибки автоматически:
-
-### 1. Дополнение метаданных
-
-Если метаданные неполные, система дополняет их на основе:
-
-- Аннотаций типов для определения типов параметров
-- Сигнатуры функции для определения обязательных параметров
-- Значений по умолчанию для определения default значений
-
-```python
-# Дополнение метаданных на основе аннотаций типов
-type_hints = get_type_hints(handler)
-for param_name, param_type in type_hints.items():
-    if param_name == 'return':
-        continue
-        
-    if param_name not in metadata["parameters"]:
-        metadata["parameters"][param_name] = {
-            "type": map_type_to_openapi(param_type),
-            "description": f"Параметр {param_name}",
-            "required": param_name in required_params
-        }
-```
-
-### 2. Извлечение описаний из докстрингов
-
-Если докстринги есть, но метаданные неполные, система извлекает описания из докстрингов:
-
-```python
-# Извлечение описаний из докстрингов
-parsed_doc = docstring_parser.parse(handler.__doc__ or "")
-for param in parsed_doc.params:
-    param_name = param.arg_name
-    if param_name in metadata["parameters"]:
-        metadata["parameters"][param_name]["description"] = param.description
-```
-
-### 3. Генерация базовых описаний
-
-Если описания отсутствуют, система генерирует базовые описания:
-
-```python
-# Генерация базовых описаний
-if not metadata.get("description"):
-    metadata["description"] = f"Команда {command_name}"
-
-if not metadata.get("summary"):
-    metadata["summary"] = command_name.replace("_", " ").title()
-```
-
-## Заключение
-
-Система валидации Command Registry помогает обеспечить высокое качество документации API за счет строгой проверки соответствия докстрингов, метаданных и сигнатур функций. 
-
-Рекомендуется использовать строгий режим валидации (strict=True) для гарантии качества документации, особенно в процессе CI/CD и в продакшен-среде. Режим автоисправления (auto_fix=True) полезен на ранних этапах разработки, когда документация еще не полностью оформлена. 

examples/mcp_proxy_config.json

@@ -1,175 +0,0 @@
-{
-  "version": "1.0",
-  "tools": [
-    {
-      "name": "mcp_get_items",
-      "description": "Get list of all items",
-      "parameters": {
-        "type": "object",
-        "properties": {},
-        "required": []
-      }
-    },
-    {
-      "name": "mcp_get_item",
-      "description": "Get item by ID",
-      "parameters": {
-        "type": "object",
-        "properties": {
-          "item_id": {
-            "type": "integer",
-            "description": "Item ID to search for"
-          }
-        },
-        "required": [
-          "item_id"
-        ]
-      }
-    },
-    {
-      "name": "mcp_create_item",
-      "description": "Create new item",
-      "parameters": {
-        "type": "object",
-        "properties": {
-          "item": {
-            "type": "object",
-            "description": "Item data"
-          }
-        },
-        "required": [
-          "item"
-        ]
-      }
-    },
-    {
-      "name": "mcp_update_item",
-      "description": "Update item by ID",
-      "parameters": {
-        "type": "object",
-        "properties": {
-          "item_id": {
-            "type": "integer",
-            "description": "Item ID to update"
-          },
-          "updated_data": {
-            "type": "object",
-            "description": "Updated data"
-          }
-        },
-        "required": [
-          "item_id",
-          "updated_data"
-        ]
-      }
-    },
-    {
-      "name": "mcp_delete_item",
-      "description": "Delete item by ID",
-      "parameters": {
-        "type": "object",
-        "properties": {
-          "item_id": {
-            "type": "integer",
-            "description": "Item ID to delete"
-          }
-        },
-        "required": [
-          "item_id"
-        ]
-      }
-    },
-    {
-      "name": "mcp_search_items",
-      "description": "Search items by keyword",
-      "parameters": {
-        "type": "object",
-        "properties": {
-          "keyword": {
-            "type": "string",
-            "description": "Search keyword"
-          }
-        },
-        "required": [
-          "keyword"
-        ]
-      }
-    },
-    {
-      "name": "mcp_execute",
-      "description": "Universal command for executing queries",
-      "parameters": {
-        "type": "object",
-        "properties": {
-          "query": {
-            "type": "string",
-            "description": "Query to execute"
-          },
-          "subcommand": {
-            "type": "string",
-            "description": "Subcommand to execute"
-          }
-        },
-        "required": []
-      }
-    }
-  ],
-  "routes": [
-    {
-      "tool_name": "mcp_get_items",
-      "endpoint": "/cmd",
-      "method": "post",
-      "json_rpc": {
-        "method": "get_items"
-      }
-    },
-    {
-      "tool_name": "mcp_get_item",
-      "endpoint": "/cmd",
-      "method": "post",
-      "json_rpc": {
-        "method": "get_item"
-      }
-    },
-    {
-      "tool_name": "mcp_create_item",
-      "endpoint": "/cmd",
-      "method": "post",
-      "json_rpc": {
-        "method": "create_item"
-      }
-    },
-    {
-      "tool_name": "mcp_update_item",
-      "endpoint": "/cmd",
-      "method": "post",
-      "json_rpc": {
-        "method": "update_item"
-      }
-    },
-    {
-      "tool_name": "mcp_delete_item",
-      "endpoint": "/cmd",
-      "method": "post",
-      "json_rpc": {
-        "method": "delete_item"
-      }
-    },
-    {
-      "tool_name": "mcp_search_items",
-      "endpoint": "/cmd",
-      "method": "post",
-      "json_rpc": {
-        "method": "search_items"
-      }
-    },
-    {
-      "tool_name": "mcp_execute",
-      "endpoint": "/cmd",
-      "method": "post",
-      "json_rpc": {
-        "method": "execute"
-      }
-    }
-  ]
-}

mcp_proxy_adapter-2.1.2.dist-info/RECORD

@@ -1,61 +0,0 @@
-docs/README.md,sha256=XpZqqKcf7GZ_uqtaadmIZc4dE9oyKv7biKj41kDtQo4,4633
-docs/README_ru.md,sha256=Ln8oDVOurhBVurQaEFDweVvq_bZZbdFSSTvWTrpBgMs,6326
-docs/architecture.md,sha256=wF5-RMQI-QssY4jA2lSKjjq6iHunda-n2PqI5ELAj84,10430
-docs/architecture_ru.md,sha256=Ato3CoAmhNBukMO6uje12e5-OlpDYVrwGIcN1CKqTsw,15529
-docs/command_development.md,sha256=-CKfEtLO-4tB2WKZNbIT1Ao4juiKFBcKS7As4_1ja74,6645
-docs/command_development_ru.md,sha256=kzvYpnEfsXfZxZY1wswwDChzBtMtEY9l74M7XkWxtHk,19968
-docs/deployment.md,sha256=eOOCq8V6Gz_SDo9hReXKXXNtaS8WmrxR-KXjJjUE1pw,4988
-docs/deployment_ru.md,sha256=0eNxKqiqc-sIht4brdZVEcxZkbrUP4y95PhfpD_0Qyg,40107
-docs/examples.md,sha256=85kfd73rgqJ2DUD3PrRfjViCXgv5bM_9Uqizm_ET7NE,6348
-docs/examples_ru.md,sha256=mxQqwKXMX6OcY6tyfuRgmYqAQXYnrzTGOJS_u5ECUcs,11866
-docs/mcp_proxy_adapter.md,sha256=Y-dcFKwYbYJe5_zDrvlDPuSz-S1czL7Gh848EzclS7k,8210
-docs/mcp_proxy_adapter_ru.md,sha256=aJ1KAyoyzcRPSn7YGralpUGO-zmUQMtDKoQ2zrOUVTc,17489
-docs/quickstart.md,sha256=YH0KspJcbe59ynpRf9kne-QsLGcUo4kKtNiEZ48nrus,5419
-docs/quickstart_ru.md,sha256=biipkQ4_XGVzqxLeGptzfWxyr6J9TN1ggdhCf2pDWKA,11884
-docs/testing.md,sha256=Z1hdqairo14QMoPxeBX1_YAbbS3Uedy4uaxfvu8aG5k,7572
-docs/testing_ru.md,sha256=z2-zGIXuFx8GpLYwydP9Oe3N8l_zVzheLBYvxgI-f6k,18219
-docs/validation_ru.md,sha256=iYtM3ZoFGe3_EaCG0738LkGJ5FPayrEr2z_KPhNcs0Q,15886
-examples/analyze_config.py,sha256=vog7TNHDw5ZoYhQLbAvZvEoufmQwH54KJzQBJrSq5w4,4283
-examples/basic_integration.py,sha256=w_oA777YiQt36gzI113KPQ6k45caXbMCqW9hD8sy8zo,4657
-examples/docstring_and_schema_example.py,sha256=c96L4KF_7yWzffmvd4hyeQuXSdYyYkv7Uvuy0QxgMcQ,1929
-examples/extension_example.py,sha256=vnatnFdNTapMpPcQ79Ugitk92ZiUfpLTs7Dvsodf1og,2277
-examples/help_best_practices.py,sha256=wUtZRnAktnpfAc9vAvqSxUquHEr5ewaPDPyc6BoCqdQ,2637
-examples/help_usage.py,sha256=UOd3HJeYlQpQkAyceGNm66jXX_h-T05pjIGD-b7-Pfg,2568
-examples/mcp_proxy_client.py,sha256=z4IzFlGigVTQSb8TpcrQ_a0migsmC58LnNwc8wZmTfw,3811
-examples/mcp_proxy_config.json,sha256=39aeV7NNEZstX9RAOdsr5tUZnvCuo7bR38Xc1sGGCJI,3655
-examples/openapi_server.py,sha256=hueoG9KcimOc4W27euWksMYjjG8Jz-li9hEKi3ZCDBk,12515
-examples/project_structure_example.py,sha256=sswTo6FZb1F5juHa0FYG3cgvrh3wfgGfJu2bBy5tCm4,1460
-examples/testing_example.py,sha256=AB13c4C1bjs1145O-yriwyreeVXtMOlQLzs2BCGmprk,1719
-mcp_proxy_adapter/__init__.py,sha256=_6D-TfANWp9zc550M5LUeGPvioFqG1bAl3tZj-gNmJU,463
-mcp_proxy_adapter/adapter.py,sha256=76dkVeDuqLsJ5AhuftzLlwy2M6yr_PfNbmNfo9dXVhc,28844
-mcp_proxy_adapter/models.py,sha256=acqVQBYAojHXeJ1MJyvpMyT6-J6aMxWuZMszn_-RsOU,2338
-mcp_proxy_adapter/registry.py,sha256=jgC4TKaPbMbAsoxvGp2ToaOE4drD-VfZug7WJbm4IW4,15853
-mcp_proxy_adapter/schema.py,sha256=HZM0TTQTSi8ha1TEeVevdCyGZOUPoT1soB7Nex0hV50,10947
-mcp_proxy_adapter/analyzers/__init__.py,sha256=2rcYZDP-bXq078MQpxP32lAwYYyRhOwAQGBcefBfBzY,368
-mcp_proxy_adapter/analyzers/docstring_analyzer.py,sha256=T3FLJEo_uChShfiEKRl8GpVoHvh5HiudZkxnj4KixfA,7541
-mcp_proxy_adapter/analyzers/type_analyzer.py,sha256=6Wac7osKwF03waFSwQ8ZM0Wqn_zAP2D-I4WMEpR0hQM,5230
-mcp_proxy_adapter/dispatchers/__init__.py,sha256=FWgimgInGphIjCEnvA3-ZExiapUzYAVis2H9C5IWivU,365
-mcp_proxy_adapter/dispatchers/base_dispatcher.py,sha256=S5_Xri058jAmOWeit1tedB_GMZQ9RLcNcYabA83ZF6k,2288
-mcp_proxy_adapter/dispatchers/json_rpc_dispatcher.py,sha256=ffu1M32E1AdC7IB44mlbV2L56eJQMsp-7fYi_r4rmHc,6331
-mcp_proxy_adapter/validators/docstring_validator.py,sha256=Onpq2iNJ1qF4ejkJJIlBkLROuSNIVALHVmXIgkCpaFI,2934
-mcp_proxy_adapter/validators/metadata_validator.py,sha256=uCrn38-VYYn89l6f5CC_GoTAHAweaOW2Z6Esro1rtGw,3155
-mcp_proxy_adapter-2.1.2.dist-info/licenses/LICENSE,sha256=OkApFEwdgMCt_mbvUI-eIwKMSTe38K3XnU2DT5ub-wI,1072
-scripts/publish.py,sha256=MMKksSAzWoZOlxxHOm9-o6juEJYj5AMS4OG5pDIeChw,2627
-scripts/code_analyzer/code_analyzer.py,sha256=FmWctoxttImvIPJoyNMLyUt7pEg3mQihqt6T9vMBKVQ,12766
-scripts/code_analyzer/register_commands.py,sha256=GpQxdFsA0BWHONZpDjl18zkoqlbV6pmkabLMwIR_1JE,20545
-tests/conftest.py,sha256=gkusSolrEp6-AHLjMKDUVxEcmfboa2P5SbeyiMugP-E,495
-tests/test_adapter.py,sha256=ohLX1wGFmHnv5DXJx2segjT2EEg9-3ZU9FKwS74D7KI,18247
-tests/test_adapter_coverage.py,sha256=k5oCvT9EQy_8JYam4Os88Npnn-Hgr0pm_ChHyRwk4Vc,8813
-tests/test_basic_dispatcher.py,sha256=wB30AM3UPI_EklAMrGIwQHDTqbfY80I5spi6arpdxCc,5472
-tests/test_command_registry.py,sha256=Ze4qwi2fV-EOuJ0su2l-jclLRCB9ZdZNUY54GFtde9E,12000
-tests/test_examples.py,sha256=dYiRgV3Z74MiOJq4I1soPE4xmJNSM8L-IqxdV4vXCWI,1615
-tests/test_mcp_proxy_adapter.py,sha256=WDYkLpz9Kd4OW0XbfhSanmhca7m7DIGZNC1L6CAoNpA,24890
-tests/test_mcp_proxy_adapter_basic.py,sha256=gKIcqYzZVEdJcp3PKKJPKNxtJ05l80Wj4ig1Vd2dagM,10624
-tests/test_part1.py,sha256=gb7lQ-lKjqYMMLGMt_7aSuScXSqy80tP8vBq2TBSiTs,14191
-tests/test_part2.py,sha256=842aTEHCwqS6UBs3sE0DRbXRdeiZ8n0w4rJTAWschnY,18220
-tests/test_schema.py,sha256=-X_323kncA0l3o1GKIKYf9OjhIj1hOJBPCH71682pk8,13704
-tests/test_simple_adapter.py,sha256=IFLbVphiRMl1w5LoT1AihYOt0b66GNnt8uDafwokVCI,8374
-mcp_proxy_adapter-2.1.2.dist-info/METADATA,sha256=RWCuMTdFD78eQjOZ_r33iBT8ChwqBJcKu_0T4MDQr6E,8150
-mcp_proxy_adapter-2.1.2.dist-info/WHEEL,sha256=wXxTzcEDnjrTwFYjLPcsW_7_XihufBwmpiBeiXNBGEA,91
-mcp_proxy_adapter-2.1.2.dist-info/top_level.txt,sha256=FkpPEr9rFZcEWxGfy6kRIUkCiLMxHpTD3--73ThTnPo,46
-mcp_proxy_adapter-2.1.2.dist-info/RECORD,,

mcp_proxy_adapter-2.1.2.dist-info/top_level.txt

@@ -1,5 +0,0 @@
-docs
-examples
-mcp_proxy_adapter
-scripts
-tests