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

mcp_proxy_adapter/examples/README.md

@@ -1,124 +1,257 @@
-# MCP Proxy Adapter Examples
+# MCP Proxy Adapter - Examples and Security Testing
 
-This directory contains examples demonstrating different usage patterns of the MCP Proxy Adapter framework.
+Этот каталог содержит примеры использования MCP Proxy Adapter с различными конфигурациями безопасности и комплексную систему тестирования.
 
-## Examples Overview
+## 📁 Структура каталога
 
-### 1. Basic Server (`basic_server/`)
-Minimal server example with only built-in commands. Demonstrates:
-- Basic framework setup
-- Built-in command discovery
-- Standard JSON-RPC API
-- Backward compatibility with property setting
+```
+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
+```
 
-### 2. Custom Commands Server (`custom_commands/`)
-Advanced server example with custom commands and hooks. Demonstrates:
-- Custom command registration
-- Basic hooks (before/after execution)
-- Global hooks
-- Performance and security monitoring
-- Advanced hooks with data transformation and command interception
+## 🚀 Быстрый старт
 
-## Setting Application Title and Description
+### 1. Подготовка окружения
 
-The framework supports two ways to set application properties:
+```bash
+# Активируйте виртуальную среду
+source .venv/bin/activate
+
+# Установите зависимости
+pip install -e .
+```
 
-### Method 1: During Creation (Recommended)
-```python
-from mcp_proxy_adapter import create_app
+### 2. Генерация сертификатов
 
-app = create_app(
-    title="My Custom Server",
-    description="My custom server description",
-    version="2.0.0"
-)
+```bash
+# Сгенерируйте все необходимые сертификаты
+cd mcp_proxy_adapter/examples
+python generate_certificates.py
 ```
 
-### Method 2: After Creation (Backward Compatible)
-```python
-from mcp_proxy_adapter import create_app
+### 3. Запуск тестов безопасности
+
+```bash
+# Запустите все тесты безопасности
+python run_security_tests.py
+```
 
-app = create_app()
+## 🔧 Конфигурации серверов
 
-# Set properties after creation
-app.set_properties(
-    new_title="My Custom Server",
-    new_description="My custom server description",
-    new_version="2.0.0"
-)
+### Базовый 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
 ```
 
-## Running Examples
+### HTTPS (порт 8443)
+```bash
+python -m mcp_proxy_adapter.main --config server_configs/config_https.json
+```
 
-### Basic Server
+### HTTPS + Токен аутентификация (порт 8444)
 ```bash
-cd mcp_proxy_adapter/examples/basic_server
-python server.py
+python -m mcp_proxy_adapter.main --config server_configs/config_https_token.json
 ```
 
-### Custom Commands Server
+### mTLS (порт 8445)
 ```bash
-cd mcp_proxy_adapter/examples/custom_commands
-python server.py
+python -m mcp_proxy_adapter.main --config server_configs/config_mtls.json
 ```
 
-## Testing Examples
+## 🧪 Тестирование
+
+### Тестирование отдельного сервера
 
-### Basic Server Commands
 ```bash
-# Get help
-curl -X POST http://localhost:8000/cmd \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc": "2.0", "method": "help", "id": 1}'
+# Тест базового 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
 
-# Get health
-curl -X POST http://localhost:8000/cmd \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc": "2.0", "method": "health", "id": 2}'
+# Тест 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
 ```
 
-### Custom Commands Server Commands
+### Тестирование всех сценариев
+
 ```bash
