kite-agent 0.1.0__py3-none-any.whl

kite/tools/mcp/stripe_mcp_server.py

@@ -0,0 +1,219 @@
+"""
+Stripe MCP Server Implementation
+Based on Chapter 4: Model Context Protocol
+
+Lessons from $15K Refund Loop (Chapter 1):
+- Idempotency keys MANDATORY
+- Circuit breaker REQUIRED
+- Confirmation prompts for all write operations
+- Detailed audit logging
+"""
+
+import os
+import json
+import hashlib
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+# ============================================================================
+# SAFETY COMPONENTS
+# ============================================================================
+
+class RefundStatus(Enum):
+    """Refund processing status."""
+    PENDING = "pending"
+    PROCESSING = "processing"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    DUPLICATE = "duplicate"
+
+
+@dataclass
+class IdempotencyKey:
+    """Idempotency key for preventing duplicates."""
+    key: str
+    created_at: datetime
+    result: Optional[Dict] = None
+
+
+class IdempotencyManager:
+    """Prevents duplicate operations using idempotency keys."""
+    
+    def __init__(self, ttl_seconds: int = 86400):
+        self.cache: Dict[str, IdempotencyKey] = {}
+        self.ttl_seconds = ttl_seconds
+    
+    def generate_key(self, operation: str, **params) -> str:
+        data = json.dumps({"operation": operation, **params}, sort_keys=True)
+        key = hashlib.sha256(data.encode()).hexdigest()[:16]
+        return f"idem_{key}"
+    
+    def get_cached(self, key: str) -> Optional[Dict]:
+        if key in self.cache:
+            idem = self.cache[key]
+            if (datetime.now() - idem.created_at).seconds < self.ttl_seconds:
+                return idem.result
+            del self.cache[key]
+        return None
+    
+    def store(self, key: str, result: Dict):
+        self.cache[key] = IdempotencyKey(key=key, created_at=datetime.now(), result=result)
+
+
+class RefundCircuitBreaker:
+    """Circuit breaker to stop repeated refund failures."""
+    
+    def __init__(self, failure_threshold: int = 3, timeout_seconds: int = 60):
+        self.failure_threshold = failure_threshold
+        self.timeout_seconds = timeout_seconds
+        self.failure_count = 0
+        self.last_failure_time: Optional[datetime] = None
+        self.state = "closed"
+    
+    def can_attempt(self) -> tuple[bool, str]:
+        if self.state == "closed": return True, "OK"
+        if self.state == "open":
+            if self.last_failure_time and (datetime.now() - self.last_failure_time).seconds >= self.timeout_seconds:
+                self.state = "half_open"
+                return True, "Testing"
+            return False, "Circuit open"
+        return True, "Testing"
+    
+    def record_success(self):
+        self.failure_count = 0
+        self.state = "closed"
+    
+    def record_failure(self):
+        self.failure_count += 1
+        self.last_failure_time = datetime.now()
+        if self.failure_count >= self.failure_threshold:
+            self.state = "open"
+
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+@dataclass
+class StripeConfig:
+    """Configuration for Stripe MCP server."""
+    api_key: str = ""
+    max_refund_amount: float = 1000.00
+    require_confirmation: bool = True
+    max_refunds_per_hour: int = 10
+    rate_limit_per_minute: int = 30
+    enable_read: bool = True
+    enable_refund: bool = False
+
+
+# ============================================================================
+# STRIPE MCP SERVER
+# ============================================================================
+
+class StripeMCPServer:
+    """
+    MCP Server for Stripe integration with safety defaults.
+    """
+    
+    def __init__(self, config: StripeConfig = None, client = None, **kwargs):
+        # Handle api_key if passed directly
+        if 'api_key' in kwargs and config is None:
+            config = StripeConfig(api_key=kwargs['api_key'])
+        
+        self.config = config or StripeConfig()
+        self.stripe = client # Should be a real stripe client in production
+        
+        # SAFETY COMPONENTS
+        self.idempotency = IdempotencyManager()
+        self.circuit_breaker = RefundCircuitBreaker()
+        
+        # Rate limiting
+        self.request_count = 0
+        self.refund_count_hour = 0
+        self.window_start = datetime.now()
+        self.hour_start = datetime.now()
+        
+        # Audit log
+        self.audit_log: List[Dict] = []
+        
+        print(f"[OK] Stripe MCP Server initialized (SAFETY MODE: EXTREME)")
+    
+    def _check_rate_limit(self) -> bool:
+        now = datetime.now()
+        if (now - self.window_start).seconds >= 60:
+            self.request_count = 0
+            self.window_start = now
+        if self.request_count >= self.config.rate_limit_per_minute:
+            return False
+        self.request_count += 1
+        return True
+    
+    def _check_refund_limit(self) -> bool:
+        now = datetime.now()
+        if (now - self.hour_start).seconds >= 3600:
+            self.refund_count_hour = 0
+            self.hour_start = now
+        return self.refund_count_hour < self.config.max_refunds_per_hour
+    
+    def _log_audit(self, operation: str, params: Dict, result: Dict):
+        self.audit_log.append({
+            "timestamp": datetime.now().isoformat(),
+            "operation": operation,
+            "params": params,
+            "result": result
+        })
+    
+    def get_payment(self, charge_id: str) -> Dict[str, Any]:
+        """Get payment details (READ-ONLY)."""
+        if not self.config.enable_read or not self._check_rate_limit():
+            return {"success": False, "error": "Access denied or rate limited"}
+        
+        try:
+            # Placeholder for real stripe call
+            if not self.stripe: return {"success": False, "error": "Stripe client not configured"}
+            charge = self.stripe.charges_retrieve(charge_id)
+            return {"success": True, "charge_id": charge_id, "amount": charge["amount"]/100}
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    def process_refund(self, charge_id: str, amount: Optional[float] = None) -> Dict[str, Any]:
+        """Process refund with safety checks."""
+        if not self.config.enable_refund: return {"success": False, "error": "Refunds disabled"}
+        if not self._check_rate_limit() or not self._check_refund_limit():
+            return {"success": False, "error": "Limit exceeded"}
+        
+        idem_key = self.idempotency.generate_key("refund", charge_id=charge_id, amount=amount)
+        cached = self.idempotency.get_cached(idem_key)
+        if cached: return {**cached, "duplicate_prevented": True}
+        
+        can_attempt, _ = self.circuit_breaker.can_attempt()
+        if not can_attempt: return {"success": False, "error": "Circuit breaker open"}
+        
+        if amount and amount > self.config.max_refund_amount and self.config.require_confirmation:
+            return {"success": False, "error": "Approval required", "requires_approval": True}
+        
+        try:
+            if not self.stripe: raise Exception("Stripe client not configured")
+            refund = self.stripe.refunds_create(charge=charge_id, amount=int(amount*100) if amount else None)
+            self.circuit_breaker.record_success()
+            self.refund_count_hour += 1
+            result = {"success": True, "refund_id": refund["id"], "charge_id": charge_id}
+            self.idempotency.store(idem_key, result)
+            self._log_audit("process_refund", {"charge_id": charge_id}, result)
+            return result
+        except Exception as e:
+            self.circuit_breaker.record_failure()
+            return {"success": False, "error": str(e)}
+
+    def get_tool_definitions(self) -> List[Dict]:
+        """Get MCP tool definitions."""
+        return [
+            {"name": "stripe_get_payment", "description": "Get payment details (READ)"},
+            {"name": "stripe_process_refund", "description": "Process refund (WRITE)"}
+        ]

