Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

47.2 KB
Raw Blame
"""
MCP Server for Local Deep Research.

This module provides an MCP (Model Context Protocol) server that exposes
LDR's research capabilities to AI agents like Claude.

Security Notice:
    This server is designed for LOCAL USE ONLY via STDIO transport
    (e.g., Claude Desktop). It has no built-in authentication or rate
    limiting. Do NOT expose this server over a network without implementing
    proper security controls (OAuth, rate limiting, input validation).

    When running locally via STDIO, security is provided by your operating
    system's user permissions.

Tools:
    - quick_research: Fast research summary (1-5 min)
    - detailed_research: Comprehensive analysis (5-15 min)
    - generate_report: Full markdown report (10-30 min)
    - analyze_documents: Search local document collection (30s-2 min)
    - search: Raw search results without LLM processing (5-30s)
    - list_search_engines: List available search engines
    - list_strategies: List available research strategies
    - get_configuration: Get current server configuration

Usage:
    python -m local_deep_research.mcp
    # or
    ldr-mcp
"""

import re
import sys
from collections.abc import Callable
from typing import Any, Dict, Optional, cast

from loguru import logger
from mcp.server.fastmcp import FastMCP

from local_deep_research.api.research_functions import (
    analyze_documents as ldr_analyze_documents,
    detailed_research as ldr_detailed_research,
    generate_report as ldr_generate_report,
    quick_summary as ldr_quick_summary,
)
from local_deep_research.api.settings_utils import create_settings_snapshot
from local_deep_research.search_system_factory import (
    get_available_strategies,
)
from ..constants import DEFAULT_SEARCH_TOOL
from ..security.egress.policy import PolicyDeniedError

# Create FastMCP server instance
mcp = FastMCP(
    "local-deep-research",
    instructions="AI-powered deep research assistant with iterative analysis using LLMs and web searches",
)

_HTTP_ERROR_CODE_RE = re.compile(r"(?<!\d)(?:401|404|429|503)(?!\d)")


def _classify_error(error_msg: str) -> str:
    """Classify error for client handling."""
    error_lower = error_msg.lower()
    # Exception messages can contain timestamps, counters, or OS thread IDs.
    # Only standalone three-digit values are HTTP status codes; matching a
    # substring inside a longer number makes classification nondeterministic.
    status_codes = set(_HTTP_ERROR_CODE_RE.findall(error_msg))
    if "503" in status_codes or "unavailable" in error_lower:
        return "service_unavailable"
    if "404" in status_codes or "not found" in error_lower:
        return "model_not_found"
    if (
        "api key" in error_lower
        or "authentication" in error_lower
        or "unauthorized" in error_lower
        or "401" in status_codes
    ):
        return "auth_error"
    if "timeout" in error_lower or "timed out" in error_lower:
        return "timeout"
    if "rate limit" in error_lower or "429" in status_codes:
        return "rate_limit"
    if "connection" in error_lower:
        return "connection_error"
    if "validation" in error_lower or "invalid" in error_lower:
        return "validation_error"
    return "unknown"


def _policy_denied_response(
    error: PolicyDeniedError, operation: str
) -> Dict[str, Any]:
    """Build a machine-readable, leak-safe response for a PolicyDeniedError.

    The PDP's short ``reason`` code (e.g. ``scope_mismatch_private_only``) is
    safe to surface -- it is a machine code, never user content. The
    ``target`` attribute is not (engine names / URLs may carry user content
    or internal hostnames), so it is logged at audit level but never returned
    to the client. Fail-closed is preserved by construction: this helper only
    runs after the PEP has already raised, so the underlying engine run has
    already been blocked.
    """
    reason = error.decision.reason
    logger.bind(policy_audit=True).warning(
        "MCP tool denied by egress policy",
        operation=operation,
        reason=reason,
    )
    return {
        "status": "error",
        "error_type": "policy_denied",
        "reason": reason,
        "error": f"{operation} denied by egress policy: {reason}.",
    }


class ValidationError(Exception):
    """Raised when parameter validation fails."""

    pass


_COLLECTION_NAME_RE = re.compile(r"^[A-Za-z0-9 _-]{1,100}$")


def _validate_range(
    value: Any,
    name: str,
    min_val: int | float,
    max_val: int | float,
    *,
    type_check: type | tuple[type, ...] = int,
    allow_none: bool = True,
    convert_to: Optional[Callable[[int | float], int | float]] = None,
    type_error: Optional[str] = None,
    min_error: Optional[str] = None,
    max_error: Optional[str] = None,
) -> int | float | None:
    """Validate a numeric parameter and optionally normalize its type."""
    if value is None:
        if allow_none:
            return None
        raise ValidationError(type_error or f"{name} is required")
    if not isinstance(value, type_check):
        raise ValidationError(type_error or f"{name} must be a number")
    numeric_value = cast(int | float, value)
    if not numeric_value >= min_val:
        raise ValidationError(min_error or f"{name} must be at least {min_val}")
    if not numeric_value <= max_val:
        raise ValidationError(max_error or f"{name} cannot exceed {max_val}")
    return (
        convert_to(numeric_value) if convert_to is not None else numeric_value
    )


