~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 Server for Local Deep Research.
This module provides an MCP (Model Context Protocol) server that exposes
LDR's research capabilities to AI agents like Claude.
Security Notice:
This server is designed for LOCAL USE ONLY via STDIO transport
(e.g., Claude Desktop). It has no built-in authentication or rate
limiting. Do NOT expose this server over a network without implementing
proper security controls (OAuth, rate limiting, input validation).
When running locally via STDIO, security is provided by your operating
system's user permissions.
Tools:
- quick_research: Fast research summary (1-5 min)
- detailed_research: Comprehensive analysis (5-15 min)
- generate_report: Full markdown report (10-30 min)
- analyze_documents: Search local document collection (30s-2 min)
- search: Raw search results without LLM processing (5-30s)
- list_search_engines: List available search engines
- list_strategies: List available research strategies
- get_configuration: Get current server configuration
Usage:
python -m local_deep_research.mcp
# or
ldr-mcp
"""
import re
import sys
from collections.abc import Callable
from typing import Any, Dict, Optional, cast
from loguru import logger
from mcp.server.fastmcp import FastMCP
from local_deep_research.api.research_functions import (
analyze_documents as ldr_analyze_documents,
detailed_research as ldr_detailed_research,
generate_report as ldr_generate_report,
quick_summary as ldr_quick_summary,
)
from local_deep_research.api.settings_utils import create_settings_snapshot
from local_deep_research.search_system_factory import (
get_available_strategies,
)
from ..constants import DEFAULT_SEARCH_TOOL
from ..security.egress.policy import PolicyDeniedError
# Create FastMCP server instance
mcp = FastMCP(
"local-deep-research",
instructions="AI-powered deep research assistant with iterative analysis using LLMs and web searches",
)
_HTTP_ERROR_CODE_RE = re.compile(r"(?<!\d)(?:401|404|429|503)(?!\d)")
def _classify_error(error_msg: str) -> str:
"""Classify error for client handling."""
error_lower = error_msg.lower()
# Exception messages can contain timestamps, counters, or OS thread IDs.
# Only standalone three-digit values are HTTP status codes; matching a
# substring inside a longer number makes classification nondeterministic.
status_codes = set(_HTTP_ERROR_CODE_RE.findall(error_msg))
if "503" in status_codes or "unavailable" in error_lower:
return "service_unavailable"
if "404" in status_codes or "not found" in error_lower:
return "model_not_found"
if (
"api key" in error_lower
or "authentication" in error_lower
or "unauthorized" in error_lower
or "401" in status_codes
):
return "auth_error"
if "timeout" in error_lower or "timed out" in error_lower:
return "timeout"
if "rate limit" in error_lower or "429" in status_codes:
return "rate_limit"
if "connection" in error_lower:
return "connection_error"
if "validation" in error_lower or "invalid" in error_lower:
return "validation_error"
return "unknown"
def _policy_denied_response(
error: PolicyDeniedError, operation: str
) -> Dict[str, Any]:
"""Build a machine-readable, leak-safe response for a PolicyDeniedError.
The PDP's short ``reason`` code (e.g. ``scope_mismatch_private_only``) is
safe to surface -- it is a machine code, never user content. The
``target`` attribute is not (engine names / URLs may carry user content
or internal hostnames), so it is logged at audit level but never returned
to the client. Fail-closed is preserved by construction: this helper only
runs after the PEP has already raised, so the underlying engine run has
already been blocked.
"""
reason = error.decision.reason
logger.bind(policy_audit=True).warning(
"MCP tool denied by egress policy",
operation=operation,
reason=reason,
)
return {
"status": "error",
"error_type": "policy_denied",
"reason": reason,
"error": f"{operation} denied by egress policy: {reason}.",
}
class ValidationError(Exception):
"""Raised when parameter validation fails."""
pass
_COLLECTION_NAME_RE = re.compile(r"^[A-Za-z0-9 _-]{1,100}$")
def _validate_range(
value: Any,
name: str,
min_val: int | float,
max_val: int | float,
*,
type_check: type | tuple[type, ...] = int,
allow_none: bool = True,
convert_to: Optional[Callable[[int | float], int | float]] = None,
type_error: Optional[str] = None,
min_error: Optional[str] = None,
max_error: Optional[str] = None,
) -> int | float | None:
"""Validate a numeric parameter and optionally normalize its type."""
if value is None:
if allow_none:
return None
raise ValidationError(type_error or f"{name} is required")
if not isinstance(value, type_check):
raise ValidationError(type_error or f"{name} must be a number")
numeric_value = cast(int | float, value)
if not numeric_value >= min_val:
raise ValidationError(min_error or f"{name} must be at least {min_val}")
if not numeric_value <= max_val:
raise ValidationError(max_error or f"{name} cannot exceed {max_val}")
return (
convert_to(numeric_value) if convert_to is not None else numeric_value
)
def _error_result(
error: Exception | str,
*,
operation: Optional[str] = None,
error_type: Optional[str] = None,
) -> Dict[str, Any]:
"""Build an MCP error result without changing its public message shape.
``operation`` is the complete operation-specific wording that precedes
``(<error_type>)``. Omitting it preserves ``error`` verbatim, which is
used for validation and other deliberately client-visible messages.
"""
error_text = str(error)
resolved_type = error_type or _classify_error(error_text)
public_message = (
error_text
if operation is None
else f"{operation} ({resolved_type}). Check server logs for details."
)
return {
"status": "error",
"error": public_message,
"error_type": resolved_type,
}
def _validate_query(query: str) -> str:
"""Validate and sanitize query parameter."""
if not query or not query.strip():
raise ValidationError("Query cannot be empty")
query = query.strip()
if len(query) > 10000:
raise ValidationError(
"Query exceeds maximum length of 10000 characters"
)
return query
def _validate_iterations(
iterations: Optional[int], max_val: int = 20
) -> Optional[int]:
"""Validate iterations parameter."""
positive_error = "Iterations must be a positive integer"
return cast(
Optional[int],
_validate_range(
iterations,
"Iterations",
1,
max_val,
type_error=positive_error,
min_error=positive_error,
),
)
def _validate_questions_per_iteration(qpi: Optional[int]) -> Optional[int]:
"""Validate questions_per_iteration parameter."""
positive_error = "Questions per iteration must be a positive integer"
return cast(
Optional[int],
_validate_range(
qpi,
"Questions per iteration",
1,
10,
type_error=positive_error,
min_error=positive_error,
),
)
def _validate_max_results(max_results: int) -> int:
"""Validate max_results parameter."""
positive_error = "Max results must be a positive integer"
return cast(
int,
_validate_range(
max_results,
"Max results",
1,
100,
allow_none=False,
type_error=positive_error,
min_error=positive_error,
),
)
def _validate_searches_per_section(searches_per_section: int) -> int:
"""Validate searches_per_section parameter."""
positive_error = "Searches per section must be a positive integer"
return cast(
int,
_validate_range(
searches_per_section,
"Searches per section",
1,
10,
allow_none=False,
type_error=positive_error,
min_error=positive_error,
),
)
def _validate_temperature(temperature: Optional[float]) -> Optional[float]:
"""Validate and normalize a temperature setting."""
range_error = "Temperature must be between 0.0 and 2.0"
return cast(
Optional[float],
_validate_range(
temperature,
"Temperature",
0.0,
2.0,
type_check=(int, float),
convert_to=float,
type_error="Temperature must be a number",
min_error=range_error,
max_error=range_error,
),
)
def _validate_search_engine(engine: Optional[str]) -> Optional[str]:
"""Validate search engine name against available engines."""
if engine is None:
return None
engine = engine.strip()
if not engine:
return None
try:
from local_deep_research.web_search_engines.search_engines_config import (
search_config,
)
settings = create_settings_snapshot()
available = search_config(settings_snapshot=settings)
if engine not in available:
available_names = sorted(available.keys())
raise ValidationError( # noqa: TRY301
f"Unknown search engine '{engine}'. Available: {', '.join(available_names)}"
)
except ValidationError:
raise
except Exception:
logger.exception("Could not load engine config to validate engine")
raise ValidationError(
f"Cannot validate search engine '{engine}': engine configuration unavailable"
)
return engine
def _validate_strategy(strategy: Optional[str]) -> Optional[str]:
"""Validate strategy name against available strategies."""
if strategy is None:
return None
strategy = strategy.strip()
if not strategy:
return None
available = get_available_strategies()
available_names = [s["name"] for s in available]
if strategy not in available_names:
raise ValidationError(
f"Unknown strategy '{strategy}'. Available: {', '.join(available_names)}"
)
return strategy
def _build_settings_overrides(
search_engine: Optional[str] = None,
strategy: Optional[str] = None,
iterations: Optional[int] = None,
questions_per_iteration: Optional[int] = None,
temperature: Optional[float] = None,
) -> Dict[str, Any]:
"""Build settings overrides dict from tool parameters."""
overrides: dict[str, Any] = {}
if search_engine is not None:
search_engine = _validate_search_engine(search_engine)
if search_engine:
overrides["search.tool"] = search_engine
if strategy is not None:
strategy = _validate_strategy(strategy)
if strategy:
overrides["search.search_strategy"] = strategy
if iterations is not None:
overrides["search.iterations"] = iterations
if questions_per_iteration is not None:
overrides["search.questions_per_iteration"] = questions_per_iteration
if temperature is not None:
overrides["llm.temperature"] = _validate_temperature(temperature)
return overrides
# =============================================================================
# Research Tools
# =============================================================================
@mcp.tool()
def quick_research(
query: str,
search_engine: Optional[str] = None,
strategy: Optional[str] = None,
iterations: Optional[int] = None,
questions_per_iteration: Optional[int] = None,
) -> Dict[str, Any]:
"""
Perform quick research on a topic.
This tool performs a fast research summary on the given query. It searches
the web, analyzes sources, and generates a concise summary with findings.
IMPORTANT: This is a synchronous operation that typically takes 1-5 minutes
to complete depending on the complexity and configuration.
Args:
query: The research question or topic to investigate.
search_engine: Search engine to use (e.g., "wikipedia", "arxiv", "searxng").
Use list_search_engines() to see available options.
strategy: Research strategy to use (e.g., "source-based", "rapid", "iterative").
Use list_strategies() to see available options.
iterations: Number of search iterations (1-10). More iterations = deeper research.
questions_per_iteration: Questions to generate per iteration (1-5).
Returns:
Dictionary containing:
- status: "success" or "error"
- summary: The research summary text
- findings: List of detailed findings from each search
- sources: List of source URLs discovered
- iterations: Number of iterations performed
- error: Error message (only if status is "error")
- error_type: Error classification (only if status is "error")
"""
try:
# Validate parameters
query = _validate_query(query)
iterations = _validate_iterations(iterations, max_val=10)
questions_per_iteration = _validate_questions_per_iteration(
questions_per_iteration
)
logger.info(f"Starting quick research for query: {query[:100]}...")
overrides = _build_settings_overrides(
search_engine=search_engine,
strategy=strategy,
iterations=iterations,
questions_per_iteration=questions_per_iteration,
)
settings = (
create_settings_snapshot(overrides=overrides)
if overrides
else create_settings_snapshot()
)
result = ldr_quick_summary(query, settings_snapshot=settings)
return {
"status": "success",
"summary": result.get("summary", ""),
"findings": result.get("findings", []),
"sources": result.get("sources", []),
"iterations": result.get("iterations", 0),
"formatted_findings": result.get("formatted_findings", ""),
}
except ValidationError as e:
logger.warning("Validation failed for quick research")
return _error_result(e, error_type="validation_error")
except PolicyDeniedError as e:
return _policy_denied_response(e, "Quick research")
except Exception as e:
logger.exception(
f"Quick research failed for query: {query[:100] if query else 'empty'}"
)
return _error_result(e, operation="Quick research failed")
@mcp.tool()
def detailed_research(
query: str,
search_engine: Optional[str] = None,
strategy: Optional[str] = None,
iterations: Optional[int] = None,
questions_per_iteration: Optional[int] = None,
) -> Dict[str, Any]:
"""
Perform detailed research with comprehensive analysis.
This tool performs a thorough research analysis on the given query, returning
structured data with detailed findings, sources, and metadata.
IMPORTANT: This is a synchronous operation that typically takes 5-15 minutes
to complete depending on the complexity and configuration.
Args:
query: The research question or topic to investigate.
search_engine: Search engine to use (e.g., "wikipedia", "arxiv", "searxng").
strategy: Research strategy to use (e.g., "source-based", "iterative", "evidence").
iterations: Number of search iterations (1-10). More iterations = deeper research.
questions_per_iteration: Questions to generate per iteration (1-5).
Returns:
Dictionary containing:
- status: "success" or "error"
- query: The original query
- research_id: Unique identifier for this research
- summary: The research summary text
- findings: List of detailed findings
- sources: List of source URLs
- iterations: Number of iterations performed
- metadata: Additional metadata (timestamp, search_tool, strategy)
- error/error_type: Error info (only if status is "error")
"""
try:
# Validate parameters
query = _validate_query(query)
iterations = _validate_iterations(iterations, max_val=20)
questions_per_iteration = _validate_questions_per_iteration(
questions_per_iteration
)
logger.info(f"Starting detailed research for query: {query[:100]}...")
overrides = _build_settings_overrides(
search_engine=search_engine,
strategy=strategy,
iterations=iterations,
questions_per_iteration=questions_per_iteration,
)
settings = (
create_settings_snapshot(overrides=overrides)
if overrides
else create_settings_snapshot()
)
result = ldr_detailed_research(query, settings_snapshot=settings)
return {
"status": "success",
"query": result.get("query", query),
"research_id": result.get("research_id", ""),
"summary": result.get("summary", ""),
"findings": result.get("findings", []),
"sources": result.get("sources", []),
"iterations": result.get("iterations", 0),
"formatted_findings": result.get("formatted_findings", ""),
"metadata": result.get("metadata", {}),
}
except ValidationError as e:
logger.warning("Validation failed for detailed research")
return _error_result(e, error_type="validation_error")
except PolicyDeniedError as e:
return _policy_denied_response(e, "Detailed research")
except Exception as e:
logger.exception(
f"Detailed research failed for query: {query[:100] if query else 'empty'}"
)
return _error_result(e, operation="Detailed research failed")
@mcp.tool()
def generate_report(
query: str,
search_engine: Optional[str] = None,
searches_per_section: int = 2,
) -> Dict[str, Any]:
"""
Generate a comprehensive markdown research report.
This tool generates a full structured research report with sections,
citations, and comprehensive analysis. The output is formatted as markdown.
IMPORTANT: This is a synchronous operation that typically takes 10-30 minutes
to complete due to the comprehensive nature of the report.
Args:
query: The research question or topic for the report.
search_engine: Search engine to use (e.g., "wikipedia", "arxiv", "searxng").
searches_per_section: Number of searches per report section (1-10). Default is 2.
Returns:
Dictionary containing:
- status: "success" or "error"
- content: The full report content in markdown format
- metadata: Report metadata (timestamp, query)
- error/error_type: Error info (only if status is "error")
"""
try:
# Validate parameters
query = _validate_query(query)
searches_per_section = _validate_searches_per_section(
searches_per_section
)
logger.info(f"Starting report generation for query: {query[:100]}...")
overrides = {}
if search_engine:
search_engine = _validate_search_engine(search_engine)
if search_engine:
overrides["search.tool"] = search_engine
settings = (
create_settings_snapshot(overrides=overrides)
if overrides
else create_settings_snapshot()
)
result = ldr_generate_report(
query,
settings_snapshot=settings,
searches_per_section=searches_per_section,
)
return {
"status": "success",
"content": result.get("content", ""),
"metadata": result.get("metadata", {}),
}
except ValidationError as e:
logger.warning("Validation failed for report generation")
return _error_result(e, error_type="validation_error")
except PolicyDeniedError as e:
return _policy_denied_response(e, "Report generation")
except Exception as e:
logger.exception(
f"Report generation failed for query: {query[:100] if query else 'empty'}"
)
return _error_result(e, operation="Report generation failed")
@mcp.tool()
def analyze_documents(
query: str,
collection_name: str,
max_results: int = 10,
) -> Dict[str, Any]:
"""
Search and analyze documents in a local collection.
This tool performs RAG (Retrieval Augmented Generation) search on a
local document collection and generates a summary of relevant findings.
Args:
query: The search query for the documents.
collection_name: Name of the local document collection to search.
max_results: Maximum number of documents to retrieve (1-100). Default is 10.
Returns:
Dictionary containing:
- status: "success" or "error"
- summary: Summary of findings from the documents
- documents: List of matching documents with content and metadata
- collection: Name of the collection searched
- document_count: Number of documents found
- error/error_type: Error info (only if status is "error")
"""
try:
# Validate parameters
query = _validate_query(query)
if not collection_name or not collection_name.strip():
raise ValidationError("Collection name cannot be empty") # noqa: TRY301
collection_name = collection_name.strip()
if not _COLLECTION_NAME_RE.match(collection_name):
raise ValidationError( # noqa: TRY301
"Collection name may only contain letters, digits, spaces, hyphens, and underscores (max 100 chars)"
)
max_results = _validate_max_results(max_results)
logger.info(
f"Analyzing documents in '{collection_name}' for query: {query[:100]}..."
)
# Build a settings snapshot the same way the other MCP tools do.
# Without this, analyze_documents falls back to JSON defaults +
# LDR_* env vars and silently ignores user-configured providers,
# API keys, and embedding model. Mirrors quick_research (line 278).
settings = create_settings_snapshot()
result = ldr_analyze_documents(
query=query,
collection_name=collection_name,
max_results=max_results,
settings_snapshot=settings,
)
return {
"status": "success",
"summary": result.get("summary", ""),
"documents": result.get("documents", []),
"collection": result.get("collection", collection_name),
"document_count": result.get("document_count", 0),
}
except ValidationError as e:
logger.warning("Validation failed for document analysis")
return _error_result(e, error_type="validation_error")
except PolicyDeniedError as e:
return _policy_denied_response(e, "Document analysis")
except Exception as e:
logger.exception(
f"Document analysis failed for collection: {collection_name if collection_name else 'empty'}"
)
return _error_result(e, operation="Document analysis failed")
@mcp.tool()
def search(
query: str,
engine: str,
max_results: int = 10,
) -> Dict[str, Any]:
"""
Search using a specific engine and return raw results without LLM processing.
This tool performs a direct search query against the specified engine and
returns raw results (title, link, snippet). No LLM is involved, making it
fast and free of LLM costs.
IMPORTANT: This is a fast operation, typically completing in 5-30 seconds.
Args:
query: The search query string.
engine: Search engine to use (e.g., "arxiv", "wikipedia", "searxng", "brave").
This is required — use list_search_engines() to see available options.
For "wayback", the query must contain a full http:// or https://
URL, or be only a bare domain such as example.com, optionally
with a port, path or query. The complete URL, including its
port, path, query and fragment, is looked up; words that
follow a URL without a space become part of it. A URL with a
user name or password before its host is not looked up, and
at most max_results URLs are.
max_results: Maximum number of results to return (1-100). Default is 10.
Returns:
Dictionary containing:
- status: "success" or "error"
- query: The original query
- engine: The engine used
- result_count: Number of results returned
- results: List of results, each with title, link, and snippet
- error/error_type: Error info (only if status is "error")
"""
try:
# Validate parameters
query = _validate_query(query)
max_results = _validate_max_results(max_results)
# Validate engine is non-empty (required parameter)
if not engine or not engine.strip():
raise ValidationError( # noqa: TRY301
"Engine name cannot be empty. Use list_search_engines() to see available options."
)
engine = engine.strip()
# Create settings snapshot (reused for all steps)
settings = create_settings_snapshot()
# Validate engine name against available engines
from local_deep_research.web_search_engines.search_engines_config import (
search_config,
)
engines_config = search_config(settings_snapshot=settings)
if engine not in engines_config:
available_names = sorted(engines_config.keys())
raise ValidationError( # noqa: TRY301
f"Unknown search engine '{engine}'. Available: {', '.join(available_names)}"
)
# Check API key requirement
engine_config = engines_config[engine]
if engine_config.get("requires_api_key", False):
api_key_setting = settings.get(
f"search.engine.web.{engine}.api_key"
)
api_key = None
if api_key_setting:
api_key = (
api_key_setting.get("value")
if isinstance(api_key_setting, dict)
else api_key_setting
)
if not api_key:
raise ValidationError( # noqa: TRY301
f"Engine '{engine}' requires an API key. "
f"Set the LDR_SEARCH_ENGINE_WEB_{engine.upper()}_API_KEY environment variable "
f"or configure it in the UI at search.engine.web.{engine}.api_key"
)
logger.info(
f"Starting search on '{engine}' for query: {query[:100]}..."
)
# Set thread-local settings context so that engine constructors
# which internally call get_llm() or get_setting_from_snapshot()
# (e.g., arxiv's JournalReputationFilter) can resolve settings.
from local_deep_research.config.thread_settings import (
clear_settings_context,
set_settings_context,
)
from local_deep_research.settings.manager import SnapshotSettingsContext
set_settings_context(SnapshotSettingsContext(settings))
try:
return _execute_search(query, engine, max_results, settings)
finally:
clear_settings_context()
except ValidationError as e:
logger.warning("Validation failed for search")
return _error_result(e, error_type="validation_error")
except PolicyDeniedError as e:
return _policy_denied_response(e, "Search")
except Exception as e:
logger.exception(
f"Search failed for query: {query[:100] if query else 'empty'}"
)
return _error_result(e, operation="Search failed")
def _egress_audit_net(settings: Dict[str, Any]):
"""Best-effort context manager that arms the egress audit-hook net for
a direct MCP search.
Direct MCP searches call ``engine.run()`` without going through
``AdvancedSearchSystem`` (which arms the net itself), so under
PRIVATE_ONLY/STRICT the socket-level backstop would otherwise stay
inactive for this path. Returns a nullcontext when the policy cannot
be built or a context is already armed — the factory PEP remains the
primary enforcement, and an unevaluable policy must not break MCP.
"""
from contextlib import nullcontext
try:
from local_deep_research.security.egress.audit_hook import (
active_egress_context,
get_active_context,
)
from local_deep_research.security.egress.policy import (
PolicyDeniedError,
context_from_snapshot,
resolve_run_primary_engine,
)
except Exception:
return nullcontext()
if not settings or get_active_context() is not None:
return nullcontext()
try:
ctx = context_from_snapshot(
settings,
resolve_run_primary_engine(settings),
username=settings.get("_username"),
)
except (PolicyDeniedError, ValueError):
logger.bind(policy_audit=True).debug(
"egress audit net not armed for MCP search: policy unevaluable",
exc_info=True,
)
return nullcontext()
except Exception:
return nullcontext()
return active_egress_context(ctx)
def _execute_search(
query: str, engine: str, max_results: int, settings: Dict[str, Any]
) -> Dict[str, Any]:
"""Execute the search after settings context is established."""
from local_deep_research.web_search_engines.search_engine_factory import (
create_search_engine,
)
search_engine = create_search_engine(
engine_name=engine,
llm=None,
settings_snapshot=settings,
programmatic_mode=True,
max_results=max_results,
)
if search_engine is None:
return _error_result(
f"Failed to create search engine '{engine}'. "
f"This engine may require an LLM or have other prerequisites. "
f"Check server logs for details.",
error_type="configuration_error",
)
try:
# Execute search with the egress audit-hook net armed (no-op
# under scopes that don't arm it or when policy is unavailable).
with _egress_audit_net(settings):
results = search_engine.run(query)
# Normalize results: ensure consistent 'snippet' key
for result in results:
if "snippet" not in result and "body" in result:
result["snippet"] = result["body"]
return {
"status": "success",
"query": query,
"engine": engine,
"result_count": len(results),
"results": results,
}
finally:
from local_deep_research.utilities.resource_utils import safe_close
safe_close(search_engine, "MCP search engine")
# =============================================================================
# Discovery Tools
# =============================================================================
@mcp.tool()
def list_search_engines() -> Dict[str, Any]:
"""
List available search engines.
Returns a list of search engines that can be used with the research tools.
Each engine has different strengths - some are better for academic research,
others for current events, etc.
Returns:
Dictionary containing:
- status: "success" or "error"
- engines: List of available search engine configurations
- error/error_type: Error info (only if status is "error")
"""
try:
from local_deep_research.api.settings_utils import (
create_settings_snapshot,
)
from local_deep_research.web_search_engines.search_engines_config import (
search_config,
)
settings = create_settings_snapshot()
engines_config = search_config(settings_snapshot=settings)
engines = []
for name, config in engines_config.items():
engine_info = {
"name": name,
"description": config.get("description", ""),
"strengths": config.get("strengths", []),
"weaknesses": config.get("weaknesses", []),
"requires_api_key": config.get("requires_api_key", False),
"is_local": config.get("is_local", False),
}
engines.append(engine_info)
return {
"status": "success",
"engines": sorted(engines, key=lambda x: x["name"]),
}
except Exception as e:
logger.exception("Failed to list search engines")
return _error_result(e, operation="Failed to list search engines")
@mcp.tool()
def list_strategies() -> Dict[str, Any]:
"""
List available research strategies.
Returns a list of research strategies that can be used with the research tools.
Each strategy has different characteristics suited for different types of queries.
Returns:
Dictionary containing:
- status: "success" or "error"
- strategies: List of available strategies with names and descriptions
- error/error_type: Error info (only if status is "error")
"""
try:
return {
"status": "success",
"strategies": get_available_strategies(),
}
except Exception as e:
logger.exception("Failed to list strategies")
return _error_result(e, operation="Failed to list strategies")
@mcp.tool()
def get_configuration() -> Dict[str, Any]:
"""
Get current server configuration.
Returns the current configuration settings being used by the MCP server,
including LLM provider, default search engine, and other settings.
Returns:
Dictionary containing:
- status: "success" or "error"
- config: Current configuration settings
- error/error_type: Error info (only if status is "error")
"""
try:
from local_deep_research.api.settings_utils import (
create_settings_snapshot,
extract_setting_value,
)
settings = create_settings_snapshot()
config = {
"llm": {
"provider": extract_setting_value(
settings, "llm.provider", "unknown"
),
"model": extract_setting_value(
settings, "llm.model", "unknown"
),
"temperature": extract_setting_value(
settings, "llm.temperature", 0.7
),
},
"search": {
"default_engine": extract_setting_value(
settings, "search.tool", DEFAULT_SEARCH_TOOL
),
"default_strategy": extract_setting_value(
settings, "search.search_strategy", "source-based"
),
"iterations": extract_setting_value(
settings, "search.iterations", 2
),
"questions_per_iteration": extract_setting_value(
settings, "search.questions_per_iteration", 3
),
"max_results": extract_setting_value(
settings, "search.max_results", 10
),
},
}
return {
"status": "success",
"config": config,
}
except Exception as e:
logger.exception("Failed to get configuration")
return _error_result(e, operation="Failed to get configuration")
# =============================================================================
# Server Entry Point
# =============================================================================
def configure_mcp_logging(sink=None):
"""Send this process's logs to stderr, with credentials redacted from
log messages, bound ``extra`` fields and rendered exceptions (value,
notes, chained and grouped exceptions), and control characters stripped.
MCP uses stdout for JSON-RPC, so logging goes to stderr. This runs in a
separate subprocess (ldr-mcp), so logger.remove() only affects this MCP
process, not the main LDR application.
"""
from ..security.log_sanitizer import redact_log_record
logger.remove()
# local_deep_research/__init__.py disables the package's own namespace, so
# without this nothing logged from inside the package reaches the sink and
# only third-party records get here. config_logger does the same on the
# web path.
logger.enable("local_deep_research")
# The same redaction chokepoint config_logger's _sanitize_record installs
# for the web process's sinks: control characters stripped (a query
# containing a newline used to split one WARNING into two stderr lines)
# AND credentials redacted (a bare api_key=/token= in a message, a secret
# bound via logger.bind(), or one inside an exception logged by the
# logger.exception() calls in this file), reaching this process's stderr
# without going through scrub_error first. loguru holds one patcher per
# process, so this has to be set here rather than inherited.
# redact_log_record lives in security/log_sanitizer.py rather than
# utilities/log_utils.py (which would pull in the web stack) precisely so
# the MCP subprocess can share it.
logger.configure(patcher=redact_log_record)
# diagnose=False: loguru's default is True, which renders repr() of every
# local in every traceback frame on exception. The many logger.exception()
# call sites in this file run with frame locals that hold credentials
# (api_key, Authorization headers, search-engine secrets), so leaving the
# default on would write them to the MCP client's stderr log on any
# failure. Companion to #4185 / config_logger's LDR_LOGURU_DIAGNOSE gate;
# the MCP subprocess has no debug mode, so the gate is unconditionally off.
#
# enqueue=True: mirrors config_logger's stderr sink (utilities/log_utils.py).
# Without it, this call blocks on stderr I/O while holding loguru's
# handler lock, and when stderr back-pressures every logging thread piles
# up behind that lock (#4431). The re-enable above (logger.enable(...))
# means every INFO+ record from the whole research pipeline now reaches
# this sink — that's exactly the condition #4431 was about, so this
# sink needs the same protection. Note it's a bounded grace window
# (roughly one queue pipe buffer, ~64KB on Linux), not immunity:
# SimpleQueue.put() still runs inside emit()'s handler lock and blocks
# once that buffer fills, so a stderr stall long enough to exhaust it
# reproduces the same pile-up. Safe with the control-char patcher above
# regardless: loguru applies core.patcher() to build the record and
# formats the sink's output string before handing it to the enqueue
# thread, so the message is already scrubbed by the time it's queued
# (verified in loguru._logger.Logger._log / loguru._handler.Handler.emit).
logger.add(
sink if sink is not None else sys.stderr,
level="INFO",
format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} | {message}",
diagnose=False,
enqueue=True,
)
def run_server():
"""Run the MCP server using STDIO transport."""
configure_mcp_logging()
# The drain `finally` opens immediately after the sink exists, not just
# around `mcp.run()`: the startup window below logs through the same
# enqueue=True sink, and the legacy-docstore sweep only catches
# `Exception`. A KeyboardInterrupt/SystemExit raised inside
# `migrate_legacy_docstores()` would otherwise escape with the startup
# lines still queued and reproduce the very inversion this fixes.
try:
from ..security.process_dump_policy import enforce_process_dump_policy
enforce_process_dump_policy()
logger.info("Starting Local Deep Research MCP server...")
# Phase-1 of the RAG plaintext-at-rest migration must run here too,
# not only in the ldr-web entrypoint: an MCP-only deployment (Claude
# Desktop / Code / OpenClaw) that never launches ldr-web would
# otherwise never purge a pre-existing legacy plaintext <hash>.pkl
# docstore, leaving chunk text on disk indefinitely. The sweep is
# filesystem-only (no DB/login needed), idempotent (a clean tree
# no-ops), and logs its own errors — wrapped so a cleanup issue never
# blocks the server. Mirrors web/app.py's main().
try:
from ..vector_stores.legacy_cleanup import (
migrate_legacy_docstores,
)
migrate_legacy_docstores()
except Exception:
logger.exception(
"Legacy RAG docstore migration failed at MCP startup"
)
mcp.run(transport="stdio")
finally:
# Drain the enqueue=True stderr sink (see configure_mcp_logging)
# before this function returns or raises, on every exit a
# `finally` covers - normal disconnect, Exception, and BaseException
# (KeyboardInterrupt) alike.
#
# loguru's enqueue=True handler runs a daemon writer thread reading
# off a multiprocessing.SimpleQueue; loguru/__init__.py registers
# `atexit.register(logger.remove)` for us, and draining (verified in
# the installed loguru 0.7.3's _handler.py) is FIFO-sentinel based:
# `Handler.stop()` enqueues a `None` sentinel and joins the writer
# thread, so every message queued ahead of it is written first. On
# its own, that atexit hook already keeps the *normal*-shutdown case
# from losing buffered lines, as long as the interpreter reaches a
# normal shutdown.
#
# What the atexit hook does NOT fix is ordering on an unhandled
# exception. CPython's default excepthook prints the traceback to
# stderr once the exception has finished propagating out of the top
# frame, and only afterwards does the interpreter run its atexit
# callbacks - so the atexit drain is strictly later than the
# traceback. Without this `finally`, whatever is still sitting in
# the queue when the exception is raised is written *after* the
# traceback, so the client's stderr capture can read [traceback]
# then [the log lines that led up to it], inverted from causal
# order. (Only records still queued at raise time invert; anything
# the writer thread already drained is unaffected.) Draining here,
# in a `finally` around the server body, runs while the exception is
# still propagating *through this frame* - strictly before it
# reaches the top-level excepthook - so the log lines that explain
# the crash are flushed first, then the traceback.
#
# This is `logger.complete()`, deliberately not `logger.remove()`
# (verified in the installed loguru 0.7.3): `remove(None)` empties the
# global handler table, so any record logged after this frame - a
# caller catching the exception to log its own failure, or background
# threads winding down - is silently dropped by `_log()`, which returns
# early on `not core.handlers`. No caller does the former today: the
# `ldr-mcp` console script (`pyproject.toml`:
# `local_deep_research.mcp:run_server`) and `mcp/__main__.py`'s bare
# `run_server()` call both invoke it with nothing wrapping the call to
# catch and log a failure of its own. The property is kept as a general
# guarantee `complete()` has over `remove()`, not a fix for an existing
# caller. `complete()` drains the same queue (per enqueue handler it
# enqueues a `True` confirmation token FIFO, then waits on the writer's
# confirmation event) while *retaining* every handler, so those later
# records still reach the sink. Sink teardown stays with its owner:
# loguru's atexit-registered `logger.remove()`.
#
# Boundedness, precisely: the *enqueue* side is byte-bounded
# back-pressure (SimpleQueue.put() runs under the handler lock and
# stalls producers once the pipe buffer fills - the #4431 / #5804
# window), but the drain itself is not time-bounded. The confirmation
# wait in `Handler.complete_queue()` passes no timeout, so a sink that
# blocks indefinitely blocks this `finally` indefinitely;
# `Logger.complete()` additionally holds `_core.lock` across that wait,
# so a concurrent `add`/`remove`/`configure` would block for the same
# duration (ordinary logging would not - `_log()` never takes that
# lock), and `tasks_to_complete()` briefly takes `_queue_lock`, the
# same lock the writer thread holds around `sink.write()`. loguru
# offers no honest bound to add here, so we accept the same
# unbounded-in-time wait the writer thread already needs to drain its
# queue. One practical consequence: a shutdown Ctrl-C now lands
# *inside* this drain, so a second Ctrl-C raises KeyboardInterrupt out
# of the `finally`, abandoning the drain and replacing whatever
# exception was propagating.
#
# One case that leaves out: a *dead* writer thread. `complete_queue()`
# first does `self._queue.put(True)` - which can itself block on a full
# pipe before the wait even starts, while holding both
# `Logger.complete()`'s `_core.lock` and its own `_confirmation_lock` -
# then waits on `_confirmation_event` with no timeout and no check that
# the writer thread is still alive to ever call `.set()` on it. If that
# thread has already died, `logger.complete()` never returns.
# `Handler.stop()` does not share this gap: `Thread.join()` returns
# immediately once its target thread has already finished, so a dead
# writer thread hangs `complete_queue()`, not `stop()`. Not reachable
# with the shipped sink: it defaults to `sys.stderr`, which CPython
# pins to `errors='backslashreplace'`, and a broken pipe raises
# `OSError`, which `ErrorInterceptor.print()` (`_error_interceptor.py`)
# itself catches around its own `sys.stderr.write()` when it reports a
# sink failure - so the writer thread's loop keeps running. It becomes
# reachable only if `sys.stderr` itself, not just this function's
# `sink` argument, is ever pointed at a stream whose `write()` can
# raise something other than `OSError`, since `ErrorInterceptor` always
# reports to `sys.stderr` directly, independent of the handler's
# configured sink. `Logger.enable()` and `.disable()` also take
# `_core.lock` (`_logger.py`'s `_change_activation()`, ~line 1782), so
# the full list of calls this drain can block is
# `add`/`remove`/`configure`/`enable`/`disable`.
#
# Limit, not a regression: SIGTERM under its default disposition
# kills the process outright and never runs this `finally` (nor
# loguru's atexit hook), so anything still queued is lost - which is
# what `scripts/mcp_smoke_test.sh`'s `timeout 5` does. Only in-band
# exits (return, exception, KeyboardInterrupt) are covered.
logger.complete()
if __name__ == "__main__":
run_server()