traia-iatp 0.1.2__py3-none-any.whl → 0.1.67__py3-none-any.whl

traia_iatp/mcp/templates/server.py.j2

@@ -1,240 +1,217 @@
 #!/usr/bin/env python3
 """
-{{ api_name }} MCP Server{{ auth_description }}
+{{ api_name }} MCP Server - FastMCP with D402 Transport Wrapper
 
-A Model Context Protocol server providing {{ api_description }}
-using the {{ api_name }} API{{ auth_details }}.
+Uses FastMCP from official MCP SDK with D402MCPTransport wrapper for HTTP 402.
+
+Architecture:
+- FastMCP for tool decorators and Context objects
+- D402MCPTransport wraps the /mcp route for HTTP 402 interception
+- Proper HTTP 402 status codes (not JSON-RPC wrapped)
+
+Generated from OpenAPI: {{ docs_url }}
+
+Environment Variables:
+{% if requires_auth %}- {{ api_key_env_var }}: Server's internal API key (for paid requests)
+{% endif %}- SERVER_ADDRESS: Payment address (IATP wallet contract)
+- MCP_OPERATOR_PRIVATE_KEY: Operator signing key
+- D402_TESTING_MODE: Skip facilitator (default: true)
 """
 
-import asyncio
-import logging
 import os
+import logging
 import sys
 from typing import Dict, Any, Optional
 from datetime import datetime
 
-# Third-party imports
 import requests
-from fastmcp import FastMCP, Context
-from fastmcp.server.middleware import Middleware, MiddlewareContext
-from fastmcp.server.dependencies import get_http_request, get_context
-from starlette.requests import Request
-from starlette.responses import JSONResponse
 from retry import retry
-{% if sdk_package %}
-# {{ api_name }} SDK
-# TODO: Adjust the import based on the SDK documentation
-# Common patterns:
-#   - from {{ sdk_module }} import Client
-#   - from {{ sdk_module }} import {{ api_name }}Client  
-#   - import {{ sdk_module }}
-# Check the SDK docs for the correct import statement
-import {{ sdk_module }}
-{% endif %}
+from dotenv import load_dotenv
+import uvicorn
+
+load_dotenv()
 
 # Configure logging
 logging.basicConfig(
-    level=logging.INFO,
+    level=os.getenv("LOG_LEVEL", "INFO").upper(),
     format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
 )
-logger = logging.getLogger('{{ logger_name }}')
+logger = logging.getLogger('{{ api_slug }}_mcp')
 
-# Get stage from environment (useful for different API endpoints)
-STAGE = os.getenv("STAGE", "MAINNET").upper()
+# FastMCP from official SDK
+from mcp.server.fastmcp import FastMCP, Context
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.middleware.cors import CORSMiddleware
 
+# D402 payment protocol - using Starlette middleware
+from traia_iatp.d402.starlette_middleware import D402PaymentMiddleware
+from traia_iatp.d402.mcp_middleware import require_payment_for_tool, get_active_api_key
+from traia_iatp.d402.payment_introspection import extract_payment_configs_from_mcp
+from traia_iatp.d402.types import TokenAmount, TokenAsset, EIP712Domain
+
+# Configuration
+STAGE = os.getenv("STAGE", "MAINNET").upper()
+PORT = int(os.getenv("PORT", "8000"))
+SERVER_ADDRESS = os.getenv("SERVER_ADDRESS")
+if not SERVER_ADDRESS:
+    raise ValueError("SERVER_ADDRESS required for payment protocol")
 
 {% if requires_auth %}