def _error_result(
    error: Exception | str,
    *,
    operation: Optional[str] = None,
    error_type: Optional[str] = None,
) -> Dict[str, Any]:
    """Build an MCP error result without changing its public message shape.

    ``operation`` is the complete operation-specific wording that precedes
    ``(<error_type>)``. Omitting it preserves ``error`` verbatim, which is
    used for validation and other deliberately client-visible messages.
    """
    error_text = str(error)
    resolved_type = error_type or _classify_error(error_text)
    public_message = (
        error_text
        if operation is None
        else f"{operation} ({resolved_type}). Check server logs for details."
    )
    return {
        "status": "error",
        "error": public_message,
        "error_type": resolved_type,
    }


def _validate_query(query: str) -> str:
    """Validate and sanitize query parameter."""
    if not query or not query.strip():
        raise ValidationError("Query cannot be empty")
    query = query.strip()
    if len(query) > 10000:
        raise ValidationError(
            "Query exceeds maximum length of 10000 characters"
        )
    return query


def _validate_iterations(
    iterations: Optional[int], max_val: int = 20
) -> Optional[int]:
    """Validate iterations parameter."""
    positive_error = "Iterations must be a positive integer"
    return cast(
        Optional[int],
        _validate_range(
            iterations,
            "Iterations",
            1,
            max_val,
            type_error=positive_error,
            min_error=positive_error,
        ),
    )


def _validate_questions_per_iteration(qpi: Optional[int]) -> Optional[int]:
    """Validate questions_per_iteration parameter."""
    positive_error = "Questions per iteration must be a positive integer"
    return cast(
        Optional[int],
        _validate_range(
            qpi,
            "Questions per iteration",
            1,
            10,
            type_error=positive_error,
            min_error=positive_error,
        ),
    )


def _validate_max_results(max_results: int) -> int:
    """Validate max_results parameter."""
    positive_error = "Max results must be a positive integer"
    return cast(
        int,
        _validate_range(
            max_results,
            "Max results",
            1,
            100,
            allow_none=False,
            type_error=positive_error,
            min_error=positive_error,
        ),
    )


def _validate_searches_per_section(searches_per_section: int) -> int:
    """Validate searches_per_section parameter."""
    positive_error = "Searches per section must be a positive integer"
    return cast(
        int,
        _validate_range(
            searches_per_section,
            "Searches per section",
            1,
            10,
            allow_none=False,
            type_error=positive_error,
            min_error=positive_error,
        ),
    )


def _validate_temperature(temperature: Optional[float]) -> Optional[float]:
    """Validate and normalize a temperature setting."""
    range_error = "Temperature must be between 0.0 and 2.0"
    return cast(
        Optional[float],
        _validate_range(
            temperature,
            "Temperature",
            0.0,
            2.0,
            type_check=(int, float),
            convert_to=float,
            type_error="Temperature must be a number",
            min_error=range_error,
            max_error=range_error,
        ),
    )


def _validate_search_engine(engine: Optional[str]) -> Optional[str]:
    """Validate search engine name against available engines."""
    if engine is None:
        return None
    engine = engine.strip()
    if not engine:
        return None
    try:
        from local_deep_research.web_search_engines.search_engines_config import (
            search_config,
        )

        settings = create_settings_snapshot()
        available = search_config(settings_snapshot=settings)
        if engine not in available:
            available_names = sorted(available.keys())
            raise ValidationError(  # noqa: TRY301
                f"Unknown search engine '{engine}'. Available: {', '.join(available_names)}"
            )
    except ValidationError:
        raise
    except Exception:
        logger.exception("Could not load engine config to validate engine")
        raise ValidationError(
            f"Cannot validate search engine '{engine}': engine configuration unavailable"
        )
    return engine


def _validate_strategy(strategy: Optional[str]) -> Optional[str]:
    """Validate strategy name against available strategies."""
    if strategy is None:
        return None
    strategy = strategy.strip()
    if not strategy:
        return None
    available = get_available_strategies()
    available_names = [s["name"] for s in available]
    if strategy not in available_names:
        raise ValidationError(
            f"Unknown strategy '{strategy}'. Available: {', '.join(available_names)}"
        )
    return strategy


def _build_settings_overrides(
    search_engine: Optional[str] = None,
    strategy: Optional[str] = None,
    iterations: Optional[int] = None,
    questions_per_iteration: Optional[int] = None,
    temperature: Optional[float] = None,
) -> Dict[str, Any]:
    """Build settings overrides dict from tool parameters."""
    overrides: dict[str, Any] = {}
    if search_engine is not None:
        search_engine = _validate_search_engine(search_engine)
        if search_engine:
            overrides["search.tool"] = search_engine
    if strategy is not None:
        strategy = _validate_strategy(strategy)
        if strategy:
            overrides["search.search_strategy"] = strategy
    if iterations is not None:
        overrides["search.iterations"] = iterations
    if questions_per_iteration is not None:
        overrides["search.questions_per_iteration"] = questions_per_iteration
    if temperature is not None:
        overrides["llm.temperature"] = _validate_temperature(temperature)
    return overrides


