~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
"""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