mcp-web-engine 1.0.4__py3-none-any.whl

mcp_web_engine/__init__.py

@@ -0,0 +1,3 @@
+"""MCP Web Engine package."""
+
+__version__ = "1.0.4"

mcp_web_engine/config.py

@@ -0,0 +1,24 @@
+"""
+Centralized Configuration Module (Pydantic Settings / Environment Variables)
+"""
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    API_KEY: str = Field(default="sk_mcp_dev_key_12345", description="Bearer API key for authentication")
+    SEARXNG_URL: str = Field(default="http://127.0.0.1:8082/search", description="Internal SearXNG URL")
+    PORT: int = Field(default=5050, description="Service listening port")
+    HOST: str = Field(default="0.0.0.0", description="Service listening host")
+    
+    # Rate Limiting & Limits
+    RATE_LIMIT_PER_MINUTE: int = Field(default=120, description="Max requests per minute per API key")
+    DEFAULT_TIMEOUT_SEC: float = Field(default=10.0, description="Default HTTP request timeout in seconds")
+    MAX_PAYLOAD_BYTES: int = Field(default=2 * 1024 * 1024, description="Max payload size limit (2 MB)")
+    
+    # Environment & Logging
+    ENV: str = Field(default="production", description="Environment (development/production)")
+    LOG_LEVEL: str = Field(default="INFO", description="Log level")
+
+settings = Settings()

mcp_web_engine/logging_obs.py

@@ -0,0 +1,111 @@
+"""
+Structured JSON Logging & Observability Metrics Module with Per-Beta-Key Telemetry Tracking
+"""
+import logging
+import json
+import time
+import os
+from typing import Optional
+from datetime import datetime
+from .config import settings
+
+BETA_KEYS_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "beta_keys.json")
+
+class JSONFormatter(logging.Formatter):
+    def format(self, record):
+        log_obj = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "level": record.levelname,
+            "module": record.module,
+            "message": record.getMessage()
+        }
+        if hasattr(record, "extra_data"):
+            log_obj["extra"] = self.sanitize_data(record.extra_data)
+        return json.dumps(log_obj)
+
+    def sanitize_data(self, data):
+        if isinstance(data, dict):
+            clean = {}
+            for k, v in data.items():
+                if "key" in k.lower() or "token" in k.lower() or "secret" in k.lower() or "auth" in k.lower():
+                    clean[k] = "REDACTED"
+                else:
+                    clean[k] = self.sanitize_data(v)
+            return clean
+        elif isinstance(data, list):
+            return [self.sanitize_data(i) for i in data]
+        return data
+
+logger = logging.getLogger("mcp_web_engine")
+logger.setLevel(getattr(logging, settings.LOG_LEVEL.upper(), logging.INFO))
+handler = logging.StreamHandler()
+handler.setFormatter(JSONFormatter())
+logger.addHandler(handler)
+
+# In-memory Metrics Store
+class MetricsTracker:
+    def __init__(self):
+        self.total_requests = 0
+        self.total_errors = 0
+        self.tool_calls = {"web_search": 0, "fetch_url": 0, "extract_markdown": 0}
+        self.total_units_consumed = 0
+        self.latencies_ms = []
+
+    def record(self, tool_name: str, latency_ms: float, success: bool, units: int = 1, api_key: Optional[str] = None):
+        self.total_requests += 1
+        if tool_name in self.tool_calls:
+            self.tool_calls[tool_name] += 1
+        if not success:
+            self.total_errors += 1
+        self.total_units_consumed += units
+        self.latencies_ms.append(latency_ms)
+        if len(self.latencies_ms) > 1000:
+            self.latencies_ms = self.latencies_ms[-1000:]
+
+        if api_key and api_key.startswith("sk_mcp_beta_"):
+            self.update_beta_telemetry(api_key, tool_name, latency_ms, success)
+
+    def update_beta_telemetry(self, api_key: str, tool_name: str, latency_ms: float, success: bool):
+        if not os.path.exists(BETA_KEYS_FILE):
+            return
+        try:
+            with open(BETA_KEYS_FILE, "r", encoding="utf-8") as f:
+                keys = json.load(f)
+
+            if api_key in keys:
+                t = keys[api_key].setdefault("telemetry", {
+                    "requests": 0,
+                    "web_search": 0,
+                    "fetch_url": 0,
+                    "extract_markdown": 0,
+                    "errors": 0,
+                    "avg_latency_ms": 0.0,
+                    "last_seen": None
+                })
+                t["requests"] += 1
+                if tool_name in t:
+                    t[tool_name] += 1
+                if not success:
+                    t["errors"] += 1
+
+                old_avg = t.get("avg_latency_ms", 0.0)
+                n = t["requests"]
+                t["avg_latency_ms"] = round(((old_avg * (n - 1)) + latency_ms) / n, 2)
+                t["last_seen"] = datetime.utcnow().isoformat() + "Z"
+
+                with open(BETA_KEYS_FILE, "w", encoding="utf-8") as f:
+                    json.dump(keys, f, indent=2)
+        except Exception as e:
+            logger.error(f"Failed to update beta telemetry: {str(e)}")
+
+    def get_summary(self):
+        avg_lat = round(sum(self.latencies_ms) / len(self.latencies_ms), 2) if self.latencies_ms else 0.0
+        return {
+            "total_requests": self.total_requests,
+            "total_errors": self.total_errors,
+            "tool_calls": self.tool_calls,
+            "total_units_consumed": self.total_units_consumed,
+            "avg_latency_ms": avg_lat
+        }
+
+metrics = MetricsTracker()

mcp_web_engine/main.py