# =============================================================================
# Research Tools
# =============================================================================


@mcp.tool()
def quick_research(
    query: str,
    search_engine: Optional[str] = None,
    strategy: Optional[str] = None,
    iterations: Optional[int] = None,
    questions_per_iteration: Optional[int] = None,
) -> Dict[str, Any]:
    """
    Perform quick research on a topic.

    This tool performs a fast research summary on the given query. It searches
    the web, analyzes sources, and generates a concise summary with findings.

    IMPORTANT: This is a synchronous operation that typically takes 1-5 minutes
    to complete depending on the complexity and configuration.

    Args:
        query: The research question or topic to investigate.
        search_engine: Search engine to use (e.g., "wikipedia", "arxiv", "searxng").
                      Use list_search_engines() to see available options.
        strategy: Research strategy to use (e.g., "source-based", "rapid", "iterative").
                 Use list_strategies() to see available options.
        iterations: Number of search iterations (1-10). More iterations = deeper research.
        questions_per_iteration: Questions to generate per iteration (1-5).

    Returns:
        Dictionary containing:
        - status: "success" or "error"
        - summary: The research summary text
        - findings: List of detailed findings from each search
        - sources: List of source URLs discovered
        - iterations: Number of iterations performed
        - error: Error message (only if status is "error")
        - error_type: Error classification (only if status is "error")
    """
    try:
        # Validate parameters
        query = _validate_query(query)
        iterations = _validate_iterations(iterations, max_val=10)
        questions_per_iteration = _validate_questions_per_iteration(
            questions_per_iteration
        )

        logger.info(f"Starting quick research for query: {query[:100]}...")

        overrides = _build_settings_overrides(
            search_engine=search_engine,
            strategy=strategy,
            iterations=iterations,
            questions_per_iteration=questions_per_iteration,
        )

        settings = (
            create_settings_snapshot(overrides=overrides)
            if overrides
            else create_settings_snapshot()
        )

        result = ldr_quick_summary(query, settings_snapshot=settings)

        return {
            "status": "success",
            "summary": result.get("summary", ""),
            "findings": result.get("findings", []),
            "sources": result.get("sources", []),
            "iterations": result.get("iterations", 0),
            "formatted_findings": result.get("formatted_findings", ""),
        }

    except ValidationError as e:
        logger.warning("Validation failed for quick research")
        return _error_result(e, error_type="validation_error")
    except PolicyDeniedError as e:
        return _policy_denied_response(e, "Quick research")
    except Exception as e:
        logger.exception(
            f"Quick research failed for query: {query[:100] if query else 'empty'}"
        )
        return _error_result(e, operation="Quick research failed")


@mcp.tool()
def detailed_research(
    query: str,
    search_engine: Optional[str] = None,
    strategy: Optional[str] = None,
    iterations: Optional[int] = None,
    questions_per_iteration: Optional[int] = None,
) -> Dict[str, Any]:
    """
    Perform detailed research with comprehensive analysis.

    This tool performs a thorough research analysis on the given query, returning
    structured data with detailed findings, sources, and metadata.

    IMPORTANT: This is a synchronous operation that typically takes 5-15 minutes
    to complete depending on the complexity and configuration.

    Args:
        query: The research question or topic to investigate.
        search_engine: Search engine to use (e.g., "wikipedia", "arxiv", "searxng").
        strategy: Research strategy to use (e.g., "source-based", "iterative", "evidence").
        iterations: Number of search iterations (1-10). More iterations = deeper research.
        questions_per_iteration: Questions to generate per iteration (1-5).

    Returns:
        Dictionary containing:
        - status: "success" or "error"
        - query: The original query
        - research_id: Unique identifier for this research
        - summary: The research summary text
        - findings: List of detailed findings
        - sources: List of source URLs
        - iterations: Number of iterations performed
        - metadata: Additional metadata (timestamp, search_tool, strategy)
        - error/error_type: Error info (only if status is "error")
    """
    try:
        # Validate parameters
        query = _validate_query(query)
        iterations = _validate_iterations(iterations, max_val=20)
        questions_per_iteration = _validate_questions_per_iteration(
            questions_per_iteration
        )

        logger.info(f"Starting detailed research for query: {query[:100]}...")

        overrides = _build_settings_overrides(
            search_engine=search_engine,
            strategy=strategy,
            iterations=iterations,
            questions_per_iteration=questions_per_iteration,
        )

        settings = (
            create_settings_snapshot(overrides=overrides)
            if overrides
            else create_settings_snapshot()
        )

        result = ldr_detailed_research(query, settings_snapshot=settings)

        return {
            "status": "success",
            "query": result.get("query", query),
            "research_id": result.get("research_id", ""),
            "summary": result.get("summary", ""),
            "findings": result.get("findings", []),
            "sources": result.get("sources", []),
            "iterations": result.get("iterations", 0),
            "formatted_findings": result.get("formatted_findings", ""),
            "metadata": result.get("metadata", {}),
        }

    except ValidationError as e:
        logger.warning("Validation failed for detailed research")
        return _error_result(e, error_type="validation_error")
    except PolicyDeniedError as e:
        return _policy_denied_response(e, "Detailed research")
    except Exception as e:
        logger.exception(
            f"Detailed research failed for query: {query[:100] if query else 'empty'}"
        )
        return _error_result(e, operation="Detailed research failed")


