Skip to main content
Glama
deenesjakoruzh
thehappyboy

Web Search MCP

by thehappyboy
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

웹 검색 MCP

RRF 융합, 4계층 URL 추출, 제공자 상태 추적 기능을 갖춘 다중 소스 웹 검색 MCP 서버입니다.

상태

Phase 2: 5개 제공자 (SearXNG/ddgr/Tavily/Exa/opencli-zh), RRF 융합, 스니펫 정리 (규칙 + 선택적 LLM 압축), search/extract/doctor 도구, 자동 저하 기능이 있는 제공자 상태 추적.

Related MCP server: Prism

설치

Claude Desktop 3P 설정에 추가 (~/Library/Application Support/Claude-3p/configLibrary/<uuid>.json):

{
  "name": "web-search",
  "source": "user",
  "transport": "stdio",
  "command": "node",
  "args": ["/Users/hades/projects/web-search-mcp/bin/cli.js"],
  "env": {
    "SEARXNG_URL": "http://localhost:18443",
    "TAVILY_API_KEY": "...",
    "EXA_API_KEY": "...",
    "FIRECRAWL_API_KEY": "...",
    "WSM_LLM_PROVIDER": "haiku",
    "ANTHROPIC_API_KEY": "..."
  },
  "toolPolicy": {
    "search": "allow",
    "extract": "allow",
    "doctor": "allow"
  }
}

npm에 게시되면 command: "node" + 절대 경로를 command: "npx" + args: ["-y", "@thehappyboy/web-search-mcp@latest"]로 바꾸세요.

설정

환경 변수 (또는 cwd 또는 ~/.agents/skills/web-search/.env의 .env):

변수

기본값

필수

설명

SEARXNG_URL

http://localhost:18443

아니오

SearXNG 기본 URL

TAVILY_API_KEY

—

아니오

Tavily 제공자 활성화

EXA_API_KEY

—

아니오

Exa 제공자 활성화

FIRECRAWL_API_KEY

—

아니오

추출 파이프라인(계층 3)에서 Firecrawl 활성화

WSM_LLM_PROVIDER

none

아니오

haiku (Anthropic), local (Ollama), none (비활성화)

ANTHROPIC_API_KEY

—

아니오

WSM_LLM_PROVIDER=haiku일 때 필요

WSM_LOCAL_LLM_URL

—

아니오

WSM_LLM_PROVIDER=local일 때 필요

WSM_MAX_RESULTS

10

아니오

기본 최대 결과 수

WSM_TIMEOUT_MS

25000

아니오

전체 검색 타임아웃

키가 없는 제공자는 자동으로 비활성화됩니다. 검색 도구는 사용 가능한 제공자로 계속 작동합니다. ddgr, opencli, defuddle은 which를 통해 자동 감지됩니다.

도구

search

{
  query: string,              // required
  max_results?: number,       // 1-30, default 10
  category?: 'general'|'news'|'science',
  mode?: 'fast'|'quality',    // quality = LLM compression (top-5 results)
  providers?: string[],       // override default list (replace semantics)
}

반환:

{
  count: number,
  took_ms: number,
  providers_used: string[],     // providers that returned ≥1 result
  providers_failed: string[],   // providers that errored OR returned []
  results: [{
    title, url, snippet,
    providers: string[],        // which sources surfaced this URL (multi-source corroboration)
    rrf_score: number,          // reciprocal rank fusion score
  }]
}

opencli-zh 자동 라우팅: 쿼리에 知乎, 小红书, 雪球, B站, 微博 같은 키워드나 600519.SH 같은 패턴이 포함되면 opencli-zh 제공자가 해당 어댑터로 라우팅합니다. opencli_sites로 특정 사이트를 강제 지정할 수 있습니다 (제공자 확장을 통해 전달, 오케스트레이터 참조).

extract

{
  url: string,                 // required
  timeout?: number,            // 5-60 seconds, default 20
}

다음 4개 계층을 순서대로 시도하여 하나가 성공할 때까지 진행:

  1. defuddle — 가장 빠름, 순수 텍스트 사이트

  2. opencli 어댑터 — 알려진 사이트용 (zhihu/xiaohongshu/xueqiu/bilibili/weibo)

  3. Firecrawl — JS 렌더링 페이지 (FIRECRAWL_API_KEY 필요)

  4. opencli 브라우저 — 최후의 수단, 실제 Chrome 구동

반환:

{
  content: string,             // markdown
  source: 'defuddle'|'opencli'|'firecrawl'|'opencli-browser'|'none',
  took_ms: number,
  error?: string,              // only when source === 'none'
}

doctor

{} // no arguments

제공자 가용성 및 런타임 상태 통계 반환:

{
  providers: {
    searxng:    { available: true, url: "http://localhost:18443" },
    ddgr:       { available: true },
    tavily:     { available: true },
    exa:        { available: true },
    opencli_zh: { available: true },
    firecrawl:  { available: true },
    llm:        { available: true, provider: "haiku" },
  },
  health: {
    tavily: {
      total: 24,
      success: 15,
      fail: 9,
      success_rate: 0.625,
      last_failure: "2026-07-06T...",
      last_failure_reason: "timeout",
      recommendation: "healthy" | "insufficient" | "degraded",
    },
    // ...
  },
  version: "0.2.0",
}

제공자의 success_rate가 20개 이상의 샘플에서 0.5 미만으로 떨어지면 자동으로 건너뜁니다 (권장: degraded). 상태 통계는 메모리 내에 있으며 재시작 시 초기화됩니다.

개발

npm test                  # all tests (unit + integration, 158 total)
npm run test:unit         # unit only
npm run test:integration  # integration only (needs searxng at SEARXNG_URL)
npm start                 # start stdio server

아키텍처

MCP client (Claude/Cowork)
  │ JSON-RPC over stdio
  ▼
server.js ───┬── search tool ──→ search.js (orchestrator)
             ├── extract tool ─→ extract/index.js (4-layer pipeline)
             └── doctor tool ──→ health tracker snapshot

search.js:
  Provider layer (parallel, isolated failure)
    searxng | ddgr | tavily | exa | opencli-zh
  ▼
  Merger layer: normalize → dedup(URL) → RRF(k=60)
  ▼
  Cleaner layer: rules (default) | LLM compression (quality mode, top-5)
  ▼
  Health tracker records success/failure per provider

extract/index.js:
  defuddle → opencli adapter → Firecrawl → opencli browser
  (each layer returns null on failure, falls through to next)

단계 기록

  • Phase 1 (15개 작업): 4개 제공자 (searxng/ddgr/tavily/exa), RRF 융합, 규칙 기반 정리, stdio MCP, search 도구만

  • Phase 2 (8개 작업): opencli-zh 제공자, LLM 품질 모드, 4계층 extract, doctor + 상태 자동 저하

라이선스

MIT

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • mcp-serp

    MCP server for Google search results via SERP API

  • qsearch

    Multi-engine search for AI agents. Trust scoring, local corpus, MCP-native. Self-hostable, BYOK.

  • exa

    Fast, intelligent web search and web crawling. New mcp tool: Exa-code is a context tool for coding

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/thehappyboy/web-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server