Metadata-Version: 2.4
Name: mcp-ferris-search
Version: 0.1.0
Summary: A blazing-fast MCP server for multi-engine web search
Project-URL: Homepage, https://github.com/lispking/ferris-search
Project-URL: Repository, https://github.com/lispking/ferris-search
Author: Ferris Search Team
License: Apache-2.0
Keywords: ai,claude,mcp,search,web
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp[cli]>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# MCP Ferris Search

A blazing-fast MCP (Model Context Protocol) server for multi-engine web search, written in Python.

This is a Python implementation inspired by the original [ferris-search](https://github.com/lispking/ferris-search) Rust project.

## Features

- **Multi-engine fan-out** — search across multiple engines simultaneously with a single call
- **9 search engines** — Bing, DuckDuckGo, Brave, Baidu, CSDN, Juejin, Zhihu, GitHub, GitHub Code
- **7 MCP tools** — `web_search` + 6 content fetchers
- **No API keys required** for most engines (Brave requires API key)
- **Proxy support** — HTTP/SOCKS5 proxy via environment variables

## Installation

### From PyPI (recommended)

```bash
pip install mcp-ferris-search
```

### Using uvx

```bash
uvx mcp-ferris-search
```

### From source

```bash
git clone https://github.com/your-username/mcp-ferris-search.git
cd mcp-ferris-search
pip install -e .
```

## Configuration

### Claude Desktop / Cursor

Add to your MCP settings:

```json
{
  "mcpServers": {
    "ferris-search": {
      "command": "uvx",
      "args": ["mcp-ferris-search"],
      "env": {
        "DEFAULT_SEARCH_ENGINE": "bing"
      }
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DEFAULT_SEARCH_ENGINE` | `bing` | Default engine when `engines` param is omitted |
| `ALLOWED_SEARCH_ENGINES` | all engines | Comma-separated allow-list |
| `BRAVE_API_KEY` | — | Required for Brave search |
| `GITHUB_TOKEN` | — | Optional, raises GitHub API rate limit |
| `USE_PROXY` | `false` | Enable HTTP/SOCKS5 proxy |
| `PROXY_URL` | `http://127.0.0.1:7890` | Proxy address |

## MCP Tools

### `web_search`

Search the web using one or more engines simultaneously.

```json
{
  "query": "rust async runtime",
  "engines": ["bing", "duckduckgo"],
  "limit": 10
}
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | required | Search query |
| `engines` | string[] | server default | Engines to search |
| `limit` | number | 10 | Max results per engine (1–50) |

Supported engines: `bing`, `duckduckgo`, `brave`, `baidu`, `csdn`, `juejin`, `zhihu`, `github`, `github_code`

### `fetch_web_content`

Fetch and extract text content from any public URL.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | required | Public HTTP/HTTPS URL |
| `max_chars` | number | 30000 | Max characters to return |

### `fetch_github_readme`

Fetch the README from a GitHub repository.

| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | string | GitHub repository URL |

### `fetch_csdn_article` / `fetch_juejin_article` / `fetch_zhihu_article`

Domain-specific fetchers with better content extraction.

| Tool | URL Constraint |
|------|----------------|
| `fetch_csdn_article` | must contain `csdn.net` |
| `fetch_juejin_article` | must contain `juejin.cn` and `/post/` |
| `fetch_zhihu_article` | must contain `zhihu.com` |

## Development

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with MCP Inspector for debugging
mcp dev src/mcp_ferris_search/server.py
```

## Publishing to PyPI

```bash
# Build
python -m build

# Upload
python -m twine upload dist/*
```

## Deploying to ModelScope MCP Hub

1. Publish to PyPI first
2. Go to https://modelscope.cn/mcp/servers/create?template=customize
3. Fill in the form:
   - **Name**: Ferris Search
   - **Source**: PyPI package `mcp-ferris-search`
   - **Hosting Type**: 可托管部署 (Hosted)
   - **Command**: `uvx mcp-ferris-search`

## License

Apache-2.0

## Acknowledgements

- Inspired by [ferris-search](https://github.com/lispking/ferris-search) (Rust version)
- Built with [FastMCP](https://github.com/anthropics/mcp) and [Model Context Protocol](https://modelcontextprotocol.io/)