@mcp.tool()
def generate_report(
    query: str,
    search_engine: Optional[str] = None,
    searches_per_section: int = 2,
) -> Dict[str, Any]:
    """
    Generate a comprehensive markdown research report.

    This tool generates a full structured research report with sections,
    citations, and comprehensive analysis. The output is formatted as markdown.

    IMPORTANT: This is a synchronous operation that typically takes 10-30 minutes
    to complete due to the comprehensive nature of the report.

    Args:
        query: The research question or topic for the report.
        search_engine: Search engine to use (e.g., "wikipedia", "arxiv", "searxng").
        searches_per_section: Number of searches per report section (1-10). Default is 2.

    Returns:
        Dictionary containing:
        - status: "success" or "error"
        - content: The full report content in markdown format
        - metadata: Report metadata (timestamp, query)
        - error/error_type: Error info (only if status is "error")
    """
    try:
        # Validate parameters
        query = _validate_query(query)
        searches_per_section = _validate_searches_per_section(
            searches_per_section
        )

        logger.info(f"Starting report generation for query: {query[:100]}...")

        overrides = {}
        if search_engine:
            search_engine = _validate_search_engine(search_engine)
            if search_engine:
                overrides["search.tool"] = search_engine

        settings = (
            create_settings_snapshot(overrides=overrides)
            if overrides
            else create_settings_snapshot()
        )

        result = ldr_generate_report(
            query,
            settings_snapshot=settings,
            searches_per_section=searches_per_section,
        )

        return {
            "status": "success",
            "content": result.get("content", ""),
            "metadata": result.get("metadata", {}),
        }

    except ValidationError as e:
        logger.warning("Validation failed for report generation")
        return _error_result(e, error_type="validation_error")
    except PolicyDeniedError as e:
        return _policy_denied_response(e, "Report generation")
    except Exception as e:
        logger.exception(
            f"Report generation failed for query: {query[:100] if query else 'empty'}"
        )
        return _error_result(e, operation="Report generation failed")


@mcp.tool()
def analyze_documents(
    query: str,
    collection_name: str,
    max_results: int = 10,
) -> Dict[str, Any]:
    """
    Search and analyze documents in a local collection.

    This tool performs RAG (Retrieval Augmented Generation) search on a
    local document collection and generates a summary of relevant findings.

    Args:
        query: The search query for the documents.
        collection_name: Name of the local document collection to search.
        max_results: Maximum number of documents to retrieve (1-100). Default is 10.

    Returns:
        Dictionary containing:
        - status: "success" or "error"
        - summary: Summary of findings from the documents
        - documents: List of matching documents with content and metadata
        - collection: Name of the collection searched
        - document_count: Number of documents found
        - error/error_type: Error info (only if status is "error")
    """
    try:
        # Validate parameters
        query = _validate_query(query)
        if not collection_name or not collection_name.strip():
            raise ValidationError("Collection name cannot be empty")  # noqa: TRY301
        collection_name = collection_name.strip()
        if not _COLLECTION_NAME_RE.match(collection_name):
            raise ValidationError(  # noqa: TRY301
                "Collection name may only contain letters, digits, spaces, hyphens, and underscores (max 100 chars)"
            )
        max_results = _validate_max_results(max_results)

        logger.info(
            f"Analyzing documents in '{collection_name}' for query: {query[:100]}..."
        )

        # Build a settings snapshot the same way the other MCP tools do.
        # Without this, analyze_documents falls back to JSON defaults +
        # LDR_* env vars and silently ignores user-configured providers,
        # API keys, and embedding model. Mirrors quick_research (line 278).
        settings = create_settings_snapshot()

        result = ldr_analyze_documents(
            query=query,
            collection_name=collection_name,
            max_results=max_results,
            settings_snapshot=settings,
        )

        return {
            "status": "success",
            "summary": result.get("summary", ""),
            "documents": result.get("documents", []),
            "collection": result.get("collection", collection_name),
            "document_count": result.get("document_count", 0),
        }

    except ValidationError as e:
        logger.warning("Validation failed for document analysis")
        return _error_result(e, error_type="validation_error")
    except PolicyDeniedError as e:
        return _policy_denied_response(e, "Document analysis")
    except Exception as e:
        logger.exception(
            f"Document analysis failed for collection: {collection_name if collection_name else 'empty'}"
        )
        return _error_result(e, operation="Document analysis failed")


