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.

45.3 KB
Raw Blame
"""Contracts for the non-web entry points: ``ldr-web`` and ``ldr-mcp``.

These are the only ``[project.scripts]`` entries, and ``ldr-mcp`` (plus
``python -m local_deep_research.mcp``) is the only way into the research
core that never goes through a FastAPI request.  That makes it the one
caller for which nothing sets the request-context username, nothing
opens a per-user SQLCipher database, and nothing runs the settings /
egress / auth checks the web routers apply.

Why this file exists at ``tests/`` root rather than under ``tests/mcp/``:

  * SDK-dependent tests under ``tests/mcp/`` require the installed extra
    (see ``tests/mcp/test_server_validators.py``), and the default unit
    suite does NOT install the ``[mcp]`` extra, so those tests are skipped
    there;
  * ``.github/workflows/mcp-tests.yml`` installs the extra and also runs
    this file, but only triggers on changes to the MCP code, tests, or
    workflow.

These root-level tests also cover changes to ``utilities/db_utils.py``,
``settings/``, or ``api/research_functions.py`` that do not trigger the
dedicated MCP job. They stub the ``mcp`` package boundary when it is absent
so they run in the default suite; the dedicated job verifies them against
the installed SDK too.

No server is started, no LLM is called, and no network request is made:
the FastMCP boundary is stubbed, ``run_server``'s transport call is
patched, and ``get_llm`` is patched to a sentinel so that if a guard
under test ever stops firing the test fails loudly instead of dialling
out.
"""

from __future__ import annotations

import ast
import json
import sys
import threading
import tomllib
import types
from pathlib import Path
from unittest.mock import patch

import anyio
import anyio.to_thread
import pytest
from loguru import logger

from tests.mcp_sdk import is_mcp_installed

REPO_ROOT = Path(__file__).resolve().parents[1]
SRC_ROOT = REPO_ROOT / "src"
PYPROJECT = REPO_ROOT / "pyproject.toml"

# The thread name the MCP Python SDK's sync-tool dispatch produces:
# FastMCP hands a non-async tool to ``anyio.to_thread.run_sync``.
# ``test_anyio_worker_thread_is_not_mainthread`` pins that this really is
# what anyio names its workers, so the constant is not folklore.
ANYIO_WORKER_THREAD_NAME = "AnyIO worker thread"

# Resolved at import time, BEFORE the fixture below may install a stub
# ``mcp`` in sys.modules -- otherwise the two real-SDK tests would happily
# run against the stub and assert nothing.
REAL_MCP_INSTALLED = is_mcp_installed()

requires_real_mcp = pytest.mark.skipif(
    not REAL_MCP_INSTALLED, reason="[mcp] extra not installed"
)


def test_mcp_availability_does_not_accept_a_namespace_or_stub(monkeypatch):
    from importlib.metadata import PackageNotFoundError

    from tests import mcp_sdk

    namespace = types.ModuleType("mcp")
    namespace.__path__ = [str(REPO_ROOT / "tests" / "mcp")]
    monkeypatch.setitem(sys.modules, "mcp", namespace)

    def absent(_name):
        raise PackageNotFoundError("mcp")

    monkeypatch.setattr(mcp_sdk, "distribution", absent)
    assert not mcp_sdk.is_mcp_installed()


def test_installed_but_broken_mcp_is_not_silently_skipped(monkeypatch):
    from tests import mcp_sdk

    monkeypatch.setattr(mcp_sdk, "distribution", lambda _name: object())
    monkeypatch.setitem(sys.modules, "mcp", None)
    assert mcp_sdk.is_mcp_installed()
    with pytest.raises(ModuleNotFoundError):
        __import__("mcp")


# ---------------------------------------------------------------------------
# Loading local_deep_research.mcp.server without the [mcp] extra
# ---------------------------------------------------------------------------


class _StubFastMCP:
    """Stand-in for ``mcp.server.fastmcp.FastMCP``.

    Only the three members ``server.py`` touches are modelled: the
    constructor, the ``tool()`` decorator (which, like the real SDK,
    returns the undecorated function so the module-level names stay
    directly callable), and ``run()``.
    """

    def __init__(self, name, instructions=None, **kwargs):
        self.name = name
        self.instructions = instructions
        self.registered_tools = []
        self.run_calls = []

    def tool(self, *args, **kwargs):
        def decorator(fn):
            self.registered_tools.append(fn.__name__)
            return fn

        return decorator

    def run(self, transport=None, **kwargs):
        self.run_calls.append(transport)


def _install_mcp_stub():
    """Register a minimal ``mcp.server.fastmcp`` in ``sys.modules``."""
    pkg = types.ModuleType("mcp")
    server = types.ModuleType("mcp.server")
    fastmcp = types.ModuleType("mcp.server.fastmcp")
    fastmcp.FastMCP = _StubFastMCP
    pkg.server = server
    server.fastmcp = fastmcp
    sys.modules["mcp"] = pkg
    sys.modules["mcp.server"] = server
    sys.modules["mcp.server.fastmcp"] = fastmcp


