ddgs-mcp-server 0.2.0__tar.gz

ddgs_mcp_server-0.2.0/.env.example

@@ -0,0 +1,15 @@
+# --- PyPI Publishing Secrets ---
+# Required to publish the package to PyPI.
+# Get this from: https://pypi.org/manage/account/token/
+# 1. Log in to PyPI.
+# 2. Go to Account Settings -> API Tokens.
+# 3. Create a new token (scope: "Entire account" for new projects).
+# 4. Copy the token (starts with pypi-).
+TWINE_USERNAME=__token__
+TWINE_PASSWORD=pypi-xxxxxxxxxxxxxxxx
+
+# --- Application Configuration (Optional) ---
+# If you are running this in a restricted network or need to bypass rate limits.
+# DDGS supports http/https/socks5 proxies.
+# Example: http://user:pass@10.10.1.10:3128
+DDGS_PROXY=

ddgs_mcp_server-0.2.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

ddgs_mcp_server-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.env
+.venv
+venv/
+*.egg-info/

ddgs_mcp_server-0.2.0/Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY server.py .
+COPY start_api.sh .
+
+# Make startup script executable
+RUN chmod +x start_api.sh
+
+# Expose port
+EXPOSE 8000
+
+# Run the server
+CMD ["./start_api.sh"]

