mcp-proxy-adapter 3.1.6__py3-none-any.whl → 4.1.0__py3-none-any.whl

mcp_proxy_adapter/examples/README.md

@@ -0,0 +1,124 @@
+# MCP Proxy Adapter Examples
+
+This directory contains examples demonstrating different usage patterns of the MCP Proxy Adapter framework.
+
+## 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
+
+### 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
+
+The framework supports two ways to set application properties:
+
+### Method 1: During Creation (Recommended)
+```python
+from mcp_proxy_adapter import create_app
+
+app = create_app(
+    title="My Custom Server",
+    description="My custom server description",
+    version="2.0.0"
+)
+```
+
+### Method 2: After Creation (Backward Compatible)
+```python
+from mcp_proxy_adapter import create_app
+
+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"
+)
+```
+
+## Running Examples
+
+### Basic Server
+```bash
+cd mcp_proxy_adapter/examples/basic_server
+python server.py
+```
+
+### Custom Commands Server
+```bash
+cd mcp_proxy_adapter/examples/custom_commands
+python server.py
+```
+
+## 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}'
+
+# Get health
+curl -X POST http://localhost:8000/cmd \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "health", "id": 2}'
+```
+
+### 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 

mcp_proxy_adapter/examples/__init__.py

@@ -0,0 +1,7 @@
+"""
+MCP Proxy Adapter Examples
+
+This package contains examples and templates for using the MCP Proxy Adapter framework.
+"""
+
+__version__ = "1.0.0" 

mcp_proxy_adapter/examples/basic_server/README.md

@@ -0,0 +1,60 @@
+# Basic Server Example
+
+A minimal example of MCP Proxy Adapter server without additional commands.
+
+## Features
+
+This example demonstrates:
+- Basic server setup
+- Built-in commands only (help, health)
+- Default configuration
+- No custom commands
+
+## Available Commands
+
+- `help` - Get information about available commands
+- `health` - Get server health status
+
+## Usage
+
+### Run the server
+
+```bash
+python server.py
+```
+
+### Test the server
+
+```bash
+# Get help
+curl -X POST http://localhost:8000/cmd \
+  -H "Content-Type: application/json" \
+  -d '{"command": "help"}'
+
+# Get health status
+curl -X POST http://localhost:8000/cmd \
+  -H "Content-Type: application/json" \
+  -d '{"command": "health"}'
+```
+
+## API Endpoints
+
+- `POST /cmd` - Execute commands
+- `GET /health` - Health check
+- `GET /commands` - List available commands
+- `GET /docs` - API documentation
+
+## Configuration
+
+The server uses default configuration. You can customize it by:
+
+1. Creating a `config.json` file
+2. Setting environment variables
+3. Passing configuration to `create_app()`
+
+## Notes
+
+- This is the simplest possible setup
+- No custom commands are registered
+- Uses framework defaults
+- Good starting point for understanding the framework 

mcp_proxy_adapter/examples/basic_server/__init__.py

@@ -0,0 +1,7 @@
+"""
+Basic Server Example
+
+A minimal example of MCP Proxy Adapter server without additional commands.
+"""
+
+__version__ = "1.0.0" 

mcp_proxy_adapter/examples/basic_server/basic_custom_settings.json

@@ -0,0 +1,39 @@
+{
+  "application": {
+    "name": "Basic MCP Proxy Server with Custom Settings",
+    "version": "1.1.0",
+    "environment": "development",
+    "description": "Basic server demonstrating custom settings usage"
+  },
+  "features": {
+    "basic_logging": true,
+    "simple_commands": true,
+    "custom_settings_demo": true,
+    "file_based_config": true
+  },
+  "server_info": {
+    "description": "Basic server with file-based custom settings",
+    "author": "MCP Proxy Adapter Team",
+    "contact": "support@example.com",
+    "documentation": "https://example.com/docs"
+  },
+  "demo_settings": {
+    "welcome_message": "Welcome to Basic MCP Proxy Server with Custom Settings!",
+    "max_connections": 150,
+    "timeout": 45,
+    "debug_mode": true,
+    "log_level": "INFO"
+  },
+  "performance": {
+    "enable_caching": true,
+    "cache_ttl": 300,
+    "max_cache_size": 1000
+  },
+  "security": {
+    "enable_rate_limiting": false,
+    "max_request_size": "5MB",
+    "allowed_origins": [
+      "*"
+    ]
+  }
+}

mcp_proxy_adapter/examples/basic_server/config.json

@@ -0,0 +1,35 @@
+{
+  "server": {
+    "host": "127.0.0.1",
+    "port": 8000,
+    "debug": true,
+    "log_level": "DEBUG"
+  },
+  "logging": {
+    "level": "DEBUG",
+    "log_dir": "./logs/basic_server",
+    "log_file": "basic_server.log",
+    "error_log_file": "basic_server_error.log",
+    "access_log_file": "basic_server_access.log",
+    "max_file_size": "5MB",
+    "backup_count": 3,
+    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    "date_format": "%Y-%m-%d %H:%M:%S",
+    "console_output": true,
+    "file_output": true
+  },
+  "commands": {
+    "auto_discovery": true,
+    "discovery_path": "mcp_proxy_adapter.commands",
+    "custom_commands_path": null
+  },
+  "custom": {
+    "server_name": "Basic MCP Proxy Server",
+    "description": "Simple example server with basic configuration",
+    "features": {
+      "hooks_enabled": false,
+      "custom_commands_enabled": false,
+      "advanced_logging": false
+    }
+  }
+} 

mcp_proxy_adapter/examples/basic_server/custom_settings_example.py

@@ -0,0 +1,238 @@
+"""
+Custom Settings Example for Basic Server
+
+This example demonstrates how to use custom settings in a basic server.
+"""
+
+import json
+import os
+from mcp_proxy_adapter.core.settings import (
+    add_custom_settings,
+    get_custom_setting_value,
+    set_custom_setting_value,
+    get_custom_settings
+)
+from mcp_proxy_adapter.core.logging import get_logger
+
+
+def setup_basic_custom_settings():
+    """
+    Setup basic custom settings for the basic server example.
+    
+    This demonstrates how to add custom settings to the framework
+    and access them throughout the application.
+    """
+    logger = get_logger("basic_server_custom_settings")
+    
+    # Define basic custom settings
+    basic_settings = {
+        "application": {
+            "name": "Basic MCP Proxy Server",
+            "version": "1.0.0",
+            "environment": "development"
+        },
+        "features": {
+            "basic_logging": True,
+            "simple_commands": True,
+            "custom_settings_demo": True
+        },
+        "server_info": {
+            "description": "Basic server with custom settings example",
+            "author": "MCP Proxy Adapter Team",
+            "contact": "support@example.com"
+        },
+        "demo_settings": {
+            "welcome_message": "Welcome to Basic MCP Proxy Server!",
+            "max_connections": 100,
+            "timeout": 30,
+            "debug_mode": True
+        }
+    }
+    
+    # Add settings to the framework
+    add_custom_settings(basic_settings)
+    
+    logger.info("✅ Basic custom settings loaded")
+    logger.info(f"📋 Application: {basic_settings['application']['name']} v{basic_settings['application']['version']}")
+    logger.info(f"🔧 Features: {list(basic_settings['features'].keys())}")
+    
+    return basic_settings
+
+
+def demonstrate_custom_settings_usage():
+    """
+    Demonstrate how to use custom settings in the application.
+    """
+    logger = get_logger("basic_server_custom_settings")
+    
+    # Get specific settings
+    app_name = get_custom_setting_value("application.name", "Unknown")
+    app_version = get_custom_setting_value("application.version", "0.0.0")
+    welcome_msg = get_custom_setting_value("demo_settings.welcome_message", "Hello!")
+    max_connections = get_custom_setting_value("demo_settings.max_connections", 50)
+    
+    logger.info(f"🏷️  Application: {app_name} v{app_version}")
+    logger.info(f"💬 Welcome Message: {welcome_msg}")
+    logger.info(f"🔗 Max Connections: {max_connections}")
+    
+    # Check if features are enabled
+    features = get_custom_setting_value("features", {})
+    enabled_features = [name for name, enabled in features.items() if enabled]
+    
+    logger.info(f"✅ Enabled Features: {', '.join(enabled_features)}")
+    
+    # Set a new custom setting
+    set_custom_setting_value("demo_settings.last_updated", "2025-08-08")
+    logger.info("🔧 Set new custom setting: demo_settings.last_updated")
+    
+    # Get all custom settings
+    all_custom_settings = get_custom_settings()
+    logger.info(f"📊 Total custom settings: {len(all_custom_settings)} sections")
+    
+    return {
+        "app_name": app_name,
+        "app_version": app_version,
+        "welcome_message": welcome_msg,
+        "max_connections": max_connections,
+        "enabled_features": enabled_features,
+        "total_settings_sections": len(all_custom_settings)
+    }
+
+
+def create_custom_settings_file():
+    """
+    Create a custom settings JSON file for the basic server.
+    """
+    custom_settings = {
+        "application": {
+            "name": "Basic MCP Proxy Server with Custom Settings",
+            "version": "1.1.0",
+            "environment": "development",
+            "description": "Basic server demonstrating custom settings usage"
+        },
+        "features": {
+            "basic_logging": True,
+            "simple_commands": True,
+            "custom_settings_demo": True,
+            "file_based_config": True
+        },
+        "server_info": {
+            "description": "Basic server with file-based custom settings",
+            "author": "MCP Proxy Adapter Team",
+            "contact": "support@example.com",
+            "documentation": "https://example.com/docs"
+        },
+        "demo_settings": {
+            "welcome_message": "Welcome to Basic MCP Proxy Server with Custom Settings!",
+            "max_connections": 150,
+            "timeout": 45,
+            "debug_mode": True,
+            "log_level": "INFO"
+        },
+        "performance": {
+            "enable_caching": True,
+            "cache_ttl": 300,
+            "max_cache_size": 1000
+        },
+        "security": {
+            "enable_rate_limiting": False,
+            "max_request_size": "5MB",
+            "allowed_origins": ["*"]
+        }
+    }
+    
+    # Write to file
+    settings_file = "basic_custom_settings.json"
+    with open(settings_file, 'w', encoding='utf-8') as f:
+        json.dump(custom_settings, f, indent=2, ensure_ascii=False)
+    
+    print(f"✅ Created custom settings file: {settings_file}")
+    return settings_file
+
+
+def load_custom_settings_from_file(file_path: str = "basic_custom_settings.json"):
+    """
+    Load custom settings from a JSON file.
+    
+    Args:
+        file_path: Path to the custom settings JSON file
+    """
+    logger = get_logger("basic_server_custom_settings")
+    
+    try:
+        if os.path.exists(file_path):
+            with open(file_path, 'r', encoding='utf-8') as f:
+                custom_settings = json.load(f)
+            
+            # Add to framework
+            add_custom_settings(custom_settings)
+            
+            logger.info(f"📁 Loaded custom settings from: {file_path}")
+            logger.info(f"📋 Application: {custom_settings.get('application', {}).get('name', 'Unknown')}")
+            
+            return custom_settings
+        else:
+            logger.warning(f"⚠️  Custom settings file not found: {file_path}")
+            return None
+            
+    except Exception as e:
+        logger.error(f"❌ Failed to load custom settings from {file_path}: {e}")
+        return None
+
+
+def print_custom_settings_summary():
+    """
+    Print a summary of current custom settings.
+    """
+    logger = get_logger("basic_server_custom_settings")
+    
+    all_settings = get_custom_settings()
+    
+    logger.info("📊 Custom Settings Summary:")
+    
+    # Application info
+    app_name = get_custom_setting_value("application.name", "Unknown")
+    app_version = get_custom_setting_value("application.version", "0.0.0")
+    logger.info(f"   Application: {app_name} v{app_version}")
+    
+    # Features
+    features = get_custom_setting_value("features", {})
+    enabled_features = [name for name, enabled in features.items() if enabled]
+    logger.info(f"   Enabled Features: {', '.join(enabled_features) if enabled_features else 'None'}")
+    
+    # Demo settings
+    welcome_msg = get_custom_setting_value("demo_settings.welcome_message", "Hello!")
+    max_connections = get_custom_setting_value("demo_settings.max_connections", 50)
+    logger.info(f"   Welcome Message: {welcome_msg}")
+    logger.info(f"   Max Connections: {max_connections}")
+    
+    # Performance
+    caching_enabled = get_custom_setting_value("performance.enable_caching", False)
+    logger.info(f"   Caching: {'Enabled' if caching_enabled else 'Disabled'}")
+    
+    # Security
+    rate_limiting = get_custom_setting_value("security.enable_rate_limiting", False)
+    logger.info(f"   Rate Limiting: {'Enabled' if rate_limiting else 'Disabled'}")
+    
+    logger.info(f"   Total Settings Sections: {len(all_settings)}")
+
+
+if __name__ == "__main__":
+    # Setup basic custom settings
+    setup_basic_custom_settings()
+    
+    # Demonstrate usage
+    demo_info = demonstrate_custom_settings_usage()
+    
+    # Create custom settings file
+    settings_file = create_custom_settings_file()
+    
+    # Load from file
+    load_custom_settings_from_file(settings_file)
+    
+    # Print summary
+    print_custom_settings_summary()
+    
+    print("\n🎉 Custom settings demonstration completed!")
+    print(f"📁 Custom settings file: {settings_file}")
+    print("🔧 You can now use these settings in your basic server application.") 

mcp_proxy_adapter/examples/basic_server/server.py

@@ -0,0 +1,98 @@
+"""
+Basic Server Example
+
+This example demonstrates a minimal MCP Proxy Adapter server
+without any additional custom commands.
+"""
+
+import asyncio
+import uvicorn
+import sys
+import os
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+
+from mcp_proxy_adapter import create_app
+from mcp_proxy_adapter.core.logging import get_logger, setup_logging
+from mcp_proxy_adapter.core.settings import (
+    Settings, 
+    get_server_host, 
+    get_server_port, 
+    get_server_debug,
+    get_setting
+)
+
+
+def main():
+    """Run the basic server example."""
+    # Load configuration from config.json in the same directory
+    config_path = os.path.join(os.path.dirname(__file__), "config.json")
+    if os.path.exists(config_path):
+        from mcp_proxy_adapter.config import config
+        config.load_from_file(config_path)
+        print(f"✅ Loaded configuration from: {config_path}")
+    else:
+        print(f"⚠️  Configuration file not found: {config_path}")
+        print("   Using default configuration")
+    
+    # Setup logging with configuration
+    setup_logging()
+    logger = get_logger("basic_server")
+    
+    # Get settings from configuration
+    server_settings = Settings.get_server_settings()
+    logging_settings = Settings.get_logging_settings()
+    commands_settings = Settings.get_commands_settings()
+    custom_settings = Settings.get_custom_setting("custom", {})
+    
+    # Print server header and description
+    print("=" * 80)
+    print("🔧 BASIC MCP PROXY ADAPTER SERVER")
+    print("=" * 80)
+    print("📋 Description:")
+    print(f"   {custom_settings.get('description', 'Basic server example')}")
+    print()
+    print("⚙️  Configuration:")
+    print(f"   • Server: {server_settings['host']}:{server_settings['port']}")
+    print(f"   • Debug: {server_settings['debug']}")
+    print(f"   • Log Level: {logging_settings['level']}")
+    print(f"   • Log Directory: {logging_settings['log_dir']}")
+    print(f"   • Auto Discovery: {commands_settings['auto_discovery']}")
+    print()
+    print("🔧 Available Commands:")
+    print("   • help - Built-in help command")
+    print("   • health - Built-in health command")
+    print("   • config - Built-in config command")
+    print("   • reload - Built-in reload command")
+    print()
+    print("🎯 Features:")
+    print("   • Standard JSON-RPC API")
+    print("   • Built-in command discovery")
+    print("   • Basic logging and error handling")
+    print("   • OpenAPI schema generation")
+    print("   • Configuration-driven settings")
+    print("=" * 80)
+    print()
+    
+    logger.info("Starting Basic MCP Proxy Adapter Server...")
+    logger.info(f"Server configuration: {server_settings}")
+    logger.info(f"Logging configuration: {logging_settings}")
+    logger.info(f"Commands configuration: {commands_settings}")
+    
+    # Create application with settings from configuration
+    app = create_app(
+        title=custom_settings.get('server_name', 'Basic MCP Proxy Adapter Server'),
+        description=custom_settings.get('description', 'Minimal server example with only built-in commands'),
+        version="1.0.0"
+    )
+    
+    # Run the server with configuration settings
+    uvicorn.run(
+        app,
+        host=server_settings['host'],
+        port=server_settings['port'],
+        log_level=server_settings['log_level'].lower()
+    )
+
+
+if __name__ == "__main__":
+    main()