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.

24.4 KB
Raw Blame
"""
MCP protocol tests for the MCP server.

Tests for server setup, tool registration, and logging configuration.
"""

import sys
import io
from contextlib import contextmanager
from unittest.mock import patch

import pytest
from loguru import logger

# Skip all tests if MCP is not available
from tests.mcp_sdk import is_mcp_installed

MCP_AVAILABLE = is_mcp_installed()

pytestmark = pytest.mark.skipif(
    not MCP_AVAILABLE, reason="MCP package not installed"
)


class TestMCPServerSetup:
    """Tests for MCP server initialization and configuration."""

    def test_mcp_server_instance_created(self):
        """Verify FastMCP server instance is created correctly."""
        from local_deep_research.mcp.server import mcp

        assert mcp is not None
        assert mcp.name == "local-deep-research"

    def test_mcp_server_instructions_set(self):
        """Verify server instructions/description is set."""
        from local_deep_research.mcp.server import mcp

        # FastMCP stores instructions
        assert mcp.instructions is not None
        assert "research" in mcp.instructions.lower()

    def test_run_server_function_exists(self):
        """Verify run_server function is exported."""
        from local_deep_research.mcp import run_server

        assert callable(run_server)


class TestMCPToolRegistration:
    """Tests for MCP tool decorators and registration."""

    def test_all_expected_tools_are_defined(self):
        """Verify all 7 expected tools are defined as functions."""
        from local_deep_research.mcp.server import (
            quick_research,
            detailed_research,
            generate_report,
            analyze_documents,
            list_search_engines,
            list_strategies,
            get_configuration,
        )

        # All tools should be callable
        assert callable(quick_research)
        assert callable(detailed_research)
        assert callable(generate_report)
        assert callable(analyze_documents)
        assert callable(list_search_engines)
        assert callable(list_strategies)
        assert callable(get_configuration)

    def test_quick_research_has_docstring(self):
        """Verify quick_research has documentation."""
        from local_deep_research.mcp.server import quick_research

        assert quick_research.__doc__ is not None
        assert len(quick_research.__doc__) > 50  # Substantial docstring
        assert "query" in quick_research.__doc__.lower()

    def test_detailed_research_has_docstring(self):
        """Verify detailed_research has documentation."""
        from local_deep_research.mcp.server import detailed_research

        assert detailed_research.__doc__ is not None
        assert "detailed" in detailed_research.__doc__.lower()

    def test_generate_report_has_docstring(self):
        """Verify generate_report has documentation."""
        from local_deep_research.mcp.server import generate_report

        assert generate_report.__doc__ is not None
        assert "report" in generate_report.__doc__.lower()

    def test_analyze_documents_has_docstring(self):
        """Verify analyze_documents has documentation."""
        from local_deep_research.mcp.server import analyze_documents

        assert analyze_documents.__doc__ is not None
        assert "document" in analyze_documents.__doc__.lower()

    def test_list_search_engines_has_docstring(self):
        """Verify list_search_engines has documentation."""
        from local_deep_research.mcp.server import list_search_engines

        assert list_search_engines.__doc__ is not None
        assert "search" in list_search_engines.__doc__.lower()

    def test_list_strategies_has_docstring(self):
        """Verify list_strategies has documentation."""
        from local_deep_research.mcp.server import list_strategies

        assert list_strategies.__doc__ is not None
        assert "strateg" in list_strategies.__doc__.lower()

    def test_get_configuration_has_docstring(self):
        """Verify get_configuration has documentation."""
        from local_deep_research.mcp.server import get_configuration

        assert get_configuration.__doc__ is not None
        assert "config" in get_configuration.__doc__.lower()

    def test_search_docstring_states_wayback_input_contract(self):
        """The wayback hint states what the engine looks up."""
        from local_deep_research.mcp.server import search

        doc = " ".join(search.__doc__.split())
        assert "full http:// or https:// URL" in doc
        assert "or be only a bare domain such as example.com" in doc
        assert (
            "The complete URL, including its port, path, query and "
            "fragment, is looked up" in doc
        )
        assert (
            "words that follow a URL without a space become part of it" in doc
        )
        assert (
            "A URL with a user name or password before its host is not "
            "looked up" in doc
        )
        assert "at most max_results URLs" in doc


