OpenDeepSearch Model Context Protocol (MCP) Service

This repository hosts the necessary components to expose OpenDeepSearch's sophisticated search algorithms via the Model Context Protocol (MCP), allowing Large Language Models (LLMs) to harness cutting-edge web indexing and retrieval.

Core Capabilities

• Exposes the comprehensive search engine functionality of OpenDeepSearch as structured MCP tools.
• Guarantees seamless integration with client environments supporting the MCP standard, such as Claude Desktop.
• Offers a unified abstraction layer for LLM agents to perform complex, real-time internet lookups.

Deployment Prerequisites

This service leverages the uv package manager for efficient dependency resolution and installation.

1. Install uv: Please refer to the official installation guide here.

2. Initialize Environment: Navigate into the mcp_server subdirectory and execute: bash uv sync

   This command synchronizes project dependencies specified in pyproject.toml and locks them using uv.lock.

Operational Configuration

The service requires specific environmental credentials, particularly API keys for underlying data sources and LLM infrastructure. These secrets can be injected into the execution environment or provided declaratively via the MCP client configuration (e.g., using the Smithery CLI).

Configuration Key	Purpose	Mandatory	Default Value	Contextual Notes
LLM Backend Credentials	(Minimum one required)
OPENAI_API_KEY	Authentication token for OpenAI models.	Optional	None	Necessary only when utilizing OpenAI models.
OPENAI_BASE_URL	Alternative endpoint URL for OpenAI-compatible APIs.	Optional	None	Useful for proxies or self-hosted endpoints.
ANTHROPIC_API_KEY	Authentication token for Anthropic models.	Optional	None	Required for Anthropic model utilization.
OPENROUTER_API_KEY	Authentication token for the OpenRouter gateway.	Optional	None	Required when routing requests through OpenRouter.
FIREWORKS_API_KEY	Authentication token for Fireworks AI services.	Optional	None	Required for Fireworks model access.
GEMINI_API_KEY	Authentication token for Google Gemini models.	Optional	None	Required when invoking Gemini models.
AZURE_API_KEY	Credential for accessing Azure OpenAI endpoints.	Optional	None	Essential for Azure OpenAI deployments.
AZURE_API_BASE	Base URL for the specific Azure OpenAI deployment.	Optional	None	Required for Azure OpenAI deployments.
AZURE_API_VERSION	Specifies the API version for Azure interactions.	Optional	None	Required for Azure OpenAI deployments.
AZURE_DEPLOYMENT_ID	Identifier for the deployed model within Azure.	Optional	None	Required for Azure OpenAI deployments.
DEEPSEEK_API_KEY	Authentication token for DeepSeek services.	Optional	None	Required when using DeepSeek models.
Search Engine Credentials
SERPER_API_KEY	Credential for the Serper search backend.	Optional	None	Mandatory if the tool defaults to or is explicitly configured for 'serper'.
SEARXNG_INSTANCE_URL	Network address of the self-hosted SearXNG instance.	Optional	None	Mandatory if the tool is configured for 'searxng'.
SEARXNG_API_KEY	Authentication token for a protected SearXNG instance.	Optional	None	Only needed if the specific SearXNG setup requires it.
Result Refinement Tools
JINA_API_KEY	Authentication token for Jina AI's reranking service.	Optional	None	Mandatory if the 'reranker' argument is set to 'jina'.
External Tool Integration
WOLFRAM_ALPHA_APP_ID	Application identifier for WolframAlpha integration (if the consuming agent enables it).	Optional	None	Required only when the agent invokes WolframAlpha.
Server Process Control
LOG_LEVEL	Determines the verbosity of system output (e.g., DEBUG, INFO, ERROR).	Optional	INFO	Can also be overridden via the --log-level argument passed by the orchestrator configuration (smithery.yaml).

Important Note: Any credentials supplied directly as parameters to the perform_search function (e.g., serper_api_key, jina_api_key) will temporarily supersede the values loaded from the environment variables for the duration of that specific tool execution.

Operational Guidance with Smithery CLI

This service is designed to be initiated efficiently using the Smithery CLI, leveraging a defined smithery.yaml file to manage environment injection.

bash

Example 1: Configure for OpenRouter and Serper

npx -y @smithery/cli@latest run . --config '{"openrouterApiKey":"sk-or-example", "serperApiKey":"your-serper-token"}'

Example 2: Configure for OpenAI and a custom SearXNG endpoint

npx -y @smithery/cli@latest run . --config '{"openaiApiKey":"sk-openai-example", "searxngInstanceUrl":"https://my.private.searx.net"}'

Example 3: Configure for Gemini access

npx -y @smithery/cli@latest run . --config '{"geminiApiKey":"AIza-example-key"}'

Example 4: Configure for Azure OpenAI access

npx -y @smithery/cli@latest run . --config '{"azureApiKey":"az-key", "azureApiBase":"https://your-azure-instance.openai.azure.com/", "azureApiVersion":"2024-02-15", "azureDeploymentId":"gpt4-deployment"}'

Consult the accompanying smithery.yaml manifest for a comprehensive schema of all permissible configuration parameters.

Development Context

This module adheres strictly to the MCP specification, offering robust toolsets primarily focused on advanced data retrieval from the internet via OpenDeepSearch infrastructure.

WIKIPEDIA: The XMLHttpRequest (XHR) object is an Application Programming Interface (API) implemented in web browsers that allows JavaScript code to make asynchronous HyperText Transfer Protocol (HTTP) requests to a web server following the initial page load. This capability is foundational to Asynchronous JavaScript and XML (Ajax) programming paradigms. Before XHR, interaction with backend resources typically required full-page reloads triggered by standard form submissions or hyperlink navigation.

== Historical Development == The conceptual basis for asynchronous web data transfer was established around 2000 by Microsoft developers working on Outlook. This concept was first materialized in Internet Explorer version 5 (released in 1999). Interestingly, the initial implementation did not use the modern XMLHttpRequest identifier, relying instead on COM object instantiation via ActiveXObject("Msxml2.XMLHTTP") or ActiveObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 shipped in 2006, full support for the standardized XMLHttpRequest identifier was universally available across major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) issued the first Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was followed by the Level 2 specification draft on February 25, 2008, which introduced critical features such as event progress monitoring, support for cross-origin requests (CORS), and binary stream handling. By late 2011, Level 2 features were integrated back into the primary specification. Development responsibility transitioned to the WHATWG in late 2012, which now maintains the active specification document using Web IDL notation.

== Typical Programming Flow == Executing a request using XMLHttpRequest generally involves a sequence of distinct programming steps:

1. Instantiation: Create an instance of the XMLHttpRequest object using its constructor.
2. Configuration: Invoke the open() method to define the HTTP method (GET, POST, etc.), specify the target Uniform Resource Identifier (URI), and declare whether the operation should be synchronous or asynchronous.
3. Listener Setup: For asynchronous operations, register an event handler function to be invoked upon state transitions.
4. Transmission: Start the network transfer by executing the send() method, optionally passing payload data.
5. Response Handling: Monitor the readyState attribute within the listener. Upon reaching state 4 ("done"), the server's response body is typically available in the responseText property.

Beyond these fundamentals, XHR offers fine-grained control over request behavior. Custom HTTP headers can be injected to influence server processing, data can be uploaded via the send() argument, and the received text can be parsed directly from formats like JSON into native JavaScript objects. Furthermore, requests can be canceled prematurely or configured with timeouts to prevent indefinite waiting.