mcp-proxy-adapter 6.1.0__py3-none-any.whl → 6.1.1__py3-none-any.whl

mcp_proxy_adapter/docs/RU/TROUBLESHOOTING.md

@@ -0,0 +1,285 @@
+# Руководство по устранению неполадок
+
+Это руководство посвящено решению распространенных проблем с фреймворком MCP Proxy Adapter, особенно связанных с ProtocolMiddleware и конфигурацией SSL/TLS.
+
+## Распространенные проблемы
+
+### Проблема 1: ProtocolMiddleware блокирует HTTPS запросы
+
+**Проблема:** ProtocolMiddleware инициализируется с дефолтными настройками и не обновляется при изменении конфигурации SSL.
+
+**Симптомы:**
+```
+Protocol 'https' not allowed for request to /health
+INFO: 127.0.0.1:42038 - "GET /health HTTP/1.1" 403 Forbidden
+```
+
+**Причина:** ProtocolMiddleware создавался как глобальный экземпляр с дефолтными настройками и не обновлялся при включении SSL.
+
+**Решение:** 
+1. **Использовать обновленный ProtocolManager** (Исправлено в v1.1.0):
+   - ProtocolManager теперь динамически обновляется на основе конфигурации SSL
+   - Автоматически разрешает HTTPS при включении SSL
+
+2. **Отключить ProtocolMiddleware для HTTPS** (Временное решение):
+   ```json
+   {
+     "server": {"host": "127.0.0.1", "port": 10004},
+     "ssl": {"enabled": true, "cert_file": "./certs/server.crt", "key_file": "./certs/server.key"},
+     "security": {"enabled": true, "auth": {"enabled": true, "methods": ["api_key"]}},
+     "protocols": {"enabled": false}
+   }
+   ```
+
+### Проблема 2: Конфликты конфигурации SSL
+
+**Проблема:** Фреймворк читает конфигурацию SSL из двух мест: `ssl` (legacy) и `security.ssl`, что приводит к путанице.
+
+**Симптомы:**
+```
+🔍 Debug: SSL config at start of validation: enabled=False
+🔍 Debug: Root SSL section found: enabled=True
+🔍 Debug: _get_ssl_config: security.ssl key_file=None
+🔍 Debug: _get_ssl_config: legacy ssl key_file=./certs/server.key
+```
+
+**Решение:**
+1. **Использовать унифицированную конфигурацию SSL** (Рекомендуется):
+   ```json
+   {
+     "security": {
+       "ssl": {
+         "enabled": true,
+         "cert_file": "./certs/server.crt",
+         "key_file": "./certs/server.key"
+       }
+     }
+   }
+   ```
+
+2. **Использовать legacy конфигурацию SSL** (Обратная совместимость):
+   ```json
+   {
+     "ssl": {
+       "enabled": true,
+       "cert_file": "./certs/server.crt",
+       "key_file": "./certs/server.key"
+     }
+   }
+   ```
+
+### Проблема 3: Ошибки инициализации security framework
+
+**Проблема:** Security framework падает при инициализации из-за отсутствующих или null значений конфигурации.
+
+**Симптомы:**
+```
+Failed to initialize security components: Failed to load roles configuration: argument should be a str or an os.PathLike object where __fspath__ returns a str, not 'NoneType'
+```
+
+**Решение:**
+1. **Предоставить файл ролей** (Если используются роли):
+   ```json
+   {
+     "security": {
+       "permissions": {
+         "enabled": true,
+         "roles_file": "./roles.json"
+       }
+     }
+   }
+   ```
+
+2. **Отключить permissions** (Если роли не используются):
+   ```json
+   {
+     "security": {
+       "permissions": {
+         "enabled": false
+       }
+     }
+   }
+   ```
+
+3. **Использовать graceful fallback** (Исправлено в v1.1.0):
+   - Security framework теперь продолжает работу без ролей, если roles_file равен null
+   - Логирует предупреждение вместо падения
+
+## Примеры конфигураций
+
+### HTTP Simple
+```json
+{
+  "server": {"host": "127.0.0.1", "port": 10001},
+  "ssl": {"enabled": false},
+  "security": {"enabled": false},
+  "protocols": {"enabled": true, "allowed_protocols": ["http"]}
+}
+```
+
+### HTTPS Simple
+```json
+{
+  "server": {"host": "127.0.0.1", "port": 10002},
+  "ssl": {"enabled": true, "cert_file": "./certs/server.crt", "key_file": "./certs/server.key"},
+  "security": {"enabled": false},
+  "protocols": {"enabled": true, "allowed_protocols": ["http", "https"]}
+}
+```
+
+### HTTPS с токен-аутентификацией
+```json
+{
+  "server": {"host": "127.0.0.1", "port": 10003},
+  "ssl": {"enabled": true, "cert_file": "./certs/server.crt", "key_file": "./certs/server.key"},
+  "security": {
+    "enabled": true,
+    "auth": {"enabled": true, "methods": ["api_key"]}
+  },
+  "protocols": {"enabled": true, "allowed_protocols": ["http", "https"]}
+}
+```
+
+### HTTPS без ProtocolMiddleware
+```json
+{
+  "server": {"host": "127.0.0.1", "port": 10004},
+  "ssl": {"enabled": true, "cert_file": "./certs/server.crt", "key_file": "./certs/server.key"},
+  "security": {
+    "enabled": true,
+    "auth": {"enabled": true, "methods": ["api_key"]}
+  },
+  "protocols": {"enabled": false}
+}
+```
+
+### mTLS Simple
+```json
+{
+  "server": {"host": "127.0.0.1", "port": 10005},
+  "ssl": {
+    "enabled": true,
+    "cert_file": "./certs/server.crt",
+    "key_file": "./certs/server.key",
+    "ca_cert": "./certs/ca.crt",
+    "verify_client": true
+  },
+  "security": {
+    "enabled": true,
+    "auth": {"enabled": true, "methods": ["certificate"]}
+  },
+  "protocols": {"enabled": true, "allowed_protocols": ["https", "mtls"]}
+}
+```
+
+## Тестирование конфигурации
+
+### Тест HTTP
+```bash
+curl http://127.0.0.1:10001/health
+```
+
+### Тест HTTPS
+```bash
+curl -k https://127.0.0.1:10002/health
+```
+
+### Тест HTTPS с аутентификацией
+```bash
+curl -k -H "Authorization: Bearer your-api-key" https://127.0.0.1:10003/health
+```
+
+### Тест mTLS
+```bash
+curl -k --cert ./certs/client.crt --key ./certs/client.key https://127.0.0.1:10005/health
+```
+
+## Отладка
+
+### Включить debug логирование
+```json
+{
+  "logging": {
+    "level": "DEBUG",
+    "console_output": true
+  }
+}
+```
+
+### Проверить статус Protocol Manager
+```python
+from mcp_proxy_adapter.core.protocol_manager import get_protocol_manager
+from mcp_proxy_adapter.config import config
+
+pm = get_protocol_manager(config.get_all())
+print(f"Allowed protocols: {pm.get_allowed_protocols()}")
+print(f"Protocol info: {pm.get_protocol_info()}")
+```
+
+### Проверить конфигурацию SSL
+```python
+from mcp_proxy_adapter.config import config
+
+ssl_config = config.get("ssl", {})
+security_ssl = config.get("security", {}).get("ssl", {})
+print(f"Legacy SSL: {ssl_config}")
+print(f"Security SSL: {security_ssl}")
+```
+
+## Руководство по миграции
+
+### От legacy к новой конфигурации
+
+**Старая (Legacy):**
+```json
+{
+  "ssl": {"enabled": true, "cert_file": "./certs/server.crt", "key_file": "./certs/server.key"}
+}
+```
+
+**Новая (Рекомендуется):**
+```json
+{
+  "security": {
+    "ssl": {"enabled": true, "cert_file": "./certs/server.crt", "key_file": "./certs/server.key"}
+  }
+}
+```
+
+### Добавление управления протоколами
+
+**Без управления протоколами:**
+```json
+{
+  "protocols": {"enabled": false}
+}
+```
+
+**С управлением протоколами:**
+```json
+{
+  "protocols": {
+    "enabled": true,
+    "allowed_protocols": ["http", "https"]
+  }
+}
+```
+
+## Лучшие практики
+
+1. **Используйте security.ssl вместо legacy ssl** для новых конфигураций
+2. **Отключайте ProtocolMiddleware** если не нужна валидация протоколов
+3. **Предоставляйте roles_file** или отключайте permissions при использовании security framework
+4. **Тестируйте конфигурации** перед развертыванием в продакшене
+5. **Используйте debug логирование** для отладки
+6. **Храните сертификаты и ключи в безопасности** и правильно настраивайте
+
+## Поддержка
+
+Если вы столкнулись с проблемами, не описанными в этом руководстве:
+
+1. Проверьте логи для получения подробных сообщений об ошибках
+2. Включите debug логирование для получения дополнительной информации
+3. Убедитесь, что файлы сертификатов существуют и доступны для чтения
+4. Тестируйте с простыми конфигурациями сначала
+5. Сообщайте о проблемах с полной конфигурацией и логами ошибок