-# Test echo command
-curl -X POST http://localhost:8000/cmd \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello!"}, "id": 1}'
-
-# Test data transformation
-curl -X POST http://localhost:8000/cmd \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc": "2.0", "method": "data_transform", "params": {"data": {"name": "test", "value": 123}}, "id": 2}'
-
-# Test command interception (bypass_flag=0)
-curl -X POST http://localhost:8000/cmd \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc": "2.0", "method": "intercept", "params": {"bypass_flag": 0}, "id": 3}'
-
-# Test command execution (bypass_flag=1)
-curl -X POST http://localhost:8000/cmd \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc": "2.0", "method": "intercept", "params": {"bypass_flag": 1}, "id": 4}'
-```
-
-## Features Demonstrated
-
-### Basic Server
-- ✅ Standard JSON-RPC API
-- ✅ Built-in command discovery
-- ✅ Basic logging
-- ✅ OpenAPI schema generation
-- ✅ Backward compatibility
-
-### Custom Commands Server
-- ✅ Custom command registration
-- ✅ Command override with priority
-- ✅ Basic hooks (before/after)
-- ✅ Global hooks
-- ✅ Performance monitoring
-- ✅ Security monitoring
-- ✅ Data transformation hooks
-- ✅ Command interception hooks
-- ✅ Conditional processing
-- ✅ Smart interception
-- ✅ Centralized logging
-- ✅ Advanced error handling 
+# Запустите все серверы и протестируйте их
+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

mcp_proxy_adapter/examples/README_EN.md

@@ -0,0 +1,258 @@
+# MCP Proxy Adapter - Examples and Security Testing
+
+This directory contains examples of using MCP Proxy Adapter with various security configurations and a comprehensive testing system.
+
+## 📁 Directory Structure
+
+```
+examples/
+├── README.md                           # This documentation
+├── README_EN.md                        # English documentation
+├── SECURITY_TESTING.md                 # Security testing documentation
+├── generate_certificates.py            # Certificate generation script
+├── security_test_client.py             # Security testing client
+├── run_security_tests.py               # Main test runner script
+├── cert_config.json                    # Certificate generation configuration
+├── certs/                              # Generated certificates
+├── keys/                               # Private keys
+├── server_configs/                     # Server configurations
+│   ├── config_basic_http.json         # Basic HTTP
+│   ├── config_http_token.json         # HTTP + token
+│   ├── config_https.json              # HTTPS
+│   ├── config_https_token.json        # HTTPS + token
+│   ├── config_mtls.json               # mTLS
+│   └── roles.json                     # Roles and permissions
+└── commands/                           # Custom commands
+    └── __init__.py
+```
+
+## 🚀 Quick Start
+
+### 1. Environment Setup
+
+```bash
+# Activate virtual environment
+source .venv/bin/activate
+
+# Install dependencies
+pip install -e .
+```
+
+### 2. Generate Certificates
+
+```bash
+# Generate all necessary certificates
+cd mcp_proxy_adapter/examples
+python generate_certificates.py
+```
+
+### 3. Run Security Tests
+
+```bash
+# Run all security tests
+python run_security_tests.py
+```
+
+## 🔧 Server Configurations
+
+### Basic HTTP (port 8000)
+```bash
+python -m mcp_proxy_adapter.main --config server_configs/config_basic_http.json
+```
+
+### HTTP + Token Authentication (port 8001)
+```bash
+python -m mcp_proxy_adapter.main --config server_configs/config_http_token.json
+```
+
+### HTTPS (port 8443)
+```bash
+python -m mcp_proxy_adapter.main --config server_configs/config_https.json
+```
+
+### HTTPS + Token Authentication (port 8444)
+```bash
+python -m mcp_proxy_adapter.main --config server_configs/config_https_token.json
+```
+
+### mTLS (port 8445)
+```bash
+python -m mcp_proxy_adapter.main --config server_configs/config_mtls.json
+```
+
+## 🧪 Testing
+
+### Testing Individual Server
+
+```bash
+# Test basic HTTP server
+python security_test_client.py --server http://localhost:8000 --auth none
+
+# Test HTTP with token
+python security_test_client.py --server http://localhost:8001 --auth api_key --token test-token-123
+
+# Test HTTPS server
+python security_test_client.py --server https://localhost:8443 --auth none
+
+# Test HTTPS with token
+python security_test_client.py --server https://localhost:8444 --auth api_key --token test-token-123
+
+# Test mTLS with certificate
+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
+```
+
+### Testing All Scenarios
+
+```bash
+# Start all servers and test them
+python run_security_tests.py
+```
+
+## 📋 Testing Scenarios
+
+### 1. Basic HTTP (config_basic_http.json)
+- **Port**: 8000
+- **Security**: Disabled
+- **Authentication**: None
+- **Tests**: Health check, echo command
+
+### 2. HTTP + Token (config_http_token.json)
+- **Port**: 8001
+- **Security**: API Key authentication
+- **Tokens**: 
+  - `test-token-123` (admin)
+  - `user-token-456` (user)
+- **Tests**: Role-based authentication, negative tests
+
+### 3. HTTPS (config_https.json)
+- **Port**: 8443
+- **Security**: SSL/TLS
+- **Certificates**: Self-signed
+- **Tests**: Secure connections
+
+### 4. HTTPS + Token (config_https_token.json)
+- **Port**: 8444
+- **Security**: SSL/TLS + API Key
+- **Tests**: Combined security
+
+### 5. mTLS (config_mtls.json)
+- **Port**: 8445
+- **Security**: Mutual certificate authentication
+- **Tests**: Certificate authentication
+
+## 🔑 Test Tokens
+
+```json
+{
+  "test-token-123": {
+    "roles": ["admin"],
+    "permissions": ["*"]
+  },
+  "user-token-456": {
+    "roles": ["user"],
+    "permissions": ["read", "execute"]
+  }
+}
+```
+
+## 📜 Roles and Permissions
+
+```json
+{
+  "admin": ["*"],
+  "user": ["read", "write", "execute"],
+  "readonly": ["read"],
+  "guest": ["read"]
+}
+```
+
+## 🛠️ Configuration Generation
+
+Use the built-in configuration generator:
+
+```bash
+# Generate all configuration types
+python -m mcp_proxy_adapter.utils.config_generator --all --output-dir ./generated_configs
+
+# Generate specific type
+python -m mcp_proxy_adapter.utils.config_generator --type https_token --output ./my_config.json
+```
+
+Available configuration types:
+- `minimal` - Minimal configuration
+- `development` - For development
+- `secure` - Maximum security
+- `full` - Full configuration
+- `basic_http` - Basic HTTP
+- `http_token` - HTTP + token
+- `https` - HTTPS
+- `https_token` - HTTPS + token
+- `mtls` - mTLS
+
+## 🔍 Monitoring and Logs
+
+Logs are saved to:
+- `./logs/server.log` - Server logs
+- `./logs/security.log` - Security logs
+
+To view logs in real-time:
+```bash
+tail -f logs/server.log
+tail -f logs/security.log
+```
+
+## 🚨 Troubleshooting
+
+### Issue: Certificates not found
+```bash
+# Check certificate availability
+ls -la certs/
+ls -la keys/
+
+# Regenerate certificates
+python generate_certificates.py
+```
+
+### Issue: Port in use
+```bash
+# Find process using port
+lsof -i :8000
+lsof -i :8443
+
+# Stop process
+kill -9 <PID>
+```
+
+### Issue: SSL errors
+```bash
+# Check certificates
+openssl x509 -in certs/server_cert.pem -text -noout
+
+# Check private key
+openssl rsa -in keys/server_key.pem -check
+```
+
+## 📚 Additional Documentation
+
+- [SECURITY_TESTING.md](SECURITY_TESTING.md) - Detailed security testing guide
+- [API Documentation](../docs/api/) - API documentation
+- [Configuration Guide](../docs/configuration.md) - Configuration guide
+
+## 🤝 Support
+
+If you encounter issues:
+
+1. Check logs in `./logs/`
+2. Ensure all dependencies are installed
+3. Verify certificates are generated correctly
+4. Refer to troubleshooting documentation
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](../../LICENSE) file for details.
+
+---
+
+**Author**: Vasiliy Zdanovskiy  
+**Email**: vasilyvz@gmail.com  
+**Version**: 1.0.0