Argus

Multi-engine web search MCP server for AI agents. Searches Google + Bing + Yahoo via headless browser, extracts clean page content, and returns structured JSON. No API keys required.

Named after Argus Panoptes — the hundred-eyed giant of Greek mythology who sees everything.

Features

• Multi-engine search — Google + Bing + Yahoo via Playwright (headless Chromium). Three independent sources, zero API keys.
• Dual depth modes — basic (fast snippets) or advanced (full page content extraction)
• Content extraction — Mozilla's Readability strips chrome and returns clean body text
• Freshness filtering — optional time_range filters advanced results by detected publish date
• Highlights & metadata — advanced results include query-relevant highlights, publish date, and author when available
• Quality filtering — discards CAPTCHA pages, SPA shells, and near-empty content
• Encoding handling — automatic GBK/GB2312/Big5 → UTF-8 conversion via iconv-lite
• LRU cache — in-memory, 5-minute TTL, avoids redundant fetches within a session
• Rate limiting — per-hostname concurrency and interval controls for polite scraping
• Playwright fallback — headless Chromium for JS-rendered pages that plain HTTP can't get
• Resilient — partial results returned when one engine fails, never a hard error

Prerequisites

• Node.js ≥ 18
• Playwright Chromium（可选，用于 JS 渲染页面的 fallback）— 安装后运行 npx playwright install chromium

Installation

npm（推荐）

npm install -g @yikwing/argus

本地开发

git clone https://github.com/yikwing/argus.git && cd argus
bun install
npx playwright install chromium  # 可选，启用 headless 浏览器 fallback

MCP Configuration

使用 npm 包（推荐）

Add to your Claude Desktop or Claude Code mcpServers config:

{
  "mcpServers": {
    "argus": {
      "command": "npx",
      "args": ["-y", "@yikwing/argus"]
    }
  }
}

使用本地源码

{
  "mcpServers": {
    "argus": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/src/server.ts"]
    }
  }
}

Tool: argus_search

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | yes | — | Search query (1-500 chars). Use natural language, keywords, or phrases. | | depth | "basic" | "advanced" | yes | — | Basic = snippets only (~2-5s). Advanced = full page content (~5-15s). | | max_results | number | no | 10 | Number of results (1-20). | | time_range | "day" | "week" | "month" | "year" | no | — | Filter by detected publish date. Supplying this requires page metadata, so Argus performs advanced extraction even if depth is basic; undated results are kept. |

Example Response

{
  "query": "苹果 2026Q2 财报",
  "search_time_ms": 4873,
  "results": [
    {
      "title": "苹果发布2026年第二财季业绩",
      "url": "https://finance.sina.com.cn/stock/...",
      "snippet": "苹果公司今日发布2026财年第二季度财报...",
      "score": 0.95,
      "source_engines": ["google", "bing"],
      "content": "苹果公司今日发布2026财年第二季度财报，营收达到...",
      "content_length": 4827,
      "content_truncated": true,
      "site_name": "finance.sina.com.cn",
      "published_date": "2026-05-02T12:00:00.000Z",
      "author": "财经编辑部",
      "highlights": [
        {
          "text": "苹果公司今日发布2026财年第二季度财报，营收达到...",
          "score": 0.83
        }
      ]
    }
  ],
  "errors": [],
  "discarded": [
    {
      "url": "https://blocked.example.com",
      "reason": "captcha_detected"
    }
  ]
}

Development

# Development with watch mode
bun run dev

# Run tests
bun run test

# Run tests in watch mode
bun run test:watch

# Type-check
bun run typecheck

# CLI search
argus -q "kotlin multiplatform"                   # 全局安装后直接使用
bun run search -q "kotlin multiplatform"           # 本地开发
bun run search -q "kotlin multiplatform" --json    # machine-readable JSON
bun run search -q "kotlin multiplatform" --mcp     # MCP/script-safe JSON
ARGUS_MCP=1 bun run search -q "kotlin multiplatform"  # default JSON output

CLI Output Modes

• Default CLI output is a Catppuccin Mocha colored, human-readable result list.
• --no-color keeps the human-readable list format but disables ANSI colors.
• --json changes the output format to raw JSON for scripts and pipes.
• --mcp is the conservative machine mode: JSON output with colors disabled.
• Actual MCP server calls use src/server.ts and always return protocol-safe JSON; CLI color settings do not apply there.
• ARGUS_MCP=1 or ARGUS_OUTPUT=json makes JSON the default CLI output mode for scripts or wrappers.

Architecture

src/
├── server.ts              # MCP server entry point (argus_search tool)
├── search-pipeline.ts     # Core orchestrator: search → aggregate → fetch → extract
├── types.ts               # All shared type definitions
├── config.ts              # Configuration constants
├── browser.ts             # Shared Playwright browser instance manager
├── cache.ts               # In-memory LRU cache with TTL
├── fetcher.ts             # HTTP fetcher with encoding detection + rate limiting
├── aggregator.ts          # Cross-engine dedup, interleaving, and scoring
├── extractor.ts           # Content extraction via Mozilla Readability + quality filters
├── logger.ts              # Structured logging via Pino
├── playwright-fallback.ts # Headless Chromium fallback for JS-rendered pages
├── async-utils.ts         # Shared AbortSignal-aware async helpers
└── search/
    ├── google.ts          # Google via Playwright
    ├── yahoo.ts           # Yahoo via Playwright
    ├── bing-playwright.ts # Bing via Playwright
    ├── bing-api.ts        # Bing Web Search API adapter (not enabled by default)
    └── duckduckgo.ts      # DuckDuckGo HTML scraper (unreliable)

License

MIT