@pytest.fixture(scope="module")
def mcp_server():
    """Import ``local_deep_research.mcp.server``, stubbing ``mcp`` if needed.

    ``sys.modules`` is restored afterwards so later tests see the original
    SDK/module state on the same worker.
    """
    saved = {
        name: sys.modules.get(name)
        for name in (
            "mcp",
            "mcp.server",
            "mcp.server.fastmcp",
            "local_deep_research.mcp",
            "local_deep_research.mcp.server",
        )
    }
    if not REAL_MCP_INSTALLED:
        _install_mcp_stub()
        # A preceding classifier test may have loaded these tools using a
        # different SDK stub. Rebind the tools to this fixture's faithful
        # decorator instead of reusing functions wrapped in MagicMock.
        sys.modules.pop("local_deep_research.mcp.server", None)
        sys.modules.pop("local_deep_research.mcp", None)

    try:
        import local_deep_research.mcp.server as server_module

        yield server_module
    finally:
        for name, module in saved.items():
            if module is None:
                sys.modules.pop(name, None)
            else:
                sys.modules[name] = module
        import local_deep_research

        if saved["local_deep_research.mcp"] is None:
            # Drop the attribute the import bound on the parent package too.
            if getattr(local_deep_research, "mcp", None) is not None:
                delattr(local_deep_research, "mcp")
        else:
            local_deep_research.mcp = saved["local_deep_research.mcp"]


@pytest.fixture
def no_llm_escape_hatch():
    """Hard-stop every LLM/search construction inside the research API.

    The defect these tests pin raises *before* the API function body runs.
    Patching here means that if the guard is ever removed the test sees
    ``_EscapeHatch`` rather than a real provider call, so the suite can
    never make a network request while proving a negative.
    """

    class _EscapeHatch(RuntimeError):
        pass

    def _boom(*args, **kwargs):
        raise _EscapeHatch(
            "reached LLM/search construction -- the thread-context guard "
            "no longer fires"
        )

    target = "local_deep_research.api.research_functions"
    with (
        patch(f"{target}.get_llm", side_effect=_boom),
        patch(f"{target}.get_search", side_effect=_boom),
    ):
        yield _EscapeHatch


def _run_off_mainthread(fn, *args, **kwargs):
    """Call *fn* on a thread named exactly like an MCP sync-tool worker."""
    box = {}

    def target():
        try:
            box["value"] = fn(*args, **kwargs)
        except BaseException as exc:  # noqa: BLE001 - re-raised below
            box["error"] = exc

    thread = threading.Thread(target=target, name=ANYIO_WORKER_THREAD_NAME)
    thread.start()
    thread.join(timeout=60)
    assert not thread.is_alive(), f"{fn} hung off MainThread"
    if "error" in box:
        raise box["error"]
    return box["value"]


# ---------------------------------------------------------------------------
# Static resolution of the declared console scripts
# ---------------------------------------------------------------------------


def _declared_scripts() -> dict[str, str]:
    data = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
    return data["project"]["scripts"]


def _module_source_path(dotted: str) -> Path | None:
    base = SRC_ROOT / Path(*dotted.split("."))
    for candidate in (base.with_suffix(".py"), base / "__init__.py"):
        if candidate.is_file():
            return candidate
    return None


def _top_level_names(path: Path) -> set[str]:
    """Names a module binds at import time, without importing it."""
    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
    names: set[str] = set()
    for node in tree.body:
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            names.add(node.name)
        elif isinstance(node, ast.ClassDef):
            names.add(node.name)
        elif isinstance(node, ast.Assign):
            for tgt in node.targets:
                if isinstance(tgt, ast.Name):
                    names.add(tgt.id)
        elif isinstance(node, ast.AnnAssign) and isinstance(
            node.target, ast.Name
        ):
            names.add(node.target.id)
        elif isinstance(node, (ast.Import, ast.ImportFrom)):
            for alias in node.names:
                names.add(alias.asname or alias.name.split(".")[0])
    return names