ddgs_mcp_server-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chirag Singhal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ddgs_mcp_server-0.2.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: ddgs-mcp-server
+Version: 0.2.0
+Summary: DuckDuckGo Search MCP Server
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: duckduckgo-search>=6.0.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# DDGS MCP Server
+
+A Model Context Protocol (MCP) server that provides DuckDuckGo Search capabilities to AI agents.
+
+## Features
+
+- **search_text**: advanced metasearch using `bing`, `brave`, `duckduckgo`, `google`, `mojeek`, `yahoo`, `yandex`, `wikipedia`.
+
+
+## Installation & Usage
+
+You can run this server directly using `uvx` without installing it globally.
+
+### VS Code (Claude Desktop / Cline)
+
+Add this to your MCP settings file (e.g., `cline_mcp_settings.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ddgs-search": {
+      "command": "uvx",
+      "args": [
+        "ddgs-mcp-server"
+      ],
+      "disabled": false,
+      "alwaysAllow": []
+    }
+  }
+}
+```
+
+### Manual Execution
+
+```bash
+uvx ddgs-mcp-server
+```
+
+
+## Secrets & Configuration
+
+This project technically **does not require API keys** to run locally, as it scrapes DuckDuckGo. However, for **publishing** or **proxy usage**, you should configure your environment.
+
+### 1. Set up Secrets
+Copy the example file:
+```bash
+cp .env.example .env
+```
+
+### 2. Required Tokens
+
+| Token | Purpose | How to Get It |
+| :--- | :--- | :--- |
+| **PyPI API Token** | Publishing to PyPI | 1. Go to [PyPI Account Settings](https://pypi.org/manage/account/token/)<br>2. Select "Add API Token"<br>3. Scope to "Entire account" (for first publish)<br>4. Set as `TWINE_PASSWORD` in `.env` |
+| **Proxy URL** | Bypassing Blocks (Optional) | Use any HTTP/SOCKS5 proxy provider if you encounter rate limits. |
+
+## Development / Publishing
+
+To build and publish this package to PyPI (using the secrets from above):
+
+1.  **Build**:
+    ```bash
+    pip install build twine
+    python -m build
+    ```
+
+2.  **Publish** (loads secrets from .env if you export them, or prompts you):
+    ```bash
+    # If using .env variables (PowerShell)
+    # $env:TWINE_USERNAME = "__token__"
+    # $env:TWINE_PASSWORD = "pypi-..."
+
+    python -m twine upload dist/*
+    ```

ddgs_mcp_server-0.2.0/README.md

@@ -0,0 +1,74 @@
+# DDGS MCP Server
+
+A Model Context Protocol (MCP) server that provides DuckDuckGo Search capabilities to AI agents.
+
+## Features
+
+- **search_text**: advanced metasearch using `bing`, `brave`, `duckduckgo`, `google`, `mojeek`, `yahoo`, `yandex`, `wikipedia`.
+
+
+## Installation & Usage
+
+You can run this server directly using `uvx` without installing it globally.
+
+### VS Code (Claude Desktop / Cline)
+
+Add this to your MCP settings file (e.g., `cline_mcp_settings.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ddgs-search": {
+      "command": "uvx",
+      "args": [
+        "ddgs-mcp-server"
+      ],
+      "disabled": false,
+      "alwaysAllow": []
+    }
+  }
+}
+```
+
+### Manual Execution
+
+```bash
+uvx ddgs-mcp-server
+```
+
+
+## Secrets & Configuration
+
+This project technically **does not require API keys** to run locally, as it scrapes DuckDuckGo. However, for **publishing** or **proxy usage**, you should configure your environment.
+
+### 1. Set up Secrets
+Copy the example file:
+```bash
+cp .env.example .env
+```
+
+### 2. Required Tokens
+
+| Token | Purpose | How to Get It |
+| :--- | :--- | :--- |
+| **PyPI API Token** | Publishing to PyPI | 1. Go to [PyPI Account Settings](https://pypi.org/manage/account/token/)<br>2. Select "Add API Token"<br>3. Scope to "Entire account" (for first publish)<br>4. Set as `TWINE_PASSWORD` in `.env` |
+| **Proxy URL** | Bypassing Blocks (Optional) | Use any HTTP/SOCKS5 proxy provider if you encounter rate limits. |
+
+## Development / Publishing
+
+To build and publish this package to PyPI (using the secrets from above):
+
+1.  **Build**:
+    ```bash
+    pip install build twine
+    python -m build
+    ```
+
+2.  **Publish** (loads secrets from .env if you export them, or prompts you):
+    ```bash
+    # If using .env variables (PowerShell)
+    # $env:TWINE_USERNAME = "__token__"
+    # $env:TWINE_PASSWORD = "pypi-..."
+
+    python -m twine upload dist/*
+    ```

ddgs_mcp_server-0.2.0/docker-compose.yml

@@ -0,0 +1,12 @@
+version: '3.8'
+
+services:
+  ddgs-mcp:
+    build: .
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/app
+    environment:
+      - PYTHONUNBUFFERED=1
+    restart: always

ddgs_mcp_server-0.2.0/main.py

@@ -0,0 +1,19 @@
+import asyncio
+import sys
+from mcp.server.stdio import stdio_server
+from server import server
+
+async def main():
+    """
+    Main entry point for UVX / Stdio usage.
+    """
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)

ddgs_mcp_server-0.2.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ddgs-mcp-server"
+version = "0.2.0"
+description = "DuckDuckGo Search MCP Server"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "duckduckgo-search>=6.0.0"
+]
+
+[project.scripts]
+ddgs-mcp-server = "ddgs_mcp_server.main:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ddgs_mcp_server"]

ddgs_mcp_server-0.2.0/requirements.txt

@@ -0,0 +1,5 @@
+mcp>=1.0.0
+duckduckgo-search>=6.0.0
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+sse-starlette>=2.0.0

ddgs_mcp_server-0.2.0/server.py

@@ -0,0 +1,216 @@
+
+import asyncio
+import json
+import logging
+import uuid
+from typing import Optional, Literal
+
+import uvicorn
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from sse_starlette.sse import EventSourceResponse
+
+# MCP Imports
+from mcp.server import Server
+from mcp.server.sse import SseServerTransport
+import mcp.types as types
+
+# DDGS Import
+from duckduckgo_search import DDGS
+
+# Logging Configuration
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("ddgs-mcp")
+
+app = FastAPI(title="DDGS MCP Server")
+
+# MCP Server
+server = Server("ddgs-mcp-server")
+
+# --- DDGS Wrappers ---
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="search_text",
+            description="Perform a text search using DuckDuckGo. Use this for general web queries.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query"},
+                    "region": {"type": "string", "default": "us-en", "description": "e.g., us-en, uk-en"},
+                    "safesearch": {"type": "string", "enum": ["on", "moderate", "off"], "default": "moderate"},
+                    "timelimit": {"type": "string", "enum": ["d", "w", "m", "y"], "default": None},
+                    "max_results": {"type": "integer", "default": 10}
+                },
+                "required": ["query"]
+            }
+        ),
+        types.Tool(
+            name="search_images",
+            description="Perform an image search using DuckDuckGo.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "region": {"type": "string", "default": "us-en"},
+                    "safesearch": {"type": "string", "default": "moderate"},
+                    "timelimit": {"type": "string", "default": None},
+                    "max_results": {"type": "integer", "default": 10}
+                },
+                "required": ["query"]
+            }
+        ),
+        types.Tool(
+            name="search_videos",
+            description="Perform a video search using DuckDuckGo.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "region": {"type": "string", "default": "us-en"},
+                    "safesearch": {"type": "string", "default": "moderate"},
+                    "timelimit": {"type": "string", "default": None},
+                    "max_results": {"type": "integer", "default": 10}
+                },
+                "required": ["query"]
+            }
+        ),
+        types.Tool(
+            name="search_news",
+            description="Perform a news search using DuckDuckGo.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "region": {"type": "string", "default": "us-en"},
+                    "safesearch": {"type": "string", "default": "moderate"},
+                    "timelimit": {"type": "string", "default": None},
+                    "max_results": {"type": "integer", "default": 10}
+                },
+                "required": ["query"]
+            }
+        ),
+         types.Tool(
+            name="search_books",
+            description="Perform a book search using DuckDuckGo (Anna's Archive backend).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "max_results": {"type": "integer", "default": 10}
+                },
+                "required": ["query"]
+            }
+        )
+    ]
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+    logger.info(f"Calling tool: {name} with args: {arguments}")
+
+    query = arguments.get("query")
+    region = arguments.get("region", "us-en")
+    safesearch = arguments.get("safesearch", "moderate")
+    timelimit = arguments.get("timelimit")
+    max_results = arguments.get("max_results", 10)
+
+    try:
+        # Using context manager for DDGS
+        with DDGS() as ddgs:
+            results = []
+            if name == "search_text":
+                results = ddgs.text(keywords=query, region=region, safesearch=safesearch, timelimit=timelimit, max_results=max_results)
+            elif name == "search_images":
+                results = ddgs.images(keywords=query, region=region, safesearch=safesearch, timelimit=timelimit, max_results=max_results)
+            elif name == "search_videos":
+                results = ddgs.videos(keywords=query, region=region, safesearch=safesearch, timelimit=timelimit, max_results=max_results)
+            elif name == "search_news":
+                results = ddgs.news(keywords=query, region=region, safesearch=safesearch, timelimit=timelimit, max_results=max_results)
+            elif name == "search_books":
+                # Check for books method availability or fallback
+                if hasattr(ddgs, 'books'):
+                    results = ddgs.books(keywords=query, max_results=max_results)
+                else:
+                    return [types.TextContent(type="text", text="Error: 'books' search backend not available in this version of python-ddgs.")]
+            else:
+                raise ValueError(f"Unknown tool: {name}")
+
+            return [types.TextContent(type="text", text=json.dumps(results, indent=2))]
+
+    except Exception as e:
+        logger.error(f"Error executing {name}: {e}")
+        return [types.TextContent(type="text", text=f"Error performing search: {str(e)}")]
+
+
+# --- SSE Transport Integration ---
+
+class SessionManager:
+    """Simple in-memory session manager for SSE transports."""
+    def __init__(self):
+        self.sessions = {}
+
+    def add_session(self, session_id: str, transport: SseServerTransport):
+        self.sessions[session_id] = transport
+
+    def get_session(self, session_id: str) -> Optional[SseServerTransport]:
+        return self.sessions.get(session_id)
+
+    def remove_session(self, session_id: str):
+        if session_id in self.sessions:
+            del self.sessions[session_id]
+
+session_manager = SessionManager()
+
+@app.get("/sse")
+async def handle_sse(request: Request):
+    import uuid
+
+    # Create a new transport for this connection
+    # The endpoint passed here is where the client should send messages (POST)
+    # We append the session ID to it so we can route correctly in the /messages handler
+    session_id = str(uuid.uuid4())
+    transport = SseServerTransport(f"/messages?session_id={session_id}")
+
+    async def sse_generator():
+        logger.info(f"New SSE connection: {session_id}")
+        session_manager.add_session(session_id, transport)
+
+        try:
+            # transport.connect_sse yields (read_stream, write_stream)
+            async with transport.connect_sse(request.scope, request.receive, request._send) as streams:
+                read_stream, write_stream = streams
+                # Run the MCP server for this session
+                await server.run(read_stream, write_stream, server.create_initialization_options())
+        except Exception as e:
+            logger.error(f"SSE session {session_id} error: {e}")
+            pass
+        finally:
+            logger.info(f"Closing SSE connection: {session_id}")
+            session_manager.remove_session(session_id)
+
+    return EventSourceResponse(sse_generator())
+
+@app.post("/messages")
+async def handle_messages(request: Request):
+    session_id = request.query_params.get("session_id")
+    if not session_id:
+        return JSONResponse(status_code=400, content={"error": "Missing session_id"})
+
+    transport = session_manager.get_session(session_id)
+    if not transport:
+        return JSONResponse(status_code=404, content={"error": "Session not found or expired"})
+
+    # Forward the request logic to the transport
+    # transport.handle_post_message processes the request body and pushes to the read stream
+    await transport.handle_post_message(request.scope, request.receive, request._send)
+    return JSONResponse(content={"status": "ok"})
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "active_sessions": len(session_manager.sessions)}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