@mcp.tool()
def search(
    query: str,
    engine: str,
    max_results: int = 10,
) -> Dict[str, Any]:
    """
    Search using a specific engine and return raw results without LLM processing.

    This tool performs a direct search query against the specified engine and
    returns raw results (title, link, snippet). No LLM is involved, making it
    fast and free of LLM costs.

    IMPORTANT: This is a fast operation, typically completing in 5-30 seconds.

    Args:
        query: The search query string.
        engine: Search engine to use (e.g., "arxiv", "wikipedia", "searxng", "brave").
                This is required — use list_search_engines() to see available options.
                For "wayback", the query must contain a full http:// or https://
                URL, or be only a bare domain such as example.com, optionally
                with a port, path or query. The complete URL, including its
                port, path, query and fragment, is looked up; words that
                follow a URL without a space become part of it. A URL with a
                user name or password before its host is not looked up, and
                at most max_results URLs are.
        max_results: Maximum number of results to return (1-100). Default is 10.

    Returns:
        Dictionary containing:
        - status: "success" or "error"
        - query: The original query
        - engine: The engine used
        - result_count: Number of results returned
        - results: List of results, each with title, link, and snippet
        - error/error_type: Error info (only if status is "error")
    """
    try:
        # Validate parameters
        query = _validate_query(query)
        max_results = _validate_max_results(max_results)

        # Validate engine is non-empty (required parameter)
        if not engine or not engine.strip():
            raise ValidationError(  # noqa: TRY301
                "Engine name cannot be empty. Use list_search_engines() to see available options."
            )
        engine = engine.strip()

        # Create settings snapshot (reused for all steps)
        settings = create_settings_snapshot()

        # Validate engine name against available engines
        from local_deep_research.web_search_engines.search_engines_config import (
            search_config,
        )

        engines_config = search_config(settings_snapshot=settings)
        if engine not in engines_config:
            available_names = sorted(engines_config.keys())
            raise ValidationError(  # noqa: TRY301
                f"Unknown search engine '{engine}'. Available: {', '.join(available_names)}"
            )

        # Check API key requirement
        engine_config = engines_config[engine]
        if engine_config.get("requires_api_key", False):
            api_key_setting = settings.get(
                f"search.engine.web.{engine}.api_key"
            )
            api_key = None
            if api_key_setting:
                api_key = (
                    api_key_setting.get("value")
                    if isinstance(api_key_setting, dict)
                    else api_key_setting
                )
            if not api_key:
                raise ValidationError(  # noqa: TRY301
                    f"Engine '{engine}' requires an API key. "
                    f"Set the LDR_SEARCH_ENGINE_WEB_{engine.upper()}_API_KEY environment variable "
                    f"or configure it in the UI at search.engine.web.{engine}.api_key"
                )

        logger.info(
            f"Starting search on '{engine}' for query: {query[:100]}..."
        )

        # Set thread-local settings context so that engine constructors
        # which internally call get_llm() or get_setting_from_snapshot()
        # (e.g., arxiv's JournalReputationFilter) can resolve settings.
        from local_deep_research.config.thread_settings import (
            clear_settings_context,
            set_settings_context,
        )
        from local_deep_research.settings.manager import SnapshotSettingsContext

        set_settings_context(SnapshotSettingsContext(settings))
        try:
            return _execute_search(query, engine, max_results, settings)
        finally:
            clear_settings_context()

    except ValidationError as e:
        logger.warning("Validation failed for search")
        return _error_result(e, error_type="validation_error")
    except PolicyDeniedError as e:
        return _policy_denied_response(e, "Search")
    except Exception as e:
        logger.exception(
            f"Search failed for query: {query[:100] if query else 'empty'}"
        )
        return _error_result(e, operation="Search failed")


def _egress_audit_net(settings: Dict[str, Any]):
    """Best-effort context manager that arms the egress audit-hook net for
    a direct MCP search.

    Direct MCP searches call ``engine.run()`` without going through
    ``AdvancedSearchSystem`` (which arms the net itself), so under
    PRIVATE_ONLY/STRICT the socket-level backstop would otherwise stay
    inactive for this path. Returns a nullcontext when the policy cannot
    be built or a context is already armed — the factory PEP remains the
    primary enforcement, and an unevaluable policy must not break MCP.
    """
    from contextlib import nullcontext

    try:
        from local_deep_research.security.egress.audit_hook import (
            active_egress_context,
            get_active_context,
        )
        from local_deep_research.security.egress.policy import (
            PolicyDeniedError,
            context_from_snapshot,
            resolve_run_primary_engine,
        )
    except Exception:
        return nullcontext()

    if not settings or get_active_context() is not None:
        return nullcontext()
    try:
        ctx = context_from_snapshot(
            settings,
            resolve_run_primary_engine(settings),
            username=settings.get("_username"),
        )
    except (PolicyDeniedError, ValueError):
        logger.bind(policy_audit=True).debug(
            "egress audit net not armed for MCP search: policy unevaluable",
            exc_info=True,
        )
        return nullcontext()
    except Exception:
        return nullcontext()
    return active_egress_context(ctx)