class TestMCPLogging:
    """Tests for MCP logging configuration (critical for STDIO)."""

    def test_no_stdout_pollution_from_list_strategies(self):
        """Verify list_strategies doesn't write to stdout."""
        from local_deep_research.mcp.server import list_strategies

        # Capture stdout
        old_stdout = sys.stdout
        sys.stdout = captured_stdout = io.StringIO()

        try:
            result = list_strategies()
            stdout_output = captured_stdout.getvalue()
        finally:
            sys.stdout = old_stdout

        # Should have no stdout output (MCP uses stdout for JSON-RPC)
        assert stdout_output == "", f"Unexpected stdout output: {stdout_output}"
        assert result["status"] == "success"

    def test_no_stdout_pollution_from_get_configuration(self):
        """Verify get_configuration doesn't write to stdout."""
        from local_deep_research.mcp.server import get_configuration

        # Capture stdout
        old_stdout = sys.stdout
        sys.stdout = captured_stdout = io.StringIO()

        try:
            result = get_configuration()
            stdout_output = captured_stdout.getvalue()
        finally:
            sys.stdout = old_stdout

        # Should have no stdout output
        assert stdout_output == "", f"Unexpected stdout output: {stdout_output}"
        assert result["status"] == "success"

    def test_no_stdout_pollution_during_error(self):
        """Verify error handling doesn't write to stdout."""
        from local_deep_research.mcp.server import quick_research

        # Capture stdout
        old_stdout = sys.stdout
        sys.stdout = captured_stdout = io.StringIO()

        try:
            with patch(
                "local_deep_research.mcp.server.ldr_quick_summary",
                side_effect=Exception("Test error"),
            ):
                result = quick_research(query="test")
            stdout_output = captured_stdout.getvalue()
        finally:
            sys.stdout = old_stdout

        # Should have no stdout output even during errors
        assert stdout_output == "", f"Unexpected stdout output: {stdout_output}"
        assert result["status"] == "error"

    def test_run_server_installs_control_char_scrubber(self):
        """run_server must install the control-char sink-scrubber AND
        re-enable the "local_deep_research" logger namespace.

        The MCP subprocess bypasses config_logger, so without an explicit
        logger.configure(patcher=...) the raw user queries and exception
        text logged by engines/strategies reach the MCP client's stderr
        with C0/C1 control chars and Unicode format chars intact
        (log-injection / forged-log-line). This asserts run_server wires
        the same patcher config_logger installs for the web/CLI logger,
        and that the patcher actually strips control chars from a record's
        message using the shared strip_control_chars machinery.

        It also asserts run_server re-enables the "local_deep_research"
        logger namespace: local_deep_research/__init__.py calls
        logger.disable("local_deep_research") at import time (so importing
        the package doesn't spam a caller's logs before they've configured
        sinks), and only config_logger() re-enables it elsewhere in the
        codebase. Without an equivalent call here, EVERY app log record —
        not just the ones the patcher above scrubs — is silently dropped
        before reaching any sink, in this MCP subprocess: the installed
        patcher above never runs, and the "Starting..." line below (emitted
        from a module inside the still-disabled namespace) would itself be
        discarded.
        """
        from local_deep_research.mcp.server import run_server
        from local_deep_research.security.log_sanitizer import (
            strip_control_chars,
        )

        configured = {}

        def _fake_configure(*args, **kwargs):
            configured["patcher"] = kwargs.get("patcher")

        # Stop run_server after logging setup so we never launch the server
        # or run the legacy-docstore migration (which needs real state).
        class _StopHere(Exception):
            pass

        with (
            patch("local_deep_research.mcp.server.logger.remove"),
            patch("local_deep_research.mcp.server.logger.add"),
            patch(
                "local_deep_research.mcp.server.logger.enable"
            ) as mock_enable,
            patch(
                "local_deep_research.mcp.server.logger.configure",
                side_effect=_fake_configure,
            ),
            patch(
                "local_deep_research.mcp.server.logger.info",
                side_effect=_StopHere,
            ),
        ):
            with pytest.raises(_StopHere):
                run_server()

        patcher = configured.get("patcher")
        assert patcher is not None, (
            "run_server did not call logger.configure(patcher=...) — MCP "
            "stderr is not control-char scrubbed"
        )

        # The installed patcher must actually strip control chars, matching
        # the shared sink-scrubber's behavior.
        dirty = "user query\r\n2026-01-01 | FORGED admin login\x00\x1b[31m"
        record = {"message": dirty}
        patcher(record)
        assert record["message"] == strip_control_chars(dirty)
        assert "\r" not in record["message"]
        assert "\n" not in record["message"]
        assert "\x00" not in record["message"]
        assert "\x1b" not in record["message"]

        # Without this, the patcher above (and every other app log record)
        # is inert: the "local_deep_research" namespace stays disabled for
        # the lifetime of the MCP subprocess.
        mock_enable.assert_called_once_with("local_deep_research")


