# rival-search-mcp

Adopt this skill: https://proskills.md/skills/other/damionrashford-rivalsearchmcp-plugins-rival-search-mcp-skills-skills-rival-searc

Page: https://proskills.md/skills/other/damionrashford-rivalsearchmcp-plugins-rival-search-mcp-skills-skills-rival-searc
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: plugins/rival-search-mcp-skills/skills/rival-search-mcp/SKILL.md
size: 3226
upstream: https://github.com/damionrashford/rivalsearchmcp/blob/main/plugins/rival-search-mcp-skills/skills/rival-search-mcp/SKILL.md

````text
---
name: rival-search-mcp
description: "Deterministic deep research via RivalSearchMCP. 9 tools: 5-engine web search (DuckDuckGo/Bing/Yahoo/Mojeek/Wikipedia), 9-platform social search (Reddit/HN/StackOverflow/Dev.to/Medium/ProductHunt/Bluesky/Lobste.rs/Lemmy), 5-source news (Google/Bing/Guardian/GDELT/DDG), 5 academic DBs (OpenAlex/CrossRef/arXiv/PubMed/EuropePMC), GitHub search, website mapping, content extraction with OCR, and research topic synthesis. No API keys required. Use when the user needs web research, competitive analysis, content discovery, or academic paper search."
---

# RivalSearchMCP

You have access to 9 research tools via the CLI at `scripts/cli.py`. Run all commands with `uv run scripts/cli.py`.

Every tool returns deterministic, auditable output. There is no in-server LLM — you're the one doing the synthesis.

## How to invoke tools

```bash
uv run scripts/cli.py call-tool <tool_name> --flag value
```

## Available tools

- `web_search` — concurrent search across DuckDuckGo, Bing, Yahoo, Mojeek, Wikipedia. Use for general web queries.
- `social_search` — Reddit, Hacker News, Stack Overflow, Dev.to, Medium, Product Hunt, Bluesky, Lobste.rs, Lemmy. Use for community discussions.
- `news_aggregation` — Google News, Bing News, The Guardian, GDELT, DuckDuckGo News. Use for current events. Accepts `--time-range day|week|month|anytime`.
- `github_search` — search public GitHub repos. Use for code, libraries, projects.
- `map_website` — crawl a site in `research` / `docs` / `map` mode. Use to explore site structure or documentation.
- `content_operations` — one tool, six ops (`retrieve`, `stream`, `analyze`, `extract`, `score`, `find_conflicts`). Use to get full page content, rate source quality, or surface disagreements between sources.
- `document_analysis` — extract text from PDFs, Word docs, images (image OCR via EasyOCR). Use for document processing.
- `research_topic` — end-to-end research workflow for a topic, combining search, content retrieval, and analysis.
- `scientific_research` — OpenAlex, CrossRef, arXiv, PubMed, Europe PMC (papers) + Kaggle, HuggingFace, Dataverse, Zenodo (datasets).

## When to chain tools

- Found a URL from search? → `content_operations --operation retrieve --url <url>`
- Want to assess source trust before using results? → `content_operations --operation score --urls '[…]'`
- Two sources seem to disagree? → `content_operations --operation find_conflicts --urls '[…]'`
- Found a PDF link? → `document_analysis --url <url>`
- Need to explore a website? → `map_website --url <url> --mode docs`
- Need a unified entity profile in one shot? → `research_topic --mode entity --topic "OpenAI"`

## Tool reference

For full flags, types, and defaults for each tool, read:

- [resources/search.md](resources/search.md) — web_search, social_search, news_aggregation, github_search, map_website
- [resources/content.md](resources/content.md) — content_operations, document_analysis
- [resources/research.md](resources/research.md) — research_topic, scientific_research

## Output

All tools return structured text to stdout. Errors go to stderr. Exit codes: 0 success, 1 tool error, 2 connection failed.
````

## File: README.md
upstream: https://github.com/damionrashford/rivalsearchmcp/blob/main/README.md