@@ -0,0 +1,237 @@
+"""
+Main FastAPI Application Gateway & MCP Protocol Handler (SSE & STDIO Modes)
+"""
+import time
+import json
+import os
+import sys
+import asyncio
+from fastapi import FastAPI, Depends, HTTPException, status, Response, Request, Header
+from typing import Optional
+from sse_starlette.sse import EventSourceResponse
+from .config import settings
+from .security import verify_api_key, check_rate_limit
+from .logging_obs import logger, metrics
+from .mcp_tools import MCP_TOOL_DEFINITIONS, handle_mcp_tool_call, WebSearchInput, FetchUrlInput, ExtractMarkdownInput
+from .mcp_protocol import (
+    process_mcp_2026_stateless,
+    process_mcp_2025_legacy_stateful,
+    validate_2026_mcp_headers,
+    MCP_PROTOCOL_VERSION_2026,
+    MCP_PROTOCOL_VERSION_LEGACY
+)
+from .web_engine import execute_web_search, execute_fetch_url, execute_extract_markdown
+
+BETA_KEYS_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "beta_keys.json")
+
+app = FastAPI(
+    title="MCP Web Engine & Search Gateway",
+    description="High-performance, SSRF-hardened MCP Server (Spec 2026-07-28 Pure Stateless Core & Legacy 2025-11-25)",
+    version="1.0.4"
+)
+
+@app.get("/health")
+async def health_check():
+    return {
+        "status": "ok",
+        "environment": settings.ENV,
+        "searxng_url": settings.SEARXNG_URL,
+        "mcp_version": MCP_PROTOCOL_VERSION_2026
+    }
+
+@app.get("/v1/metrics")
+async def get_metrics(api_key: str = Depends(verify_api_key)):
+    return metrics.get_summary()
+
+@app.get("/v1/beta/telemetry")
+async def get_beta_telemetry(api_key: str = Depends(verify_api_key)):
+    if not os.path.exists(BETA_KEYS_FILE):
+        return {"users_count": 0, "telemetry": {}}
+    try:
+        with open(BETA_KEYS_FILE, "r", encoding="utf-8") as f:
+            keys = json.load(f)
+        
+        summary = {}
+        for k, v in keys.items():
+            beta_id = v.get("id", "Unknown")
+            summary[beta_id] = {
+                "id": beta_id,
+                "status": v.get("status"),
+                "limit": v.get("limit"),
+                "telemetry": v.get("telemetry", {})
+            }
+        return {"users_count": len(summary), "telemetry": summary}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+# OFFICIAL MCP 2026-07-28 STATELESS CORE ENDPOINT (POST /v1/mcp)
+@app.post("/v1/mcp")
+async def mcp_2026_stateless_endpoint(
+    request: Request,
+    api_key: str = Depends(verify_api_key),
+    mcp_protocol_version: Optional[str] = Header(None, alias="MCP-Protocol-Version"),
+    mcp_method: Optional[str] = Header(None, alias="Mcp-Method"),
+    mcp_name: Optional[str] = Header(None, alias="Mcp-Name")
+):
+    check_rate_limit(api_key)
+    try:
+        payload = await request.json()
+    except Exception:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "INVALID_JSON", "message": "Request body must be valid JSON-RPC 2.0."}
+        )
+
+    validate_2026_mcp_headers(mcp_protocol_version, mcp_method, mcp_name, payload)
+
+    res_body, http_status = await process_mcp_2026_stateless(payload, api_key=api_key)
+    
+    headers = {
+        "MCP-Protocol-Version": MCP_PROTOCOL_VERSION_2026,
+        "Mcp-Method": mcp_method,
+        "Content-Type": "application/json"
+    }
+    if mcp_name:
+        headers["Mcp-Name"] = mcp_name
+    
+    return Response(
+        content=json.dumps(res_body, ensure_ascii=False) if res_body else "",
+        status_code=http_status,
+        headers=headers
+    )
+
+# UNCHANGED LEGACY 2025-11-25 STATEFUL ENDPOINT (POST /v1/mcp/legacy)
+@app.post("/v1/mcp/legacy")
+async def mcp_2025_legacy_endpoint(
+    request: Request,
+    api_key: str = Depends(verify_api_key),
+    mcp_session_id: Optional[str] = Header(None, alias="Mcp-Session-Id")
+):
+    check_rate_limit(api_key)
+    try:
+        payload = await request.json()
+    except Exception:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "INVALID_JSON", "message": "Request body must be valid JSON-RPC 2.0."}
+        )
+
+    res_body, http_status, out_session_id = await process_mcp_2025_legacy_stateful(payload, mcp_session_id)
+    
+    headers = {
+        "MCP-Protocol-Version": MCP_PROTOCOL_VERSION_LEGACY,
+        "Mcp-Session-Id": out_session_id,
+        "Content-Type": "application/json"
+    }
+    
+    return Response(
+        content=json.dumps(res_body, ensure_ascii=False) if res_body else "",
+        status_code=http_status,
+        headers=headers
+    )
+
+# SSE Event Endpoint
+@app.get("/v1/mcp")
+async def mcp_sse_endpoint(
+    request: Request,
+    api_key: str = Depends(verify_api_key)
+):
+    check_rate_limit(api_key)
+
+    async def event_generator():
+        yield {
+            "event": "endpoint",
+            "data": "/v1/mcp"
+        }
+
+    return EventSourceResponse(event_generator())
+
+# Legacy REST Tool Listing Endpoint (Compatibility)
+@app.post("/v1/mcp/tools")
+async def list_mcp_tools(api_key: str = Depends(verify_api_key)):
+    check_rate_limit(api_key)
+    return {"tools": MCP_TOOL_DEFINITIONS}
+
+# Legacy REST Tool Invocation Endpoint (Compatibility)
+@app.post("/v1/mcp/invoke")
+async def invoke_mcp_tool(payload: dict, api_key: str = Depends(verify_api_key)):
+    check_rate_limit(api_key)
+    tool_name = payload.get("tool")
+    arguments = payload.get("arguments", {})
+
+    if not tool_name:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "MISSING_TOOL", "message": "Payload must include 'tool' parameter."}
+        )
+
+    start_t = time.time()
+    try:
+        res = await handle_mcp_tool_call(tool_name, arguments)
+        lat = round((time.time() - start_t) * 1000, 2)
+        metrics.record(tool_name, lat, success=True, api_key=api_key)
+        return {"tool": tool_name, "status": "success", "result": res}
+    except HTTPException as e:
+        lat = round((time.time() - start_t) * 1000, 2)
+        metrics.record(tool_name, lat, success=False, api_key=api_key)
+        raise e
+    except Exception as e:
+        lat = round((time.time() - start_t) * 1000, 2)
+        metrics.record(tool_name, lat, success=False, api_key=api_key)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={"error": "TOOL_EXECUTION_ERROR", "message": str(e)}
+        )
+
+# Direct REST Endpoints
+@app.post("/v1/search")
+async def search_endpoint(body: WebSearchInput, api_key: str = Depends(verify_api_key)):
+    check_rate_limit(api_key)
+    return await execute_web_search(body.query, body.limit)
+
+@app.post("/v1/extract")
+async def extract_endpoint(body: ExtractMarkdownInput, api_key: str = Depends(verify_api_key)):
+    check_rate_limit(api_key)
+    return await execute_extract_markdown(body.url, body.max_bytes)
+
+async def run_mcp_stdio_server():
+    """
+    Robust Stdio MCP protocol handler using asyncio.to_thread for cross-platform compatibility
+    (Works on Linux RPi5, x86_64, Windows, macOS without epoll PermissionError)
+    """
+    while True:
+        line_str = await asyncio.to_thread(sys.stdin.readline)
+        if not line_str:
+            break
+        line_str = line_str.strip()
+        if not line_str:
+            continue
+        try:
+            payload = json.loads(line_str)
+            res_body, _ = await process_mcp_2026_stateless(payload, api_key="local-stdio")
+            if res_body:
+                sys.stdout.write(json.dumps(res_body, ensure_ascii=False) + "\n")
+                sys.stdout.flush()
+        except Exception as e:
+            err_res = {
+                "jsonrpc": "2.0",
+                "id": None,
+                "error": {"code": -32603, "message": str(e)}
+            }
+            sys.stdout.write(json.dumps(err_res) + "\n")
+            sys.stdout.flush()
+
+def cli_entrypoint():
+    """
+    Console script entrypoint for PyPI / uvx (mcp-web-engine).
+    Runs Stdio MCP mode by default; runs FastAPI HTTP server if --serve is passed.
+    """
+    is_serve = "--serve" in sys.argv or "--sse" in sys.argv
+    if is_serve:
+        import uvicorn
+        uvicorn.run("mcp_web_engine.main:app", host=settings.HOST, port=settings.PORT, reload=False)
+    else:
+        asyncio.run(run_mcp_stdio_server())
+
+if __name__ == "__main__":
+    cli_entrypoint()

