# Web Search MCP Server

A Model Context Protocol (MCP) server that provides a web search tool using the [Tavily API](https://tavily.com/). This server enables AI models to search the internet and retrieve up-to-date information.

## Overview

This MCP server implements a single tool:

- `search_web_tool`: Searches the web using Tavily API and returns relevant search results.

The server acts as a bridge between AI models and the Tavily search engine, allowing models to access current information from the internet during conversations.

## Features

- Real-time web search capabilities
- Customizable search parameters:
  - Search topic (general, news, finance)
  - Search depth (basic, advanced)
  - Maximum number of results
  - Time range filtering (day, week, month, year)
  - Domain inclusion/exclusion

## Requirements

- Python 3.13+
- [uv](https://github.com/astral-sh/uv) - Python package installer and resolver
- Tavily API key (sign up at [tavily.com](https://tavily.com/))

## Installation

1. Clone the repository (if applicable)

2. Set up a virtual environment using uv (optional but recommended):
   ```bash
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. Install dependencies using uv:
   ```bash
   uv pip sync
   ```

## Configuration

1. Create a `.env` file by copying the provided template:
   ```bash
   cp env-sample .env
   ```

2. Add your Tavily API key to the `.env` file:
   ```
   TAVILY_API_KEY=your-api-key-here
   ```

## Usage

Run the server using uv:

```bash
uv run web_search_server.py
```

The server operates using the stdio transport method for MCP communication, making it suitable for integration with various AI systems that support the Model Context Protocol.

### Tool Parameters

The `search_web_tool` accepts the following parameters:

- `query` (str, required): The search query.
- `search_topic` (str, optional): The topic of the search. Can be "general", "news", or "finance". Defaults to "general".
- `search_depth` (str, optional): The depth of the search. Can be "basic" or "advanced". Defaults to "basic".
- `max_results` (int, optional): The maximum number of results to return. Defaults to 1.
- `time_range` (str, optional): The time range for the search. Can be "day", "week", "month", or "year". Defaults to None.
- `include_domains` (list[str], optional): A list of domains to include in the search.
- `exclude_domains` (list[str], optional): A list of domains to exclude from the search.

## Response Format

The tool returns a list of search results, each containing:
- `title`: The title of the search result
- `url`: The URL of the search result
- `content`: The content of the search result
- `score`: The relevance score of the search result

## Error Handling

If an error occurs during the search operation, the tool will return an error message describing the issue.