class TestDeclaredEntryPoints:
    """``[project.scripts]`` targets must exist in the tree.

    The wheel-level equivalent of this check lives in
    ``release-gate.yml`` (``entry_points().load()``), which runs only at
    release time -- after the dead ``ldr = ...main:main`` entry had
    already shipped broken "for every release since", per the comment
    that still sits above these lines in pyproject.toml.  This is the
    per-PR version, and it needs neither an install nor the [mcp] extra.
    """

    def test_every_declared_script_target_exists(self):
        scripts = _declared_scripts()
        assert set(scripts) == {"ldr-web", "ldr-mcp"}, (
            "console_scripts changed; the entry-point smoke in "
            f"release-gate.yml pins exactly ldr-web/ldr-mcp, got {scripts}"
        )
        for name, target in scripts.items():
            module_name, _, attribute = target.partition(":")
            assert attribute, f"{name} -> {target} names no attribute"
            path = _module_source_path(module_name)
            assert path is not None, (
                f"console_script {name} points at module {module_name!r}, "
                "which does not exist under src/ (this is exactly the "
                "'ldr -> main:main' failure mode)"
            )
            assert attribute in _top_level_names(path), (
                f"console_script {name} -> {target}: {path} does not bind "
                f"a top-level name {attribute!r}"
            )

    def test_module_entry_point_calls_run_server(self):
        """``python -m local_deep_research.mcp`` is a documented entry."""
        path = SRC_ROOT / "local_deep_research" / "mcp" / "__main__.py"
        source = path.read_text(encoding="utf-8")
        tree = ast.parse(source, filename=str(path))

        imported_from_server = {
            alias.name
            for node in tree.body
            if isinstance(node, ast.ImportFrom) and node.module == "server"
            for alias in node.names
        }
        assert "run_server" in imported_from_server, (
            "__main__.py must import run_server from .server; got "
            f"{imported_from_server}"
        )

        guarded_calls = [
            child.func.id
            for node in tree.body
            if isinstance(node, ast.If)
            for child in ast.walk(node)
            if isinstance(child, ast.Call) and isinstance(child.func, ast.Name)
        ]
        assert "run_server" in guarded_calls, (
            "__main__.py must call run_server() under the "
            "`if __name__ == '__main__'` guard"
        )

    def test_neither_entry_point_reads_argv(self):
        """Argv is not an input surface for either script.

        release-gate.yml records that "neither parses --help".  That is a
        deliberate contract, and it is also the argument-validation
        answer for these entry points: a hostile ``ldr-web --host
        0.0.0.0`` or ``ldr-mcp --transport sse`` cannot change the bind
        address or the transport, because argv is never consulted.  If
        someone adds argv parsing, this test fires and the hostile-input
        surface has to be reviewed.
        """
        for rel in ("web/app.py", "mcp/server.py", "mcp/__main__.py"):
            path = SRC_ROOT / "local_deep_research" / rel
            tree = ast.parse(path.read_text(encoding="utf-8"))
            argv_reads = [
                node
                for node in ast.walk(tree)
                if isinstance(node, ast.Attribute)
                and node.attr == "argv"
                and isinstance(node.value, ast.Name)
                and node.value.id == "sys"
            ]
            assert not argv_reads, (
                f"{rel} now reads sys.argv; the entry points are documented "
                "as taking no arguments and nothing validates them"
            )

    def test_mcp_transport_is_a_hardcoded_stdio_literal(self):
        """The MCP server ships with no auth -- stdio must not be tunable.

        ``mcp/server.py``'s own Security Notice says the server "has no
        built-in authentication or rate limiting" and that security comes
        from OS user permissions under STDIO.  That guarantee only holds
        while the transport is a literal: an env-var or argv-driven
        transport would turn the same unauthenticated tool surface into a
        network listener.
        """
        path = SRC_ROOT / "local_deep_research" / "mcp" / "server.py"
        tree = ast.parse(path.read_text(encoding="utf-8"))
        transports = [
            kw.value
            for node in ast.walk(tree)
            if isinstance(node, ast.Call)
            and isinstance(node.func, ast.Attribute)
            and node.func.attr == "run"
            for kw in node.keywords
            if kw.arg == "transport"
        ]
        assert transports, "no mcp.run(transport=...) call found"
        for value in transports:
            assert isinstance(value, ast.Constant), (
                "mcp.run(transport=...) must be a literal; a computed "
                "transport can expose the unauthenticated tool surface "
                "over the network"
            )
            assert value.value == "stdio", (
                f"transport literal is {value.value!r}, expected 'stdio'"
            )


# ---------------------------------------------------------------------------
# The entry point still imports, and still exposes its tool surface
# ---------------------------------------------------------------------------


class TestMcpModuleSurface:
    @pytest.fixture(autouse=True)
    def _loguru_core_untouched(self):
        """run_server() must not reconfigure the worker's logger.

        It calls ``configure_mcp_logging``, which runs ``logger.enable``
        and ``logger.configure(patcher=...)`` against loguru's single
        per-process ``_core``.  Mocking ``logger.remove`` and
        ``logger.add`` lets both of those through, and
        ``logger.configure(patcher=None)`` does not undo them afterwards:
        ``None`` means "leave unchanged".  This file runs in the default
        unit suite, so anything left behind reaches every later test on
        the same xdist worker.
        """
        core = logger._core
        before = (
            core.patcher,
            list(core.activation_list),
            core.activation_none,
        )
        yield
        assert (
            core.patcher,
            list(core.activation_list),
            core.activation_none,
        ) == before

    def test_server_module_exposes_the_documented_tool_surface(
        self, mcp_server
    ):
        """Floor assertion for "it still imports" after the port.

        The module docstring enumerates eight tools; ``ldr-mcp`` resolves
        ``run_server``.  An empty or half-imported module fails here.
        """
        expected = {
            "quick_research",
            "detailed_research",
            "generate_report",
            "analyze_documents",
            "search",
            "list_search_engines",
            "list_strategies",
            "get_configuration",
        }
        exported = {
            name
            for name in expected
            if callable(getattr(mcp_server, name, None))
        }
        assert exported == expected, f"missing MCP tools: {expected - exported}"
        assert callable(mcp_server.run_server)
        assert mcp_server.mcp is not None

    def test_run_server_starts_on_stdio_and_survives_a_failed_migration(
        self, mcp_server
    ):
        """The startup path runs end to end without binding anything.

        ``run_server`` also runs the plaintext-docstore sweep, which its
        own comment says must never block the server.  Both halves are
        pinned here because a raise from the sweep would leave an
        MCP-only deployment with no server at all.
        """
        migrate = "local_deep_research.vector_stores.legacy_cleanup"
        with (
            patch.object(mcp_server.mcp, "run") as run,
            patch(
                f"{migrate}.migrate_legacy_docstores",
                side_effect=OSError("disk gone"),
            ) as migrated,
            patch.object(mcp_server, "logger") as mcp_logger,
        ):
            mcp_server.run_server()

        assert migrated.called, "legacy docstore sweep was not attempted"
        run.assert_called_once()
        assert run.call_args.kwargs.get("transport") == "stdio"

        add_sink = mcp_logger.add
        add_sink.assert_called_once()
        sink = add_sink.call_args.args[0]
        assert sink is sys.stderr, (
            "MCP speaks JSON-RPC on stdout; the log sink must be stderr, "
            f"got {sink!r}"
        )
        assert add_sink.call_args.kwargs.get("diagnose") is False, (
            "loguru diagnose=True renders repr() of frame locals holding "
            "api keys into the MCP client's log"
        )