-class AuthMiddleware(Middleware):
-    """Middleware to extract and store API keys from Authorization headers."""
-    
-    async def on_request(self, context: MiddlewareContext, call_next):
-        """Extract bearer token on each request and bind to context state."""
-        try:
-            # Access the raw HTTP request
-            request: Request = get_http_request()
-            
-            # Debug: log all headers
-            logger.info(f"AuthMiddleware: Received request with headers: {dict(request.headers)}")
-            logger.info(f"AuthMiddleware: Method: {request.method}, URL: {request.url}")
-            
-            # Extract bearer token from Authorization header
-            auth = request.headers.get("Authorization", "")
-            token = auth[7:].strip() if auth.lower().startswith("bearer ") else None
-            
-            if not token:
-                # Check X-API-KEY header as alternative
-                token = request.headers.get("X-API-KEY", "")
-            
-            if token:
-                # Store the API key in the context state
-                # This will be accessible in tools via get_context()
-                if hasattr(context, 'state'):
-                    context.state.api_key = token
-                    logger.info(f"API key bound to context state: {token[:10]}...")
-                else:
-                    # Try to store it in the request state as fallback
-                    request.state.api_key = token
-                    logger.info(f"API key bound to request state: {token[:10]}...")
-            else:
-                logger.warning(f"No API key provided in request headers")
-            
-        except Exception as e:
-            # This might happen in non-HTTP transports or if get_http_request fails
-            logger.debug(f"Could not extract API key from request: {e}")
-            
-        # Proceed with the request (authentication check happens in the tools)
-        return await call_next(context)
-
-
-# Initialize FastMCP server with middleware
-mcp = FastMCP("{{ api_name }} MCP Server", middleware=[AuthMiddleware()])
+API_KEY = os.getenv("{{ api_key_env_var }}")
+if not API_KEY:
+    logger.warning(f"⚠️  {{ api_key_env_var }} not set - payment required for all requests")
 {% else %}
-# Initialize FastMCP server
-mcp = FastMCP("{{ api_name }} MCP Server")
+API_KEY = None
 {% endif %}
 
-
-# Add health check endpoint using FastMCP's custom_route
-@mcp.custom_route("/health", methods=["GET"])
-async def health_check(request: Request) -> JSONResponse:
-    """Health check endpoint for container orchestration."""
-    return JSONResponse(
-        content={
-            "status": "healthy",
-            "service": "{{ api_slug }}-mcp-server",
-            "timestamp": datetime.now().isoformat()
-        }
-    )
-
-
+logger.info("="*80)
+logger.info(f"{{ api_name }} MCP Server (FastMCP + D402 Wrapper)")
+logger.info(f"API: {{ api_url }}")
+logger.info(f"Payment: {SERVER_ADDRESS}")
 {% if requires_auth %}
-def get_session_api_key(context: Context) -> Optional[str]:
-    """Get the API key for the current session."""
-    try:
-        # Try to get the API key from the context state
-        # The middleware should have stored it there
-        if hasattr(context, 'state') and hasattr(context.state, 'api_key'):
-            return context.state.api_key
-        
-        # Fallback: try to get it from the current HTTP request
-        try:
-            request: Request = get_http_request()
-            if hasattr(request.state, 'api_key'):
-                return request.state.api_key
-        except Exception:
-            pass
-        
-        # If we're in a tool context, try to get the context using the dependency
-        try:
-            ctx = get_context()
-            if hasattr(ctx, 'state') and hasattr(ctx.state, 'api_key'):
-                return ctx.state.api_key
-        except Exception:
-            pass
-            
-    except Exception as e:
-        logger.debug(f"Could not retrieve API key from context: {e}")
-    
-    return None
+logger.info(f"API Key: {'✅' if API_KEY else '❌ Payment required'}")
 {% endif %}
+logger.info("="*80)
+
+# Create FastMCP server
+mcp = FastMCP("{{ api_name }} MCP Server", host="0.0.0.0")
 
+logger.info(f"✅ FastMCP server created")
 
+# ============================================================================
+# TOOL IMPLEMENTATIONS
+# ============================================================================
+# Tool implementations will be added here by endpoint_implementer_crew
+# Each tool will use the @mcp.tool() and @require_payment_for_tool() decorators
 # TODO: Add your API-specific functions here
