mcp-proxy-adapter 2.1.17__py3-none-any.whl → 3.0.1__py3-none-any.whl

examples/__init__.py

@@ -0,0 +1,19 @@
+"""
+Examples package for MCP Microservice.
+
+This package contains examples of using the MCP Microservice framework
+for building microservices with different levels of complexity.
+
+Examples:
+- minimal_example: Minimal working example with a single command
+- basic_example: Basic example with multiple commands and tests
+- complete_example: Complete example with Docker support and advanced features
+- anti_patterns: Examples of anti-patterns and bad practices (for educational purposes)
+"""
+
+__all__ = [
+    "minimal_example",
+    "basic_example",
+    "complete_example",
+    "anti_patterns"
+] 

examples/anti_patterns/README.md

@@ -0,0 +1,51 @@
+# Anti-Patterns for MCP Microservice
+
+This directory contains examples of anti-patterns and bad practices when using MCP Microservice.
+These examples demonstrate what **NOT** to do and common mistakes to avoid.
+
+## Categories
+
+1. **Bad Design Patterns** - Examples of poor architectural and design choices
+2. **Performance Issues** - Examples that can cause performance problems
+3. **Security Problems** - Examples with potential security vulnerabilities
+
+## Purpose
+
+These examples serve as educational resources to help you:
+
+1. Recognize common mistakes
+2. Understand why they are problematic
+3. Learn better alternatives
+
+**WARNING:** These examples contain intentional errors, bugs, and security vulnerabilities.
+Do not use them in production environments or as a basis for your own code.
+
+## Structure
+
+```
+anti_patterns/
+├── bad_design/              # Poor architectural and design choices
+│   ├── monolithic_command.py    # Example of a command that does too much
+│   ├── global_state.py          # Example of using global state
+│   └── README.md                # Explanation of bad design patterns
+├── performance_issues/      # Performance problems
+│   ├── blocking_operations.py   # Example of blocking the event loop
+│   ├── memory_leaks.py          # Example of potential memory leaks
+│   └── README.md                # Explanation of performance issues
+├── security_problems/       # Security vulnerabilities
+│   ├── no_validation.py         # Example of missing input validation
+│   ├── command_injection.py     # Example of command injection vulnerability
+│   └── README.md                # Explanation of security problems
+└── README.md                # This file
+```
+
+## How to Use
+
+Each example directory contains a README.md file explaining:
+
+1. What the anti-pattern is
+2. Why it's problematic
+3. Better alternatives
+4. How to fix the issues
+
+Use these examples as a reference for what to avoid, not as templates for your code. 

examples/anti_patterns/__init__.py

@@ -0,0 +1,9 @@
+"""
+Anti-patterns examples for MCP Microservice.
+
+This package contains examples of anti-patterns and bad practices 
+when using MCP Microservice framework. These examples are for educational
+purposes only and should NOT be used in production.
+"""
+
+__all__ = [] 

examples/anti_patterns/bad_design/README.md

@@ -0,0 +1,72 @@
+# Bad Design Patterns
+
+This directory contains examples of poor architectural and design choices when using MCP Microservice.
+
+## Included Examples
+
+1. **[monolithic_command.py](./monolithic_command.py)** - A command that tries to do too much
+2. **[global_state.py](./global_state.py)** - Using global state for command data
+
+## Monolithic Command Anti-Pattern
+
+### Problem
+
+The `MonolithicCommand` tries to handle multiple responsibilities:
+- Data processing
+- Validation
+- Database operations
+- File operations
+- Notification
+
+### Why It's Bad
+
+1. **Violates Single Responsibility Principle**: Each command should do one thing well
+2. **Difficult to Test**: Large commands with many responsibilities are hard to test
+3. **Hard to Maintain**: Changes to one feature may affect others
+4. **Poor Reusability**: Cannot reuse parts of the functionality
+
+### Better Alternative
+
+Split the monolithic command into multiple smaller commands:
+- `ProcessDataCommand` - Handles data processing
+- `SaveDataCommand` - Handles database operations
+- `GenerateReportCommand` - Handles file operations
+- `SendNotificationCommand` - Handles notifications
+
+## Global State Anti-Pattern
+
+### Problem
+
+The `GlobalStateCommand` uses global variables to store and share data between command executions.
+
+### Why It's Bad
+
+1. **Thread Safety**: Global state is not thread-safe in asynchronous environments
+2. **Testing Difficulty**: Commands with global state are hard to test in isolation
+3. **Hidden Dependencies**: Dependencies are not explicit
+4. **State Management**: Difficult to track and manage state changes
+
+### Better Alternative
+
+Use proper dependency injection and maintain state within the command instance:
+
+```python
+class ProperStateCommand(Command):
+    name = "proper_state"
+    result_class = StateResult
+    
+    def __init__(self):
+        self._state = {}  # State is maintained per instance
+    
+    async def execute(self, key: str, value: Any = None) -> StateResult:
+        if value is not None:
+            self._state[key] = value
+        return StateResult(key, self._state.get(key))
+```
+
+## How to Fix
+
+1. **Identify Single Responsibilities**: Break down commands by responsibility
+2. **Explicit Dependencies**: Use constructor parameters or method arguments
+3. **Avoid Global State**: Maintain state within instances or external services
+4. **Use Dependency Injection**: Inject dependencies through constructors 

