# Perplexity Search MCP

This tool wraps the search functionality of [Perplexity AI](https://www.perplexity.ai/) into a standardized tool using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It allows you to perform advanced search queries with filtering and customization options.

This project is built with TypeScript and runs on the [Bun](https://bun.sh/) runtime.

## ✨ Features

- Provides the `perplexity-search` tool via MCP.
- Supports various parameters for Perplexity search:
  - `query`: A single search query or an array of queries for multi-query search.
  - `max_results`: Specifies the maximum number of search results to return (maximum 20).
  - `country`: Filters search results by geographic location (e.g., 'US', 'GB', 'DE').
  - `max_tokens_per_page`: Controls the maximum number of tokens retrieved from each webpage during search processing. Higher values provide more comprehensive content extraction but may increase processing time.
  - `search_domain_filter`: A list of domains/URLs to restrict search results. For example: `["science.org", "pnas.org", "cell.com"]`
- Communicates with the host environment via standard input/output (Stdio).

## 🚀 Getting Started

### 1. Prerequisites

- Ensure you have [Bun](https://bun.sh/docs/installation) installed.
- Obtain an API key from Perplexity AI.

### 2. Installation

After cloning the project, run the following command in the root directory to install the required dependencies:

```bash
bun install
```

### 3. Configuration

Set the `PERPLEXITY_API_KEY` environment variable with your Perplexity API key.

### 4. Running the Server (Development)

To run the server directly from the TypeScript source for development, execute the following command:

```bash
bun run index.ts
```

The server will start and listen for MCP messages on standard I/O.

### 5. Building the Project

You can build the project into a single, optimized JavaScript file:

```bash
bun run build
```

This compiles `index.ts` and places the output in `dist/perplexity-search-mcp.js`.

After building, you can run the compiled file directly:

```bash
bun dist/perplexity-search-mcp.js
```

or

```bash
node dist/perplexity-search-mcp.js
```

## 🛠️ Tool Definition

### `perplexity-search`

**Description**: Retrieve ranked search results from Perplexity’s continuously refreshed index, with advanced filtering and customization options.

**Input Parameters**:

| Parameter             | Type                     | Description                                                                                                                                                    | Default  |
| --------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `query`               | `string` or `string[]`   | The search query or queries to execute. Can be a single query or a list of queries for multi-query search.                                                       | Required |
| `max_results`         | `number`                 | The maximum number of search results to return (must be a positive integer no greater than 20).                                                                   | `10`     |
| `country`             | `string`                 | Country code to filter search results by geographic location (e.g., 'US', 'GB', 'DE').                                                                          | Optional |
| `max_tokens_per_page` | `number`                 | Maximum number of tokens to retrieve from each webpage. Higher values yield more comprehensive content extraction but may increase processing time.          | `2048`   |
| `search_domain_filter`| `string[]`               | An optional list of domains/URLs to which search results should be limited (e.g., `["science.org", "pnas.org", "cell.com"]`).                                   | Optional |

**Output**:

The tool returns a JSON string containing an array of search results from the Perplexity API.