# MCP RSS Feed Searcher

[![MCP](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io/)
[![Python](https://img.shields.io/badge/Python-3.8+-green)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
[![FastMCP](https://img.shields.io/badge/FastMCP-Framework-orange)](https://github.com/modelcontextprotocol/python-sdk)
[![RSS](https://img.shields.io/badge/RSS-Feeds-red)](https://www.rssboard.org/)
[![Open Source](https://img.shields.io/badge/Open%20Source-%E2%9D%A4-brightgreen)](#-contributing)
[![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-blueviolet)](CONTRIBUTING.md)

An extensible Model Context Protocol (MCP) server for searching across multiple RSS feed sources. Built for developers who want to aggregate content from various sources through a unified interface.

## 🌟 Features

- **Multi-Source Search**: Search across multiple RSS feeds simultaneously
- **Extensible Architecture**: Easy to add new feed sources
- **MCP Protocol Support**: Compatible with MCP Inspector and other MCP clients
- **Multiple Transport Modes**: STDIO and HTTP support
- **Built-in Feeds**:
  - FreeCodeCamp News (programming tutorials)
  - FreeCodeCamp YouTube (video content)
  - Bing News (general news search)

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/mcp-rss-feed-searcher.git
cd mcp-rss-feed-searcher

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### Running the Server

**STDIO Mode (Default):**
```bash
python main.py
```

**HTTP Mode:**
```bash
python main.py --mode http
```

### Testing with MCP Inspector

```bash
# STDIO mode
npx @modelcontextprotocol/inspector python main.py --mode stdio

# HTTP mode (run in background)
python main.py --mode http &
npx @modelcontextprotocol/inspector http://localhost:8003/mcp
```

## 📚 Available MCP Tools

| Tool | Description |
|------|-------------|
| `list_feeds` | List all available feed sources |
| `search_feed` | Search a specific feed by name |
| `search_all_feeds` | Search across all feeds simultaneously |
| `search_multiple_feeds` | Search specific multiple feeds |

### Example Usage

**List available feeds:**
```json
{
  "tool": "list_feeds"
}
```

**Search a specific feed:**
```json
{
  "tool": "search_feed",
  "arguments": {
    "feed_name": "freecodecamp_news",
    "query": "python tutorial",
    "max_results": 5
  }
}
```

**Search all feeds:**
```json
{
  "tool": "search_all_feeds",
  "arguments": {
    "query": "machine learning",
    "max_results": 3
  }
}
```

**Search multiple specific feeds:**
```json
{
  "tool": "search_multiple_feeds",
  "arguments": {
    "feed_names": ["freecodecamp_news", "bing_news"],
    "query": "artificial intelligence",
    "max_results": 5
  }
}
```

## 🏗️ Project Structure

```
mcp-rss-feed-searcher/
├── src/
│   ├── __init__.py
│   ├── mcp_server.py        # MCP server implementation
│   └── feeds/
│       ├── __init__.py      # Feed package initialization
│       ├── base.py          # BaseFeed abstract class
│       ├── registry.py      # Feed registry system
│       ├── freecodecamp.py  # FreeCodeCamp feeds
│       └── bing_news.py     # Bing News feed
├── input_data/              # Input data directory
├── output_data/             # Output data directory
├── main.py                  # Entry point
├── requirements.txt         # Dependencies
└── README.md               # This file
```

## 🔧 Available Feed Sources

### FreeCodeCamp News
- **Name:** `freecodecamp_news`
- **Content:** Programming tutorials, tech articles, coding guides
- **Source:** https://www.freecodecamp.org/news/rss/

### FreeCodeCamp YouTube
- **Name:** `freecodecamp_youtube`
- **Content:** Video tutorials, full courses, programming walkthroughs
- **Source:** YouTube channel RSS feed

### Bing News
- **Name:** `bing_news`
- **Content:** Latest news articles across all topics
- **Source:** Bing News RSS search
- **Note:** Dynamic feed based on search query

## 🛠️ Troubleshooting

### Common Issues and Solutions

#### MCP Inspector won't connect

**Issue**: MCP Inspector fails to connect to the server
**Solutions**:
- Ensure you're using the correct command for your mode:
  ```bash
  # STDIO mode
  npx @modelcontextprotocol/inspector python main.py --mode stdio

  # HTTP mode (server must be running)
  python main.py --mode http
  # Then in another terminal:
  npx @modelcontextprotocol/inspector http://localhost:8003/mcp
  ```
- Check that all dependencies are installed: `pip install -r requirements.txt`
- Verify Python version is 3.8 or higher: `python --version`

#### No search results returned

**Issue**: `search_feed` returns empty results
**Solutions**:
- Verify the feed name is correct (use `list_feeds` to see available feeds)
- Check your internet connection
- Some feeds may be temporarily unavailable - try again later
- Ensure your query isn't too specific; try broader search terms

#### ModuleNotFoundError when running

**Issue**: `ModuleNotFoundError: No module named 'src'` or similar
**Solutions**:
- Make sure you're running from the project root directory
- Ensure the virtual environment is activated
- Reinstall dependencies: `pip install -r requirements.txt`

#### HTTP mode connection refused

**Issue**: `Connection refused` when connecting to HTTP server
**Solutions**:
- Verify the server is running: `python main.py --mode http`
- Check the port isn't in use: `lsof -i :8003` (Linux/Mac) or `netstat -ano | findstr :8003` (Windows)
- Try a different port: `python main.py --mode http --port 8004`

#### Feed parsing errors

**Issue**: Errors parsing RSS feeds
**Solutions**:
- Check your internet connection
- Some RSS feeds may have temporary issues - wait a few minutes and retry
- Verify the feed URL is accessible in a browser
- Check console output for specific error messages

### Getting Help

If you encounter an issue not listed here:
1. Check existing [GitHub Issues](https://github.com/yourusername/mcp-rss-feed-searcher/issues)
2. Review the [Contributing Guide](CONTRIBUTING.md) for development setup details
3. Create a new issue with:
   - Clear description of the problem
   - Steps to reproduce
   - Error messages or logs
   - Your environment (OS, Python version)

## 🤝 Contributing

We welcome contributions! Whether you want to add a new feed source, fix a bug, or improve documentation, please check out our [Contributing Guide](CONTRIBUTING.md).

### Quick Contribution Ideas

- Add new RSS feed sources (Reddit, Hacker News, Dev.to, Medium, GitHub Trending, ArXiv, Stack Overflow, etc.)
- Implement feed caching for better performance
- Add result filtering and sorting options (by date, source, relevance)
- Create output formatting options (JSON, Markdown, HTML)
- Add more comprehensive tests and test coverage
- Improve documentation with examples and tutorials
- Add Docker support for easy deployment
- Implement rate limiting awareness for feeds
- Add result deduplication across multiple sources
- Create a CLI interface for standalone usage
- Add feed result pagination support
- Implement async/await support for concurrent searches
- Add support for private/authenticated feeds
- Create a web dashboard for feed management
- Add export functionality (CSV, PDF, etc.)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk)
- Uses [feedparser](https://github.com/kurtmckee/feedparser) for RSS parsing
- MCP protocol by [Anthropic](https://www.anthropic.com/)

## 💬 Support

- Open an issue for bugs or feature requests
- Check existing issues for solutions
- Read the [Contributing Guide](CONTRIBUTING.md) for development setup

## 🔮 Roadmap

- [ ] Add caching layer for feed results
- [ ] Support for feed authentication
- [ ] More built-in feed sources
- [ ] Result deduplication across sources
- [ ] Advanced filtering options
- [ ] REST API mode
- [ ] Docker support

---

**Happy searching!** 🔍