def _execute_search(
    query: str, engine: str, max_results: int, settings: Dict[str, Any]
) -> Dict[str, Any]:
    """Execute the search after settings context is established."""
    from local_deep_research.web_search_engines.search_engine_factory import (
        create_search_engine,
    )

    search_engine = create_search_engine(
        engine_name=engine,
        llm=None,
        settings_snapshot=settings,
        programmatic_mode=True,
        max_results=max_results,
    )

    if search_engine is None:
        return _error_result(
            f"Failed to create search engine '{engine}'. "
            f"This engine may require an LLM or have other prerequisites. "
            f"Check server logs for details.",
            error_type="configuration_error",
        )

    try:
        # Execute search with the egress audit-hook net armed (no-op
        # under scopes that don't arm it or when policy is unavailable).
        with _egress_audit_net(settings):
            results = search_engine.run(query)

        # Normalize results: ensure consistent 'snippet' key
        for result in results:
            if "snippet" not in result and "body" in result:
                result["snippet"] = result["body"]

        return {
            "status": "success",
            "query": query,
            "engine": engine,
            "result_count": len(results),
            "results": results,
        }
    finally:
        from local_deep_research.utilities.resource_utils import safe_close

        safe_close(search_engine, "MCP search engine")


# =============================================================================
# Discovery Tools
# =============================================================================


@mcp.tool()
def list_search_engines() -> Dict[str, Any]:
    """
    List available search engines.

    Returns a list of search engines that can be used with the research tools.
    Each engine has different strengths - some are better for academic research,
    others for current events, etc.

    Returns:
        Dictionary containing:
        - status: "success" or "error"
        - engines: List of available search engine configurations
        - error/error_type: Error info (only if status is "error")
    """
    try:
        from local_deep_research.api.settings_utils import (
            create_settings_snapshot,
        )
        from local_deep_research.web_search_engines.search_engines_config import (
            search_config,
        )

        settings = create_settings_snapshot()
        engines_config = search_config(settings_snapshot=settings)

        engines = []
        for name, config in engines_config.items():
            engine_info = {
                "name": name,
                "description": config.get("description", ""),
                "strengths": config.get("strengths", []),
                "weaknesses": config.get("weaknesses", []),
                "requires_api_key": config.get("requires_api_key", False),
                "is_local": config.get("is_local", False),
            }
            engines.append(engine_info)

        return {
            "status": "success",
            "engines": sorted(engines, key=lambda x: x["name"]),
        }

    except Exception as e:
        logger.exception("Failed to list search engines")
        return _error_result(e, operation="Failed to list search engines")


@mcp.tool()
def list_strategies() -> Dict[str, Any]:
    """
    List available research strategies.

    Returns a list of research strategies that can be used with the research tools.
    Each strategy has different characteristics suited for different types of queries.

    Returns:
        Dictionary containing:
        - status: "success" or "error"
        - strategies: List of available strategies with names and descriptions
        - error/error_type: Error info (only if status is "error")
    """
    try:
        return {
            "status": "success",
            "strategies": get_available_strategies(),
        }

    except Exception as e:
        logger.exception("Failed to list strategies")
        return _error_result(e, operation="Failed to list strategies")


@mcp.tool()
def get_configuration() -> Dict[str, Any]:
    """
    Get current server configuration.

    Returns the current configuration settings being used by the MCP server,
    including LLM provider, default search engine, and other settings.

    Returns:
        Dictionary containing:
        - status: "success" or "error"
        - config: Current configuration settings
        - error/error_type: Error info (only if status is "error")
    """
    try:
        from local_deep_research.api.settings_utils import (
            create_settings_snapshot,
            extract_setting_value,
        )

        settings = create_settings_snapshot()

        config = {
            "llm": {
                "provider": extract_setting_value(
                    settings, "llm.provider", "unknown"
                ),
                "model": extract_setting_value(
                    settings, "llm.model", "unknown"
                ),
                "temperature": extract_setting_value(
                    settings, "llm.temperature", 0.7
                ),
            },
            "search": {
                "default_engine": extract_setting_value(
                    settings, "search.tool", DEFAULT_SEARCH_TOOL
                ),
                "default_strategy": extract_setting_value(
                    settings, "search.search_strategy", "source-based"
                ),
                "iterations": extract_setting_value(
                    settings, "search.iterations", 2
                ),
                "questions_per_iteration": extract_setting_value(
                    settings, "search.questions_per_iteration", 3
                ),
                "max_results": extract_setting_value(
                    settings, "search.max_results", 10
                ),
            },
        }

        return {
            "status": "success",
            "config": config,
        }

    except Exception as e:
        logger.exception("Failed to get configuration")
        return _error_result(e, operation="Failed to get configuration")


# =============================================================================
# Server Entry Point
# =============================================================================


