cpp-enhancement-mcp-server/BRAVE_SEARCH_SETUP.md

MCP server for C++ programming enhancement with modern best practices, performance optimization, and real-time web research. Requires Python 3.8+.

# Brave Search API Setup Guide

The C++ Enhancement MCP Server can use Brave Search API to provide real-time web search results for the latest C++ techniques, best practices, and solutions.

## Why Brave Search?

- **Privacy-focused**: No tracking or data collection
- **High-quality results**: Clean, relevant search results
- **Developer-friendly**: Simple REST API
- **Free tier available**: 2,000 queries per month
- **Fast and reliable**: Low latency responses

## Getting Your API Key

### Step 1: Visit Brave Search API
Go to: https://api.search.brave.com/

### Step 2: Sign Up
1. Click "Get Started" or "Sign Up"
2. Create an account with your email
3. Verify your email address

### Step 3: Get API Key
1. Log into your Brave Search API dashboard
2. Navigate to "API Keys" section
3. Click "Create New API Key"
4. Give it a name (e.g., "C++ Enhancement MCP")
5. Copy the generated API key

### Step 4: Configure the MCP Server
Run the setup command:
```bash
cpp-enhancement-server --setup
```

Or manually add to your configuration file at `~/.cpp-enhancement-mcp/config.json`:
```json
{
  "brave_api_key": "your-api-key-here",
  "enable_web_search": true,
  "max_search_results": 5
}
```

## API Limits

### Free Tier
- **2,000 queries per month**
- **Rate limit**: 1 query per second
- **No credit card required**

### Paid Plans
- **Basic**: $3/month for 20,000 queries
- **Pro**: $15/month for 200,000 queries
- **Enterprise**: Custom pricing

## Features Enabled with API Key

### 🌐 Real-time Web Search
- Latest C++ techniques and best practices
- Recent conference talks and articles
- Modern C++ feature documentation
- Performance optimization guides
- Community discussions and solutions

### 📊 Enhanced Results
- Live search results from authoritative sources
- Recent blog posts and tutorials
- Stack Overflow discussions
- GitHub repositories and examples
- Official documentation updates

## Configuration Options

### Basic Configuration
```json
{
  "brave_api_key": "your-api-key-here",
  "enable_web_search": true,
  "max_search_results": 5
}
```

### Advanced Configuration
```json
{
  "brave_api_key": "your-api-key-here",
  "enable_web_search": true,
  "max_search_results": 8,
  "search_timeout": 10,
  "fallback_to_curated": true,
  "cache_results": true,
  "cache_duration": 3600
}
```

## Commands

### Setup API Key
```bash
cpp-enhancement-server --setup
```

### Check Configuration
```bash
cpp-enhancement-server --config
```

### Test Search
```bash
cpp-enhancement-server --demo
```

## Troubleshooting

### API Key Not Working
1. **Check the key**: Ensure you copied the full API key
2. **Verify account**: Make sure your Brave Search account is active
3. **Check limits**: Ensure you haven't exceeded monthly quota
4. **Test manually**: Try the API key with curl:
   ```bash
   curl -H "Accept: application/json" \
        -H "X-Subscription-Token: YOUR_API_KEY" \
        "https://api.search.brave.com/res/v1/web/search?q=C%2B%2B%20programming"
   ```

### Rate Limiting
- The server automatically handles rate limits
- If you hit limits, it falls back to curated knowledge base
- Consider upgrading to a paid plan for higher limits

### Network Issues
- Check your internet connection
- Verify firewall settings allow HTTPS requests
- Try running with `--demo` to test connectivity

## Privacy and Security

### Data Handling
- API keys are stored locally in `~/.cpp-enhancement-mcp/config.json`
- No search queries are logged by the MCP server
- Brave Search respects user privacy

### Security Best Practices
1. **Keep API key secure**: Don't share or commit to version control
2. **Use environment variables**: For production deployments
3. **Monitor usage**: Check your Brave Search dashboard regularly
4. **Rotate keys**: Periodically generate new API keys

## Alternative: Using Without API Key

If you prefer not to use the Brave Search API, the MCP server works perfectly with its comprehensive curated knowledge base:

- ✅ Modern C++ best practices
- ✅ Performance optimization techniques
- ✅ RAII and memory management guidance
- ✅ Template programming help
- ✅ Curated examples and code snippets

Simply skip the API setup or disable web search:
```bash
cpp-enhancement-server --setup
# Press Enter when prompted for API key to skip
```

## Support

For issues with:
- **Brave Search API**: Contact Brave Support
- **MCP Server**: Check GitHub issues or documentation
- **Configuration**: Run `cpp-enhancement-server --help`

---

**Ready to enhance your C++ programming with real-time web search? Get your API key and run the setup!**