ddgs_mcp_server-0.2.0/src/ddgs_mcp_server/main.py

@@ -0,0 +1,20 @@
+
+import asyncio
+import sys
+from mcp.server.stdio import stdio_server
+from .server import server
+
+async def run():
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+def main():
+    try:
+        asyncio.run(run())
+    except KeyboardInterrupt:
+        pass
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+
+if __name__ == "__main__":
+    main()

ddgs_mcp_server-0.2.0/src/ddgs_mcp_server/server.py

@@ -0,0 +1,70 @@
+
+import json
+import logging
+from typing import Optional, Literal
+from mcp.server import Server
+import mcp.types as types
+from duckduckgo_search import DDGS
+
+# Logging Configuration
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("ddgs-mcp")
+
+# MCP Server
+server = Server("ddgs-mcp-server")
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="search_text",
+            description="Perform a metasearch using various backends (DuckDuckGo, Google, Bing, etc.). Use this to find APIs, libraries, developer tools, and general information.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query"},
+                    "backend": {
+                        "type": "string",
+                        "enum": ["auto", "html", "lite", "bing", "brave", "duckduckgo", "google", "grokipedia", "mojeek", "yandex", "yahoo", "wikipedia"],
+                        "default": "auto",
+                        "description": "Search engine backend to use."
+                    },
+                    "region": {"type": "string", "default": "us-en", "description": "e.g., us-en, uk-en"},
+                    "safesearch": {"type": "string", "enum": ["on", "moderate", "off"], "default": "moderate"},
+                    "timelimit": {"type": "string", "enum": ["d", "w", "m", "y"], "default": None},
+                    "max_results": {"type": "integer", "default": 10}
+                },
+                "required": ["query"]
+            }
+        )
+    ]
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+    logger.info(f"Calling tool: {name} with args: {arguments}")
+
+    if name != "search_text":
+        raise ValueError(f"Unknown tool: {name}")
+
+    query = arguments.get("query")
+    backend = arguments.get("backend", "auto")
+    region = arguments.get("region", "us-en")
+    safesearch = arguments.get("safesearch", "moderate")
+    timelimit = arguments.get("timelimit")
+    max_results = arguments.get("max_results", 10)
+
+    try:
+        with DDGS() as ddgs:
+            results = ddgs.text(
+                keywords=query,
+                region=region,
+                safesearch=safesearch,
+                timelimit=timelimit,
+                max_results=max_results,
+                backend=backend
+            )
+            return [types.TextContent(type="text", text=json.dumps(results, indent=2))]
+
+    except Exception as e:
+        logger.error(f"Error executing {name}: {e}")
+        return [types.TextContent(type="text", text=f"Error performing search: {str(e)}")]

ddgs_mcp_server-0.2.0/start_api.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+uvicorn server:app --host 0.0.0.0 --port 8000 --reload