def configure_mcp_logging(sink=None):
    """Send this process's logs to stderr, with credentials redacted from
    log messages, bound ``extra`` fields and rendered exceptions (value,
    notes, chained and grouped exceptions), and control characters stripped.

    MCP uses stdout for JSON-RPC, so logging goes to stderr. This runs in a
    separate subprocess (ldr-mcp), so logger.remove() only affects this MCP
    process, not the main LDR application.
    """
    from ..security.log_sanitizer import redact_log_record

    logger.remove()
    # local_deep_research/__init__.py disables the package's own namespace, so
    # without this nothing logged from inside the package reaches the sink and
    # only third-party records get here. config_logger does the same on the
    # web path.
    logger.enable("local_deep_research")
    # The same redaction chokepoint config_logger's _sanitize_record installs
    # for the web process's sinks: control characters stripped (a query
    # containing a newline used to split one WARNING into two stderr lines)
    # AND credentials redacted (a bare api_key=/token= in a message, a secret
    # bound via logger.bind(), or one inside an exception logged by the
    # logger.exception() calls in this file), reaching this process's stderr
    # without going through scrub_error first. loguru holds one patcher per
    # process, so this has to be set here rather than inherited.
    # redact_log_record lives in security/log_sanitizer.py rather than
    # utilities/log_utils.py (which would pull in the web stack) precisely so
    # the MCP subprocess can share it.
    logger.configure(patcher=redact_log_record)
    # diagnose=False: loguru's default is True, which renders repr() of every
    # local in every traceback frame on exception. The many logger.exception()
    # call sites in this file run with frame locals that hold credentials
    # (api_key, Authorization headers, search-engine secrets), so leaving the
    # default on would write them to the MCP client's stderr log on any
    # failure. Companion to #4185 / config_logger's LDR_LOGURU_DIAGNOSE gate;
    # the MCP subprocess has no debug mode, so the gate is unconditionally off.
    #
    # enqueue=True: mirrors config_logger's stderr sink (utilities/log_utils.py).
    # Without it, this call blocks on stderr I/O while holding loguru's
    # handler lock, and when stderr back-pressures every logging thread piles
    # up behind that lock (#4431). The re-enable above (logger.enable(...))
    # means every INFO+ record from the whole research pipeline now reaches
    # this sink — that's exactly the condition #4431 was about, so this
    # sink needs the same protection. Note it's a bounded grace window
    # (roughly one queue pipe buffer, ~64KB on Linux), not immunity:
    # SimpleQueue.put() still runs inside emit()'s handler lock and blocks
    # once that buffer fills, so a stderr stall long enough to exhaust it
    # reproduces the same pile-up. Safe with the control-char patcher above
    # regardless: loguru applies core.patcher() to build the record and
    # formats the sink's output string before handing it to the enqueue
    # thread, so the message is already scrubbed by the time it's queued
    # (verified in loguru._logger.Logger._log / loguru._handler.Handler.emit).
    logger.add(
        sink if sink is not None else sys.stderr,
        level="INFO",
        format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} | {message}",
        diagnose=False,
        enqueue=True,
    )