class TestMcpProcessDumpPolicy:
    def test_policy_runs_before_migration_and_stdio(
        self, mcp_server, monkeypatch
    ):
        from local_deep_research.security import process_dump_policy
        from local_deep_research.vector_stores import legacy_cleanup

        order = []
        monkeypatch.setattr(mcp_server, "configure_mcp_logging", lambda: None)
        monkeypatch.setattr(
            mcp_server,
            "logger",
            types.SimpleNamespace(
                info=lambda *_args: None, complete=lambda: None
            ),
        )
        monkeypatch.setattr(
            process_dump_policy,
            "enforce_process_dump_policy",
            lambda: order.append("policy"),
        )
        monkeypatch.setattr(
            legacy_cleanup,
            "migrate_legacy_docstores",
            lambda: order.append("migration"),
        )
        monkeypatch.setattr(
            mcp_server.mcp, "run", lambda **_kwargs: order.append("stdio")
        )

        mcp_server.run_server()

        assert order == ["policy", "migration", "stdio"]

    def test_policy_failure_stops_stdio_and_drains_logger(
        self, mcp_server, monkeypatch
    ):
        from unittest.mock import Mock

        from local_deep_research.security import process_dump_policy
        from local_deep_research.vector_stores import legacy_cleanup

        log = Mock()
        migrate = Mock()
        serve = Mock()
        monkeypatch.setattr(mcp_server, "configure_mcp_logging", lambda: None)
        monkeypatch.setattr(mcp_server, "logger", log)
        monkeypatch.setattr(legacy_cleanup, "migrate_legacy_docstores", migrate)
        monkeypatch.setattr(mcp_server.mcp, "run", serve)
        monkeypatch.setattr(
            process_dump_policy,
            "enforce_process_dump_policy",
            Mock(
                side_effect=process_dump_policy.ProcessDumpPolicyError(
                    "synthetic refusal"
                )
            ),
        )

        with pytest.raises(process_dump_policy.ProcessDumpPolicyError):
            mcp_server.run_server()

        migrate.assert_not_called()
        serve.assert_not_called()
        log.complete.assert_called_once_with()


class TestWebEntryPoint:
    def test_main_launches_uvicorn_with_the_resolved_config(self):
        """``ldr-web`` still reaches uvicorn after the port (no socket)."""
        from local_deep_research.web import app as web_app

        config = {
            "host": "127.0.0.1",
            "port": 5000,
            "debug": False,
            "use_https": False,
        }
        with (
            patch.object(web_app, "load_server_config", return_value=config),
            patch.object(web_app, "config_logger"),
            patch.object(web_app, "_run_with_uvicorn") as run,
            patch(
                "local_deep_research.vector_stores.legacy_cleanup"
                ".migrate_legacy_docstores"
            ),
        ):
            web_app.main()

        run.assert_called_once_with("127.0.0.1", 5000, False)

    def test_main_reraises_so_a_dead_server_exits_nonzero(self):
        """``@logger.catch(reraise=True)`` is load-bearing.

        Without the re-raise a fatal startup error is logged, ``main()``
        returns None, and the console script exits 0 -- so systemd
        ``Restart=on-failure`` reads a dead server as a clean shutdown.
        """
        from local_deep_research.web import app as web_app

        config = {
            "host": "127.0.0.1",
            "port": 5000,
            "debug": False,
            "use_https": False,
        }
        with (
            patch.object(web_app, "load_server_config", return_value=config),
            patch.object(web_app, "config_logger"),
            patch.object(
                web_app,
                "_run_with_uvicorn",
                side_effect=RuntimeError("secret key unavailable"),
            ),
            patch(
                "local_deep_research.vector_stores.legacy_cleanup"
                ".migrate_legacy_docstores"
            ),
            pytest.raises(RuntimeError, match="secret key unavailable"),
        ):
            web_app.main()


# ---------------------------------------------------------------------------
# Context resolution -- the headline defect
# ---------------------------------------------------------------------------


