# Agent Search MCP

> 🔍 Free multi-source search for AI agents — multi-source verification, token savings, MCP native.

[![License](https://img.shields.io/github/license/lennney/agent-search-mcp)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)

**Works with Hermes, Claude Code, Cursor, Windsurf, OpenClaw, and any MCP-compatible client.**

---

[English](#features) · [中文](#特性) · [安装](#quick-start) · [文档](#documentation)

---

## Quick Start

```bash
# Option 1: npx (recommended)
npx agent-search-mcp

# Option 2: global install
npm install -g agent-search-mcp
```

### Platform Setup

<details>
<summary><b>Hermes</b></summary>

```yaml
# ~/.hermes/config.yaml
mcp_servers:
  agent-search:
    command: npx
    args: ["agent-search-mcp"]
```
</details>

<details>
<summary><b>Claude Code</b></summary>

```json
// ~/.claude/mcp.json
{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b></summary>

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Windsurf</b></summary>

```json
// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>OpenClaw</b></summary>

```typescript
// openclaw.config.ts
{
  mcpServers: {
    "agent-search": {
      command: "npx",
      args: ["agent-search-mcp"]
    }
  }
}
```
</details>

---

## Features

### 🆓 Free by Default

No API key required. Uses DuckDuckGo + Sogou search engines.

| Engine | Type | API Key | Coverage |
|--------|------|---------|----------|
| DuckDuckGo | Free | ❌ | Global |
| Sogou | Free | ❌ | Chinese |
| Brave Search | Paid (Free Tier) | Optional | Global |
| Tavily | Paid (Free Tier) | Optional | Global |

### 🎯 Multi-Source Verification

Results are verified across multiple search engines. Each result includes a **confidence score** (1-3) based on how many engines returned it.

```json
{
  "title": "Build an MCP Server",
  "url": "https://example.com/mcp",
  "snippet": "How to build MCP servers...",
  "confidence": 2  // Verified by 2 engines
}
```

### 💰 Save Tokens

Optimized output reduces token consumption by ~40-50%:

| Optimization | Savings |
|-------------|---------|
| Top-1 snippet per URL | ~25% |
| Title truncation (≤100 chars) | ~15% |
| Snippet truncation (≤200 chars) | ~15% |
| Deduplication | ~10% |
| Confidence filtering | ~10% |

### 🔧 Progressive Disclosure

Three tools, discoverable by agents:

| Tool | Purpose | When to Use |
|------|---------|-------------|
| `free_search` | Basic search | Quick questions |
| `free_search_advanced` | Filtered search | Date ranges, domains, high confidence |
| `free_extract` | URL extraction | Read full page content |

---

## Tools

### `free_search`

Basic web search with multi-source verification.

```json
{
  "query": "TypeScript MCP server",
  "count": 5
}
```

### `free_search_advanced`

Advanced search with filters.

```json
{
  "query": "MCP server",
  "count": 10,
  "min_confidence": 2,
  "time_range": "week",
  "language": "zh",
  "include_domains": ["github.com"],
  "exclude_domains": ["reddit.com"]
}
```

**Parameters:**
- `min_confidence` (1-3): Only return results verified by N+ sources
- `time_range`: day, week, month, year
- `language`: auto, en, zh
- `include_domains`: Only search these domains
- `exclude_domains`: Exclude these domains

### `free_extract`

Extract full content from a URL as Markdown.

```json
{
  "url": "https://example.com/article",
  "max_length": 5000
}
```

---

## Resources

### `search://capabilities`

Returns a Markdown document describing all available tools and features. Agents can discover capabilities on-demand.

### `search://health`

Returns JSON with health status of each search provider:

```json
[
  {
    "provider": "duckduckgo",
    "lastSuccess": 1719000000000,
    "errorCount": 0,
    "avgLatency": 450,
    "isHealthy": true
  }
]
```

---

## Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `BRAVE_API_KEY` | Brave Search API key (2000 free/month) | No |
| `TAVILY_API_KEY` | Tavily API key (1000 free/month) | No |
| `LOG_LEVEL` | Log level (info, debug) | No |

**Zero config works** — no API keys needed for basic search.

### With Paid Engines

Set environment variables to enable fallback to paid engines when free results are insufficient:

```bash
export BRAVE_API_KEY=your_key_here
export TAVILY_API_KEY=your_key_here
```

---

## Architecture

```
Agent
  ↓ MCP Protocol (stdio)
MCP Server
  ├── Tools Layer (progressive disclosure)
  │   ├── free_search (default)
  │   ├── free_search_advanced (optional)
  │   └── free_extract (optional)
  ├── Aggregation Layer
  │   ├── Top-1 Snippet merge
  │   ├── URL + Title dedup
  │   ├── Scoring + Confidence
  │   └── Output truncation
  ├── Fallback Chain
  │   ├── Phase 1: Free engines (DDG + Sogou)
  │   └── Phase 2: Paid engines (Brave + Tavily)
  └── Infrastructure
      ├── Cache (LRU, 60s TTL)
      ├── Rate Limiter (1s per provider)
      ├── Health Tracker
      └── SSRF Protection
```

---

## Documentation / 文档

| Document | Description |
|----------|-------------|
| [PRD](docs/prd.md) | Product Requirements Document |
| [Architecture](docs/architecture.md) | Technical Architecture |
| [Plan](docs/plan.md) | Implementation Plan |
| [Review Results](docs/review-results.md) | 5-Team Review Results |
| [Fork Plan](docs/fork-plan.md) | Fork & Modification Plan |
| [CHANGELOG](CHANGELOG.md) | Version History |

---

## Development

```bash
# Clone
git clone https://github.com/lennney/agent-search-mcp.git
cd agent-search-mcp

# Install
npm install

# Build
npm run build

# Test
npm test

# Run
npm start
```

---

## License

[Apache License 2.0](LICENSE)

Based on [open-websearch](https://github.com/Aas-ee/open-websearch) by Aas-ee.

```
Copyright 2025 Open-WebSearch MCP Server Contributors
Based on open-websearch by Aas-ee (Apache 2.0).
Modified by Agent Search MCP Contributors.
Copyright 2026 Agent Search MCP Contributors
```

---

## Contributing

Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

---

## Keywords

MCP server, Model Context Protocol, AI agent search, free web search, multi-source search, DuckDuckGo MCP, Sogou search, token optimization, Hermes MCP, Claude Code MCP, Cursor MCP, AI tool, web search for agents, search aggregation, confidence scoring