kite/tools/search.py

@@ -0,0 +1,90 @@
+"""
+Standard Web Search Tool using DuckDuckGo Lite.
+"""
+import requests
+import asyncio
+import re
+import time
+from typing import Dict, Any
+
+class WebSearchTool:
+    """Real web search using DuckDuckGo Lite (No API key required)."""
+    def __init__(self):
+        self.name = "web_search"
+        self.description = "Search the real web for current information. Returns snippets."
+        self.session = requests.Session()
+        self.session.headers.update({
+            "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+        })
+    
+    def get_definition(self):
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string", "description": "Search query"}
+                    },
+                    "required": ["query"]
+                }
+            }
+        }
+        
+    def to_schema(self):
+        return self.get_definition()
+        
+    async def execute(self, query: str = None, **kwargs):
+        if not query:
+            return "Error: Please provide a search query."
+            
+        print(f"      [Tool] Real Web Search for: '{query}'...")
+        await asyncio.sleep(1) # Be polite (Async sleep)
+        
+        try:
+            # DuckDuckGo Lite (HTML version)
+            url = "https://html.duckduckgo.com/html/"
+            data = {'q': query}
+            
+            # Using asyncio toThread for blocking request if needed, but requests is sync.
+            # In a real async framework we might use aiohttp, but here we wrap or accept block for now.
+            # Or use run_in_executor to avoid blocking the loop
+            loop = asyncio.get_running_loop()
+            resp = await loop.run_in_executor(None, lambda: self.session.post(url, data=data, timeout=10))
+            
+            if resp.status_code != 200:
+                return f"Error: Search failed with status {resp.status_code}"
+                
+            # Regex scrape (Simple but effective for DDG Lite)
+            results = []
+            
+            # Extract result blocks (approximate)
+            # Try BS4 if available, else regex
+            try:
+                from bs4 import BeautifulSoup
+                soup = BeautifulSoup(resp.text, 'html.parser')
+                links = soup.find_all('a', class_='result__a', limit=5)
+                for link in links:
+                    title = link.get_text(strip=True)
+                    href = link.get('href')
+                    results.append(f"Title: {title}\nURL: {href}")
+            except ImportError:
+                 # Fallback regex
+                 titles = re.findall(r'class="result__a"[^>]*>(.*?)</a>', resp.text)
+                 for i in range(min(len(titles), 5)):
+                     results.append(f"Title: {titles[i]}")
+            
+            if not results:
+                # Regex fallback if BS4 logic missed or wasn't used
+                titles = re.findall(r'class="result__a"[^>]*>(.*?)</a>', resp.text)
+                for i in range(min(len(titles), 5)):
+                    results.append(f"Title: {titles[i]}")
+
+            output = "\n---\n".join(results[:5])
+            if not output: return "No results found."
+            return output
+
+        except Exception as e:
+            return f"Search error: {e}"