class TestThreadContextResolution:
    """Every MCP research tool dies IF ever dispatched off MainThread.

    ``utilities/db_utils.get_db_session`` raises ``RuntimeError`` for a
    caller with no username once ``threading.current_thread().name !=
    "MainThread"``.  All four research entry points in
    ``api/research_functions`` are decorated with ``@no_db_settings``,
    whose wrapper calls ``get_settings_manager()`` -- with no session and
    no username -- as its very first statement, before the wrapped body.
    ``get_settings_manager`` deliberately catches only
    ``NoUserDatabaseError``, so the guard's ``RuntimeError`` propagates.

    The MCP server never resolves a username (its snapshots come from
    ``create_settings_snapshot()``, which is DB-free by design), so the
    thread identity is the only variable. As of ``mcp==1.29.1`` (pinned in
    pdm.lock), ``FastMCP.call_tool`` -> ``ToolManager.call_tool`` ->
    ``Tool.run`` -> ``func_metadata.call_fn_with_arg_validation`` calls a
    sync tool function directly (``return fn(**arguments)``) with no
    ``anyio.to_thread.run_sync`` in the path -- verified by reading
    ``mcp/server/fastmcp/utilities/func_metadata.py`` and confirmed by
    ``test_fastmcp_dispatches_sync_tools_on_mainthread`` below. So this
    defect is not reachable through the real SDK's dispatch today; the
    off-MainThread tests in this class exist as a regression guard for the
    guard logic itself (and for the day the SDK's dispatch changes again),
    using ``_run_off_mainthread`` to force the condition artificially.
    """

    RESEARCH_TOOLS = (
        ("quick_research", ("q",), {}),
        ("detailed_research", ("q",), {}),
        ("generate_report", ("q",), {}),
        ("analyze_documents", ("q", "mycollection"), {}),
    )

    def test_anyio_worker_thread_is_not_mainthread(self):
        """Pin the mechanism, not folklore about the MCP SDK."""

        def observe():
            return threading.current_thread().name

        name = anyio.run(anyio.to_thread.run_sync, observe)
        assert name != "MainThread"
        assert name == ANYIO_WORKER_THREAD_NAME, (
            "anyio renamed its worker threads; the constant used by these "
            f"tests is stale (got {name!r})"
        )

    def test_no_db_settings_raises_for_a_no_username_worker(self):
        """The guard fires in the decorator, before the wrapped body."""
        from local_deep_research.utilities.db_utils import no_db_settings

        body_ran = []

        @no_db_settings
        def wrapped():
            body_ran.append(True)
            return "ok"

        assert wrapped() == "ok", (
            "control: on MainThread with no username the decorator degrades "
            "to defaults instead of raising"
        )
        assert body_ran == [True]

        with pytest.raises(RuntimeError, match="background thread"):
            _run_off_mainthread(wrapped)
        assert body_ran == [True], (
            "the wrapped body must not have run off MainThread"
        )

    @pytest.mark.parametrize(
        "func_name",
        [
            "quick_summary",
            "detailed_research",
            "generate_report",
            "analyze_documents",
        ],
    )
    def test_research_api_refuses_every_worker_thread_call(
        self, func_name, no_llm_escape_hatch
    ):
        """DEFECT: the whole programmatic research API is MainThread-only.

        ``no_llm_escape_hatch`` guarantees the failure below is the
        context guard and not a provider call: if the guard stopped
        firing we would see ``_EscapeHatch`` instead.
        """
        from local_deep_research.api import research_functions

        func = getattr(research_functions, func_name)
        args = (
            ("q", "mycollection")
            if func_name == "analyze_documents"
            else ("q",)
        )

        with pytest.raises(RuntimeError) as excinfo:
            _run_off_mainthread(func, *args)

        message = str(excinfo.value)
        assert not isinstance(excinfo.value, no_llm_escape_hatch), (
            "reached LLM construction -- the guard no longer fires"
        )
        assert ANYIO_WORKER_THREAD_NAME in message
        assert "no request context" in message

    @pytest.mark.parametrize("tool_name, args, kwargs", RESEARCH_TOOLS)
    def test_mcp_research_tools_degrade_to_an_opaque_error_off_mainthread(
        self, mcp_server, no_llm_escape_hatch, tool_name, args, kwargs
    ):
        """DEFECT: the client is told nothing useful.

        The tool's blanket ``except Exception`` turns the context
        RuntimeError into ``error_type: "unknown"`` with "Check server
        logs for details" -- so an MCP-only deployment sees every
        research tool fail with a message that names neither the cause
        nor a fix.
        """
        recorded = []
        original = mcp_server._error_result

        def recorder(error, **kw):
            recorded.append(error)
            return original(error, **kw)

        tool = getattr(mcp_server, tool_name)
        with patch.object(mcp_server, "_error_result", side_effect=recorder):
            result = _run_off_mainthread(tool, *args, **kwargs)

        assert result["status"] == "error"
        assert result["error_type"] == "unknown", (
            f"{tool_name} classified the context failure as "
            f"{result['error_type']!r}"
        )
        assert "Check server logs" in result["error"]
        assert recorded, f"{tool_name} did not go through _error_result"
        cause = recorded[-1]
        assert isinstance(cause, RuntimeError), (
            f"{tool_name} failed for an unexpected reason: {cause!r}"
        )
        assert not isinstance(cause, no_llm_escape_hatch)
        assert "no request context" in str(cause)

    def test_same_tool_succeeds_on_mainthread(self, mcp_server):
        """Positive control: thread identity is the only difference."""
        payload = {
            "summary": "s",
            "findings": [],
            "sources": [],
            "iterations": 1,
            "formatted_findings": "",
        }
        with patch.object(
            mcp_server, "ldr_quick_summary", return_value=payload
        ) as stub:
            assert threading.current_thread().name == "MainThread"
            result = mcp_server.quick_research("q")
        assert result["status"] == "success"
        assert stub.call_count == 1

    @requires_real_mcp
    def test_fastmcp_dispatches_sync_tools_on_mainthread(self):
        """Run the real SDK dispatch when the [mcp] extra is installed.

        As of ``mcp==1.29.1`` sync tools run inline on the calling thread
        (see the class docstring). ``run_server()`` calls ``mcp.run()``
        on whatever thread invokes it -- MainThread for the ``ldr-mcp``
        CLI entry point -- so real MCP research-tool calls hit the
        MainThread-success path (``test_same_tool_succeeds_on_mainthread``),
        not the off-MainThread defect this class otherwise guards against.
        If a future SDK version reintroduces off-thread dispatch (e.g. via
        ``anyio.to_thread.run_sync``), this assertion will flip and flag
        that the defect is reachable again.
        """
        import asyncio

        from mcp.server.fastmcp import FastMCP

        assert FastMCP is not _StubFastMCP, "the stub leaked into sys.modules"
        server = FastMCP("dispatch-probe")
        observed = []

        @server.tool()
        def probe() -> str:
            observed.append(threading.current_thread().name)
            return "done"

        try:
            asyncio.run(server.call_tool("probe", {}))
        except TypeError as exc:  # pragma: no cover - SDK API drift
            pytest.skip(f"FastMCP.call_tool signature changed: {exc}")

        assert observed, "the tool body never ran"
        assert observed[0] == "MainThread", (
            "FastMCP no longer runs sync tools on MainThread; the "
            "db_utils context guard now breaks every MCP research tool "
            "again (see the class docstring) -- this is the DEFECT this "
            "class documents becoming reachable through the real SDK, not "
            "a test bug. Do not just flip this assertion back."
        )