class _ListSink:
    """Real loguru sink collecting formatted records.

    ``write`` runs only on loguru's single queue-writer thread and
    ``lines`` is append-only, so reads after a ``logger.complete()``
    barrier never race a write.
    """

    def __init__(self):
        self.lines = []

    def write(self, message):
        self.lines.append(str(message))

    def has(self, text):
        return any(text in line for line in self.lines)


@contextmanager
def _restored_logger():
    """Undo what ``configure_mcp_logging`` does to the process-wide logger.

    Twin of ``tests/mcp/test_stderr_control_chars.py::_restored_logger``
    (kept local rather than imported so this module has no import-mode
    dependence). ``logger.configure(patcher=None)`` does not clear a
    patcher: None means "leave unchanged", so the patcher would leak into
    the rest of the pytest worker. The namespace activation and the
    handlers are process-wide for the same reason, so all three are
    snapshotted off ``logger._core`` and put back.
    """
    core = logger._core
    saved = (
        core.patcher,
        core.enabled.copy(),
        list(core.activation_list),
        core.activation_none,
    )
    try:
        yield
    finally:
        logger.remove()
        (
            core.patcher,
            core.enabled,
            core.activation_list,
            core.activation_none,
        ) = saved
        # configure_mcp_logging removed loguru's default stderr handler.
        logger.add(sys.stderr)


@contextmanager
def _run_server_rig(mcp_run_factory, migrate_side_effect=None):
    """Run ``run_server()`` against a real enqueue=True sink.

    Only the two things a pytest process must not do for real are
    patched: launching the stdio server and the legacy-docstore sweep.
    The sink is injected through ``configure_mcp_logging``'s own ``sink``
    parameter, so the real ``logger.remove()``/``logger.add(enqueue=True)``
    setup, loguru's real queue-writer thread, and the real drain barrier
    in ``run_server()``'s finally all execute. ``logger.complete`` is
    wrapped by a spy that delegates to the real barrier and records its
    position in ``order`` — without the spy, "record absent from the
    sink at return time" is a race the writer thread usually (but not
    always) loses, which is exactly the nondeterminism the barrier
    exists to remove.

    ``migrate_side_effect`` is attached to the patched legacy-docstore
    sweep, so a test can raise from the startup window that now sits
    inside the same ``try``.

    Yields ``(sink, order, mock_run, real_complete)``.
    """
    from local_deep_research.mcp.server import (
        configure_mcp_logging as real_configure,
    )

    order = []
    sink = _ListSink()
    real_complete = logger.complete

    def _spy_complete():
        order.append("complete")
        real_complete()

    with _restored_logger():
        with (
            patch(
                "local_deep_research.mcp.server.configure_mcp_logging",
                side_effect=lambda: real_configure(sink=sink),
            ),
            patch(
                "local_deep_research.mcp.server.mcp.run",
                side_effect=mcp_run_factory(order),
            ) as mock_run,
            patch(
                "local_deep_research.vector_stores.legacy_cleanup"
                ".migrate_legacy_docstores",
                side_effect=migrate_side_effect,
            ),
            patch.object(logger, "complete", side_effect=_spy_complete),
        ):
            yield sink, order, mock_run, real_complete


