# MCP WebSearch Server

MCP Server for web search and advanced web scraping. Uses SearchAPI.io for Google Search and AI Mode.

## Quick Start

### Option 1: Stdio (npx)

```json
{
  "mcpServers": {
    "websearch": {
      "command": "npx",
      "args": ["-y", "mcp-websearch-server"],
      "env": {
        "SEARCHAPI_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Option 2: HTTP Server (Streamable HTTP)

Run as HTTP server:
```bash
MCP_TRANSPORT=http PORT=3000 npx mcp-websearch-server
```

Then configure MCP client with API key in URL or header:

**Option A: API key in URL query parameter**
```json
{
  "mcpServers": {
    "websearch": {
      "url": "http://localhost:3000/mcp?apikey=YOUR_KEY",
      "transport": "streamable-http"
    }
  }
}
```

**Option B: API key in header**
```json
{
  "mcpServers": {
    "websearch": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http",
      "headers": {
        "X-API-Key": "YOUR_KEY"
      }
    }
  }
}
```

**Option C: Server-side default key**
```bash
MCP_TRANSPORT=http SEARCHAPI_KEY=default-key PORT=3000 npx mcp-websearch-server
```

The server implements MCP Streamable HTTP transport (spec 2025-03-26) with:
- Session management with `Mcp-Session-Id` headers
- SSE streaming for server-initiated messages
- Resumability support with `Last-Event-ID`
- Per-user API key support via query param or header

Get your API key at [searchapi.io](https://www.searchapi.io/)

## Tools

| Tool | Description |
|------|-------------|
| `web_search` | Google Search with pagination, time filter, site filter |
| `ai_search` | Google AI Mode - get AI-generated answers with sources |
| `web_scrape` | Advanced scraper with multiple extract modes (text/markdown/structured) |
| `get_links` | Extract links from a webpage with optional filter |
| `scrape_multiple` | Scrape up to 5 URLs at once |

## Parameters

### web_search
- `query` - Search query
- `num_results` - Number of results (1-20, default 10)
- `page` - Page number for pagination (1-10)
- `time_period` - Filter: last_hour, last_day, last_week, last_month, last_year
- `site` - Limit to specific site (e.g., "github.com")

### ai_search
- `query` - Question or topic
- `image_url` - Optional image URL for visual questions
- `location` - Location for local queries

### web_scrape
- `url` - URL to scrape
- `selector` - CSS selector (optional)
- `extract_mode` - text, markdown, or structured
- `include_links` - Include links in output
- `max_length` - Max content length (1000-50000)

### get_links
- `url` - URL to extract links from
- `filter` - Text filter for URLs/anchors

### scrape_multiple
- `urls` - Array of URLs (max 5)
- `max_per_page` - Max content per page (500-5000)

## Deployment

### PM2 (Production)

1. Edit `ecosystem.config.js` and set your `SEARCHAPI_KEY`
2. Run: `npm run pm2:start`
3. Check logs: `npm run pm2:logs`

Or manually:
```bash
MCP_TRANSPORT=http PORT=3000 SEARCHAPI_KEY=your-key pm2 start index.js --name mcp-websearch
```

### Docker

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
ENV MCP_TRANSPORT=http PORT=3000
EXPOSE 3000
CMD ["node", "index.js"]
```

## Roadmap

- [ ] Add Serper.dev provider support
- [ ] Add SerpAPI provider support
- [ ] Provider auto-fallback

## License

MIT