# ---------------------------------------------------------------------------
# Credential handling
# ---------------------------------------------------------------------------


class TestCredentialHandling:
    def test_mcp_never_needs_a_sqlcipher_passphrase(self, mcp_server):
        """No per-user database is opened, so no passphrase is required.

        This is the reason ``ldr-mcp`` can run headless from Claude
        Desktop at all -- and it is the invariant that would break the
        moment a tool started resolving a user.  ``db_manager.get_session``
        is the single door to a SQLCipher database; it must stay shut.
        """
        from local_deep_research.database import encrypted_db

        opened = []

        def refuse(self, *args, **kwargs):
            opened.append(args)
            raise AssertionError(
                f"MCP opened a per-user encrypted database: {args!r}"
            )

        with patch.object(type(encrypted_db.db_manager), "get_session", refuse):
            for tool_name in (
                "get_configuration",
                "list_strategies",
                "list_search_engines",
            ):
                result = getattr(mcp_server, tool_name)()
                assert result["status"] == "success", (
                    f"{tool_name} failed: {result.get('error')}"
                )
        assert opened == []

    def test_discovery_tools_do_not_echo_configured_api_keys(
        self, mcp_server, monkeypatch
    ):
        """Env-supplied secrets must not come back out through a tool.

        ``create_settings_snapshot()`` folds every ``LDR_*`` override into
        the snapshot, api keys included, so a tool that returned the
        snapshot wholesale would hand the MCP client the operator's
        credentials.
        """
        sentinel = "SENTINEL-LEAKY-KEY-a1b2c3"
        monkeypatch.setenv("LDR_LLM_OPENAI_API_KEY", sentinel)
        monkeypatch.setenv("LDR_SEARCH_ENGINE_WEB_BRAVE_API_KEY", sentinel)
        monkeypatch.setenv("LDR_LLM_PROVIDER", "openai")

        config = mcp_server.get_configuration()
        assert config["status"] == "success"
        # Floor: the snapshot really did pick up the environment, so the
        # absence of the sentinel below is not "everything was empty".
        assert config["config"]["llm"]["provider"] == "openai"

        engines = mcp_server.list_search_engines()
        assert engines["status"] == "success"
        assert engines["engines"], "no engines returned"

        for name, payload in (
            ("get_configuration", config),
            ("list_search_engines", engines),
        ):
            assert sentinel not in json.dumps(payload, default=str), (
                f"{name} echoed an LDR_*_API_KEY value to the MCP client"
            )

    def test_credentials_never_reach_argv_or_a_child_process(self):
        """Nothing in the entry points spawns a process with secrets.

        A passphrase or api key placed on a command line is world-readable
        via /proc; the cheapest guarantee is that these entry points never
        build one.
        """
        for rel in ("mcp/server.py", "mcp/__main__.py", "web/app.py"):
            path = SRC_ROOT / "local_deep_research" / rel
            tree = ast.parse(path.read_text(encoding="utf-8"))
            spawns = [
                node.func.attr
                for node in ast.walk(tree)
                if isinstance(node, ast.Call)
                and isinstance(node.func, ast.Attribute)
                and node.func.attr
                in {"Popen", "run", "call", "check_output", "system", "execv"}
                and isinstance(node.func.value, ast.Name)
                and node.func.value.id in {"subprocess", "os"}
            ]
            assert not spawns, (
                f"{rel} spawns a subprocess ({spawns}); review whether any "
                "credential can land in its argv"
            )


