~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
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)