mcp_web_engine/manage_beta_keys.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+Beta Keys & Telemetry Management CLI for MCP Web Engine
+Genera 20 keys independientes (Beta_001 .. Beta_020), lista y gestiona telemetría por usuario en beta_keys.json.
+"""
+import sys
+import os
+import json
+import secrets
+import time
+import argparse
+
+KEYS_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "beta_keys.json")
+
+def load_keys():
+    if not os.path.exists(KEYS_FILE):
+        return {}
+    try:
+        with open(KEYS_FILE, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+def save_keys(keys):
+    with open(KEYS_FILE, "w", encoding="utf-8") as f:
+        json.dump(keys, f, indent=2)
+
+def generate_20_beta_keys():
+    keys = {}
+    generated_summary = []
+
+    for i in range(1, 21):
+        beta_id = f"Beta_{i:03d}"
+        raw_token = secrets.token_hex(16)
+        key_str = f"sk_mcp_beta_{raw_token}"
+
+        keys[key_str] = {
+            "id": beta_id,
+            "key": key_str,
+            "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "limit": 10000,
+            "rate_limit": 120,
+            "status": "active",
+            "telemetry": {
+                "requests": 0,
+                "web_search": 0,
+                "fetch_url": 0,
+                "extract_markdown": 0,
+                "errors": 0,
+                "avg_latency_ms": 0.0,
+                "last_seen": None
+            }
+        }
+        generated_summary.append((beta_id, key_str))
+
+    save_keys(keys)
+    print(f"✅ Generadas 20 Beta Keys independientes (Beta_001 .. Beta_020) en: {KEYS_FILE}")
+    for beta_id, key_str in generated_summary:
+        print(f"  - {beta_id:10s}: {key_str}")
+    return keys
+
+def list_beta_telemetry():
+    keys = load_keys()
+    if not keys:
+        print("ℹ️ No hay Beta Keys registradas.")
+        return
+
+    print("📊 DASHBOARD DE TELEMETRÍA POR USUARIO BETA:")
+    print("=" * 85)
+    print(f"{'ID Beta':10s} | {'Estado':8s} | {'Reqs':6s} | {'Search':6s} | {'Fetch':6s} | {'Extract':8s} | {'Errors':6s} | {'Last Seen'}")
+    print("=" * 85)
+    
+    total_reqs = 0
+    total_errs = 0
+    
+    for k, info in keys.items():
+        t = info.get("telemetry", {})
+        reqs = t.get("requests", 0)
+        errs = t.get("errors", 0)
+        total_reqs += reqs
+        total_errs += errs
+        
+        last_seen = t.get("last_seen") or "Nunca"
+        print(f"{info['id']:10s} | {info['status']:8s} | {reqs:6d} | {t.get('web_search', 0):6d} | {t.get('fetch_url', 0):6d} | {t.get('extract_markdown', 0):8d} | {errs:6d} | {last_seen}")
+
+    print("=" * 85)
+    print(f"📈 TOTALES: {len(keys)} Usuarios Beta | {total_reqs} Peticiones Totales | {total_errs} Errores Totales")
+
+def revoke_key_by_id(beta_id):
+    keys = load_keys()
+    found = False
+    for k, info in keys.items():
+        if info.get("id") == beta_id or k == beta_id:
+            info["status"] = "revoked"
+            found = True
+            print(f"🔴 Beta Key '{beta_id}' revocada con éxito.")
+            break
+    if found:
+        save_keys(keys)
+    else:
+        print(f"❌ Beta Key '{beta_id}' no encontrada.")
+
+def main():
+    parser = argparse.ArgumentParser(description="Beta Keys & Telemetry Manager")
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("init20", help="Genera las 20 keys de Beta_001 a Beta_020")
+    subparsers.add_parser("telemetry", help="Muestra la telemetría por usuario beta")
+    
+    rev_parser = subparsers.add_parser("revoke", help="Revoca una beta key por ID o token")
+    rev_parser.add_argument("--id", type=str, required=True, help="ID Beta (ej: Beta_001)")
+
+    args = parser.parse_args()
+
+    if args.command == "init20":
+        generate_20_beta_keys()
+    elif args.command == "telemetry":
+        list_beta_telemetry()
+    elif args.command == "revoke":
+        revoke_key_by_id(args.id)
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

mcp_web_engine/mcp_protocol.py

@@ -0,0 +1,210 @@
+"""
+MCP Protocol Handler (Spec 2026-07-28 Pure Stateless Core with Header Validation & Per-User Telemetry)
+"""
+import json
+import time
+import secrets
+from typing import Optional
+from fastapi import status, HTTPException
+from .mcp_tools import MCP_TOOL_DEFINITIONS, handle_mcp_tool_call
+from .logging_obs import logger, metrics
+
+MCP_PROTOCOL_VERSION_2026 = "2026-07-28"
+MCP_PROTOCOL_VERSION_LEGACY = "2025-11-25"
+
+REGISTERED_TOOL_NAMES = {t["name"] for t in MCP_TOOL_DEFINITIONS}
+VALID_2026_METHODS = {"server/discover", "tools/list", "tools/call"}
+
+legacy_sessions = {}
+
+# JSON-RPC 2.0 Error Codes
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+def make_jsonrpc_response(request_id, result):
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "result": result
+    }
+
+def make_jsonrpc_error(request_id, code, message, data=None):
+    err_obj = {"code": code, "message": message}
+    if data:
+        err_obj["data"] = data
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": err_obj
+    }
+
+def validate_2026_mcp_headers(
+    header_mcp_version: Optional[str],
+    header_mcp_method: Optional[str],
+    header_mcp_name: Optional[str],
+    payload: dict
+):
+    if header_mcp_version and header_mcp_version != MCP_PROTOCOL_VERSION_2026:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "INVALID_PROTOCOL_VERSION", "message": f"Expected 'MCP-Protocol-Version: {MCP_PROTOCOL_VERSION_2026}'."}
+        )
+
+    if not header_mcp_method:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "MISSING_MCP_METHOD", "message": "Header 'Mcp-Method' is required."}
+        )
+
+    clean_method = header_mcp_method.strip()
+    if clean_method not in VALID_2026_METHODS:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "INVALID_MCP_METHOD", "message": f"Method '{clean_method}' is not a valid MCP 2026-07-28 method."}
+        )
+
+    body_method = payload.get("method")
+    if clean_method != body_method:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "MISMATCHED_MCP_METHOD", "message": f"Header Mcp-Method '{clean_method}' does not match body method '{body_method}'."}
+        )
+
+    if clean_method == "tools/call":
+        if not header_mcp_name:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail={"error": "MISSING_MCP_NAME", "message": "Header 'Mcp-Name' is required for method 'tools/call'."}
+            )
+
+        clean_name = header_mcp_name.strip()
+        if clean_name not in REGISTERED_TOOL_NAMES:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail={"error": "INVALID_MCP_NAME", "message": f"Tool '{clean_name}' is not registered."}
+            )
+
+        body_tool_name = payload.get("params", {}).get("name")
+        if clean_name != body_tool_name:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail={"error": "MISMATCHED_MCP_NAME", "message": f"Header Mcp-Name '{clean_name}' does not match body params.name '{body_tool_name}'."}
+            )
+
+async def process_mcp_2026_stateless(payload: dict, api_key: Optional[str] = None) -> tuple[dict, int]:
+    if not isinstance(payload, dict) or payload.get("jsonrpc") != "2.0":
+        return make_jsonrpc_error(payload.get("id") if isinstance(payload, dict) else None, INVALID_REQUEST, "Invalid JSON-RPC 2.0 request."), status.HTTP_400_BAD_REQUEST
+
+    request_id = payload.get("id")
+    method = payload.get("method")
+    params = payload.get("params", {})
+
+    if method == "server/discover":
+        res_data = {
+            "protocolVersion": MCP_PROTOCOL_VERSION_2026,
+            "server": {
+                "name": "mcp-web-engine",
+                "version": "1.0.4"
+            },
+            "capabilities": {
+                "tools": True
+            }
+        }
+        return make_jsonrpc_response(request_id, res_data), status.HTTP_200_OK
+
+    elif method == "tools/list":
+        res_data = {
+            "tools": MCP_TOOL_DEFINITIONS,
+            "cacheScope": "global",
+            "ttlMs": 3600000,
+            "listChanged": False
+        }
+        return make_jsonrpc_response(request_id, res_data), status.HTTP_200_OK
+
+    elif method == "tools/call":
+        tool_name = params.get("name")
+        arguments = params.get("arguments", {})
+
+        if not tool_name:
+            return make_jsonrpc_error(request_id, INVALID_PARAMS, "Missing tool 'name' in params."), status.HTTP_400_BAD_REQUEST
+
+        start_t = time.time()
+        try:
+            raw_result = await handle_mcp_tool_call(tool_name, arguments)
+            lat = round((time.time() - start_t) * 1000, 2)
+            metrics.record(tool_name, lat, success=True, api_key=api_key)
+
+            content_text = json.dumps(raw_result, indent=2, ensure_ascii=False)
+            mcp_result = {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": content_text
+                    }
+                ],
+                "isError": False
+            }
+            return make_jsonrpc_response(request_id, mcp_result), status.HTTP_200_OK
+
+        except Exception as e:
+            lat = round((time.time() - start_t) * 1000, 2)
+            metrics.record(tool_name, lat, success=False, api_key=api_key)
+            logger.error(f"Error executing MCP tool '{tool_name}': {str(e)}")
+
+            error_content = {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Error executing tool '{tool_name}': {str(e)}"
+                    }
+                ],
+                "isError": True
+            }
+            return make_jsonrpc_response(request_id, error_content), status.HTTP_200_OK
+
+    else:
+        return make_jsonrpc_error(request_id, METHOD_NOT_FOUND, f"Method '{method}' not supported in MCP 2026-07-28 stateless core."), status.HTTP_404_NOT_FOUND
+
+async def process_mcp_2025_legacy_stateful(payload: dict, session_id: Optional[str] = None) -> tuple[dict, int, str]:
+    if session_id and session_id in legacy_sessions:
+        current_sess_id = session_id
+    else:
+        current_sess_id = f"mcp_sess_legacy_{secrets.token_hex(8)}"
+        legacy_sessions[current_sess_id] = {"created": time.time()}
+
+    if not isinstance(payload, dict) or payload.get("jsonrpc") != "2.0":
+        return make_jsonrpc_error(payload.get("id") if isinstance(payload, dict) else None, INVALID_REQUEST, "Invalid JSON-RPC 2.0 request."), status.HTTP_400_BAD_REQUEST, current_sess_id
+
+    request_id = payload.get("id")
+    method = payload.get("method")
+    params = payload.get("params", {})
+
+    if method == "initialize":
+        res_data = {
+            "protocolVersion": MCP_PROTOCOL_VERSION_LEGACY,
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": {"name": "mcp-web-engine-legacy", "version": "1.0.0"}
+        }
+        return make_jsonrpc_response(request_id, res_data), status.HTTP_200_OK, current_sess_id
+
+    elif method == "notifications/initialized":
+        return {}, status.HTTP_202_ACCEPTED, current_sess_id
+
+    elif method == "tools/list":
+        return make_jsonrpc_response(request_id, {"tools": MCP_TOOL_DEFINITIONS}), status.HTTP_200_OK, current_sess_id
+
+    elif method == "tools/call":
+        tool_name = params.get("name")
+        arguments = params.get("arguments", {})
+        try:
+            raw_result = await handle_mcp_tool_call(tool_name, arguments)
+            mcp_result = {"content": [{"type": "text", "text": json.dumps(raw_result)}], "isError": False}
+            return make_jsonrpc_response(request_id, mcp_result), status.HTTP_200_OK, current_sess_id
+        except Exception as e:
+            return make_jsonrpc_response(request_id, {"content": [{"type": "text", "text": str(e)}], "isError": True}), status.HTTP_200_OK, current_sess_id
+
+    else:
+        return make_jsonrpc_error(request_id, METHOD_NOT_FOUND, f"Method '{method}' not found."), status.HTTP_404_NOT_FOUND, current_sess_id

mcp_web_engine/mcp_tools.py

@@ -0,0 +1,50 @@
+"""
+MCP Tools Definition & Schema Handlers (web_search, fetch_url, extract_markdown)
+"""
+from typing import Optional
+from pydantic import BaseModel, Field
+from .web_engine import execute_web_search, execute_fetch_url, execute_extract_markdown
+
+class WebSearchInput(BaseModel):
+    query: str = Field(..., description="The search query keywords", min_length=2)
+    limit: Optional[int] = Field(default=10, description="Max results to return (1-25)", ge=1, le=25)
+
+class FetchUrlInput(BaseModel):
+    url: str = Field(..., description="Target URL to fetch content from")
+    max_bytes: Optional[int] = Field(default=None, description="Max bytes payload limit")
+
+class ExtractMarkdownInput(BaseModel):
+    url: str = Field(..., description="Target URL to convert to clean Markdown")
+    max_bytes: Optional[int] = Field(default=None, description="Max bytes payload limit")
+
+# MCP Protocol Tool Definitions
+MCP_TOOL_DEFINITIONS = [
+    {
+        "name": "web_search",
+        "description": "Performs aggregate multi-engine web search returning structured search results.",
+        "inputSchema": WebSearchInput.model_json_schema()
+    },
+    {
+        "name": "fetch_url",
+        "description": "Fetches raw text content of a web page after SSRF security checks.",
+        "inputSchema": FetchUrlInput.model_json_schema()
+    },
+    {
+        "name": "extract_markdown",
+        "description": "Scrapes a web page and converts HTML into clean, structured Markdown for LLMs.",
+        "inputSchema": ExtractMarkdownInput.model_json_schema()
+    }
+]
+
+async def handle_mcp_tool_call(tool_name: str, arguments: dict):
+    if tool_name == "web_search":
+        parsed = WebSearchInput(**arguments)
+        return await execute_web_search(parsed.query, parsed.limit)
+    elif tool_name == "fetch_url":
+        parsed = FetchUrlInput(**arguments)
+        return await execute_fetch_url(parsed.url, parsed.max_bytes)
+    elif tool_name == "extract_markdown":
+        parsed = ExtractMarkdownInput(**arguments)
+        return await execute_extract_markdown(parsed.url, parsed.max_bytes)
+    else:
+        raise ValueError(f"Unknown tool name '{tool_name}'")

mcp_web_engine/security.py

@@ -0,0 +1,169 @@
+"""
+Hardened Security Module: SSRF Protection, IP/DNS Validation, Multi-Key Auth (Master & Beta Keys) & Rate Limiting
+"""
+import ipaddress
+import socket
+import time
+import os
+import json
+import urllib.parse
+from fastapi import HTTPException, Security, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from .config import settings
+
+security_bearer = HTTPBearer(auto_error=False)
+
+rate_limit_records = {}
+BETA_KEYS_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "beta_keys.json")
+
+def is_beta_key_valid(token: str) -> bool:
+    """
+    Checks if a token is an active Beta Key in beta_keys.json.
+    """
+    if not os.path.exists(BETA_KEYS_FILE):
+        return False
+    try:
+        with open(BETA_KEYS_FILE, "r", encoding="utf-8") as f:
+            keys = json.load(f)
+            if token in keys and keys[token].get("status") == "active":
+                return True
+    except Exception:
+        pass
+    return False
+
+# Reserved Subnets for SSRF Protection
+PRIVATE_NETWORKS = [
+    ipaddress.ip_network("0.0.0.0/8"),
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("100.64.0.0/10"),
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("169.254.0.0/16"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.0.0.0/24"),
+    ipaddress.ip_network("192.0.2.0/24"),
+    ipaddress.ip_network("192.88.99.0/24"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("198.18.0.0/15"),
+    ipaddress.ip_network("198.51.100.0/24"),
+    ipaddress.ip_network("203.0.113.0/24"),
+    ipaddress.ip_network("224.0.0.0/4"),
+    ipaddress.ip_network("240.0.0.0/4"),
+    ipaddress.ip_network("255.255.255.255/32"),
+    # IPv6
+    ipaddress.ip_network("::/128"),
+    ipaddress.ip_network("::1/128"),
+    ipaddress.ip_network("fc00::/7"),
+    ipaddress.ip_network("fe80::/10")
+]
+
+FORBIDDEN_HOSTNAMES = {"localhost", "loopback", "broadcasthost", "local", "0.0.0.0", "127.0.0.1", "::1"}
+
+def is_ip_private(ip_str: str) -> bool:
+    try:
+        if ip_str.isdigit():
+            ip_obj = ipaddress.ip_address(int(ip_str))
+        else:
+            ip_obj = ipaddress.ip_address(ip_str)
+
+        for net in PRIVATE_NETWORKS:
+            if ip_obj in net:
+                return True
+        return False
+    except ValueError:
+        return False
+
+def validate_ssrf_url(url_str: str) -> str:
+    if not url_str or not isinstance(url_str, str):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "INVALID_URL", "message": "URL must be a non-empty string."}
+        )
+
+    unquoted_url = urllib.parse.unquote(url_str)
+    
+    try:
+        parsed = urllib.parse.urlparse(unquoted_url)
+    except Exception:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "INVALID_URL", "message": f"URL '{url_str}' is unparseable."}
+        )
+
+    if parsed.scheme not in ["http", "https"]:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "INVALID_SCHEME", "message": f"Scheme '{parsed.scheme}' not allowed. Only http/https supported."}
+        )
+
+    hostname = parsed.hostname
+    if not hostname:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "MISSING_HOSTNAME", "message": "URL must contain a valid hostname."}
+        )
+
+    clean_host = hostname.lower().strip(".")
+
+    if clean_host in FORBIDDEN_HOSTNAMES or clean_host.endswith(".local"):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail={"error": "SSRF_BLOCKED", "message": f"Access to hostname '{clean_host}' is blocked (SSRF protection)."}
+        )
+
+    if is_ip_private(clean_host):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail={"error": "SSRF_BLOCKED", "message": f"Access to private IP '{clean_host}' is blocked."}
+        )
+
+    try:
+        ip_addresses = socket.getaddrinfo(clean_host, None)
+    except socket.gaierror:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"error": "DNS_RESOLUTION_FAILED", "message": f"Could not resolve hostname '{clean_host}'."}
+        )
+
+    for item in ip_addresses:
+        resolved_ip = item[4][0]
+        if is_ip_private(resolved_ip):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail={"error": "SSRF_BLOCKED", "message": f"URL resolves to private/loopback IP address '{resolved_ip}' which is blocked."}
+            )
+
+    return url_str
+
+def verify_api_key(auth: HTTPAuthorizationCredentials = Security(security_bearer)):
+    if not auth or not auth.credentials:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail={"error": "UNAUTHORIZED", "message": "Invalid or missing API key."}
+        )
+
+    token = auth.credentials
+    # Valid if matches Master API_KEY or any active Beta Key
+    if token == settings.API_KEY or is_beta_key_valid(token):
+        return token
+
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail={"error": "UNAUTHORIZED", "message": "Invalid or revoked API key."}
+    )
+
+def check_rate_limit(api_key: str):
+    now = time.time()
+    window_start = now - 60.0
+
+    if api_key not in rate_limit_records:
+        rate_limit_records[api_key] = []
+
+    rate_limit_records[api_key] = [t for t in rate_limit_records[api_key] if t > window_start]
+
+    if len(rate_limit_records[api_key]) >= settings.RATE_LIMIT_PER_MINUTE:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail={"error": "RATE_LIMIT_EXCEEDED", "message": f"Rate limit of {settings.RATE_LIMIT_PER_MINUTE} req/min exceeded."}
+        )
+
+    rate_limit_records[api_key].append(now)

mcp_web_engine/web_engine.py

@@ -0,0 +1,181 @@
+"""
+Core Web Engine Module: SearXNG Connector with DuckDuckGo Direct Fallback, SSRF-Safe HTTP Fetcher & HTML/Markdown Parser
+"""
+import time
+import urllib.parse
+import re
+from curl_cffi.requests import AsyncSession
+from bs4 import BeautifulSoup
+import html2text
+from fastapi import HTTPException, status
+from .config import settings
+from .security import validate_ssrf_url
+
+USER_AGENTS = [
+    "Mozilla/5.0 (X11; Linux aarch64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
+]
+
+def get_headers():
+    return {
+        "User-Agent": USER_AGENTS[0],
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "es-ES,es;q=0.9,en-US;q=0.8,en;q=0.7",
+        "Sec-Ch-Ua": '"Not A(Brand";v="99", "Google Chrome";v="120"',
+        "Sec-Fetch-Dest": "document"
+    }
+
+async def execute_ddg_fallback(query: str, limit: int = 10):
+    """
+    Direct DuckDuckGo HTML Search Fallback if SearXNG is unavailable.
+    """
+    start_t = time.time()
+    ddg_url = f"https://html.duckduckgo.com/html/?q={urllib.parse.quote(query)}"
+    headers = get_headers()
+
+    async with AsyncSession() as session:
+        try:
+            r = await session.get(ddg_url, headers=headers, impersonate="chrome120", timeout=8)
+            if r.status_code == 200:
+                soup = BeautifulSoup(r.text, "html.parser")
+                results = []
+                for idx, a in enumerate(soup.find_all("a", class_="result__a")[:limit]):
+                    title = a.get_text(strip=True)
+                    raw_href = a.get("href", "")
+                    # Extract target URL from DDG redirect
+                    match = re.search(r"uddg=(https?%3A%2F%2F[^&]+)", raw_href)
+                    final_url = urllib.parse.unquote(match.group(1)) if match else raw_href
+                    results.append({
+                        "rank": idx + 1,
+                        "title": title,
+                        "url": final_url,
+                        "snippet": f"Search result for '{query}'",
+                        "engine": "duckduckgo_fallback"
+                    })
+                return {
+                    "query": query,
+                    "count": len(results),
+                    "latency_ms": round((time.time() - start_t) * 1000, 2),
+                    "results": results
+                }
+        except Exception:
+            pass
+
+    return {"query": query, "count": 0, "latency_ms": 0, "results": []}
+
+async def execute_web_search(query: str, limit: int = 10):
+    start_t = time.time()
+    url = f"{settings.SEARXNG_URL}?q={query}&format=json"
+    
+    async with AsyncSession() as session:
+        try:
+            r = await session.get(url, timeout=4.0)
+            if r.status_code == 200:
+                data = r.json()
+                results = data.get("results", [])[:limit]
+                items = []
+                for idx, item in enumerate(results):
+                    items.append({
+                        "rank": idx + 1,
+                        "title": item.get("title"),
+                        "url": item.get("url"),
+                        "snippet": item.get("content"),
+                        "engine": item.get("engine")
+                    })
+                return {
+                    "query": query,
+                    "count": len(items),
+                    "latency_ms": round((time.time() - start_t) * 1000, 2),
+                    "results": items
+                }
+        except Exception:
+            pass
+
+    # SearXNG failed or timed out -> Fallback to direct DuckDuckGo HTML parser
+    return await execute_ddg_fallback(query, limit)
+
+async def execute_fetch_url(url: str, max_bytes: int = None):
+    current_url = validate_ssrf_url(url)
+    byte_limit = max_bytes or settings.MAX_PAYLOAD_BYTES
+
+    start_t = time.time()
+    headers = get_headers()
+    max_redirects = 5
+    redirect_count = 0
+
+    async with AsyncSession() as session:
+        while redirect_count < max_redirects:
+            try:
+                r = await session.get(
+                    current_url,
+                    headers=headers,
+                    impersonate="chrome120",
+                    allow_redirects=False,
+                    timeout=settings.DEFAULT_TIMEOUT_SEC
+                )
+            except Exception as e:
+                raise HTTPException(
+                    status_code=status.HTTP_504_GATEWAY_TIMEOUT if "timeout" in str(e).lower() else status.HTTP_502_BAD_GATEWAY,
+                    detail={"error": "FETCH_ERROR", "message": f"Failed to fetch target URL: {str(e)}"}
+                )
+
+            if r.status_code in [301, 302, 303, 307, 308]:
+                location = r.headers.get("Location") or r.headers.get("location")
+                if not location:
+                    break
+                next_url = urllib.parse.urljoin(current_url, location)
+                current_url = validate_ssrf_url(next_url)
+                redirect_count += 1
+                continue
+            else:
+                break
+
+    if r.status_code != 200:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail={"error": "HTTP_FETCH_FAILED", "message": f"Target server returned HTTP status {r.status_code}."}
+        )
+
+    content = r.text[:byte_limit]
+    if not content or len(content.strip()) < 10:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail={"error": "EMPTY_RESPONSE", "message": "Target URL returned an empty or truncated payload."}
+        )
+
+    return {
+        "url": current_url,
+        "status_code": r.status_code,
+        "content_length": len(content),
+        "latency_ms": round((time.time() - start_t) * 1000, 2),
+        "content": content
+    }
+
+async def execute_extract_markdown(url: str, max_bytes: int = None):
+    fetch_res = await execute_fetch_url(url, max_bytes)
+    html_content = fetch_res["content"]
+
+    try:
+        soup = BeautifulSoup(html_content, "html.parser")
+        for tag in soup(["script", "style", "nav", "footer", "iframe"]):
+            tag.decompose()
+
+        h = html2text.HTML2Text()
+        h.ignore_links = False
+        h.ignore_images = True
+        h.body_width = 0
+        
+        markdown_text = h.handle(str(soup))
+        
+        return {
+            "url": fetch_res["url"],
+            "status_code": 200,
+            "markdown_length": len(markdown_text),
+            "latency_ms": fetch_res["latency_ms"],
+            "markdown": markdown_text
+        }
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={"error": "EXTRACTION_FAILED", "message": f"Failed to convert HTML to Markdown: {str(e)}"}
+        )

mcp_web_engine-1.0.4.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: mcp-web-engine
+Version: 1.0.4
+Summary: Privacy-First, Self-Hostable & SSRF-Hardened MCP Server & Web Engine for AI Agents
+Project-URL: Homepage, https://github.com/Arbolencio/mcp-web-engine
+Project-URL: Repository, https://github.com/Arbolencio/mcp-web-engine.git
+Author: Arbolencio
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,mcp,mcp-server,searxng,ssrf-protection,turbollm,web-scraper,web-search
+Requires-Python: >=3.9
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: curl-cffi>=0.6.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: html2text>=2024.1.14
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: sse-starlette>=2.0.0
+Requires-Dist: uvicorn>=0.27.0
+Description-Content-Type: text/markdown
+
+# 🌐 MCP Web Engine & Search Gateway
+
+> **Public HTTPS Specification 2026-07-28 Pure Stateless Core MCP Server for AI Agents**
+
+---
+
+## 🌐 Public Production HTTPS Endpoint (Cloudflare Managed Tunnel)
+
+- **Public MCP 2026-07-28 Endpoint:** `https://ultimate-ignored-over-light.trycloudflare.com/v1/mcp`
+- **Health Check:** `https://ultimate-ignored-over-light.trycloudflare.com/health`
+
+---
+
+## 📌 What it does & Why it exists
+
+`MCP Web Engine` is a high-performance Model Context Protocol (MCP) server implementing the **MCP Specification 2026-07-28 Pure Stateless Core** (JSON-RPC 2.0 over HTTPS). It provides AI Agents (Claude Desktop, Cursor, Windsurf, MCP Inspector, Hermes Agent) with secure, private access to web search, raw content fetching, and clean HTML-to-Markdown extraction.
+
+### Key Capabilities & Architecture
+- **Pure Stateless Core (Spec 2026-07-28):** Zero sessions, zero state, zero initialize handshake required. Every request is completely independent.
+- **Protocol Methods:** Implements `server/discover`, `tools/list`, and `tools/call` with standard JSON-RPC 2.0 payloads.
+- **Zero Third-Party Tracking:** Powered by an internal SearXNG meta-search engine aggregating 70+ sources with DuckDuckGo fallback.
+- **SSRF Hardened:** Pre-request DNS resolution checks prevent agents from accessing internal networks (`localhost`, `127.0.0.1`, `192.168.x.x`, `169.254.169.254`). Step-by-step HTTP 301/302 redirect re-validation.
+- **TLS Fingerprinting:** Powered by `curl_cffi` (Chrome 120+ TLS impersonation) for clean research scraping without heavy browser overhead.
+
+---
+
+## 🏗️ Architecture
+
+```
+[ MCP Client / Claude / Cursor / Windsurf / Inspector ]
+                         │
+        (HTTPS Header: Authorization: Bearer sk_mcp_...)
+        (HTTPS Header: MCP-Protocol-Version: 2026-07-28)
+                         ▼
+        [ Cloudflare Managed HTTPS Tunnel ]
+                         │
+                         ▼
+        [ FastAPI Gateway (Port 5050) ]
+           ├── Endpoint: POST /v1/mcp (Pure Stateless Core)
+           ├── Security & Auth (Bearer Token + Sliding Window Rate Limiter)
+           ├── SSRF Validator (Pre-request DNS + IP Subnet Filtering)
+           ├── Method 1: server/discover (Server Metadata Discovery)
+           ├── Method 2: tools/list (Tools Discovery)
+           └── Method 3: tools/call (Tool Execution Engine)
+```
+
+---
+
+## 🚀 Quickstart & Docker Installation (< 2 Minutes)
+
+```bash
+# 1. Clone Repository
+git clone https://github.com/Arbolencio/mcp-web-engine.git
+cd mcp-web-engine
+
+# 2. Copy Environment Example
+cp .env.example .env
+
+# 3. Launch with Docker Compose
+docker compose up -d
+
+# 4. Verify Health Check
+curl -s https://ultimate-ignored-over-light.trycloudflare.com/health
+# {"status":"ok","environment":"production","searxng_url":"http://host.docker.internal:8082/search","mcp_version":"2026-07-28"}
+```
+
+---
+
+## 🔌 Connecting from MCP Clients (Cursor, Windsurf, Inspector, Claude Desktop)
+
+### 1. Cursor / Windsurf / MCP Inspector (Direct HTTPS):
+- **Server Endpoint:** `https://ultimate-ignored-over-light.trycloudflare.com/v1/mcp`
+- **Headers:**
+  - `Authorization: Bearer YOUR_BETA_KEY_HERE`
+  - `MCP-Protocol-Version: 2026-07-28`
+
+### 2. Claude Desktop (via `mcp-remote` bridge):
+```json
+{
+  "mcpServers": {
+    "mcp-web-engine": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://ultimate-ignored-over-light.trycloudflare.com/v1/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_BETA_KEY_HERE"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ MCP 2026-07-28 Stateless Protocol Lifecycle
+
+### 1. `server/discover` Discovery
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "server/discover",
+  "params": {}
+}
+```
+
+### 2. `tools/list` Discovery
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/list",
+  "params": {}
+}
+```
+
+### 3. `tools/call` Execution
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "web_search",
+    "arguments": {
+      "query": "Model Context Protocol 2026 specification",
+      "limit": 5
+    }
+  }
+}
+```
+
+---
+
+## 🔑 Managing Beta Keys
+
+Manage API access keys using the CLI helper:
+
+```bash
+# Generate 20 Beta Keys
+python manage_beta_keys.py init20
+
+# View Beta User Telemetry
+python manage_beta_keys.py telemetry
+
+# Revoke a key by ID
+python manage_beta_keys.py revoke --id Beta_001
+```
+
+---
+
+## 🛡️ Security & Honest Technical Limits
+
+- **SSRF Hardening:** Blocks `localhost`, loopbacks, private subnets (`10.0.0.0/8`, `192.168.0.0/16`, `172.16.0.0/12`), percent-encoding bypasses (`%31%32%37...`), and re-validates `Location` headers on HTTP redirects step-by-step.
+- **Rate Limiting:** Default limit of 120 req/min per key.
+- **Honest Positioning:** Designed for research, documentation retrieval, and web search. Auth-walled sites requiring login (e.g. private social feeds) are not supported.
+
+---
+
+## 📄 License
+
+MIT License © 2026 MCP Web Engine Contributors.

mcp_web_engine-1.0.4.dist-info/RECORD

@@ -0,0 +1,14 @@
+mcp_web_engine/__init__.py,sha256=JRZV4tpld-6i_-J5WceGWJxoK8r8qDs8rOh7g6QfHIw,53
+mcp_web_engine/config.py,sha256=IUGW5AP1R65CHZjzPCmkr3W32NlCpUT4KKH3ppxri_0,1222
+mcp_web_engine/logging_obs.py,sha256=jbFLB2bQzbx133amXAJQap3DE388twsRlryVxBLyy50,4121
+mcp_web_engine/main.py,sha256=CYX8dschYnMC_b6Lsd0ehjYNW5_JLZXiOQqwqUGNd5s,8308
+mcp_web_engine/manage_beta_keys.py,sha256=aB_-G0QiXKt8qcvXw_m_McP6x9ZR2hrRuVAHHLQc6KE,3982
+mcp_web_engine/mcp_protocol.py,sha256=KjD-bsYexht8r8pcx4QvBF8X_9fAVdIh8gS7q1wnHfA,8390
+mcp_web_engine/mcp_tools.py,sha256=wzKH9C-FBcEKloEsVJaQJKpBmiXGyEHJfng4VrbVvIs,2147
+mcp_web_engine/security.py,sha256=DhH7T3LH4ys3amDX_XmxgGIRsW5s3x5hYQ70KxELoW4,5952
+mcp_web_engine/web_engine.py,sha256=E2VKiJUfJK2qC8spTojCuwFKTny_8sXiKXxZwaCwmTc,6914
+mcp_web_engine-1.0.4.dist-info/METADATA,sha256=FpG7BdXBrRxpUsNb0YaOjAcaiZ_TdJJvv09MAqzTkqY,5824
+mcp_web_engine-1.0.4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mcp_web_engine-1.0.4.dist-info/entry_points.txt,sha256=H9QHINaUpzqZXFxmFBbIhI9AJ7LkrMk5wDqFcKG5QEs,70
+mcp_web_engine-1.0.4.dist-info/licenses/LICENSE,sha256=U5YuXrvsrnK8Jwt7Hc82K5jMwwI_9tcKI2Wfo6QVzyU,1084
+mcp_web_engine-1.0.4.dist-info/RECORD,,

mcp_web_engine-1.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_web_engine-1.0.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-web-engine = mcp_web_engine.main:cli_entrypoint

mcp_web_engine-1.0.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP Web Engine Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.