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

mcp_proxy_adapter/docs/RU/TROUBLESHOOTING.md

@@ -1,285 +0,0 @@
-# Руководство по устранению неполадок
-
-Это руководство посвящено решению распространенных проблем с фреймворком 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/README.md

@@ -1,257 +0,0 @@
-# MCP Proxy Adapter - Examples and Security Testing
-
-Этот каталог содержит примеры использования MCP Proxy Adapter с различными конфигурациями безопасности и комплексную систему тестирования.
-
-## 📁 Структура каталога
-
-```
-examples/
-├── README.md                           # Эта документация
-├── SECURITY_TESTING.md                 # Документация по тестированию безопасности
-├── generate_certificates.py            # Скрипт генерации сертификатов
-├── security_test_client.py             # Клиент для тестирования безопасности
-├── run_security_tests.py               # Основной скрипт запуска тестов
-├── cert_config.json                    # Конфигурация для генерации сертификатов
-├── certs/                              # Сгенерированные сертификаты
-├── keys/                               # Приватные ключи
-├── server_configs/                     # Конфигурации серверов
-│   ├── config_basic_http.json         # Базовый HTTP
-│   ├── config_http_token.json         # HTTP + токен
-│   ├── config_https.json              # HTTPS
-│   ├── config_https_token.json        # HTTPS + токен
-│   ├── config_mtls.json               # mTLS
-│   └── roles.json                     # Роли и разрешения
-└── commands/                           # Пользовательские команды
-    └── __init__.py
-```
-
-## 🚀 Быстрый старт
-
-### 1. Подготовка окружения
-
-```bash
-# Активируйте виртуальную среду
-source .venv/bin/activate
-
-# Установите зависимости
-pip install -e .
-```
-
-### 2. Генерация сертификатов
-
-```bash
-# Сгенерируйте все необходимые сертификаты
-cd mcp_proxy_adapter/examples
-python generate_certificates.py
-```
-
-### 3. Запуск тестов безопасности
-
-```bash
-# Запустите все тесты безопасности
-python run_security_tests.py
-```
-
-## 🔧 Конфигурации серверов
-
-### Базовый HTTP (порт 8000)
-```bash
-python -m mcp_proxy_adapter.main --config server_configs/config_basic_http.json
-```
-
-### HTTP + Токен аутентификация (порт 8001)
-```bash
-python -m mcp_proxy_adapter.main --config server_configs/config_http_token.json
-```
-
-### HTTPS (порт 8443)
-```bash
-python -m mcp_proxy_adapter.main --config server_configs/config_https.json
-```
-
-### HTTPS + Токен аутентификация (порт 8444)
-```bash
-python -m mcp_proxy_adapter.main --config server_configs/config_https_token.json
-```
-
-### mTLS (порт 8445)
-```bash
-python -m mcp_proxy_adapter.main --config server_configs/config_mtls.json
-```
-
-## 🧪 Тестирование
-
-### Тестирование отдельного сервера
-
-```bash
-# Тест базового HTTP сервера
-python security_test_client.py --server http://localhost:8000 --auth none
-
-# Тест HTTP с токеном
-python security_test_client.py --server http://localhost:8001 --auth api_key --token test-token-123
-
-# Тест HTTPS сервера
-python security_test_client.py --server https://localhost:8443 --auth none
-
-# Тест HTTPS с токеном
-python security_test_client.py --server https://localhost:8444 --auth api_key --token test-token-123
-
-# Тест mTLS с сертификатом
-python security_test_client.py --server https://localhost:8445 --auth certificate --cert certs/admin_cert.pem --key keys/admin_key.pem --ca-cert certs/ca_cert.pem
-```
-
-### Тестирование всех сценариев
-
-```bash
-# Запустите все серверы и протестируйте их
-python run_security_tests.py
-```
-
-## 📋 Сценарии тестирования
-
-### 1. Базовый HTTP (config_basic_http.json)
-- **Порт**: 8000
-- **Безопасность**: Отключена
-- **Аутентификация**: Нет
-- **Тесты**: Health check, echo command
-
-### 2. HTTP + Токен (config_http_token.json)
-- **Порт**: 8001
-- **Безопасность**: API Key аутентификация
-- **Токены**: 
-  - `test-token-123` (admin)
-  - `user-token-456` (user)
-- **Тесты**: Ролевая аутентификация, негативные тесты
-
-### 3. HTTPS (config_https.json)
-- **Порт**: 8443
-- **Безопасность**: SSL/TLS
-- **Сертификаты**: Самоподписанные
-- **Тесты**: Защищенные соединения
-
-### 4. HTTPS + Токен (config_https_token.json)
-- **Порт**: 8444
-- **Безопасность**: SSL/TLS + API Key
-- **Тесты**: Комбинированная безопасность
-
-### 5. mTLS (config_mtls.json)
-- **Порт**: 8445
-- **Безопасность**: Взаимная аутентификация сертификатами
-- **Тесты**: Сертификатная аутентификация
-
-## 🔑 Токены для тестирования
-
-```json
-{
-  "test-token-123": {
-    "roles": ["admin"],
-    "permissions": ["*"]
-  },
-  "user-token-456": {
-    "roles": ["user"],
-    "permissions": ["read", "execute"]
-  }
-}
-```
-
-## 📜 Роли и разрешения
-
-```json
-{
-  "admin": ["*"],
-  "user": ["read", "write", "execute"],
-  "readonly": ["read"],
-  "guest": ["read"]
-}
-```
-
-## 🛠️ Генерация конфигураций
-
-Используйте встроенный генератор конфигураций:
-
-```bash
-# Генерация всех типов конфигураций
-python -m mcp_proxy_adapter.utils.config_generator --all --output-dir ./generated_configs
-
-# Генерация конкретного типа
-python -m mcp_proxy_adapter.utils.config_generator --type https_token --output ./my_config.json
-```
-
-Доступные типы конфигураций:
-- `minimal` - Минимальная конфигурация
-- `development` - Для разработки
-- `secure` - Максимальная безопасность
-- `full` - Полная конфигурация
-- `basic_http` - Базовый HTTP
-- `http_token` - HTTP + токен
-- `https` - HTTPS
-- `https_token` - HTTPS + токен
-- `mtls` - mTLS
-
-## 🔍 Мониторинг и логи
-
-Логи сохраняются в:
-- `./logs/server.log` - Логи сервера
-- `./logs/security.log` - Логи безопасности
-
-Для просмотра логов в реальном времени:
-```bash
-tail -f logs/server.log
-tail -f logs/security.log
-```
-
-## 🚨 Устранение неполадок
-
-### Проблема: Сертификаты не найдены
-```bash
-# Проверьте наличие сертификатов
-ls -la certs/
-ls -la keys/
-
-# Перегенерируйте сертификаты
-python generate_certificates.py
-```
-
-### Проблема: Порт занят
-```bash
-# Найдите процесс, использующий порт
-lsof -i :8000
-lsof -i :8443
-
-# Остановите процесс
-kill -9 <PID>
-```
-
-### Проблема: SSL ошибки
-```bash
-# Проверьте сертификаты
-openssl x509 -in certs/server_cert.pem -text -noout
-
-# Проверьте приватный ключ
-openssl rsa -in keys/server_key.pem -check
-```
-
-## 📚 Дополнительная документация
-
-- [SECURITY_TESTING.md](SECURITY_TESTING.md) - Подробное руководство по тестированию безопасности
-- [API Documentation](../docs/api/) - Документация API
-- [Configuration Guide](../docs/configuration.md) - Руководство по конфигурации
-
-## 🤝 Поддержка
-
-Если у вас возникли проблемы:
-
-1. Проверьте логи в `./logs/`
-2. Убедитесь, что все зависимости установлены
-3. Проверьте, что сертификаты сгенерированы корректно
-4. Обратитесь к документации по устранению неполадок
-
-## 📄 Лицензия
-
-Этот проект распространяется под лицензией MIT. См. файл [LICENSE](../../LICENSE) для подробностей.
-
----
-
-**Автор**: Vasiliy Zdanovskiy  
-**Email**: vasilyvz@gmail.com  
-**Версия**: 1.0.0