# LangSearch MCP Server

A Model Context Protocol (MCP) server that provides web search and semantic reranking capabilities using the [LangSearch API](https://docs.langsearch.com/).

## Features

- **Web Search**: Search billions of web documents with AI-optimized results
  - Full page summaries
  - Freshness filtering (day, week, month)
  - Customizable result count
  - Machine-readable structured output

- **Semantic Reranking**: Improve search accuracy with deep semantic understanding
  - Reorder documents by semantic relevance
  - Relevance scores (0-1 scale)
  - Better than traditional keyword/vector search
  - Top-N filtering

## Installation

### Prerequisites

- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- LangSearch API key from [https://langsearch.com](https://langsearch.com)

### Setup

1. Clone or navigate to the repository:
```bash
cd langsearch-mcp-python
```

2. Install dependencies:
```bash
uv sync
```

3. Configure your API key:
```bash
cp .env.example .env
# Edit .env and add your LANGSEARCH_API_KEY
```

## Usage

### Testing with MCP Inspector

Test the server interactively:
```bash
uv run mcp dev main.py
```

This opens the MCP Inspector where you can:
- Browse available tools
- Test tool invocations
- View structured responses

### Installing to Claude Desktop

Install the server for use with Claude Desktop:
```bash
uv run mcp install main.py
```

Follow the prompts to configure the installation.

### Manual Installation in Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "langsearch": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/langsearch-mcp-python",
        "run",
        "main.py"
      ],
      "env": {
        "LANGSEARCH_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Running as HTTP Server

For remote access, run as an HTTP server:
```python
# In main.py, change the last line to:
if __name__ == "__main__":
    mcp.run(transport="streamable-http")
```

Then run:
```bash
uv run main.py
```

Access at `http://localhost:8000/mcp`

## Tools

### web_search

Search the web for information across billions of documents.

**Parameters:**
- `query` (string, required): Search query
- `count` (integer, default=10): Number of results (1-50)
- `summary` (boolean, default=true): Include full page summaries
- `freshness` (string, default="noLimit"): Filter by freshness
  - `"noLimit"`: All results
  - `"day"`: Last 24 hours
  - `"week"`: Last 7 days
  - `"month"`: Last 30 days

**Returns:** Structured data with:
- Total result count
- Web pages with title, URL, snippet, summary
- Original query

**Example:**
```json
{
  "query": "latest AI developments 2026",
  "count": 5,
  "summary": true,
  "freshness": "week"
}
```

### semantic_rerank

Rerank documents based on semantic relevance to a query.

**Parameters:**
- `query` (string, required): Search query for ranking
- `documents` (array[string], required): List of document texts to rerank
- `top_n` (integer, optional): Return only top N results
- `model` (string, default="langsearch-reranker-v1"): Reranker model

**Returns:** Structured data with:
- Reranked documents with indices
- Relevance scores (0-1, higher = more relevant)
- Model used

**Example:**
```json
{
  "query": "machine learning algorithms",
  "documents": [
    "Deep learning is a subset of machine learning...",
    "The history of neural networks dates back...",
    "Random forests are ensemble learning methods..."
  ],
  "top_n": 2
}
```

## Development

### Project Structure

```
langsearch-mcp-python/
├── main.py              # MCP server implementation
├── pyproject.toml       # Project dependencies
├── uv.lock             # Locked dependencies
├── .env.example        # Example environment variables
├── .gitignore          # Git ignore rules
└── README.md           # This file
```

### Running Tests

```bash
# Test with MCP Inspector
uv run mcp dev main.py

# Test individual tools
uv run python -c "
from main import web_search
import asyncio
result = asyncio.run(web_search('Python programming', count=3))
print(result)
"
```

### Error Handling

The server provides clear error messages for:
- Missing API key
- Invalid parameters
- API errors
- Network issues

Errors are returned as structured exceptions with descriptive messages.

## API Reference

For detailed API documentation, see:
- [Web Search API](https://docs.langsearch.com/api/web-search-api)
- [Semantic Rerank API](https://docs.langsearch.com/api/semantic-rerank-api)

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `LANGSEARCH_API_KEY` | Yes | Your LangSearch API key |

## License

MIT

## Support

For issues and questions:
- LangSearch API: [docs.langsearch.com](https://docs.langsearch.com/)
- MCP Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io/)

## Contributing

Contributions are welcome! Please ensure:
- Type hints are used throughout
- Docstrings follow the existing format
- Error handling is comprehensive
- Tests pass with `uv run mcp dev`