mcp_proxy_adapter/examples/basic_framework/configs/https_auth.json

@@ -27,6 +27,10 @@
             "burst_limit": 10
         }
     },
+    "protocols": {
+        "enabled": true,
+        "allowed_protocols": ["http", "https"]
+    },
     "logging": {
         "level": "INFO",
         "console_output": true,

mcp_proxy_adapter/examples/basic_framework/configs/https_no_protocol_middleware.json

@@ -0,0 +1,36 @@
+{
+    "server": {
+        "host": "0.0.0.0",
+        "port": 8445,
+        "debug": false,
+        "log_level": "INFO"
+    },
+    "ssl": {
+        "enabled": true,
+        "cert_file": "./certs/server.crt",
+        "key_file": "./certs/server.key"
+    },
+    "security": {
+        "enabled": true,
+        "auth": {
+            "enabled": true,
+            "methods": ["api_key"],
+            "api_keys": {
+                "admin": "admin-secret-key-123",
+                "user": "user-secret-key-456"
+            }
+        }
+    },
+    "protocols": {
+        "enabled": false
+    },
+    "logging": {
+        "level": "INFO",
+        "console_output": true,
+        "file_output": false
+    },
+    "commands": {
+        "auto_discovery": true,
+        "commands_directory": "./commands"
+    }
+}

mcp_proxy_adapter/examples/basic_framework/configs/https_simple.json

@@ -13,6 +13,10 @@
     "security": {
         "enabled": false
     },
+    "protocols": {
+        "enabled": true,
+        "allowed_protocols": ["http", "https"]
+    },
     "logging": {
         "level": "INFO",
         "console_output": true,

mcp_proxy_adapter/examples/basic_framework/configs/mtls_no_protocol_middleware.json

@@ -0,0 +1,34 @@
+{
+    "server": {
+        "host": "0.0.0.0",
+        "port": 8447,
+        "debug": false,
+        "log_level": "INFO"
+    },
+    "ssl": {
+        "enabled": true,
+        "cert_file": "./certs/server.crt",
+        "key_file": "./certs/server.key",
+        "ca_cert": "./certs/ca.crt",
+        "verify_client": true
+    },
+    "security": {
+        "enabled": true,
+        "auth": {
+            "enabled": true,
+            "methods": ["certificate"]
+        }
+    },
+    "protocols": {
+        "enabled": false
+    },
+    "logging": {
+        "level": "INFO",
+        "console_output": true,
+        "file_output": false
+    },
+    "commands": {
+        "auto_discovery": true,
+        "commands_directory": "./commands"
+    }
+}

mcp_proxy_adapter/examples/basic_framework/configs/mtls_simple.json

@@ -0,0 +1,35 @@
+{
+    "server": {
+        "host": "0.0.0.0",
+        "port": 8446,
+        "debug": false,
+        "log_level": "INFO"
+    },
+    "ssl": {
+        "enabled": true,
+        "cert_file": "./certs/server.crt",
+        "key_file": "./certs/server.key",
+        "ca_cert": "./certs/ca.crt",
+        "verify_client": true
+    },
+    "security": {
+        "enabled": true,
+        "auth": {
+            "enabled": true,
+            "methods": ["certificate"]
+        }
+    },
+    "protocols": {
+        "enabled": true,
+        "allowed_protocols": ["https", "mtls"]
+    },
+    "logging": {
+        "level": "INFO",
+        "console_output": true,
+        "file_output": false
+    },
+    "commands": {
+        "auto_discovery": true,
+        "commands_directory": "./commands"
+    }
+}

mcp_proxy_adapter/examples/test_config_generator.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Test script for configuration generator utility.
+
+This script tests the configuration generator to ensure it properly generates
+configurations with the new protocols section and fixes for ProtocolMiddleware issues.
+"""
+
+import sys
+import json
+from pathlib import Path
+
+# Add the project root to the path
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from mcp_proxy_adapter.utils.config_generator import ConfigGenerator
+
+
+def test_config_generator():
+    """Test the configuration generator with different types."""
+    generator = ConfigGenerator()
+    
+    # Test configuration types
+    config_types = [
+        "basic_http",
+        "http_token", 
+        "https",
+        "https_token",
+        "https_no_protocol_middleware",
+        "mtls",
+        "mtls_no_protocol_middleware"
+    ]
+    
+    print("Testing Configuration Generator")
+    print("=" * 50)
+    
+    for config_type in config_types:
+        print(f"\nTesting {config_type} configuration:")
+        print("-" * 30)
+        
+        try:
+            # Generate configuration
+            config = generator._get_config_by_type(config_type)
+            
+            # Check if protocols section exists
+            if "protocols" in config:
+                protocols = config["protocols"]
+                print(f"✅ Protocols section found:")
+                print(f"   - enabled: {protocols.get('enabled', 'NOT SET')}")
+                print(f"   - allowed_protocols: {protocols.get('allowed_protocols', 'NOT SET')}")
+                print(f"   - default_protocol: {protocols.get('default_protocol', 'NOT SET')}")
+            else:
+                print("❌ Protocols section missing!")
+            
+            # Check SSL configuration
+            ssl_enabled = config.get("ssl", {}).get("enabled", False)
+            security_ssl_enabled = config.get("security", {}).get("ssl", {}).get("enabled", False)
+            print(f"   - legacy ssl.enabled: {ssl_enabled}")
+            print(f"   - security.ssl.enabled: {security_ssl_enabled}")
+            
+            # Check if configuration is valid for its type
+            if config_type == "https_no_protocol_middleware" or config_type == "mtls_no_protocol_middleware":
+                if protocols.get("enabled") == False:
+                    print("✅ ProtocolMiddleware correctly disabled")
+                else:
+                    print("❌ ProtocolMiddleware should be disabled but is enabled")
+            else:
+                if protocols.get("enabled") == True:
+                    print("✅ ProtocolMiddleware correctly enabled")
+                else:
+                    print("❌ ProtocolMiddleware should be enabled but is disabled")
+            
+            # Save configuration to file for inspection
+            output_file = f"test_config_{config_type}.json"
+            with open(output_file, 'w') as f:
+                json.dump(config, f, indent=2)
+            print(f"   - Configuration saved to {output_file}")
+            
+        except Exception as e:
+            print(f"❌ Error generating {config_type} configuration: {e}")
+    
+    print("\n" + "=" * 50)
+    print("Configuration generator test completed!")
+
+
+def test_config_with_comments():
+    """Test configuration generation with comments."""
+    generator = ConfigGenerator()
+    
+    print("\nTesting configuration with comments:")
+    print("-" * 40)
+    
+    try:
+        # Generate HTTPS configuration with comments
+        commented_config = generator.generate_config_with_comments("https")
+        print("✅ HTTPS configuration with comments generated successfully")
+        
+        # Save to file
+        with open("test_https_with_comments.json", 'w') as f:
+            f.write(commented_config)
+        print("   - Configuration saved to test_https_with_comments.json")
+        
+    except Exception as e:
+        print(f"❌ Error generating configuration with comments: {e}")
+
+
+if __name__ == "__main__":
+    test_config_generator()
+    test_config_with_comments()