examples/anti_patterns/bad_design/global_state.py

@@ -0,0 +1,170 @@
+"""
+ANTI-PATTERN EXAMPLE: Global State
+
+This module demonstrates an anti-pattern where a command uses global state
+to store and share data between executions.
+
+WARNING: This is a BAD EXAMPLE! Do not use this approach in production.
+"""
+
+from typing import Dict, Any, Optional
+
+from mcp_proxy_adapter import Command, SuccessResult
+
+
+# Global state - an anti-pattern that creates hidden dependencies
+# and makes the code hard to test and maintain
+GLOBAL_STATE: Dict[str, Any] = {}
+
+
+class StateResult(SuccessResult):
+    """Result of state command."""
+    
+    def __init__(self, key: str, value: Any):
+        """
+        Initialize result.
+        
+        Args:
+            key: The key accessed
+            value: The value retrieved
+        """
+        self.key = key
+        self.value = value
+        
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to dictionary."""
+        return {
+            "key": self.key,
+            "value": self.value
+        }
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """Get JSON schema for result."""
+        return {
+            "type": "object",
+            "properties": {
+                "key": {"type": "string"},
+                "value": {"type": "string"}
+            },
+            "required": ["key"]
+        }
+
+
+class GlobalStateCommand(Command):
+    """
+    ANTI-PATTERN: This command uses global state.
+    
+    It stores and retrieves values from a global dictionary,
+    creating hidden dependencies and making the code:
+    - Not thread-safe
+    - Hard to test
+    - Prone to unexpected behavior
+    - Difficult to reason about
+    """
+    
+    name = "global_state"
+    result_class = StateResult
+    
+    async def execute(self, key: str, value: Any = None) -> StateResult:
+        """
+        Execute global state command.
+        
+        Args:
+            key: Key to get or set
+            value: Value to set (if not None)
+        
+        Returns:
+            Result with key and current value
+        """
+        # Get or set value in global state
+        if value is not None:
+            # Set the value in the global state
+            GLOBAL_STATE[key] = value
+            
+        # Return the current value (which might be None if the key doesn't exist)
+        current_value = GLOBAL_STATE.get(key)
+        return StateResult(key, current_value)
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """Get JSON schema for command parameters."""
+        return {
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "description": "Key to get or set"
+                },
+                "value": {
+                    "type": ["string", "number", "boolean", "null", "array", "object"],
+                    "description": "Value to set (optional)"
+                }
+            },
+            "required": ["key"]
+        }
+
+
+# Even worse: Command with mixed global and instance state
+class MixedStateCommand(Command):
+    """
+    ANTI-PATTERN: This command mixes global and instance state.
+    
+    It's even worse than just global state because it creates confusion
+    about where state is stored and how it's accessed.
+    """
+    
+    name = "mixed_state"
+    result_class = StateResult
+    
+    def __init__(self):
+        """Initialize with instance-specific counter."""
+        self._counter = 0  # Instance state
+    
+    async def execute(self, key: str, value: Any = None, increment: bool = False) -> StateResult:
+        """
+        Execute mixed state command.
+        
+        Args:
+            key: Key to get or set
+            value: Value to set (if not None)
+            increment: Whether to increment the instance counter
+        
+        Returns:
+            Result with key and current value
+        """
+        # Instance state modification
+        if increment:
+            self._counter += 1
+        
+        # Global state modification - mixing different state types!
+        if value is not None:
+            # Set in global state
+            GLOBAL_STATE[key] = value
+            
+        # Mix instance state with the value
+        if self._counter > 0:
+            # Modify value based on instance state
+            if isinstance(GLOBAL_STATE.get(key), (int, float)):
+                GLOBAL_STATE[key] = GLOBAL_STATE.get(key, 0) + self._counter
+        
+        # Return the current value (which might be None if the key doesn't exist)
+        current_value = GLOBAL_STATE.get(key)
+        return StateResult(key, current_value)
+
+
+# Example of how this causes problems:
+# Both commands modify the same global state, which creates hidden dependencies
+# and makes behavior unpredictable, especially with concurrent requests.
+
+# Usage example (don't do this!):
+#
+# # Command 1 sets a value
+# await GlobalStateCommand().execute("user_count", 10)
+#
+# # Command 2 also modifies the same value
+# await MixedStateCommand().execute("user_count", 5)
+#
+# # Command 1 reads the value but gets a result it didn't expect
+# result = await GlobalStateCommand().execute("user_count")
+# # result.value might be 5 instead of 10! 

examples/anti_patterns/bad_design/monolithic_command.py

@@ -0,0 +1,272 @@
+"""
+ANTI-PATTERN EXAMPLE: Monolithic Command
+
+This module demonstrates an anti-pattern where a command tries to do too much,
+violating the Single Responsibility Principle.
+
+WARNING: This is a BAD EXAMPLE! Do not use this approach in production.
+"""
+
+import os
+import json
+import sqlite3
+import smtplib
+import time
+from email.message import EmailMessage
+from typing import Dict, Any, List, Optional
+
+from mcp_proxy_adapter import Command, SuccessResult
+
+
+# Global connection pool - another anti-pattern
+DB_CONNECTIONS = {}
+
+
+class MonolithicResult(SuccessResult):
+    """Result of monolithic command."""
+    
+    def __init__(self, status: str, data: Dict[str, Any]):
+        """
+        Initialize result.
+        
+        Args:
+            status: Operation status
+            data: Result data
+        """
+        self.status = status
+        self.data = data
+        
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to dictionary."""
+        return {
+            "status": self.status,
+            "data": self.data
+        }
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """Get JSON schema for result."""
+        return {
+            "type": "object",
+            "properties": {
+                "status": {"type": "string"},
+                "data": {"type": "object"}
+            },
+            "required": ["status", "data"]
+        }
+
+
+class MonolithicCommand(Command):
+    """
+    ANTI-PATTERN: This command tries to do too much.
+    
+    It handles:
+    1. Data processing
+    2. Validation
+    3. Database operations
+    4. File operations
+    5. Notifications
+    
+    This violates the Single Responsibility Principle and makes the code:
+    - Hard to test
+    - Hard to maintain
+    - Difficult to reuse
+    """
+    
+    name = "do_everything"
+    result_class = MonolithicResult
+    
+    async def execute(
+        self,
+        action: str,
+        data: Dict[str, Any],
+        save_to_db: bool = True,
+        generate_report: bool = True,
+        notify_users: List[str] = None
+    ) -> MonolithicResult:
+        """
+        Execute monolithic command.
+        
+        Args:
+            action: Action to perform (process, update, delete)
+            data: Input data to process
+            save_to_db: Whether to save data to database
+            generate_report: Whether to generate a report
+            notify_users: List of users to notify
+        
+        Returns:
+            Result of operations
+        """
+        result_data = {}
+        
+        # Step 1: Process data - this should be a separate command
+        processed_data = self._process_data(action, data)
+        result_data["processed"] = processed_data
+        
+        # Step 2: Save to database - this should be a separate command
+        if save_to_db:
+            db_result = self._save_to_database(processed_data)
+            result_data["database"] = db_result
+        
+        # Step 3: Generate report - this should be a separate command
+        if generate_report:
+            report_path = self._generate_report(processed_data)
+            result_data["report"] = report_path
+        
+        # Step 4: Notify users - this should be a separate command
+        if notify_users:
+            notification_result = self._send_notifications(
+                notify_users, processed_data, report_path if generate_report else None
+            )
+            result_data["notifications"] = notification_result
+        
+        return MonolithicResult("success", result_data)
+    
+    def _process_data(self, action: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Process input data based on action."""
+        # Simulate data processing
+        processed = dict(data)
+        
+        if action == "process":
+            # Complex data processing logic
+            processed["status"] = "processed"
+            processed["timestamp"] = time.time()
+            
+            # Calculate some values
+            if "values" in processed and isinstance(processed["values"], list):
+                processed["sum"] = sum(processed["values"])
+                processed["average"] = sum(processed["values"]) / len(processed["values"])
+            
+        elif action == "update":
+            # Update logic
+            processed["status"] = "updated"
+            processed["updated_at"] = time.time()
+            
+        elif action == "delete":
+            # Delete logic
+            processed["status"] = "deleted"
+            processed["deleted_at"] = time.time()
+            
+        return processed
+    
+    def _save_to_database(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Save data to database - should be a separate command."""
+        # Get or create database connection
+        conn = self._get_db_connection()
+        cursor = conn.cursor()
+        
+        # Create table if not exists
+        cursor.execute("""
+        CREATE TABLE IF NOT EXISTS items (
+            id INTEGER PRIMARY KEY,
+            data TEXT,
+            status TEXT,
+            timestamp REAL
+        )
+        """)
+        
+        # Insert data
+        data_json = json.dumps(data)
+        cursor.execute(
+            "INSERT INTO items (data, status, timestamp) VALUES (?, ?, ?)",
+            (data_json, data.get("status", "unknown"), time.time())
+        )
+        
+        # Get ID of inserted row
+        row_id = cursor.lastrowid
+        conn.commit()
+        
+        return {"id": row_id, "status": "saved"}
+    
+    def _generate_report(self, data: Dict[str, Any]) -> str:
+        """Generate report file - should be a separate command."""
+        # Create reports directory if not exists
+        os.makedirs("reports", exist_ok=True)
+        
+        # Generate report filename
+        filename = f"reports/report_{int(time.time())}.json"
+        
+        # Write report to file
+        with open(filename, "w") as f:
+            json.dump(data, f, indent=2)
+        
+        return filename
+    
+    def _send_notifications(
+        self, 
+        recipients: List[str], 
+        data: Dict[str, Any],
+        report_path: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Send notifications to users - should be a separate command."""
+        # Configure email server (hardcoded values - another anti-pattern)
+        smtp_server = "smtp.example.com"
+        smtp_port = 587
+        smtp_user = "service@example.com"
+        smtp_password = "password123"  # Hardcoding passwords is a security issue!
+        
+        # Create message
+        msg = EmailMessage()
+        msg["Subject"] = f"Data {data.get('status', 'processed')}"
+        msg["From"] = "service@example.com"
+        msg["To"] = ", ".join(recipients)
+        
+        # Set content
+        content = f"Data has been {data.get('status', 'processed')}.\n\n"
+        if report_path:
+            content += f"Report is available at: {report_path}\n"
+        msg.set_content(content)
+        
+        # Send email (commented out to prevent actual sending)
+        # with smtplib.SMTP(smtp_server, smtp_port) as server:
+        #     server.login(smtp_user, smtp_password)
+        #     server.send_message(msg)
+        
+        # Simulate successful sending
+        return {
+            "sent_to": recipients,
+            "status": "sent"
+        }
+    
+    def _get_db_connection(self) -> sqlite3.Connection:
+        """Get database connection from pool."""
+        if "default" not in DB_CONNECTIONS:
+            # Create new connection
+            DB_CONNECTIONS["default"] = sqlite3.connect(":memory:")
+        
+        return DB_CONNECTIONS["default"]
+    
+    @classmethod
+    def get_schema(cls) -> Dict[str, Any]:
+        """Get JSON schema for command parameters."""
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["process", "update", "delete"],
+                    "description": "Action to perform"
+                },
+                "data": {
+                    "type": "object",
+                    "description": "Input data to process"
+                },
+                "save_to_db": {
+                    "type": "boolean",
+                    "description": "Whether to save data to database",
+                    "default": True
+                },
+                "generate_report": {
+                    "type": "boolean",
+                    "description": "Whether to generate a report",
+                    "default": True
+                },
+                "notify_users": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "List of users to notify",
+                    "default": []
+                }
+            },
+            "required": ["action", "data"]
+        }