# Tavily Web Research

Download and extract web articles using Tavily via mcporter.

## When to Use

Use this skill when you need to:
- Download articles from URLs for research
- Extract content from websites
- Get full text from paywalled or restricted sites
- Archive web content for later reference
- Research topics from multiple sources

## Prerequisites

- **mcporter** must be installed: `npm install -g mcporter`
- **Tavily** must be configured in mcporter:
  ```bash
  mcporter config add tavily "https://mcp.tavily.com/mcp/?tavilyApiKey=YOUR_API_KEY"
  ```

## Commands

### Search the Web

Search for recent articles on a topic:

```bash
mcporter call tavily.tavily_search "query=YOUR_SEARCH_QUERY" max_results=5 time_range=week
```

**Parameters:**
- `query`: Search terms (required)
- `max_results`: Number of results (default: 5)
- `time_range`: Filter by time - `day`, `week`, `month`, `year`
- `search_depth`: `basic`, `advanced`, `fast`, `ultra-fast`

### Extract Article Content

Get full text from a specific URL:

```bash
mcporter call tavily.tavily_extract 'urls=["https://example.com/article"]' extract_depth=advanced format=markdown
```

**Parameters:**
- `urls`: Array of URLs to extract (required)
- `extract_depth`: `basic` or `advanced` (use advanced for paywalled sites)
- `format`: `markdown` or `text`

### Research a Topic

Deep research across multiple sources:

```bash
mcporter call tavily.tavily_research "input=DETAILED_RESEARCH_QUESTION" model=pro
```

**Parameters:**
- `input`: Comprehensive research question (required)
- `model`: `mini`, `pro`, or `auto` (pro for broad topics)

## Examples

### Example 1: Search for Recent AI News

```bash
mcporter call tavily.tavily_search "query=OpenAI GPT-5 release" max_results=5 time_range=week
```

### Example 2: Extract Article from URL

```bash
mcporter call tavily.tavily_extract 'urls=["https://x.com/Voxyz_ai/status/2019914775061270747"]' extract_depth=advanced
```

### Example 3: Research a Topic

```bash
mcporter call tavily.tavily_research "input=What are the latest trends in AI agent architectures for 2026?" model=pro
```

## Output Format

Search results include:
- `title`: Article headline
- `url`: Source URL
- `content`: Article summary/snippet
- `score`: Relevance score

Extract results include:
- `raw_content`: Full article text
- `title`: Page title
- `url`: Source URL

## Use in OpenClaw

When asked to research a URL:

1. Use `tavily.tavily_extract` to get full content
2. Save to a file or process the content
3. Summarize key points for the user

Example workflow:
```
User: "Research this article: https://example.com"
→ mcporter call tavily.tavily_extract 'urls=["https://example.com"]' extract_depth=advanced
→ Parse results
→ Present summary with key takeaways
```

## Tips

- Use `extract_depth=advanced` for paywalled sites (better success rate)
- Use `format=markdown` for cleaner text extraction
- Set `time_range=week` for recent news
- Tavily has a generous free tier (1000 searches/month)
- Rate limits: ~1 request per second to avoid throttling

## Troubleshooting

**"Skill not found" error:**
- Ensure mcporter is installed: `npm install -g mcporter`
- Check Tavily is configured: `mcporter list`

**"Rate limit exceeded" error:**
- Wait 10-15 seconds between requests
- Tavily limits requests to prevent abuse

**Empty results:**
- Try `extract_depth=advanced` instead of `basic`
- Some sites block crawlers (LinkedIn, etc.)
- Check the URL is accessible publicly

## API Key

Get your Tavily API key at: https://tavily.com

Free tier includes:
- 1,000 API calls/month
- Full search capabilities
- Content extraction
- No credit card required