def run_server():
    """Run the MCP server using STDIO transport."""
    configure_mcp_logging()

    # The drain `finally` opens immediately after the sink exists, not just
    # around `mcp.run()`: the startup window below logs through the same
    # enqueue=True sink, and the legacy-docstore sweep only catches
    # `Exception`. A KeyboardInterrupt/SystemExit raised inside
    # `migrate_legacy_docstores()` would otherwise escape with the startup
    # lines still queued and reproduce the very inversion this fixes.
    try:
        from ..security.process_dump_policy import enforce_process_dump_policy

        enforce_process_dump_policy()
        logger.info("Starting Local Deep Research MCP server...")

        # Phase-1 of the RAG plaintext-at-rest migration must run here too,
        # not only in the ldr-web entrypoint: an MCP-only deployment (Claude
        # Desktop / Code / OpenClaw) that never launches ldr-web would
        # otherwise never purge a pre-existing legacy plaintext <hash>.pkl
        # docstore, leaving chunk text on disk indefinitely. The sweep is
        # filesystem-only (no DB/login needed), idempotent (a clean tree
        # no-ops), and logs its own errors — wrapped so a cleanup issue never
        # blocks the server. Mirrors web/app.py's main().
        try:
            from ..vector_stores.legacy_cleanup import (
                migrate_legacy_docstores,
            )

            migrate_legacy_docstores()
        except Exception:
            logger.exception(
                "Legacy RAG docstore migration failed at MCP startup"
            )

        mcp.run(transport="stdio")
    finally:
        # Drain the enqueue=True stderr sink (see configure_mcp_logging)
        # before this function returns or raises, on every exit a
        # `finally` covers - normal disconnect, Exception, and BaseException
        # (KeyboardInterrupt) alike.
        #
        # loguru's enqueue=True handler runs a daemon writer thread reading
        # off a multiprocessing.SimpleQueue; loguru/__init__.py registers
        # `atexit.register(logger.remove)` for us, and draining (verified in
        # the installed loguru 0.7.3's _handler.py) is FIFO-sentinel based:
        # `Handler.stop()` enqueues a `None` sentinel and joins the writer
        # thread, so every message queued ahead of it is written first. On
        # its own, that atexit hook already keeps the *normal*-shutdown case
        # from losing buffered lines, as long as the interpreter reaches a
        # normal shutdown.
        #
        # What the atexit hook does NOT fix is ordering on an unhandled
        # exception. CPython's default excepthook prints the traceback to
        # stderr once the exception has finished propagating out of the top
        # frame, and only afterwards does the interpreter run its atexit
        # callbacks - so the atexit drain is strictly later than the
        # traceback. Without this `finally`, whatever is still sitting in
        # the queue when the exception is raised is written *after* the
        # traceback, so the client's stderr capture can read [traceback]
        # then [the log lines that led up to it], inverted from causal
        # order. (Only records still queued at raise time invert; anything
        # the writer thread already drained is unaffected.) Draining here,
        # in a `finally` around the server body, runs while the exception is
        # still propagating *through this frame* - strictly before it
        # reaches the top-level excepthook - so the log lines that explain
        # the crash are flushed first, then the traceback.
        #
        # This is `logger.complete()`, deliberately not `logger.remove()`
        # (verified in the installed loguru 0.7.3): `remove(None)` empties the
        # global handler table, so any record logged after this frame - a
        # caller catching the exception to log its own failure, or background
        # threads winding down - is silently dropped by `_log()`, which returns
        # early on `not core.handlers`. No caller does the former today: the
        # `ldr-mcp` console script (`pyproject.toml`:
        # `local_deep_research.mcp:run_server`) and `mcp/__main__.py`'s bare
        # `run_server()` call both invoke it with nothing wrapping the call to
        # catch and log a failure of its own. The property is kept as a general
        # guarantee `complete()` has over `remove()`, not a fix for an existing
        # caller. `complete()` drains the same queue (per enqueue handler it
        # enqueues a `True` confirmation token FIFO, then waits on the writer's
        # confirmation event) while *retaining* every handler, so those later
        # records still reach the sink. Sink teardown stays with its owner:
        # loguru's atexit-registered `logger.remove()`.
        #
        # Boundedness, precisely: the *enqueue* side is byte-bounded
        # back-pressure (SimpleQueue.put() runs under the handler lock and
        # stalls producers once the pipe buffer fills - the #4431 / #5804
        # window), but the drain itself is not time-bounded. The confirmation
        # wait in `Handler.complete_queue()` passes no timeout, so a sink that
        # blocks indefinitely blocks this `finally` indefinitely;
        # `Logger.complete()` additionally holds `_core.lock` across that wait,
        # so a concurrent `add`/`remove`/`configure` would block for the same
        # duration (ordinary logging would not - `_log()` never takes that
        # lock), and `tasks_to_complete()` briefly takes `_queue_lock`, the
        # same lock the writer thread holds around `sink.write()`. loguru
        # offers no honest bound to add here, so we accept the same
        # unbounded-in-time wait the writer thread already needs to drain its
        # queue. One practical consequence: a shutdown Ctrl-C now lands
        # *inside* this drain, so a second Ctrl-C raises KeyboardInterrupt out
        # of the `finally`, abandoning the drain and replacing whatever
        # exception was propagating.
        #
        # One case that leaves out: a *dead* writer thread. `complete_queue()`
        # first does `self._queue.put(True)` - which can itself block on a full
        # pipe before the wait even starts, while holding both
        # `Logger.complete()`'s `_core.lock` and its own `_confirmation_lock` -
        # then waits on `_confirmation_event` with no timeout and no check that
        # the writer thread is still alive to ever call `.set()` on it. If that
        # thread has already died, `logger.complete()` never returns.
        # `Handler.stop()` does not share this gap: `Thread.join()` returns
        # immediately once its target thread has already finished, so a dead
        # writer thread hangs `complete_queue()`, not `stop()`. Not reachable
        # with the shipped sink: it defaults to `sys.stderr`, which CPython
        # pins to `errors='backslashreplace'`, and a broken pipe raises
        # `OSError`, which `ErrorInterceptor.print()` (`_error_interceptor.py`)
        # itself catches around its own `sys.stderr.write()` when it reports a
        # sink failure - so the writer thread's loop keeps running. It becomes
        # reachable only if `sys.stderr` itself, not just this function's
        # `sink` argument, is ever pointed at a stream whose `write()` can
        # raise something other than `OSError`, since `ErrorInterceptor` always
        # reports to `sys.stderr` directly, independent of the handler's
        # configured sink. `Logger.enable()` and `.disable()` also take
        # `_core.lock` (`_logger.py`'s `_change_activation()`, ~line 1782), so
        # the full list of calls this drain can block is
        # `add`/`remove`/`configure`/`enable`/`disable`.
        #
        # Limit, not a regression: SIGTERM under its default disposition
        # kills the process outright and never runs this `finally` (nor
        # loguru's atexit hook), so anything still queued is lost - which is
        # what `scripts/mcp_smoke_test.sh`'s `timeout 5` does. Only in-band
        # exits (return, exception, KeyboardInterrupt) are covered.
        logger.complete()


if __name__ == "__main__":
    run_server()