# RSS Reader MCP Server

A TypeScript-based MCP server that provides RSS feed reading capabilities for fetching and parsing RSS/Atom feeds from URLs.

## Overview

This MCP server implements RSS feed reading functionality by providing tools to fetch, parse, and extract structured data from RSS and Atom feeds. It uses the `rss-parser` library for robust feed parsing and `axios` for HTTP requests with proper error handling and timeouts.

## Features

### Tools
- **`get_items`** - Fetch RSS feed items from a given URL
  - **Input**: RSS feed URL (required)
  - **Output**: Structured JSON containing feed metadata and items
  - **Capabilities**:
    - Fetches RSS/Atom feeds with 10-second timeout
    - Parses standard RSS fields (title, link, description, pubDate, author, etc.)
    - Extracts custom fields (media content, thumbnails, encoded content)
    - Handles categories and enclosures
    - Provides comprehensive error handling for network and parsing issues

### Supported Feed Formats
- RSS 2.0
- RSS 1.0 (RDF)
- Atom feeds
- Custom fields including:
  - Media content and thumbnails
  - Dublin Core creator fields
  - Content-encoded fields

### Error Handling
- URL validation
- Network timeout handling (10 seconds)
- HTTP error status handling
- RSS parsing error handling
- Comprehensive error messages for debugging

## Development

Install dependencies:
```bash
npm install
```

Build the server:
```bash
npm run build
```

For development with auto-rebuild:
```bash
npm run watch
```

## Installation

To use with Claude Desktop, add the server config:

On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "rss-reader-server": {
      "command": "node",
      "args": ["/path/to/rss-reader-server/build/index.js"]
    }
  }
}
```

## Usage Example

Once connected, you can use the `get_items` tool to fetch RSS feed items:

```
Tool: get_items
Input: { "url": "https://example.com/feed.xml" }
```

The server will return a structured JSON response containing:
- Feed URL
- Total item count
- Array of feed items with:
  - Title, link, description
  - Publication date and author
  - Categories (if available)
  - Enclosure information (for podcasts/media)

## Dependencies

- **@modelcontextprotocol/sdk**: MCP protocol implementation
- **rss-parser**: RSS/Atom feed parsing
- **axios**: HTTP client for fetching feeds
- **zod**: Runtime type validation

## Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:

```bash
npm run inspector
```

The Inspector will provide a URL to access debugging tools in your browser.

## Error Responses

The server provides detailed error messages for common issues:
- Invalid URL format
- Network connectivity problems
- HTTP errors (404, 500, etc.)
- Request timeouts
- RSS parsing failures

All errors are returned in a structured format with descriptive messages to help with troubleshooting.