mcp-web-engine 1.0.4 → 1.2.0

package/src/mcp_web_engine/web_engine.py

@@ -0,0 +1,315 @@
+"""
+Core Web Engine Module: SearXNG Connector with DuckDuckGo Direct Fallback, SSRF-Safe HTTP Fetcher & HTML/Markdown Parser
+"""
+
+import asyncio
+import json
+import logging
+import re
+import time
+import urllib.parse
+
+import html2text
+from bs4 import BeautifulSoup
+from curl_cffi import CurlError, CurlOpt
+from curl_cffi.curl import CURL_WRITEFUNC_ERROR
+from curl_cffi.requests import AsyncSession
+from fastapi import HTTPException, status
+
+from .config import settings
+from .security import _parse_http_url, resolve_ssrf_target
+
+logger = logging.getLogger(__name__)
+
+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)}"
+    try:
+        r, body, _ = await _bounded_request(ddg_url, _payload_limit(), timeout=8)
+        if r.status_code == 200:
+            soup = BeautifulSoup(_decode_body(r, body), "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 (HTTPException, ValueError, TypeError, AttributeError) as exc:
+        logger.warning("DuckDuckGo fallback unavailable (%s)", type(exc).__name__)
+
+    return {"query": query, "count": 0, "latency_ms": 0, "results": []}
+
+
+def normalize_searxng_url(base_url: str) -> str:
+    url = base_url.rstrip("/")
+    if not url.endswith("/search"):
+        url = f"{url}/search"
+    return url
+
+
+async def execute_web_search(query: str, limit: int = 10):
+    start_t = time.time()
+    base_searxng = normalize_searxng_url(settings.SEARXNG_URL)
+    query_params = urllib.parse.urlencode({"q": query, "format": "json"})
+    url = f"{base_searxng}?{query_params}"
+
+    try:
+        r, body, _ = await _bounded_request(
+            url, _payload_limit(), trusted_search=True, timeout=4.0
+        )
+        if r.status_code == 200:
+            data = json.loads(_decode_body(r, body))
+            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 (HTTPException, ValueError, TypeError, AttributeError) as exc:
+        logger.warning("SearXNG unavailable (%s)", type(exc).__name__)
+
+    # SearXNG failed or timed out -> only fall back when the operator opted in,
+    # so that no query ever leaves the host without explicit consent.
+    if settings.ALLOW_DDG_FALLBACK:
+        return await execute_ddg_fallback(query, limit)
+
+    return {
+        "query": query,
+        "count": 0,
+        "latency_ms": round((time.time() - start_t) * 1000, 2),
+        "results": [],
+        "error": "SEARXNG_UNAVAILABLE",
+        "detail": "SearXNG did not answer. The DuckDuckGo fallback is disabled by default; set ALLOW_DDG_FALLBACK=true to enable it.",
+    }
+
+
+def _payload_limit(max_bytes=None):
+    ceiling = settings.MAX_PAYLOAD_BYTES
+    if max_bytes is None:
+        return ceiling
+    if isinstance(max_bytes, bool) or not isinstance(max_bytes, int) or max_bytes <= 0:
+        raise HTTPException(
+            400,
+            detail={"error": "INVALID_LIMIT", "message": "max_bytes must be positive."},
+        )
+    return min(max_bytes, ceiling)
+
+
+async def _bounded_request(url, byte_limit, *, trusted_search=False, timeout=None):
+    """Private transport. Only the configured operator search URL may bypass SSRF.
+
+    Each hop gets a fresh session/connection: no stale DNS cache, pooled HTTP/2
+    coalescing, cross-origin cookies, or environment proxies. curl's write callback
+    receives decompressed data and aborts before retaining more than byte_limit.
+    """
+    deadline = time.monotonic() + (timeout or settings.DEFAULT_TIMEOUT_SEC)
+    current_url = url
+    for redirect_count in range(6):
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise HTTPException(504, detail={"error": "FETCH_TIMEOUT"})
+        if trusted_search:
+            current_url, _, _ = _parse_http_url(current_url)
+            target = None
+        else:
+            # Offload blocking resolver; outer wait bounds the caller's DNS wait.
+            try:
+                target = await asyncio.wait_for(
+                    asyncio.to_thread(resolve_ssrf_target, current_url), remaining
+                )
+            except asyncio.TimeoutError:
+                raise HTTPException(504, detail={"error": "FETCH_TIMEOUT"}) from None
+            current_url = target.url
+        options = {
+            # Set the exact canonical URL last, after requests library requoting.
+            CurlOpt.URL: current_url,
+            CurlOpt.PROXY: "",  # trust_env alone is insufficient in older releases.
+            CurlOpt.NOPROXY: "*",
+            CurlOpt.PROTOCOLS: 3,  # CURLPROTO_HTTP | CURLPROTO_HTTPS
+            CurlOpt.REDIR_PROTOCOLS: 3,
+            CurlOpt.FRESH_CONNECT: 1,
+            CurlOpt.FORBID_REUSE: 1,
+        }
+        if target is not None:
+            options[CurlOpt.RESOLVE] = [target.resolve_entry]
+        body = bytearray()
+        oversized = False
+
+        def receive(chunk, body=body):
+            nonlocal oversized
+            if len(body) + len(chunk) > byte_limit:
+                oversized = True
+                # Older curl_cffi ignores a short byte count: use the explicit
+                # libcurl abort sentinel instead of 0 (verified on 0.6 and 0.17).
+                return CURL_WRITEFUNC_ERROR
+            body.extend(chunk)
+            return len(chunk)
+
+        try:
+            async with AsyncSession(trust_env=False, curl_options=options) as session:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise asyncio.TimeoutError()
+                r = await asyncio.wait_for(
+                    session.get(
+                        current_url,
+                        headers=get_headers(),
+                        impersonate="chrome120",
+                        allow_redirects=False,
+                        timeout=remaining,
+                        content_callback=receive,
+                        accept_encoding="gzip, deflate, br",
+                    ),
+                    remaining,
+                )
+        except (CurlError, asyncio.TimeoutError, OSError, RuntimeError) as exc:
+            if oversized:
+                raise HTTPException(
+                    413,
+                    detail={
+                        "error": "PAYLOAD_TOO_LARGE",
+                        "message": "Decoded response exceeds byte limit.",
+                    },
+                ) from None
+            timed_out = (
+                isinstance(exc, asyncio.TimeoutError) or "timeout" in str(exc).lower()
+            )
+            # Never echo transport exceptions (may include sensitive URL data).
+            raise HTTPException(
+                504 if timed_out else 502,
+                detail={"error": "FETCH_ERROR", "message": "Target request failed."},
+            ) from None
+        if oversized:
+            raise HTTPException(413, detail={"error": "PAYLOAD_TOO_LARGE"})
+        if r.status_code not in (301, 302, 303, 307, 308) or trusted_search:
+            return r, bytes(body), current_url
+        location = r.headers.get("Location") or r.headers.get("location")
+        if not location:
+            return r, bytes(body), current_url
+        if redirect_count == 5:
+            raise HTTPException(502, detail={"error": "TOO_MANY_REDIRECTS"})
+        # Validate raw Location BEFORE urljoin, which also strips some controls.
+        if (
+            not isinstance(location, str)
+            or "\\" in location
+            or any(ord(c) <= 32 or ord(c) == 127 or c.isspace() for c in location)
+        ):
+            raise HTTPException(400, detail={"error": "INVALID_REDIRECT"})
+        current_url = urllib.parse.urljoin(current_url, location)
+    raise HTTPException(502, detail={"error": "TOO_MANY_REDIRECTS"})
+
+
+def _decode_body(response, body):
+    try:
+        return body.decode(response.encoding or "utf-8", errors="replace")
+    except (LookupError, AttributeError):
+        return body.decode("utf-8", errors="replace")
+
+
+async def execute_fetch_url(url: str, max_bytes: int | None = None):
+    start_t = time.monotonic()
+    r, body, current_url = await _bounded_request(url, _payload_limit(max_bytes))
+    if r.status_code != 200:
+        raise HTTPException(
+            502,
+            detail={
+                "error": "HTTP_FETCH_FAILED",
+                "message": f"Target server returned HTTP status {r.status_code}.",
+            },
+        )
+    content = _decode_body(r, body)
+    if not content or len(content.strip()) < 10:
+        raise HTTPException(
+            422,
+            detail={
+                "error": "EMPTY_RESPONSE",
+                "message": "Target returned an empty payload.",
+            },
+        )
+    return {
+        "url": current_url,
+        "status_code": r.status_code,
+        "content_length": len(body),
+        "latency_ms": round((time.monotonic() - start_t) * 1000, 2),
+        "content": content,
+    }
+
+
+async def execute_extract_markdown(url: str, max_bytes: int | None = 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 (ValueError, TypeError, RuntimeError):
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={
+                "error": "EXTRACTION_FAILED",
+                "message": "Failed to convert HTML to Markdown.",
+            },
+        )

package/config.py

@@ -1,24 +0,0 @@
-"""
-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()

package/logging_obs.py

@@ -1,111 +0,0 @@
-"""
-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()

package/main.py

@@ -1,230 +0,0 @@
-"""
-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.0"
-)
-
-@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()
-
-if __name__ == "__main__":
-    is_stdio = "--stdio" in sys.argv or not sys.stdin.isatty()
-    if is_stdio:
-        asyncio.run(run_mcp_stdio_server())
-    else:
-        import uvicorn
-        uvicorn.run("main:app", host=settings.HOST, port=settings.PORT, reload=False)