JedSearch MCP Server

Model Context Protocol (MCP) server for web search with embedded Playwright browser.

How It Works

JedSearch combines a web search API client with an embedded Playwright browser to deliver accurate, real-time web content:

1. Search – Queries the search API for top results by query.
2. Render – Launches a headless Chromium browser via Playwright WebSocket (ws://127.0.0.1:3000) to render JavaScript-heavy pages.
3. Extract – Strips UI noise (navbars, footers, ads, cookie banners) using CSS selectors, then parses clean HTML with unstructured.partition_html.
4. Fallback – If Playwright is unavailable, falls back to raw HTTP fetch with httpx.
5. Retry – Each page fetch retries up to 3 times with exponential backoff (0.5s × 1.5^n).

The container starts Playwright as a background sidecar process via entrypoint.sh, then runs the MCP server in the foreground on port 3001 (SSE or streamable-http transport).

Available Tools

Tool	Description
web_search	Search the web and fetch full page content for top results. Ideal for finding up-to-date API documentation, changelogs, release notes, or any information requiring live web lookup. Returns title, URL, strategy, and content for each result.
fetch_web_page	Fetch full page content from a single URL. Renders JavaScript via Playwright, falls back to HTTP. Returns title, URL, strategy, and content.

Configuration

Variable	Description	Default
YANDEX_SEARCH_API_KEY	Search API key	Required
YANDEX_FOLDER_ID	Cloud folder ID	Required
YANDEX_SEARCH_REGION	Search region (ru, en, tr)	ru
JEDSEARCH_API_KEY	API key for authentication	(optional)
MCP_TRANSPORT	Transport mode (stdio, sse, streamable-http)	stdio
MCP_PORT	Port for SSE mode	3001
PLAYWRIGHT_TIMEOUT	Playwright timeout (ms)	30000
HTTP_TIMEOUT	HTTP fallback timeout (s)	15
CONTENT_MAX_LENGTH	Max content length (chars)	32000
NOISE_THRESHOLD	Noise threshold (chars)	50
FETCH_MAX_RETRIES	Max retry attempts	3
FETCH_RETRY_DELAY	Initial retry delay (s)	0.5
FETCH_RETRY_BACKOFF	Backoff multiplier	1.5

Docker Compose Example

services:
  jedsearch:
    build: .
    container_name: jedsearch
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      YANDEX_SEARCH_API_KEY: "${YANDEX_SEARCH_API_KEY}"
      YANDEX_FOLDER_ID: "${YANDEX_FOLDER_ID}"
      YANDEX_SEARCH_REGION: "${YANDEX_SEARCH_REGION:-ru}"
      JEDSEARCH_API_KEY: "${JEDSEARCH_API_KEY}"
      MCP_TRANSPORT: streamable-http
      MCP_PORT: "3001"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:3001/health')"]
      interval: 10s
      timeout: 5s
      retries: 3

With a matching .env:

YANDEX_SEARCH_API_KEY=your-yandex-search-api-key
YANDEX_FOLDER_ID=your-yandex-folder-id
YANDEX_SEARCH_REGION=ru
JEDSEARCH_API_KEY=your-jedsearch-api-key

Start with:

cd jed-web-search-mcp-server
docker compose up --build --wait

Usage

Local (stdio)

YANDEX_SEARCH_API_KEY=... YANDEX_FOLDER_ID=... python3 server.py

VS Code (mcp.json)

Replace the URL with your own server address:

{
  "servers": {
    "JedSearch": {
      "url": "http://your-server-address:3001/mcp",
      "type": "http",
      "headers": {
        "X-API-Key": "your-api-key-here",
        "X-Search-Region": "ru"
      }
    }
  }
}