# 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

```yaml
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:
```bash
cd jed-web-search-mcp-server
docker compose up --build --wait
```

## Usage

### Local (stdio)
```bash
YANDEX_SEARCH_API_KEY=... YANDEX_FOLDER_ID=... python3 server.py
```

### VS Code (mcp.json)

Replace the URL with your own server address:
```json
{
  "servers": {
    "JedSearch": {
      "url": "http://your-server-address:3001/mcp",
      "type": "http",
      "headers": {
        "X-API-Key": "your-api-key-here",
        "X-Search-Region": "ru"
      }
    }
  }
}
```