# ---------------------------------------------------------------------------
# Hostile arguments
# ---------------------------------------------------------------------------


class TestHostileArguments:
    """Tool parameters are the MCP server's real input surface.

    An MCP client is an LLM: the arguments are attacker-influenceable in
    any deployment where the model reads untrusted content.  Each case
    below asserts the *backend was never reached*, not merely that an
    error came back.
    """

    @pytest.mark.parametrize(
        "collection_name",
        [
            "../../etc/passwd",
            "a/../../b",
            "..\\..\\windows\\system32",
            "coll\x00truncated",
            "$(id)",
            "coll; rm -rf /",
            "x" * 101,
        ],
    )
    def test_analyze_documents_rejects_hostile_collection_names(
        self, mcp_server, collection_name
    ):
        with patch.object(mcp_server, "ldr_analyze_documents") as backend:
            result = mcp_server.analyze_documents("query", collection_name)

        assert result["status"] == "error"
        assert result["error_type"] == "validation_error"
        assert backend.call_count == 0, (
            f"{collection_name!r} reached the RAG backend"
        )

    def test_analyze_documents_accepts_a_legitimate_name(self, mcp_server):
        """Control: the regex is not simply rejecting everything."""
        with patch.object(
            mcp_server,
            "ldr_analyze_documents",
            return_value={"summary": "s", "documents": []},
        ) as backend:
            result = mcp_server.analyze_documents("query", "My Docs_2024-a")

        assert result["status"] == "success"
        assert backend.call_count == 1
        assert backend.call_args.kwargs["collection_name"] == "My Docs_2024-a"

    def test_search_rejects_an_unknown_engine_before_the_factory(
        self, mcp_server
    ):
        factory = (
            "local_deep_research.web_search_engines.search_engine_factory"
            ".create_search_engine"
        )
        with patch(factory) as create:
            result = mcp_server.search("query", "../../etc/passwd")

        assert result["error_type"] == "validation_error"
        assert "Unknown search engine" in result["error"]
        assert create.call_count == 0

    @pytest.mark.parametrize(
        "tool_name, args, kwargs, fragment",
        [
            pytest.param(
                "quick_research",
                ("x" * 10_001,),
                {},
                "maximum length",
                id="quick-research-query-over-max",
            ),
            ("quick_research", ("q",), {"iterations": 10**9}, "cannot exceed"),
            (
                "quick_research",
                ("q",),
                {"questions_per_iteration": -1},
                "positive integer",
            ),
            ("analyze_documents", ("q", "c"), {"max_results": 10**9}, "exceed"),
            ("analyze_documents", ("q", "c"), {"max_results": 0}, "positive"),
            (
                "generate_report",
                ("q",),
                {"searches_per_section": 10**6},
                "exceed",
            ),
            ("quick_research", ("   ",), {}, "cannot be empty"),
        ],
    )
    def test_oversized_and_empty_values_are_rejected(
        self, mcp_server, tool_name, args, kwargs, fragment
    ):
        backends = {
            "quick_research": "ldr_quick_summary",
            "analyze_documents": "ldr_analyze_documents",
            "generate_report": "ldr_generate_report",
        }
        with patch.object(mcp_server, backends[tool_name]) as backend:
            result = getattr(mcp_server, tool_name)(*args, **kwargs)

        assert result["error_type"] == "validation_error"
        assert fragment in result["error"], result["error"]
        assert backend.call_count == 0

    def test_ldr_web_port_is_not_range_validated(self, monkeypatch):
        """GAP: ``LDR_WEB_PORT`` reaches uvicorn unchecked.

        ``load_server_config`` coerces the type but never bounds the
        value, so an out-of-range port surfaces as an opaque socket error
        from inside uvicorn rather than a config error naming the
        variable.  Same for the host, which is passed through verbatim.
        If this starts raising, the gap has been closed -- update the
        test to assert the rejection instead.
        """
        from local_deep_research.web.server_config import load_server_config

        monkeypatch.setenv("LDR_WEB_PORT", "99999")
        monkeypatch.setenv("LDR_WEB_HOST", "../../etc/passwd")

        config = load_server_config()

        assert config["port"] == 99999, (
            "port is now validated at config load -- good; update this test"
        )
        assert not 0 < config["port"] <= 65535
        assert config["host"] == "../../etc/passwd"


# ---------------------------------------------------------------------------
# Checks the web layer enforces and the MCP path does not
# ---------------------------------------------------------------------------