-# Use @retry decorator ONLY for external API calls (not internal functions):
-# @retry(tries=2, delay=1, backoff=2, jitter=(1, 3))
-# def call_{{ api_slug }}_api(query: str, api_key: str) -> Dict[str, Any]:
-#     """Call the {{ api_name }} API with the given query."""
-#     # You can use STAGE to determine which API endpoint to use:
-#     # base_url = "https://api-testnet.example.com" if STAGE == "TESTNET" else "https://api.example.com"
-#     # Implement your API logic here (HTTP requests, SDK calls, etc.)
-#     pass
-
-
-@mcp.tool()
-async def example_tool(
-    context: Context,
-    query: str
-) -> Dict[str, Any]:
+
+# ============================================================================
+# APPLICATION SETUP WITH STARLETTE MIDDLEWARE
+# ============================================================================
+
+def create_app_with_middleware():
     """
-    Example tool for {{ api_name }} API.
+    Create Starlette app with d402 payment middleware.
     
-    TODO: Replace this with your actual tool implementation.
-    
-    Args:
-        context: MCP context (injected automatically)
-        query: Query parameter
-        
-    Returns:
-        Dictionary with results
+    Strategy:
+    1. Get FastMCP's Starlette app via streamable_http_app()
+    2. Extract payment configs from @require_payment_for_tool decorators
+    3. Add Starlette middleware with extracted configs
+    4. Single source of truth - no duplication!
     """
-    {% if requires_auth %}
-    # Check for API key
-    api_key = get_session_api_key(context)
-    if not api_key:
-        return {"error": "No API key found. Please authenticate with Authorization: Bearer YOUR_API_KEY"}
-    {% endif %}
+    logger.info("🔧 Creating FastMCP app with middleware...")
     
-    # TODO: Implement your tool logic here
-    return {
-        "status": "success",
-        "message": "This is a placeholder. Implement your {{ api_name }} logic here.",
-        "query": query,
-        "timestamp": datetime.now().isoformat()
-    }
-
-
-@mcp.tool()
-async def get_api_info(context: Context) -> Dict[str, Any]:
-    """
-    Get information about the {{ api_name }} API service.
+    # Get FastMCP's Starlette app
+    app = mcp.streamable_http_app()
+    logger.info(f"✅ Got FastMCP Starlette app")
     
-    Args:
-        context: MCP context (injected automatically)
+    # Extract payment configs from decorators (single source of truth!)
+    tool_payment_configs = extract_payment_configs_from_mcp(mcp, SERVER_ADDRESS)
+    logger.info(f"📊 Extracted {len(tool_payment_configs)} payment configs from @require_payment_for_tool decorators")
     
-    Returns:
-        Dictionary containing API information and status
-    """
+    # D402 Configuration
+    facilitator_url = os.getenv("FACILITATOR_URL") or os.getenv("D402_FACILITATOR_URL")
+    operator_key = os.getenv("MCP_OPERATOR_PRIVATE_KEY")
+    network = os.getenv("NETWORK", "sepolia")
+    testing_mode = os.getenv("D402_TESTING_MODE", "false").lower() == "true"
+    
+    # Log D402 configuration with prominent facilitator info
+    logger.info("="*60)
+    logger.info("D402 Payment Protocol Configuration:")
+    logger.info(f"  Server Address: {SERVER_ADDRESS}")
+    logger.info(f"  Network: {network}")
+    logger.info(f"  Operator Key: {'✅ Set' if operator_key else '❌ Not set'}")
+    logger.info(f"  Testing Mode: {'⚠️  ENABLED (bypasses facilitator)' if testing_mode else '✅ DISABLED (uses facilitator)'}")
+    logger.info("="*60)
+    
+    if not facilitator_url and not testing_mode:
+        logger.error("❌ FACILITATOR_URL required when testing_mode is disabled!")
+        raise ValueError("Set FACILITATOR_URL or enable D402_TESTING_MODE=true")
+    
+    if facilitator_url:
+        logger.info(f"🌐 FACILITATOR: {facilitator_url}")
+        if "localhost" in facilitator_url or "127.0.0.1" in facilitator_url or "host.docker.internal" in facilitator_url:
+            logger.info(f"   📍 Using LOCAL facilitator for development")
+        else:
+            logger.info(f"   🌍 Using REMOTE facilitator for production")
+    else:
+        logger.warning("⚠️  D402 Testing Mode - Facilitator bypassed")
+    logger.info("="*60)
+    
+    # Add CORS middleware first (processes before other middleware)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # Allow all origins
+        allow_credentials=True,
+        allow_methods=["*"],  # Allow all methods
+        allow_headers=["*"],  # Allow all headers
+        expose_headers=["mcp-session-id"],  # Expose custom headers to browser
+    )
+    logger.info("✅ Added CORS middleware (allow all origins, expose mcp-session-id)")
+    
+    # Add D402 payment middleware with extracted configs
+    app.add_middleware(
+        D402PaymentMiddleware,
+        tool_payment_configs=tool_payment_configs,
+        server_address=SERVER_ADDRESS,
+        {% if requires_auth %}
+        requires_auth=True,  # Extracts API keys + checks payment
+        internal_api_key=API_KEY,  # Server's internal key (for Mode 2: paid access)
+        {% else %}
+        requires_auth=False,  # Only checks payment
+        {% endif %}
+        testing_mode=testing_mode,
+        facilitator_url=facilitator_url,
+        facilitator_api_key=os.getenv("D402_FACILITATOR_API_KEY"),
+        server_name="{{ api_slug }}-mcp-server"  # MCP server ID for tracking
+    )
+    logger.info("✅ Added D402PaymentMiddleware")
     {% if requires_auth %}
