free_web_mcp

Free Web MCP — бесплатный MCP-сервер, предоставляющий Claude / Cursor / другим MCP-клиентам инструменты веб-поиска (DuckDuckGo, без API-ключа) и загрузки веб-страниц + извлечения основного текста.

Подробные требования см. в docs/free_web_mcp.md.

Инструменты

Related MCP server: qsearch

Быстрый старт

uv sync

Режим stdio (локальный клиент)

uv run free-web-mcp                # 或: uv run python -m free_web_mcp

Пример конфигурации для Cursor / Claude Desktop:

{
  "mcpServers": {
    "free-web-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/free_web_mcp", "free-web-mcp"]
    }
  }
}

Режим HTTP (удалённое развёртывание)

uv run free-web-mcp --transport http   # 监听 .env 中的 HOST/PORT，默认 0.0.0.0:8000
curl http://localhost:8000/health      # -> {"status":"ok","service":"free-web-mcp"}

MCP streamable-http endpoint: http://<host>:8000/mcp.

Docker

# 默认：仅 HTTP 抓取路径
docker build -f docker/Dockerfile -t free-web-mcp .
docker run --rm -p 8000:8000 free-web-mcp

# 启用 headless 渲染（构建时下载 Chromium ~150MB；首次启动约 1-3s）
docker build -f docker/Dockerfile --build-arg INSTALL_PLAYWRIGHT_BROWSERS=true -t free-web-mcp:render .
docker run --rm -p 8000:8000 -e RENDER_ENABLED=true free-web-mcp:render

Конфигурация (.env)

Скопируйте .env.example в .env и измените по необходимости; .env не хранится в репозитории.

Разработка

uv run pytest                  # 测试
uv run ruff check .            # lint
uv run mypy                    # 类型检查（strict）

Архитектура

Строгая многоуровневая архитектура: слой MCP Tool → слой Service (SearchService/FetchService) → слой Provider/HTTP. Источник поиска подключаемый (текущая реализация: DuckDuckGoProvider), весь HTTP проходит через WebClient, для извлечения основного текста приоритет у trafilatura, запасной вариант — BeautifulSoup. Подробнее см. AGENTS.md.