class TestWebLayerChecksBypassed:
    def test_env_locked_setting_is_overridden_by_a_tool_argument(
        self, mcp_server, monkeypatch
    ):
        """DEFECT: the MCP snapshot path ignores the operator's env lock.

        An ``LDR_*`` variable is the operator's way of pinning a setting:
        ``SettingsManager.get_all_settings`` stamps such a key
        ``editable: False``, and the settings router refuses to write a
        non-editable key (``_filter_editable_settings`` in
        ``web/routers/settings.py`` deletes it from the form data).

        ``create_settings_snapshot`` applies its overrides *after* the
        env overlay and never re-checks the lock, so the MCP
        ``search_engine`` tool argument silently wins -- the snapshot
        still advertises ``editable: False`` while carrying the client's
        value.
        """
        from local_deep_research.api.settings_utils import (
            create_settings_snapshot,
        )

        monkeypatch.setenv("LDR_SEARCH_TOOL", "wikipedia")

        locked = create_settings_snapshot()["search.tool"]
        assert locked["value"] == "wikipedia"
        assert locked["editable"] is False, (
            "precondition: LDR_SEARCH_TOOL must lock the setting"
        )

        # This is exactly the dict an MCP tool builds from its arguments.
        overrides = mcp_server._build_settings_overrides(search_engine="arxiv")
        assert overrides == {"search.tool": "arxiv"}

        overridden = create_settings_snapshot(overrides=overrides)[
            "search.tool"
        ]
        assert overridden["editable"] is False
        assert overridden["value"] == "arxiv", (
            "if this now reads 'wikipedia' the env lock is honoured on the "
            "snapshot path too -- the bypass was fixed"
        )

    def test_egress_scope_env_lock_survives_a_hostile_snapshot(self):
        """Contrast: the one lock the snapshot path cannot defeat.

        ``context_from_snapshot`` re-reads ``policy.egress_scope`` from
        the environment and lets it win over the snapshot value.  That is
        the in-repo standard the ``search.tool`` case above fails to
        meet; it is asserted here so the previous test cannot be "fixed"
        by weakening the egress guard instead.
        """
        from local_deep_research.security.egress.policy import (
            EgressScope,
            context_from_snapshot,
        )

        hostile = {
            "policy.egress_scope": {"value": "unprotected"},
            "search.tool": {"value": "wikipedia"},
        }
        with patch(
            "local_deep_research.settings.manager.check_env_setting",
            side_effect=lambda key: (
                "strict" if key == "policy.egress_scope" else None
            ),
        ):
            ctx = context_from_snapshot(hostile, "wikipedia", username=None)

        assert ctx.scope is EgressScope.STRICT

    def test_mcp_search_runs_without_a_run_owner(self, mcp_server):
        """The egress audit net is armed with ``username=None``.

        ``_egress_audit_net`` reads the run owner from
        ``settings["_username"]``, but every MCP snapshot comes from
        ``create_settings_snapshot()``, which never sets that key.  The
        per-user half of egress classification therefore always resolves
        the shared namespace for MCP runs.  Pinned so that a future
        per-user policy rule is not silently inert here.
        """
        from local_deep_research.api.settings_utils import (
            create_settings_snapshot,
        )

        snapshot = create_settings_snapshot()
        assert "_username" not in snapshot

        captured = {}

        def capture(settings_snapshot, primary, *, username=None, **kwargs):
            captured["username"] = username
            captured["primary"] = primary
            raise ValueError("stop before arming")

        with patch(
            "local_deep_research.security.egress.policy.context_from_snapshot",
            side_effect=capture,
        ):
            ctx = mcp_server._egress_audit_net(snapshot)

        assert captured["username"] is None
        # An unevaluable policy must degrade to a nullcontext, never raise:
        # the factory PEP stays the primary enforcement point.
        with ctx:
            pass

    def test_mcp_tools_are_reachable_without_any_authentication(
        self, mcp_server
    ):
        """Documented, but worth pinning: no auth hook exists.

        Every web route reaches the core behind an authenticated request;
        the MCP tools are plain module-level functions with no
        auth/session/permission parameter at all.  This is the server's
        stated design (STDIO + OS permissions) -- the assertion exists so
        that adding a network transport (see
        ``test_mcp_transport_is_a_hardcoded_stdio_literal``) cannot pass
        review as a small change.
        """
        import inspect

        for tool_name in (
            "quick_research",
            "detailed_research",
            "generate_report",
            "analyze_documents",
            "search",
        ):
            params = set(
                inspect.signature(getattr(mcp_server, tool_name)).parameters
            )
            assert not params & {
                "username",
                "user",
                "session",
                "token",
                "auth",
                "request",
            }, (
                f"{tool_name} grew an identity parameter; the MCP tool "
                "surface now has an auth story that needs enforcing"
            )


@requires_real_mcp
def test_stub_boundary_is_faithful_when_the_extra_is_present():
    """If the real SDK is installed, ``tool()`` must return the function.

    These tests call the decorated tools directly as module attributes;
    that only matches production if ``@mcp.tool()`` is transparent.  The
    stub is written that way -- this checks the real SDK agrees, so the
    stub cannot drift into testing a fiction.
    """
    from mcp.server.fastmcp import FastMCP

    assert FastMCP is not _StubFastMCP, "the stub leaked into sys.modules"
    server = FastMCP("faithfulness-probe")

    def original() -> str:
        return "x"

    decorated = server.tool()(original)
    assert decorated is original