-    # Check authentication status
-    api_key = get_session_api_key(context)
-    auth_status = "authenticated" if api_key else "not authenticated"
+    logger.info("   - Auth extraction: Enabled")
+    logger.info("   - Dual mode: API key OR payment")
+    {% else %}
+    logger.info("   - Payment-only mode")
     {% endif %}
     
-    return {
-        "status": "ready",
-        {% if requires_auth %}"auth_status": auth_status,{% endif %}
-        "api_name": "{{ api_name }}",
-        "api_url": "{{ api_url }}",
-        "documentation": "{{ docs_url }}",
-        "description": "{{ api_description|capitalize }}",
-        {% if requires_auth %}"authentication": "Bearer token required in Authorization header"{% else %}"authentication": "No authentication required"{% endif %}
-    }
-
-
-def run_server():
-    """Entry point for the executable script"""
-    logger.info("Starting {{ api_name }} MCP server{{ auth_description }}...")
+    # Add health check endpoint (bypasses middleware)
+    @app.route("/health", methods=["GET"])
+    async def health_check(request: Request) -> JSONResponse:
+        """Health check endpoint for container orchestration."""
+        return JSONResponse(
+            content={
+                "status": "healthy",
+                "service": "{{ api_slug }}-mcp-server",
+                "timestamp": datetime.now().isoformat()
+            }
+        )
+    logger.info("✅ Added /health endpoint")
+    
+    return app
+
+if __name__ == "__main__":
+    logger.info("="*80)
+    logger.info(f"Starting {{ api_name }} MCP Server")
+    logger.info("="*80)
+    logger.info("Architecture:")
+    logger.info("  1. D402PaymentMiddleware intercepts requests")
     {% if requires_auth %}
-    logger.info("Authentication: Clients must provide Authorization: Bearer YOUR_API_KEY")
+    logger.info("     - Extracts API keys from Authorization header")
+    logger.info("     - Checks payment → HTTP 402 if no API key AND no payment")
+    {% else %}
+    logger.info("     - Checks payment → HTTP 402 if missing")
     {% endif %}
+    logger.info("  2. FastMCP processes valid requests with tool decorators")
+    logger.info("="*80)
     
-    # Get configuration from environment
-    port = int(os.getenv("PORT", "8000"))
-    log_level = os.getenv("LOG_LEVEL", "INFO")
-    logger.info(f"Server will listen on port {port}")
+    # Create app with middleware
+    app = create_app_with_middleware()
     
-    try:
-        mcp.run(
-            transport="streamable-http",
-            port=port,
-            host="0.0.0.0",
-            path="/mcp",
-            log_level=log_level.lower()
-        )
-    except Exception as e:
-        logger.error(f"Error starting MCP server: {e}")
-        raise
-
+    # Run with uvicorn
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=PORT,
+        log_level=os.getenv("LOG_LEVEL", "info").lower()
+    )
 
-if __name__ == "__main__":
-    run_server()