````text
# RivalSearchMCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
![MCP Server](https://img.shields.io/badge/MCP-Server-blue?style=for-the-badge)
![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white&style=for-the-badge)
![FastMCP](https://img.shields.io/badge/FastMCP-3.2+-green?style=for-the-badge)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?logo=linkedin&style=for-the-badge)](https://www.linkedin.com/in/damion-rashford)

![GitHub Stars](https://img.shields.io/github/stars/damionrashford/RivalSearchMCP?style=social)
![GitHub Forks](https://img.shields.io/github/forks/damionrashford/RivalSearchMCP?style=social)
![GitHub Issues](https://img.shields.io/github/issues/damionrashford/RivalSearchMCP?style=social)
![Last Commit](https://img.shields.io/github/last-commit/damionrashford/RivalSearchMCP?style=social)
![Visitor Count](https://visitor-badge.laobi.icu/badge?page_id=damionrashford.RivalSearchMCP)

**Deterministic research MCP server — web + social + academic + news + code + docs, all in one place. No API keys, no in-server LLM, structured outputs for agent chaining.**

> 🆓 **100% Free & Open Source** — No API keys or subscriptions for core tools. The hosted server includes fair-use rate limiting.

## What It Does

RivalSearchMCP is a FastMCP 3.x server exposing **9 specialized tools** that search, fetch, score, and compare information across:

- **5 web search engines** (DuckDuckGo, Bing, Yahoo, Mojeek, Wikipedia) — concurrent, deduplicated, with TLS-fingerprint-safe fetches via Scrapling
- **9 social platforms** (Reddit, Hacker News, Stack Overflow, Dev.to, Medium, Product Hunt, Bluesky, Lobste.rs, Lemmy) — no authentication
- **5 news sources** (Google News, Bing News, The Guardian, GDELT, DuckDuckGo News) — with time-range filtering
- **5 academic databases** (OpenAlex, CrossRef, arXiv, PubMed, Europe PMC) + **4 dataset hubs** (Kaggle, HuggingFace, Dataverse, Zenodo)
- **GitHub repositories** with built-in rate limiting
- **Documents** (PDF, Word, text, images) with OCR for images
- **Website traversal** with research, docs, and mapping modes

**No LLM runs inside the server.** Every tool returns deterministic, auditable output — the caller's model does the synthesis. Tools that benefit from structured output (`content_operations score`, `find_conflicts`) return `ToolResult` with both a human-readable markdown rendering and a parseable `structuredContent` dict, so agents can chain tool outputs without regex-parsing prose.

## ✅ Why It's Useful

- **One connection, nine tools** — no need to wire up separate MCP servers per source
- **Auto-quality scoring** — every result carries a tier/freshness/corroboration/citation score (0-100) and every multi-result response carries an aggregate confidence signal
- **Conflict detection** — `content_operations find_conflicts` surfaces numeric, date, and polarity disagreements across sources as a first-class signal instead of averaging them away
- **Entity profiles** — `research_topic(mode="entity")` fans out to 8 sources in parallel and returns a unified report with confidence
- **Production hygiene** — per-tool timeouts, rate limiting (100 req/min/session), response-size caps, error masking, middleware-level observability

## 💡 Example Query

Once connected, try asking your AI assistant:

> "Use RivalSearchMCP to research FastAPI vs Django. Run `research_topic` on both, aggregate recent news, check Reddit and Hacker News discussions, search GitHub for activity, look for academic papers, score the top sources, and flag any conflicts between them."

## 📦 How to Get Started

RivalSearchMCP runs as a **remote MCP server** hosted on FastMCP. Just follow the steps below to install, and go.

### Connect to Live Server

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=RivalSearchMCP&config=eyJ1cmwiOiJodHRwczovL1JpdmFsU2VhcmNoTUNQLmZhc3RtY3AuYXBwL21jcCJ9)

Or add this configuration manually:

**For Cursor:**
```json
{
  "mcpServers": {
    "RivalSearchMCP": {
      "url": "https://RivalSearchMCP.fastmcp.app/mcp"
    }
  }
}
```

**For Claude Desktop:**
- Go to Settings → Add Remote Server
- Enter URL: `https://RivalSearchMCP.fastmcp.app/mcp`

**For VS Code:**
- Add the above JSON to your `.vscode/mcp.json` file

**For Claude Code:**
- Use the built-in MCP management: `claude mcp add RivalSearchMCP --url https://RivalSearchMCP.fastmcp.app/mcp`

### Local Installation with FastMCP CLI

**Prerequisites:**
```bash
# Install UV (modern Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install FastMCP CLI (optional but recommended)
uv tool install fastmcp
```

**Method 1: One-Command Install (Easiest)**
```bash
# Clone repository
git clone https://github.com/damionrashford/RivalSearchMCP.git
cd RivalSearchMCP

# Install directly to your MCP client:
fastmcp install claude-desktop server.py   # For Claude Desktop
fastmcp install cursor server.py           # For Cursor
fastmcp install claude-code server.py      # For Claude Code
```

**Method 2: Quick Run (No Installation)**
```bash
git clone https://github.com/damionrashford/RivalSearchMCP.git
cd RivalSearchMCP

# Run directly with FastMCP CLI
fastmcp run server.py  # Auto-detects entrypoint, uses STDIO

# Or run in HTTP mode for testing
fastmcp run server.py --transport http --port 8000
```

**Method 3: Development with Inspector**
```bash
# Run with MCP Inspector for testing
fastmcp dev server.py
```

**Method 4: Manual UV Setup**
```bash
git clone https://github.com/damionrashford/RivalSearchMCP.git
cd RivalSearchMCP
uv sync

# Add to Claude Desktop or Cursor config:
{
  "RivalSearchMCP": {
    "command": "uv",
    "args": [
      "--directory",
      "/full/path/to/RivalSearchMCP",
      "run",
      "python",
      "server.py"
    ]
  }
}
```

## 🛠 Available Tools (9 Total)

Every tool carries `ToolAnnotations` (`readOnlyHint`, `openWorldHint`, `destructiveHint`, `idempotentHint`) so MCP clients like Claude and ChatGPT can skip confirmation prompts where safe. Every tool has a `timeout=` ceiling so a hung source can't stall the client.

### Search & Discovery (5 tools)
- **`web_search`** — concurrent multi-engine search across DuckDuckGo, Bing, Yahoo, Mojeek, and Wikipedia. Scrapling-backed TLS fingerprinting bypasses Cloudflare/Akamai fronting. Per-engine failures don't block the others.
- **`social_search`** — 9 platforms: Reddit, Hacker News, Stack Overflow, Dev.to, Medium, Product Hunt, Bluesky, Lobste.rs, Lemmy. No authentication.
- **`news_aggregation`** — 5 sources: Google News, Bing News, The Guardian, GDELT, DuckDuckGo News. Accepts `time_range` (day/week/month/anytime).
- **`github_search`** — repository search with built-in rate limiting (60/hr unauthenticated), optional README inclusion.
- **`map_website`** — traverse a site in `research`, `docs`, or `map` mode; returns per-page quality scores and an aggregate confidence signal.

### Content Analysis (3 tools)
- **`content_operations`** — one tool, six operations: `retrieve`, `stream`, `analyze`, `extract`, `score`, `find_conflicts`.
  - `score` rates URLs on tier / freshness / corroboration / citations (0-100) and returns both markdown + structured JSON.
  - `find_conflicts` compares 2-10 sources for numeric / date / polarity disagreements with confidence weights.
- **`research_topic`** — two modes: `topic` (search + fetch + relevance-ranked key findings) and `entity` (unified cross-source profile of a named entity, fanning out to web / news / GitHub / social / academic in parallel).
- **`document_analysis`** — extract text from PDF, Word, plain text, and images. Images use EasyOCR (lazy-loaded; no setup). 50 MB cap.

### Research Workflow (1 tool)
- **`scientific_research`** — academic paper and dataset search. 5 paper providers (OpenAlex, CrossRef, arXiv, PubMed, Europe PMC) and 4 dataset hubs (Kaggle, Hugging
````