kite/tools/system_tools.py

@@ -0,0 +1,54 @@
+"""
+System & Shell Tools
+===================
+Tools for interacting with the operating system.
+Designed for DevOps agents.
+"""
+
+import subprocess
+import shlex
+from kite.tool import Tool
+
+class ShellTool(Tool):
+    def __init__(self, allowed_commands=None):
+        """
+        Args:
+            allowed_commands: List of allowed command prefixes (e.g. ['ls', 'grep']). 
+                              If None, allows everything (DANGEROUS).
+        """
+        super().__init__(
+            name="shell_execute",
+            func=self.execute,
+            description="Execute a shell command. Use for system inspection, git operations, or file checks."
+        )
+        self.allowed_commands = allowed_commands or ["ls", "cat", "grep", "echo", "git", "pwd", "whoami"]
+
+    async def execute(self, command: str, **kwargs) -> str:
+        """Executes shell command."""
+        cmd_parts = shlex.split(command)
+        if not cmd_parts:
+            return "Empty command."
+            
+        base_cmd = cmd_parts[0]
+        
+        # Security Check
+        if base_cmd not in self.allowed_commands:
+            return f"Security Alert: Command '{base_cmd}' is not allowed. Allowed: {self.allowed_commands}"
+            
+        if "rm" in cmd_parts and "-rf" in cmd_parts:
+             return "Security Alert: 'rm -rf' is strictly forbidden."
+
+        try:
+            result = subprocess.run(
+                command, 
+                shell=True, 
+                capture_output=True, 
+                text=True, 
+                timeout=10
+            )
+            if result.returncode == 0:
+                return result.stdout.strip() or "[Command executed with no output]"
+            else:
+                return f"Error: {result.stderr}"
+        except Exception as e:
+            return f"Execution Failed: {e}"

kite/tools_manager.py

@@ -0,0 +1,27 @@
+"""Tools (MCP Servers) Manager"""
+
+class MCPServers:
+    def __init__(self, config, logger):
+        self.config = config
+        self.logger = logger
+        self._init_servers()
+    
+    def _init_servers(self):
+        """Initialize MCP servers from the tools.mcp package."""
+        from .tools.mcp import (
+            PostgresMCPServer, 
+            SlackMCPServer, 
+            StripeMCPServer,
+            GmailMCPServer, 
+            GDriveMCPServer
+        )
+        
+        self.postgres = PostgresMCPServer(connection_string=self.config.get('postgres_url'))
+        self.slack = SlackMCPServer(bot_token=self.config.get('slack_token'))
+        self.stripe = StripeMCPServer(api_key=self.config.get('stripe_key'))
+        self.gmail = GmailMCPServer(credentials_path=self.config.get('gmail_credentials'))
+        self.gdrive = GDriveMCPServer(credentials_path=self.config.get('gdrive_credentials'))
+        
+        self.logger.info("  [OK] Tools (MCP)")
+
+