duckduckgo -agent

This MCP server provides a minimal HTTP/SSE interface to perform web searches via DuckDuckGo. It exposes MCP protocol methods such as initialize, tools/list, and tools/call (web_search) to let an LLM request search results. The server returns results as formatted markdown items with title, URL, and snippet delivered over SSE, making it simple to stream results to LM Studio or other clients. To use it, first start the server (e.g., via Python run) and then configure LM Studio with the supplied MCP endpoint. You can then initialize the session, list available tools, and call the web_search tool with parameters like query, max_results, region, safesearch, and timelimit.

Typical workflow:

• Initialize the MCP session with the initialize method.
• List tools to confirm the available tool names (e.g., web_search).
• Call the web_search tool using tools/call with a JSON-RPC payload specifying name: "web_search" and suitable arguments.

In LM Studio, add an mcp-config.json entry pointing to http://localhost:8000 (or your server URL). The server is designed to be LM Studio friendly and supports SSE streaming for live results as the search progresses.

Prerequisites:

• Python 3.10+ or Docker installed on your system.
• Optional: Docker for containerized runs.

Option A: Local development (Python)

1. Ensure Python 3.10+ is installed.
2. Install dependencies as needed (the project uses a minimal requirements.txt; see the repository for exact packages).
3. Start the server:
   • python mcp_http_sse_server.py
4. Server will listen on port 8000 by default (adjust via MCP_PORT env var as needed).

Option B: Docker (recommended for isolation)

1. Build the Docker image (if a Dockerfile is provided):
   • make docker-build
2. Run the container:
   • make docker-run
3. The server will be accessible at http://localhost:8000 by default (adjust via environment variables in your Docker setup).

Prerequisites summary:

• Python 3.10+ or Docker
• Optional: LM Studio for testing and integration

Notes and tips:

• The server uses a single-file FastAPI app with Server-Sent Events for streaming results to clients. It does not require API keys for DuckDuckGo.
• You can customize environment variables such as MCP_PORT, MCP_ENVIRONMENT, and MCP_LOG_LEVEL (see README or mcp-config.json for examples).
• If you run in Docker, ensure port 8000 (or your chosen port) is exposed and mapped correctly to your host.
• Use the provided mcp-config.json example to register the server with LM Studio. The example name used in the docs is duckduckgo-search; you can adapt the server name as you wish.
• For development comfort, there are Makefile targets like make install-dev, make run-dev, and make docker-* commands to automate setup, run, tests, and linting.
• If you encounter issues with streaming, verify that MCP_DEBUG is true and check logs for SSE formatting errors or network issues.