class TestMCPLoggingDrainOnShutdown:
    """Real-drain regressions for the #5804 follow-up: ``run_server()`` must
    synchronously drain the enqueue=True stderr sink before it returns or
    propagates, while *retaining* the handlers so records logged afterwards
    (a caller handling the failure, background threads winding down) still
    reach the sink.

    Every test here fails if the ``finally``'s ``logger.complete()`` is
    removed, moved ahead of ``mcp.run()``, or swapped back to
    ``logger.remove()``: the first two corrupt ``order`` directly, and the
    third corrupts it too - the spy this class installs on
    ``logger.complete`` never fires under ``remove()``, so every test's
    ``order`` assertion fails first, before any ``sink.has(...)`` check
    runs. (``remove()`` would also drop a caller's post-shutdown records
    from the sink - the property
    ``test_normal_return_retains_handlers_for_caller_records`` is named for
    - but the ``order`` assertion catches the swap before that ever gets
    exercised.)
    """

    def test_normal_return_drains_queue_before_return(self):
        """A clean client disconnect leaves every record enqueued before
        return already written to the sink."""
        from local_deep_research.mcp.server import run_server

        def _stdio_disconnect(order):
            def _run(**kwargs):
                logger.error("server: stdio client disconnected")
                order.append("mcp.run")

            return _run

        with _run_server_rig(_stdio_disconnect) as (sink, order, mock_run, _):
            run_server()

            # Asserted *inside* the rig: the only drain that has run at
            # this point is the finally's barrier. (_restored_logger's
            # own logger.remove() teardown, which would also drain, is
            # still pending on the way out of the `with`.)
            mock_run.assert_called_once_with(transport="stdio")
            # Barrier ran after mcp.run() and before run_server() returned.
            assert order == ["mcp.run", "complete"]
            assert sink.has("Starting Local Deep Research MCP server")
            assert sink.has("stdio client disconnected")

    def test_normal_return_retains_handlers_for_caller_records(self):
        """After run_server() returns, the installed handlers must still
        accept records: a caller logging its own post-shutdown line
        must reach the same sink once drained. ``logger.remove()`` in
        the finally would silently drop it."""
        from local_deep_research.mcp.server import run_server

        def _stdio_disconnect(order):
            def _run(**kwargs):
                order.append("mcp.run")

            return _run

        with _run_server_rig(_stdio_disconnect) as (
            sink,
            order,
            _,
            real_complete,
        ):
            run_server()

            # Caller-side record, logged after run_server() returned...
            logger.error("caller: shutting down after server exit")
            # ...still reaches the retained sink once drained. This
            # explicit barrier is the only drain between the record and
            # the asserts below; the rig's teardown has not run yet.
            real_complete()

            assert order == ["mcp.run", "complete"]
            assert sink.has("Starting Local Deep Research MCP server")
            assert sink.has("caller: shutting down after server exit")

    def test_exception_path_drains_before_propagation_and_retains(self):
        """``mcp.run()`` raising must drain inside the finally — while the
        exception is still propagating through run_server()'s frame,
        strictly before it reaches this caller (and, in a real
        process, before CPython's excepthook prints the traceback to
        stderr, keeping causal order: log lines first, traceback
        after). Handlers must also survive for the caller's own error
        record."""
        from local_deep_research.mcp.server import run_server

        class _BoomError(Exception):
            pass

        def _stdio_crash(order):
            def _run(**kwargs):
                logger.error("server: stdio transport failed")
                order.append("mcp.run")
                raise _BoomError("client pipe broke")

            return _run

        with _run_server_rig(_stdio_crash) as (
            sink,
            order,
            _,
            real_complete,
        ):
            with pytest.raises(_BoomError):
                run_server()
            order.append("caught")

            # The crash-context record was already written when the
            # exception reached this frame: the finally's barrier is the
            # only drain that has run, the rig teardown's is still
            # pending.
            assert order == ["mcp.run", "complete", "caught"]
            assert sink.has("server: stdio transport failed")

            logger.error("caller: handling server failure")
            real_complete()
            assert sink.has("caller: handling server failure")

    def test_baseexception_path_still_drains_in_finally(self):
        """A BaseException (KeyboardInterrupt) from mcp.run() must both
        drain the queue via the finally and still propagate out of
        run_server() unchanged."""
        from local_deep_research.mcp.server import run_server

        def _interrupted(order):
            def _run(**kwargs):
                logger.error("server: interrupted while serving stdio")
                order.append("mcp.run")
                raise KeyboardInterrupt

            return _run

        with _run_server_rig(_interrupted) as (sink, order, _, _):
            with pytest.raises(KeyboardInterrupt):
                run_server()
            order.append("caught")

            # Inside the rig, so the finally's barrier is the only drain
            # these asserts can be observing.
            assert order == ["mcp.run", "complete", "caught"]
            assert sink.has("server: interrupted while serving stdio")

    def test_startup_window_is_inside_the_drain(self):
        """The startup log line and the legacy-docstore sweep run inside
        the same ``try``. The sweep only catches ``Exception``, so a
        BaseException from it escapes — and must still hit the barrier,
        or the queued startup lines land after the traceback."""
        from local_deep_research.mcp.server import run_server

        def _never_runs(order):
            def _run(**kwargs):  # pragma: no cover - must not be reached
                order.append("mcp.run")

            return _run

        with _run_server_rig(
            _never_runs, migrate_side_effect=KeyboardInterrupt
        ) as (sink, order, mock_run, _):
            with pytest.raises(KeyboardInterrupt):
                run_server()
            order.append("caught")

            mock_run.assert_not_called()
            assert order == ["complete", "caught"]
            assert sink.has("Starting Local Deep Research MCP server")


