Add environment configuration and health check for remote deployment

- Introduced .env.example file to outline environment variables for remote deployment.
- Updated Dockerfile to include environment variables and health check for container orchestration.
- Enhanced server.py to support API key retrieval from HTTP headers and added a health check endpoint for remote deployments.
- Updated main function to handle different transport modes for local and remote execution.

Author: Vikrant-Khedkar

.env.example

@@ -0,0 +1,38 @@
+# ScrapeGraph MCP Server Environment Variables
+
+# ===========================================
+# FOR REMOTE DEPLOYMENT (http mode on Render, etc.)
+# ===========================================
+
+# Transport mode: "http" for remote deployment
+MCP_TRANSPORT=http
+
+# Server host - use 0.0.0.0 for Docker/remote
+HOST=0.0.0.0
+
+# Server port - Render automatically sets this via PORT env var
+PORT=8000
+
+# ===========================================
+# FOR USERS CONNECTING TO REMOTE SERVER
+# ===========================================
+# Pass your ScrapeGraph API key via the X-API-Key header using mcp-remote.
+#
+# Example Claude Desktop config:
+# {
+#   "mcpServers": {
+#     "scrapegraph": {
+#       "command": "npx",
+#       "args": [
+#         "-y",
+#         "mcp-remote",
+#         "https://your-server.onrender.com/mcp",
+#         "--header",
+#         "X-API-Key:${SGAI_API_KEY}"
+#       ],
+#       "env": {
+#         "SGAI_API_KEY": "your-api-key-here"
+#       }
+#     }
+#   }
+# }

Dockerfile

@@ -4,7 +4,7 @@ FROM python:3.11-slim
 # Set working directory
 WORKDIR /app
 
-# Set Python unbuffered mode
+# Set Python unbuffered mode for real-time logs
 ENV PYTHONUNBUFFERED=1
 
 # Copy pyproject.toml and README.md first for better caching
@@ -16,13 +16,25 @@ COPY src/ ./src/
 # Install the package and its dependencies from pyproject.toml
 RUN pip install --no-cache-dir .
 
-# Create non-root user
+# Create non-root user for security
 RUN useradd -m -u 1000 mcpuser && \
     chown -R mcpuser:mcpuser /app
 
 # Switch to non-root user
 USER mcpuser
 
+# Environment variables for remote deployment
+# MCP_TRANSPORT: "http" for remote, "stdio" for local (default)
+# PORT: Server port (Render sets this automatically)
+ENV MCP_TRANSPORT=http
+ENV PORT=8000
+
+# Expose the port
+EXPOSE 8000
+
+# Health check for container orchestration
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:${PORT}/health')" || exit 1
+
 # Run the server
 CMD ["python", "-m", "scrapegraph_mcp.server"]
-

render.yaml

@@ -0,0 +1,27 @@
+# Render Blueprint for ScrapeGraph MCP Server
+# Deploy with: https://render.com/deploy
+# Or connect your GitHub repo to Render and it will auto-detect this file
+
+services:
+  - type: web
+    name: scrapegraph-mcp
+    runtime: docker
+    plan: starter  # Change to 'free' for testing, 'starter' or higher for production
+
+    # Docker configuration
+    dockerfilePath: ./Dockerfile
+
+    # Health check endpoint
+    healthCheckPath: /health
+
+    # Auto-deploy on push to main branch
+    autoDeploy: true
+
+    # Environment variables
+    envVars:
+      # Transport mode (http for remote deployment)
+      - key: MCP_TRANSPORT
+        value: http
+
+      # Note: SGAI_API_KEY is NOT set here.
+      # Each user passes their own API key via mcp-remote from their local environment.

src/scrapegraph_mcp/server.py

@@ -395,74 +395,59 @@ class ConfigSchema(BaseModel):
 
 def get_api_key(ctx: Context) -> str:
     """
-    Get the API key from config or environment variable.
-    
+    Get the API key from HTTP header or MCP session config.
+
+    Supports two modes:
+    - HTTP mode (Render): API key from 'X-API-Key' header via mcp-remote
+    - Stdio mode (Smithery): API key from session_config.scrapegraph_api_key
+
     Args:
         ctx: FastMCP context
-        
+
     Returns:
         API key string
-        
+
     Raises:
         ValueError: If no API key is found
     """
+    from fastmcp.server.dependencies import get_http_headers
+
+    # Try HTTP header first (for remote/Render deployments)
     try:
-        logger.info(f"Getting API key. Context type: {type(ctx)}")
-        logger.info(f"Context has session_config: {hasattr(ctx, 'session_config')}")
-        
-        # Try to get from config first, but handle cases where session_config might be None
-        api_key = None
-        if hasattr(ctx, 'session_config') and ctx.session_config is not None:
-            logger.info(f"Session config type: {type(ctx.session_config)}")
-            api_key = getattr(ctx.session_config, 'scrapegraph_api_key', None)
-            logger.info(f"API key from config: {'***' if api_key else 'None'}")
-        else:
-            logger.info("No session_config available or session_config is None")
-        
-        # If not in config, try environment variable
-        if not api_key:
-            api_key = os.getenv('SGAI_API_KEY')
-            logger.info(f"API key from env: {'***' if api_key else 'None'}")
-
-        # If still no API key found, raise error
-        if not api_key:
-            logger.error("No API key found in config or environment")
-            raise ValueError(
-                "ScapeGraph API key is required. Please provide it either:\n"
-                "1. In the MCP server configuration as 'scrapegraph_api_key'\n"
-                "2. As an environment variable 'SGAI_API_KEY'"
-            )
-        
-        logger.info("API key successfully retrieved")
-        return api_key
-    
-    except Exception as e:
-        logger.warning(f"Error getting API key from context: {e}. Falling back to cached method.")
-        # Fallback to cached method if context handling fails
-        return get_cached_api_key()
+        headers = get_http_headers()
+        api_key = headers.get('x-api-key')
+        if api_key:
+            logger.info("API key retrieved from X-API-Key header")
+            return api_key
+    except LookupError:
+        # Not in HTTP context, try session config (Smithery/stdio mode)
+        pass
+
+    # Try session config (for Smithery/stdio deployments)
+    if hasattr(ctx, 'session_config') and ctx.session_config is not None:
+        api_key = getattr(ctx.session_config, 'scrapegraph_api_key', None)
+        if api_key:
+            logger.info("API key retrieved from session config")
+            return api_key
+
+    logger.error("No API key found in header or session config")
+    raise ValueError(
+        "ScapeGraph API key is required. Please provide it via:\n"
+        "- HTTP header 'X-API-Key' (for remote server via mcp-remote)\n"
+        "- MCP config 'scrapegraphApiKey' (for Smithery/local stdio)"
+    )
 
 
 # Create MCP server instance
 mcp = FastMCP("ScapeGraph API MCP Server")
 
-# Global API key cache to handle session issues
-_api_key_cache: Optional[str] = None
 
-def get_cached_api_key() -> str:
-    """Get API key from cache or environment, bypassing session config issues."""
-    global _api_key_cache
-    
-    if _api_key_cache is None:
-        _api_key_cache = os.getenv('SGAI_API_KEY')
-        if _api_key_cache:
-            logger.info("API key loaded from environment variable")
-        else:
-            logger.error("No API key found in environment variable SGAI_API_KEY")
-            raise ValueError(
-                "ScapeGraph API key is required. Please set the SGAI_API_KEY environment variable."
-            )
-    
-    return _api_key_cache
+# Health check endpoint for remote deployments (Render, etc.)
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request):
+    """Health check endpoint for container orchestration and load balancers."""
+    from starlette.responses import JSONResponse
+    return JSONResponse({"status": "healthy", "service": "scrapegraph-mcp"})
 
 
 # Add prompts to help users interact with the server
@@ -2298,13 +2283,30 @@ def create_server() -> FastMCP:
 
 
 def main() -> None:
-    """Run the ScapeGraph MCP server."""
+    """Run the ScapeGraph MCP server.
+
+    Supports two transport modes:
+    - stdio (default): For local use with Claude Desktop, Cursor, etc.
+    - http: For remote deployment on Render, Koyeb, etc.
+
+    Set MCP_TRANSPORT=http environment variable for remote deployment.
+    """
+    transport = os.getenv("MCP_TRANSPORT", "stdio").lower()
+
     try:
-        # Verify we're running from local codebase
-        server_path = os.path.abspath(__file__)
-        logger.info(f"Starting ScapeGraph MCP server from local codebase: {server_path}")
-        print(f"Starting ScapeGraph MCP server (local codebase)")
-        mcp.run(transport="stdio")
+        if transport == "http":
+            # Remote deployment mode (Render, Koyeb, etc.)
+            host = os.getenv("HOST", "0.0.0.0")
+            port = int(os.getenv("PORT", "8000"))
+            logger.info(f"Starting ScapeGraph MCP server in HTTP mode on {host}:{port}")
+            print(f"Starting ScapeGraph MCP server in HTTP mode on {host}:{port}")
+            mcp.run(transport="http", host=host, port=port)
+        else:
+            # Local stdio mode (Claude Desktop, Cursor, etc.)
+            server_path = os.path.abspath(__file__)
+            logger.info(f"Starting ScapeGraph MCP server from local codebase: {server_path}")
+            print("Starting ScapeGraph MCP server (local codebase)")
+            mcp.run(transport="stdio")
     except Exception as e:
         logger.error(f"Failed to start MCP server: {e}")
         print(f"Error starting server: {e}")