damionrashford/RivalSearchMCP / plugins/rival-search-mcp-skills/skills/rival-search-mcp
rival-search-mcp
VerifiedDeterministic 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.2 KB |
| resources/content.md | markdown | 3.3 KB |
| resources/research.md | markdown | 2.1 KB |
| resources/search.md | markdown | 4.5 KB |
| scripts/cli.pyexecutable | script | 21.5 KB |
scripts/cli.py
View on GitHub# /// script
# dependencies = [
# "fastmcp>=3.0.0",
# "cyclopts>=3.0.0",
# "rich>=13.0.0",
# ]
# requires-python = ">=3.10"
# ///
#!/usr/bin/env python3
"""RivalSearchMCP CLI — Deep research and competitor analysis from the terminal.
9 tools for web search, social media, news, GitHub, content extraction,
scientific papers, and AI-powered research. No API keys required.
Generated by: fastmcp generate-cli https://RivalSearchMCP.fastmcp.app/mcp
Usage:
uv run cli.py call-tool web_search --query "your query"
uv run cli.py call-tool social_search --query "AI agents" --platforms reddit --platforms hackernews
uv run cli.py list-tools
uv run cli.py --help
Exit codes:
0 Success
1 Tool returned an error
2 Connection failed (server unreachable)
3 Invalid arguments
"""
import json
import sys
from typing import Annotated
import cyclopts
import mcp.types
from fastmcp import Client
from rich.console import Console
# ---------------------------------------------------------------------------
# Configuration
# ---------------------------------------------------------------------------
# Modify this to change how the CLI connects to the MCP server.
CLIENT_SPEC = "https://RivalSearchMCP.fastmcp.app/mcp"
app = cyclopts.App(
name="rival-search",
help="RivalSearchMCP CLI — Deep research and competitor analysis. 9 tools, no API keys required.",
)
call_tool_app = cyclopts.App(name="call-tool", help="Call a tool on the server")
app.command(call_tool_app)
console = Console()
err_console = Console(stderr=True)
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _print_tool_result(result):
"""Print tool result. Data goes to stdout, errors to stderr."""
if result.is_error:
for block in result.content:
if isinstance(block, mcp.types.TextContent):
err_console.print(f"Error: {block.text}")
else:
err_console.print(f"Error: {block}")
sys.exit(1)
if result.structured_content is not None:
# Structured JSON to stdout for composability
print(json.dumps(result.structured_content, indent=2))
return
for block in result.content:
if isinstance(block, mcp.types.TextContent):
print(block.text)
elif isinstance(block, mcp.types.ImageContent):
size = len(block.data) * 3 // 4
err_console.print(f"[Image: {block.mimeType}, ~{size} bytes]")
elif isinstance(block, mcp.types.AudioContent):
size = len(block.data) * 3 // 4
err_console.print(f"[Audio: {block.mimeType}, ~{size} bytes]")
async def _call_tool(tool_name: str, arguments: dict) -> None:
"""Connect to server, call tool, print result. Non-interactive."""
filtered = {
k: v
for k, v in arguments.items()
if v is not None and (not isinstance(v, list) or len(v) > 0)
}
try:
async with Client(CLIENT_SPEC) as client:
result = await client.call_tool(tool_name, filtered, raise_on_error=False)
_print_tool_result(result)
if result.is_error:
sys.exit(1)
except Exception as e:
err_console.print(f"Error: Connection failed — {e}")
err_console.print(f"Server: {CLIENT_SPEC}")
err_console.print("Check your network connection or try again.")
sys.exit(2)
# ---------------------------------------------------------------------------
# List / read commands
# ---------------------------------------------------------------------------
@app.command
async def list_tools() -> None:
"""List all available tools with their parameters."""
try:
async with Client(CLIENT_SPEC) as client:
tools = await client.list_tools()
if not tools:
print(json.dumps({"tools": []}, indent=2))
return
output = []
for tool in tools:
props = tool.inputSchema.get("properties", {})
required = set(tool.inputSchema.get("required", []))
params = {}
for pname, pschema in props.items():
params[pname] = {
"type": pschema.get("type", "string"),
"required": pname in required,
}
output.append(
{
"name": tool.name,
"description": tool.description or "",
"parameters": params,
}
)
print(json.dumps({"tools": output}, indent=2))
except Exception as e:
err_console.print(f"Error: Connection failed — {e}")
sys.exit(2)
@app.command
async def list_resources() -> None:
"""List available resources as JSON."""
try:
async with Client(CLIENT_SPEC) as client:
resources = await client.list_resources()
output = []
for r in resources:
output.append(
{
"uri": str(r.uri),
"name": r.name or "",
"description": r.description or "",
}
)
print(json.dumps({"resources": output}, indent=2))
except Exception as e:
err_console.print(f"Error: Connection failed — {e}")
sys.exit(2)
@app.command
async def read_resource(uri: Annotated[str, cyclopts.Parameter(help="Resource URI")]) -> None:
"""Read a resource by URI."""
try:
async with Client(CLIENT_SPEC) as client:
contents = await client.read_resource(uri)
for block in contents:
if isinstance(block, mcp.types.TextResourceContents):
print(block.text)
elif isinstance(block, mcp.types.BlobResourceContents):
size = len(block.blob) * 3 // 4
err_console.print(f"[Blob: {block.mimeType}, ~{size} bytes]")
except Exception as e:
err_console.print(f"Error: Connection failed — {e}")
sys.exit(2)
@app.command
async def list_prompts() -> None:
"""List available prompts as JSON."""
try:
async with Client(CLIENT_SPEC) as client:
prompts = await client.list_prompts()
output = []
for p in prompts:
args = [a.name for a in p.arguments] if p.arguments else []
output.append(
{
"name": p.name,
"description": p.description or "",
"arguments": args,
}
)
print(json.dumps({"prompts": output}, indent=2))
except Exception as e:
err_console.print(f"Error: Connection failed — {e}")
sys.exit(2)
@app.command
async def get_prompt(
name: Annotated[str, cyclopts.Parameter(help="Prompt name")],
*arguments: str,
) -> None:
"""Get a prompt by name. Pass arguments as key=value pairs."""
parsed: dict[str, str] = {}
for arg in arguments:
if "=" not in arg:
err_console.print(f"Error: Invalid argument {arg!r} — expected key=value")
err_console.print("Usage: get-prompt <name> key1=value1 key2=value2")
sys.exit(3)
key, value = arg.split("=", 1)
parsed[key] = value
try:
async with Client(CLIENT_SPEC) as client:
result = await client.get_prompt(name, parsed or None)
for msg in result.messages:
console.print(f"[bold]{msg.role}:[/bold]")
if isinstance(msg.content, mcp.types.TextContent):
console.print(f" {msg.content.text}")
elif isinstance(msg.content, mcp.types.ImageContent):
size = len(msg.content.data) * 3 // 4
err_console.print(f" [Image: {msg.content.mimeType}, ~{size} bytes]")
else:
console.print(f" {msg.content}")
console.print()
except Exception as e:
err_console.print(f"Error: Connection failed — {e}")
sys.exit(2)
# ---------------------------------------------------------------------------
# Tool commands (generated from server schema)
# ---------------------------------------------------------------------------
@call_tool_app.command(name="web_search")
async def web_search(
*,
query: Annotated[str, cyclopts.Parameter(help="Search query string")],
num_results: Annotated[
int, cyclopts.Parameter(help="Number of results per engine (default: 10)")
] = 10,
extract_content: Annotated[
bool, cyclopts.Parameter(help="Extract full page content (default: true)")
] = True,
follow_links: Annotated[
bool, cyclopts.Parameter(help="Follow internal links (default: true)")
] = True,
max_depth: Annotated[
int, cyclopts.Parameter(help="Maximum depth for link following (default: 2)")
] = 2,
use_fallback: Annotated[
bool, cyclopts.Parameter(help="Use fallback strategy if engine fails (default: true)")
] = True,
) -> None:
"""Search across Yahoo and DuckDuckGo engines with fallback support.
Examples:
uv run cli.py call-tool web_search --query "best MCP servers 2026"
uv run cli.py call-tool web_search --query "competitor analysis" --num-results 20"""
await _call_tool(
"web_search",
{
"query": query,
"num_results": num_results,
"extract_content": extract_content,
"follow_links": follow_links,
"max_depth": max_depth,
"use_fallback": use_fallback,
},
)
@call_tool_app.command(name="map_website")
async def map_website(
*,
url: Annotated[str, cyclopts.Parameter(help="Website URL to traverse")],
mode: Annotated[
str, cyclopts.Parameter(help="Traversal mode: research, docs, map (default: research)")
] = "research",
max_pages: Annotated[
int, cyclopts.Parameter(help="Maximum pages to traverse (default: 5)")
] = 5,
max_depth: Annotated[
int, cyclopts.Parameter(help="Maximum depth for mapping (default: 2)")
] = 2,
generate_llms_txt: Annotated[
bool, cyclopts.Parameter(help="Generate llms.txt output (default: false)")
] = False,
) -> None:
"""Map and explore websites with different modes.
Modes:
research — General-purpose website exploration
docs — Documentation-focused traversal
map — Site structure mapping
Examples:
uv run cli.py call-tool map_website --url "https://docs.example.com" --mode docs
uv run cli.py call-tool map_website --url "https://example.com" --mode map --max-pages 20"""
await _call_tool(
"map_website",
{
"url": url,
"mode": mode,
"max_pages": max_pages,
"max_depth": max_depth,
"generate_llms_txt": generate_llms_txt,
},
)
@call_tool_app.command(name="content_operations")
async def content_operations(
*,
operation: Annotated[
str, cyclopts.Parameter(help="Operation: retrieve, stream, analyze, extract")
],
url: Annotated[
str | None, cyclopts.Parameter(help="URL for retrieve/stream/extract operations")
] = None,
content: Annotated[
str | None, cyclopts.Parameter(help="Content string for analyze operation")
] = None,
extraction_method: Annotated[
str, cyclopts.Parameter(help="For retrieve: auto, html, text, markdown (default: auto)")
] = "auto",
analysis_type: Annotated[
str,
cyclopts.Parameter(
help="For analyze: general, sentiment, technical, business (default: general)"
),
] = "general",
max_links: Annotated[
int, cyclopts.Parameter(help="For extract: max links to extract (default: 100)")
] = 100,
link_type: Annotated[
str,
cyclopts.Parameter(
help="For extract: all, internal, external, images, documents (default: all)"
),
] = "all",
extract_key_points: Annotated[
bool, cyclopts.Parameter(help="For analyze: extract key points (default: true)")
] = True,
summarize: Annotated[
bool, cyclopts.Parameter(help="For analyze: create summary (default: true)")
] = True,
include_metadata: Annotated[
bool, cyclopts.Parameter(help="Include metadata in response (default: true)")
] = True,
) -> None:
"""Consolidated content operations: retrieve, stream, analyze, extract.
Operations:
retrieve — Fetch and extract content from a URL
stream — Stream content from a URL
analyze — Analyze content with sentiment/technical/business analysis
extract — Extract links and resources from a page
Examples:
uv run cli.py call-tool content_operations --operation retrieve --url "https://example.com"
uv run cli.py call-tool content_operations --operation analyze --content "Your text" --analysis-type sentiment
uv run cli.py call-tool content_operations --operation extract --url "https://example.com" --link-type external
"""
await _call_tool(
"content_operations",
{
"operation": operation,
"url": url,
"content": content,
"extraction_method": extraction_method,
"analysis_type": analysis_type,
"max_links": max_links,
"link_type": link_type,
"extract_key_points": extract_key_points,
"summarize": summarize,
"include_metadata": include_metadata,
},
)
@call_tool_app.command(name="research_topic")
async def research_topic(
*,
topic: Annotated[str, cyclopts.Parameter(help="Research topic")],
sources: Annotated[
str | None, cyclopts.Parameter(help="JSON array of specific sources to use")
] = None,
max_sources: Annotated[
int, cyclopts.Parameter(help="Maximum sources to research (default: 5)")
] = 5,
include_analysis: Annotated[
bool, cyclopts.Parameter(help="Include content analysis (default: true)")
] = True,
) -> None:
"""End-to-end research workflow for a topic.
Combines search, content retrieval, and analysis into a single operation.
Examples:
uv run cli.py call-tool research_topic --topic "LLM agent frameworks"
uv run cli.py call-tool research_topic --topic "MCP servers" --max-sources 10"""
sources_parsed = json.loads(sources) if isinstance(sources, str) else sources
await _call_tool(
"research_topic",
{
"topic": topic,
"sources": sources_parsed,
"max_sources": max_sources,
"include_analysis": include_analysis,
},
)
@call_tool_app.command(name="scientific_research")
async def scientific_research(
*,
operation: Annotated[
str, cyclopts.Parameter(help="Operation: academic_search or dataset_discovery")
],
query: Annotated[str, cyclopts.Parameter(help="Search query")],
max_results: Annotated[
int, cyclopts.Parameter(help="Maximum results to return (default: 10)")
] = 10,
sources: Annotated[
str | None,
cyclopts.Parameter(
help="JSON array of sources: openalex, crossref, arxiv, pubmed, europepmc, kaggle, huggingface, dataverse, zenodo"
),
] = None,
categories: Annotated[
str | None, cyclopts.Parameter(help="JSON array of categories for dataset discovery")
] = None,
) -> None:
"""Scientific research: academic papers and dataset discovery.
Operations:
academic_search — Search OpenAlex, CrossRef, arXiv, PubMed, Europe PMC
dataset_discovery — Search Kaggle, HuggingFace, Dataverse, Zenodo
Examples:
uv run cli.py call-tool scientific_research --operation academic_search --query "transformers"
uv run cli.py call-tool scientific_research --operation dataset_discovery --query "sentiment" --sources \'["huggingface"]\'
"""
sources_parsed = json.loads(sources) if isinstance(sources, str) else sources
categories_parsed = json.loads(categories) if isinstance(categories, str) else categories
await _call_tool(
"scientific_research",
{
"operation": operation,
"query": query,
"max_results": max_results,
"sources": sources_parsed,
"categories": categories_parsed,
},
)
@call_tool_app.command(name="social_search")
async def social_search(
*,
query: Annotated[str, cyclopts.Parameter(help="Search query")],
platforms: Annotated[
list[str],
cyclopts.Parameter(help="Platforms: reddit, hackernews, devto, producthunt, medium"),
] = ["reddit", "hackernews", "devto"],
max_results_per_platform: Annotated[
int, cyclopts.Parameter(help="Max results per platform (default: 10)")
] = 10,
max_results: Annotated[
int, cyclopts.Parameter(help="Global max results, 0=unlimited (default: 0)")
] = 0,
reddit_subreddit: Annotated[
str, cyclopts.Parameter(help="Subreddit to search (default: all)")
] = "all",
time_filter: Annotated[
str, cyclopts.Parameter(help="Time filter: all, day, week, month, year (default: all)")
] = "all",
) -> None:
"""Search social platforms and communities. No authentication required.
Platforms: Reddit, Hacker News, Dev.to, Product Hunt, Medium
Examples:
uv run cli.py call-tool social_search --query "AI agents" --platforms reddit --platforms hackernews
uv run cli.py call-tool social_search --query "MCP" --reddit-subreddit ClaudeAI --time-filter week
"""
await _call_tool(
"social_search",
{
"query": query,
"platforms": platforms,
"max_results_per_platform": max_results_per_platform,
"max_results": max_results,
"reddit_subreddit": reddit_subreddit,
"time_filter": time_filter,
},
)
@call_tool_app.command(name="news_aggregation")
async def news_aggregation(
*,
query: Annotated[str, cyclopts.Parameter(help="News search query")],
max_results: Annotated[int, cyclopts.Parameter(help="Maximum results (default: 10)")] = 10,
language: Annotated[str, cyclopts.Parameter(help="Language code (default: en)")] = "en",
country: Annotated[str, cyclopts.Parameter(help="Country code (default: US)")] = "US",
time_range: Annotated[
str, cyclopts.Parameter(help="Time range: anytime, day, week, month (default: anytime)")
] = "anytime",
) -> None:
"""Aggregate news from Google News RSS. No authentication required.
Examples:
uv run cli.py call-tool news_aggregation --query "AI startups" --time-range week
uv run cli.py call-tool news_aggregation --query "tech layoffs" --country GB --language en
"""
await _call_tool(
"news_aggregation",
{
"query": query,
"max_results": max_results,
"language": language,
"country": country,
"time_range": time_range,
},
)
@call_tool_app.command(name="github_search")
async def github_search(
*,
query: Annotated[str, cyclopts.Parameter(help="Search query (e.g., 'web framework')")],
language: Annotated[
str | None, cyclopts.Parameter(help="Filter by language (e.g., Python, TypeScript)")
] = None,
sort: Annotated[
str, cyclopts.Parameter(help="Sort: stars, forks, updated (default: stars)")
] = "stars",
max_results: Annotated[int, cyclopts.Parameter(help="Maximum results (default: 10)")] = 10,
include_readme: Annotated[
bool, cyclopts.Parameter(help="Fetch README content, slower (default: false)")
] = False,
) -> None:
"""Search public GitHub repositories. No authentication required. Rate limited: 60 req/hr.
Examples:
uv run cli.py call-tool github_search --query "MCP server" --language Python --sort stars
uv run cli.py call-tool github_search --query "agent framework" --include-readme"""
language_parsed = json.loads(language) if isinstance(language, str) else language
await _call_tool(
"github_search",
{
"query": query,
"language": language_parsed,
"sort": sort,
"max_results": max_results,
"include_readme": include_readme,
},
)
@call_tool_app.command(name="document_analysis")
async def document_analysis(
*,
url: Annotated[str, cyclopts.Parameter(help="URL of document (PDF, Word, Text, Image)")],
max_pages: Annotated[
int, cyclopts.Parameter(help="Max pages to extract for PDFs (default: 10)")
] = 10,
extract_metadata: Annotated[
bool, cyclopts.Parameter(help="Extract document metadata (default: true)")
] = True,
summary_length: Annotated[
int, cyclopts.Parameter(help="Text preview length (default: 500)")
] = 500,
) -> None:
'''Analyze documents with OCR support. No authentication required.
Supports: PDF, Word (.docx), Text (.txt, .md), Images (.jpg, .png).
OCR auto-downloads models on first use (~100MB).
Examples:
uv run cli.py call-tool document_analysis --url "https://arxiv.org/pdf/2301.00001"
uv run cli.py call-tool document_analysis --url "https://example.com/image.png"'''
await _call_tool(
"document_analysis",
{
"url": url,
"max_pages": max_pages,
"extract_metadata": extract_metadata,
"summary_length": summary_length,
},
)
if __name__ == "__main__":
app()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |