Ddg Web Search

DDG网络搜索

一个全面的包，用于通过CLI界面或模型上下文协议（MCP）服务器以编程方式搜索网络和获取网络内容。

特性

• 🔍 网络搜索器：使用带有浏览器自动化功能的DuckDuckGo搜索网络，以获得可靠的结果
• 📄 Web内容提取器：通过智能抓取从网页中获取和解析内容
• ⚡ MCP服务器：同时支持stdio和HTTP（SSE）传输的模型上下文协议服务器
• 💻 命令行接口：用于从终端搜索和获取内容的交互式CLI
• 🛡️ 速率限制：自动请求速率管理，以避免达到API限制
• 🔧 错误处理：针对浏览器自动化、HTTP请求和网络问题的强大错误处理
• 📝 TypeScript支持：完全支持TypeScript，具有全面的类型定义
• 🤖 浏览器自动化：使用Puppeteer进行可靠的web交互和JavaScript渲染

安装

NPM安装

要全局安装该软件包以供CLI和MCP使用，请执行以下操作：

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

或者在项目中本地安装：

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

对于MCP服务器依赖关系（自动包含）：

npm install @modelcontextprotocol/sdk puppeteer

Docker安装

使用Docker运行，以实现轻松部署和一致的环境：

# Pull from Docker Hub
docker pull realLV/ddg-web-search:latest

# Run HTTP server
docker run -p 3001:3001 realLV/ddg-web-search:latest \
  node dist/mcp.js --transport http --port 3001 --host 0.0.0.0

# Run CLI interactively
docker run -it realLV/ddg-web-search:latest node dist/cli.js interactive

或者在本地构建：

# Build from source
docker build -t ddg-web-search .

# Run HTTP server
docker run -p 3001:3001 ddg-web-search \
  node dist/mcp.js --transport http --port 3001 --host 0.0.0.0

# Run CLI interactively
docker run -it ddg-web-search node dist/cli.js interactive

看 用于发布详细信息和 医生.md 获取全面的Docker使用指南。

关键依赖关系

• 操纵者：用于可靠的浏览器自动化和JavaScript渲染
• 阿西奥斯：用于web内容获取中的HTTP请求
• 再见：用于HTML解析和内容提取
• 关闭：用于将HTML转换为Markdown
• MCP-SDK：用于模型上下文协议服务器功能

MCP服务器使用情况

该软件包包括一个模型上下文协议（MCP）服务器，该服务器将搜索和网络内容获取作为人工智能助手的工具。服务器同时支持这两种功能 标准 和 超文本传输协议 运输。

可用的MCP工具

1. 搜索：使用带有浏览器自动化的DuckDuckGo搜索网络

- 输入： { "query": "search terms" } - 返回：包含标题、URL和片段的格式化搜索结果列表 - 功能：验证码处理、反检测措施、JavaScript渲染

1. fetch_web_content：使用智能抓取从web URL获取和解析内容

- 输入： { "url": "https://example.com" } - 返回：带有元数据的解析文本内容（如果需要，内容将截断为10000个字符） - 功能：HTML到Markdown转换、元数据提取、内容清理

运行MCP服务器

标准传输（默认）

# Using global binary (after global install)
ddg-web-search-mcp

# Using npx
npx @lucid-spark/ddg-web-search mcp

# Using built files
npm run build
node dist/mcp.js

HTTP传输

# Development mode with HTTP transport
npm run mcp:http

# Production mode with HTTP transport
npm run mcp:http:build

# Or manually with custom port/host
node dist/mcp.js --transport http --port 3001 --host localhost

MCP配置

用于标准运输（默认）

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "ddg-web-search": {
      "command": "ddg-web-search-mcp",
      "args": [],
      "env": {}
    }
  }
}

或者使用npx：

{
  "mcpServers": {
    "ddg-web-search": {
      "command": "npx",
      "args": ["@lucid-spark/ddg-web-search", "mcp"],
      "env": {}
    }
  }
}

对于HTTP传输

启动HTTP服务器并配置MCP客户端以连接到HTTP端点：

# Start HTTP server (default port 3001)
npm run mcp:http:build

# Server will be available at:
# - Server info: http://localhost:3001/
# - SSE endpoint: http://localhost:3001/sse
# - Message endpoint: http://localhost:3001/message/{sessionId}

测试HTTP传输

测试HTML客户端可在 examples/http-client.html 以演示HTTP传输功能。启动HTTP服务器，在浏览器中打开HTML文件以测试连接。

命令行选项

# Show help
node dist/mcp.js --help

# Available options:
# -t, --transport     Transport type: 'stdio' or 'http' (default: stdio)
# -p, --port       Port for HTTP transport (default: 3001)
# -h, --host       Host for HTTP transport (default: localhost)

HTTP传输端点

使用HTTP传输时，服务器提供：

• 察看连接信息: GET / -返回服务器信息和可用端点
• SSE连接: GET /sse -建立服务器发送事件连接以接收响应
• 消息发送: POST /message/{sessionId} -向服务器发送MCP请求

HTTP端点示例：

GET http://localhost:3001/         # Server info
GET http://localhost:3001/sse      # SSE connection
POST http://localhost:3001/message/{sessionId}  # Send messages

CLI使用情况

全局安装后，您可以使用CLI和以下命令：

基本命令

# Search the web
ddg-web-search search "TypeScript tutorials"

# Fetch content from a URL
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

# Show version
ddg-web-search version

交互模式

启动互动模式，获得更具吸引力的体验：

ddg-web-search interactive

在交互模式下，您可以使用以下命令：

• search 或 s -搜索网页
• fetch 或 f -获取网络内容
• mcp -启动MCP服务器（stdio传输）
• mcp-http -启动MCP服务器（HTTP传输）
• help 或 h -显示帮助
• version 或 v -显示版本
• clear 或 cls -清除屏幕
• exit 或 quit 或 q -退出交互模式

CLI示例

# Search for JavaScript tutorials
ddg-web-search search "JavaScript tutorials"

# Fetch content from a specific URL
ddg-web-search fetch https://httpbin.org/html

# Start interactive session
ddg-web-search interactive

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

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

# Get help
ddg-web-search help

程序化API使用

基础示例

下面是一个如何使用WebSearcher和WebContentFetcher的简单示例：

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

async function main() {
  const searcher = new WebSearcher();
  const fetcher = new WebContentFetcher();

  try {
    // Search the web (uses Puppeteer browser automation with DuckDuckGo)
    const results = await searcher.search("TypeScript");
    console.log("Search Results:", results);

    // Fetch content from the first result (if available)
    if (results.length > 0) {
      const fetchResult = await fetcher.fetch(results[0].url);
      if (fetchResult.success && fetchResult.data?.content) {
        console.log("Content Length:", fetchResult.data.content.length);
        console.log("Page Title:", fetchResult.data.metadata?.title);
      }
    }
  } catch (error) {
    console.error("Error:", error);
  } finally {
    // Important: Close browser to free resources
    await searcher.close();
  }
}

main();

以编程方式使用MCP服务器

import { MCPServer } from "@lucid-spark/ddg-web-search/dist/mcp";

async function runMCPServer() {
  const server = new MCPServer();
  await server.run();
  // Server will handle MCP requests via stdio
}

runMCPServer();

api参考

网页搜索器

构造函数

new WebSearcher(headless?: boolean);

• headless （可选）：是否在无头模式下运行浏览器（默认： true)

- 吃起来 false 用于调试或手动验证码求解

方法

• search(query: string): Promise：使用浏览器自动化搜索DuckDuckGo，并返回一组搜索结果。线程安全，内置初始化互斥体，防止竞争条件。
• close(): Promise：关闭浏览器实例并释放资源（对内存管理很重要）

WebContentFetcher

构造函数

new WebContentFetcher(rateLimit?: number, rateLimitInterval?: number);

• rateLimit （可选）：每个间隔允许的请求数（默认值：1）
• rateLimitInterval （可选）：时间间隔（毫秒）（默认值：1000）

方法

• fetch(url: string): Promise：获取并返回指定URL的内容

命令行界面

构造函数

new CLI();

方法

• run(args: string[]): Promise：使用命令行参数运行CLI
• search(query: string): Promise：执行搜索并显示结果
• fetch(url: string): Promise：从URL获取内容并显示
• interactive(): Promise：启动交互模式

MCP服务器

构造函数

new MCPServer();

方法

• run(): Promise：启动侦听stdio的MCP服务器

类型

搜索结果

interface SearchResult {
  title: string; // The title of the search result
  url: string; // The URL of the search result
  snippet: string; // A brief description or snippet
  icon?: string; // Optional icon URL for the result
}

获取结果

interface FetchResult {
  success: boolean; // Whether the fetch was successful
  data?: WebContent; // Parsed web content (if available)
  error?: string; // Error message (if failed)
}

网页内容

interface WebContent {
  content: string; // Main content of the page (HTML converted to Markdown)
  metadata?: {
    // Optional metadata extracted from the page
    title?: string; // Page title
    description?: string; // Page description
    url?: string; // Page URL
    author?: string; // Page author
    publishDate?: string; // Publication date
  };
}

Docker支持

该项目包括对开发和生产环境的全面Docker支持。

Docker快速入门

# Using Docker Compose - HTTP transport
docker-compose --profile http up

# Using Docker Compose - Development mode
docker-compose -f docker-compose.dev.yml up

# Using Docker directly
docker build -t ddg-web-search .
docker run -p 3001:3001 ddg-web-search \
  node dist/mcp.js --transport http --port 3001 --host 0.0.0.0

Docker功能

• 🐳 多阶段构建 用于优化图像大小
• 🔒 非root用户 增强安全性
• 🚀 多个配置文件 （stdio、http、cli）
• 🔄 热重载 开发模式支持
• 🏥 健康检查 用于监测
• 📦 预配置铬 对于Puppeter

有关Docker的详细文档，包括高级用法、故障排除和最佳实践，请参阅 医生.md.

发展

配置常数

该包使用以下可配置常量：

网页搜索器:

• RATE_LIMIT_INTERVAL_MS：2000ms（每2秒1个请求）
• NAVIGATION_TIMEOUT_MS：30000ms（页面导航30秒）
• SELECTOR_WAIT_TIMEOUT_MS：5000毫秒（选择器等待5秒）
• CAPTCHA_MANUAL_SOLVE_TIMEOUT_MS：60000ms（手动验证码求解60秒）

Http客户端:

• DEFAULT_TIMEOUT_MS：10000ms（HTTP请求为10秒）

MCP服务器:

• MAX_CONTENT_LENGTH：10000个字符（内容截断限制）
• DEFAULT_HTTP_PORT：3001（HTTP传输默认端口）

命令行界面:

• CONTENT_PREVIEW_LENGTH：500个字符（预览显示限制）

建设项目

npm run build

运行测试

npm test

开发脚本

# Run example usage
npm run dev

# Test the package functionality
npm run test-package

# Run CLI in development mode
npm run cli help

# Run MCP server with stdio transport (development mode)
npm run mcp

# Run MCP server with HTTP transport (development mode)
npm run mcp:http

# Build and run compiled CLI
npm run cli:build help

# Build and run compiled MCP server with stdio transport
npm run mcp:build

# Build and run compiled MCP server with HTTP transport
npm run mcp:http:build

速率限制

WebSearcher和WebContentFetcher都包含内置的速率限制，以防止服务器不堪重负：

• 网页搜索器：默认情况下每2秒（2000ms）有1个请求-浏览器自动化的保守时间
• WebContentFetcher：可配置的速率限制（默认情况下每1000ms 1个请求）

错误处理

该软件包包括全面的错误处理：

• 捕获并记录网络错误
• 无效URL得到妥善处理
• 速率限制自动执行
• 正确键入和处理HTTP错误
• MCP服务器错误作为结构化错误响应返回
• 浏览器自动化错误（超时、验证码检测、连接问题）得到妥善处理
• 验证码检测：在无头模式下返回空结果；在非无头模式下手动求解最多等待60秒
• 资源清理确保浏览器实例不会发生内存泄漏
• 线程安全浏览器初始化可防止竞争条件

重要提示：总是打电话 searcher.close() 使用WebSearcher正确清理浏览器资源并防止内存泄漏。

CLI功能

CLI提供了一个丰富多彩的界面，包括：

• 🎨 彩色输出：不同类型的消息有不同的颜色
• 🔍 搜索功能：使用浏览器自动化直接从终端搜索网络
• 📥 内容获取：通过智能解析获取和预览web内容
• 🎯 交互模式：与指挥历史进行互动
• 📖 全面帮助：带示例的内置帮助系统
• ⚡ 快速性能：使用TypeScript构建以获得最佳性能
• 🧹 资源管理：自动清理浏览器资源

MCP集成

模型上下文协议服务器使AI助手能够：

• 🔍 搜索网络：使用具有高级浏览器自动化功能的web来呈现JavaScript内容
• 📄 获取内容：通过智能抓取从网页中检索和解析内容
• 🚀 双重运输支持：支持stdio和HTTP（SSE）传输
• ⚡ 速率限制：自动速率限制可防止API滥用
• 🛡️ 错误处理：通过结构化响应进行优雅的错误处理
• 📡 遵从标准：遵循人工智能助手集成的MCP规范
• 🤖 验证码感知：智能处理验证码挑战
• 🧹 资源效率的：正确清理浏览器实例

贡献

欢迎投稿！请打开一个问题或提交任何改进或错误修复的拉取请求。

开发设置

1. 克隆仓库
2. 安装依赖项： npm install
3. 构建项目： npm run build
4. 运行测试： npm test
5. 测试CLI： npm run cli help
6. 测试MCP服务器： npm run mcp

许可证

该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。