feat: create web search MCP with DuckDuckGo integration and Gradio UI

.gitignore

@@ -0,0 +1,7 @@
+.venv
+poetry.lock
+.env
+.ruff_cache
+*.egg-info
+build
+__pycache__

Makefile

@@ -0,0 +1,11 @@
+install:
+	python -m pip install .
+
+format:
+	python -m ruff format .
+
+lint:
+	python -m ruff check --select I,RUF022 --fix .
+
+check:
+	python -m ruff check .

app.py

@@ -0,0 +1,25 @@
+import gradio as gr
+
+from search_engines.duckduckgo import duckduckgo_search
+
+duckduckgo_interface = gr.Interface(
+    fn=duckduckgo_search,
+    inputs=[
+        gr.Textbox(label="Search Query"),
+        gr.Slider(minimum=1, maximum=10, step=1, value=5, label="Number of Results"),
+    ],
+    outputs=gr.Dataframe(label="Search Results", headers=["title", "body", "link"]),
+    title="DuckDuckGo Search",
+    description="Search the web using DuckDuckGo Search Engine.",
+)
+
+app = gr.TabbedInterface(
+    interface_list=[duckduckgo_interface],
+    tab_names=["DuckDuckGo Search"],
+)
+
+
+if __name__ == "__main__":
+    app.launch(
+        mcp_server=True,
+    )

requirements.txt

@@ -0,0 +1,8 @@
+python-dotenv==1.1.0
+gradio==5.33.0
+pydantic==2.11.5
+pydantic_settings==2.9.1
+langchain-community==0.3.24
+duckduckgo-search==8.0.2
+pandas==2.2.3
+ruff==0.11.12

search_engines/duckduckgo.py

@@ -0,0 +1,30 @@
+import pandas as pd
+from langchain_community.tools import DuckDuckGoSearchResults
+from langchain_community.utilities.duckduckgo_search import DuckDuckGoSearchAPIWrapper
+
+from utils.helpers import map_results
+
+
+async def duckduckgo_search(query: str, max_results: int = 5) -> pd.DataFrame:
+    """
+    Given a search query, returns the search results from DuckDuckGo.
+
+    Args:
+        query (str): The search query.
+        max_results (int, optional): The number of maximum results to return. Defaults to 5.
+
+    Returns:
+        str: The search results from DuckDuckGo Search Engine.
+    """
+    ddg = DuckDuckGoSearchResults(
+        output_format="list",
+    )
+    ddg.max_results = max_results
+    results = await ddg.ainvoke(query)
+    mapping = {
+        "title": "title",
+        "link": "link",
+        "snippet": "body",
+    }
+    results = await map_results(results, mapping)
+    return results

utils/helpers.py

@@ -0,0 +1,21 @@
+import pandas as pd
+
+
+async def map_results(results: list[dict], mapping: dict[str, str]) -> pd.DataFrame:
+    values = list(mapping.values())
+    if "title" not in values:
+        raise ValueError("title is required in the mapping")
+    if "link" not in values:
+        raise ValueError("link is required in the mapping")
+    if "body" not in values:
+        raise ValueError("body is required in the mapping")
+    mapped_data = [
+        {mapping.get(key, key): value for key, value in result.items()}
+        for result in results
+    ]
+    result = {"title": [], "link": [], "body": []}
+    for data in mapped_data:
+        result["title"].append(data["title"])
+        result["link"].append(data["link"])
+        result["body"].append(data["body"])
+    return pd.DataFrame(result)