# LangSearch MCP Server
A Model Context Protocol (MCP) server that provides access to LangSearch's Web Search API and Semantic Rerank API. This server enables AI assistants to perform web searches and rerank search results based on semantic relevance.
## Features
- **Web Search**: Search the web with advanced filtering options (freshness, result count, summaries)
- **Semantic Rerank**: Rerank documents based on semantic relevance to a query
## Tools
### 1. `langsearch_web_search`
Search the web using LangSearch's Web Search API.
**Parameters:**
- `query` (string, required): The search query
- `freshness` (string, optional): Filter results by freshness - "noLimit" (default), "onLimit", "day", "week", "month"
- `summary` (boolean, optional): Include full summaries in results (default: true)
- `count` (number, optional): Number of results to return (1-50, default: 10)
**Returns:**
- Structured search results with titles, URLs, snippets, and optional summaries
- Query context and metadata
### 2. `langsearch_semantic_rerank`
Rerank documents based on semantic relevance to a query.
**Parameters:**
- `query` (string, required): The search query to compare against documents
- `documents` (array of strings, required): List of document texts to rerank
- `top_n` (number, optional): Number of top results to return (default: all documents)
- `return_documents` (boolean, optional): Whether to include document text in response (default: true)
**Returns:**
- Reranked documents with relevance scores (0-1 scale)
- Original document indices and optional text content
## Installation
1. Clone or download this repository
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
4. Copy `.env.example` to `.env` and add your LangSearch API key:
```bash
cp .env.example .env
```
5. Edit `.env` and set your API key:
```
LANGSEARCH_API_KEY=your-api-key-here
```
## Getting a LangSearch API Key
Visit [LangSearch](https://langsearch.com) to sign up and obtain an API key.
## Usage
### With Claude Desktop
Add the server 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": "node",
"args": [
"/absolute/path/to/langsearch-mcp-ts/dist/index.js"
],
"env": {
"LANGSEARCH_API_KEY": "your-api-key-here"
}
}
}
}
```
Replace `/absolute/path/to/langsearch-mcp-ts` with the actual path to this project directory.
After configuration, restart Claude Desktop. The LangSearch tools will be available in your conversations.
### Standalone Mode
### Standalone Mode
#### Development Mode
Run the server in development mode with auto-reload:
```bash
npm run dev
```
#### Production Mode
Build and run the compiled server:
```bash
npm run build
npm start
```
### Testing with MCP Inspector
Test the server using the MCP Inspector:
```bash
npm run inspector
```
Then select "stdio" transport and provide the path to the server executable.
## Configuration
The server uses environment variables for configuration:
- `LANGSEARCH_API_KEY` (required): Your LangSearch API key
- `LANGSEARCH_BASE_URL` (optional): Custom API base URL (default: https://api.langsearch.com)
## Example Usage
### Web Search Example
```json
{
"name": "langsearch_web_search",
"arguments": {
"query": "latest developments in AI",
"freshness": "week",
"summary": true,
"count": 5
}
}
```
### Semantic Rerank Example
```json
{
"name": "langsearch_semantic_rerank",
"arguments": {
"query": "climate change solutions",
"documents": [
"Renewable energy is the future of power generation.",
"The stock market reached new highs today.",
"Carbon capture technology shows promise in reducing emissions."
],
"top_n": 2,
"return_documents": true
}
}
```
## API References
- [LangSearch Web Search API Documentation](https://docs.langsearch.com/api/web-search-api)
- [LangSearch Semantic Rerank API Documentation](https://docs.langsearch.com/api/semantic-rerank-api)
## Error Handling
The server implements comprehensive error handling:
- Invalid API keys return clear error messages
- Network errors are caught and reported
- Input validation ensures correct parameter types and ranges
- All errors are returned with `isError: true` flag
## TypeScript
This server is written in TypeScript with full type safety. All API responses and tool parameters are properly typed using zod schemas for runtime validation.
## License
MIT
