DDG Web Search

Features

🔍

DuckDuckGo Web Search

Search the web using DuckDuckGo with browser automation, captcha handling, anti-detection measures, and JavaScript rendering support.

📄

Web Content Fetcher

Fetch and parse content from web pages with intelligent HTML-to-Markdown conversion, metadata extraction, and comprehensive error handling.

⚡

MCP Server

Model Context Protocol server with both stdio and HTTP (SSE) transport support for seamless AI assistant integration.

💻

CLI Interface

Interactive command line interface with colorful output, resource management, and engaging user experience.

🛡️

Rate Limiting

Conservative rate management with browser automation timing to respect server resources and avoid detection.

📝

TypeScript

Full TypeScript support with comprehensive type definitions, enhanced interfaces, and excellent developer experience.

Installation

Global Installation

Install globally for CLI and MCP usage:

npm install -g @lucid-spark/ddg-web-search

Local Installation

Install locally in your project:

npm install @lucid-spark/ddg-web-search

No Installation

Use it without installing it:

npx @lucid-spark/ddg-web-search

Quick Start

Command Line Interface

# Search the web with browser automation
ddg-web-search search "TypeScript tutorials"

# Fetch content with intelligent parsing
ddg-web-search fetch https://example.com

# Start interactive mode
ddg-web-search interactive

# Start MCP server (stdio transport)
ddg-web-search mcp

# Start MCP server (HTTP transport)
ddg-web-search mcp-http

# Show help
ddg-web-search help

MCP Server Setup

# Start MCP server with stdio transport
ddg-web-search-mcp

# Start with HTTP transport
node dist/mcp.js --transport http --port 3001

# Add to Claude Desktop config
{
  "mcpServers": {
    "ddg-web-search": {
      "command": "@lucid-spark/ddg-web-search-mcp",
      "args": [],
      "env": {}
    }
  }
}

Programmatic Usage

import { WebSearcher, WebContentFetcher } from "@lucid-spark/ddg-web-search";

const searcher = new WebSearcher();
const fetcher = new WebContentFetcher();

// Search the web with browser automation
const results = await searcher.search("TypeScript");

// Fetch web content with intelligent parsing
const content = await fetcher.fetch("https://example.com");

// Important: cleanup browser resources
await searcher.close();

API Overview

WebSearcher

search(query: string): Promise<SearchResult[]>

Search the web using DuckDuckGo with browser automation with captcha handling

WebContentFetcher

fetch(url: string): Promise<FetchResult>

Fetch and parse content with intelligent HTML-to-Markdown conversion

CLI

interactive(): Promise<void>

Start interactive command-line interface with resource management

MCPServer

run(): Promise<void>

Start MCP server with stdio or HTTP transport for AI assistant integration

DDG Web Search Package