class TestAvailableStrategies:
    """Tests for the get_available_strategies function.

    MCP server exposes all strategies (show_all=True), so these tests
    validate the full list.
    """

    def test_available_strategies_is_list(self):
        """Verify get_available_strategies returns a list."""
        from local_deep_research.search_system_factory import (
            get_available_strategies,
        )

        strategies = get_available_strategies()
        assert isinstance(strategies, list)

    def test_available_strategies_has_entries(self):
        """Verify get_available_strategies has multiple entries."""
        from local_deep_research.search_system_factory import (
            get_available_strategies,
        )

        strategies = get_available_strategies()
        assert len(strategies) >= 5

    def test_available_strategies_have_required_fields(self):
        """Verify each strategy has name and description."""
        from local_deep_research.search_system_factory import (
            get_available_strategies,
        )

        strategies = get_available_strategies()
        for strategy in strategies:
            assert "name" in strategy, f"Strategy missing 'name': {strategy}"
            assert "description" in strategy, (
                f"Strategy missing 'description': {strategy}"
            )
            assert isinstance(strategy["name"], str)
            assert isinstance(strategy["description"], str)
            assert len(strategy["name"]) > 0
            assert len(strategy["description"]) > 0

    def test_source_based_strategy_exists(self):
        """Verify source-based strategy is in the list."""
        from local_deep_research.search_system_factory import (
            get_available_strategies,
        )

        strategies = get_available_strategies()
        strategy_names = [s["name"] for s in strategies]
        assert "source-based" in strategy_names

    def test_focused_iteration_strategy_exists(self):
        """Verify focused-iteration strategy is in the list."""
        from local_deep_research.search_system_factory import (
            get_available_strategies,
        )

        strategies = get_available_strategies()
        strategy_names = [s["name"] for s in strategies]
        assert "focused-iteration" in strategy_names


class TestHelperFunctions:
    """Tests for helper functions in server.py."""

    def test_classify_error_is_callable(self):
        """Verify _classify_error function exists and is callable."""
        from local_deep_research.mcp.server import _classify_error

        assert callable(_classify_error)

    def test_build_settings_overrides_is_callable(self):
        """Verify _build_settings_overrides function exists and is callable."""
        from local_deep_research.mcp.server import _build_settings_overrides

        assert callable(_build_settings_overrides)

    def test_classify_error_returns_string(self):
        """Verify _classify_error returns a string."""
        from local_deep_research.mcp.server import _classify_error

        result = _classify_error("Some error")
        assert isinstance(result, str)

    def test_build_settings_overrides_returns_dict(self):
        """Verify _build_settings_overrides returns a dict."""
        from local_deep_research.mcp.server import _build_settings_overrides

        result = _build_settings_overrides()
        assert isinstance(result, dict)