• 🇺🇸 English - English documentation
• 🇪🇸 Español - Documentación en español

A comprehensive TypeScript-based RSS aggregation service that provides both a REST API and multiple Model Context Protocol (MCP) transport options in a unified server architecture. It fetches, parses, and serves RSS feeds with full AI assistant integration capabilities, all running on a single port for simplified deployment and usage.

Everything runs on one port for maximum simplicity:

# Start the unified server (REST API + MCP HTTP + MCP SSE)
docker-compose up -d

# All services available on port 3000:
# 🌐 REST API:        http://localhost:3000/
# 📚 API Docs:        http://localhost:3000/api-docs  
# 🔌 MCP HTTP:        http://localhost:3000/mcp
# 📡 MCP SSE:         http://localhost:3000/sse
# 💬 SSE Messages:    http://localhost:3000/messages

# Test REST API
curl -X POST http://localhost:3000/Fetch_RSSfeed \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://feeds.bbci.co.uk/news/rss.xml", "https://rss.cnn.com/rss/edition.rss"]}'

# Test MCP HTTP with Inspector
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:3000/mcp

For specialized use cases, you can still run individual transports:

# Stdio transport - for CLI/subprocess integration
npm run mcp

# HTTP transport only - for web clients  
npm run mcp:http:dev

# SSE transport only - for legacy streaming clients
npm run mcp:sse:dev

The unified server combines all protocols in a single Express.js application:

• ✅ Single Port: Only port 3000 to manage and expose
• ✅ Simplified Deployment: One container, one service
• ✅ Unified Monitoring: Single health endpoint for all protocols
• ✅ Better Resource Usage: Shared memory and process management
• ✅ Easier Development: One server to start, stop, and debug
• ✅ Protocol Independence: Each transport maintains full functionality

Unified Transport Endpoints:

• REST API: http://localhost:3000/ (health, RSS endpoints)
• HTTP Transport: http://localhost:3000/mcp (MCP over HTTP)
• SSE Transport: http://localhost:3000/sse (connection) + http://localhost:3000/messages (messages)

• ✅ TypeScript: Full type safety and modern JavaScript features
• ✅ Express.js: Fast, unopinionated web framework
• ✅ RSS Aggregation: Fetch and parse multiple RSS feeds
• ✅ Multiple MCP Transports: Stdio, HTTP (StreamableHTTP), SSE, and Multi-transport
• ✅ Health Monitoring: Basic and comprehensive health checks across all transports
• ✅ Input Validation: Comprehensive request validation with detailed errors
• ✅ OpenAPI 3.0: Complete API specification and documentation
• ✅ Swagger UI: Interactive API documentation and testing
• ✅ MCP Inspector Compatible: Works with web-based MCP testing tools
• ✅ Session Management: Advanced session handling for HTTP-based transports
• ✅ CORS Support: Web client compatibility
• ✅ Jest Testing: Comprehensive unit and integration tests (65 tests, 90%+ coverage)
• ✅ Docker Support: Production-ready containerization
• ✅ Security: Non-root containers, input sanitization
• ✅ AI Integration: MCP tools, resources, and prompts for AI assistants

Traditional REST API for direct HTTP integration with applications.

Model Context Protocol server with flexible transport options:

• Stdio: For command-line tools and subprocess communication
• StreamableHTTP: Modern HTTP-based transport with full MCP support
• SSE: Server-Sent Events for real-time streaming (deprecated but supported)
• Multi-Transport: Combined HTTP and SSE support on single server

• Interactive API Docs: http://localhost:3000/api-docs
• OpenAPI Specification: http://localhost:3000/api-docs.json

• Transport Comparison: README-TRANSPORTS.md | Español - Comprehensive guide to all transport options
• HTTP Transport Guide: README-HTTP.md | Español - StreamableHTTP transport setup and usage
• MCP Setup Guide: MCP_SETUP.md - Original stdio transport setup

• Detailed Guide: OPENAPI_POSTMAN_GUIDE.md
• Project Summary: PROJECT_SUMMARY.md

1. Clone the repository

2. Install dependencies:

   npm install

Prerequisites: Docker and Docker Compose installed on your system.

# Production deployment
docker-compose up -d

# Development with hot reload
npm run compose:dev

# Build the Docker image
npm run docker:build

# Run the container
npm run docker:run

# Stop the container
npm run docker:stop

Choose the transport that best fits your use case:

• Stdio (npm run mcp): Best for Claude Desktop and CLI integration
• HTTP (unified server): Best for web applications and MCP Inspector
• SSE (unified server): For legacy SSE clients requiring real-time streaming
• Unified (npm run unified or Docker): All transports on single port 3000 (recommended)

{
  "mcpServers": {
    "rss-server": {
      "command": "node",
      "args": ["dist/mcp-server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

{
  "name": "RSS MCP Server (HTTP)",
  "transport": "http",
  "endpoint": "http://localhost:3000/mcp"
}

// SSE connection
const eventSource = new EventSource('http://localhost:3000/sse');

// Send messages
fetch('http://localhost:3000/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ jsonrpc: '2.0', method: 'ping' })
});

Run the server in development mode with TypeScript compilation:

npm run dev

1. Build the TypeScript code:

   npm run build

2. Start the server:

   npm start

Start the MCP server for AI assistant integration (choose your transport):

# Build all MCP transport variants
npm run build

# Stdio transport (original) - for CLI/subprocess integration
npm run mcp              # Production (shortcut for mcp:stdio)
npm run mcp:stdio:dev    # Development mode

# HTTP transport (recommended) - for web clients & MCP Inspector
npm run mcp:http         # Production
npm run mcp:http:dev     # Development mode

# SSE transport - for legacy real-time streaming clients
npm run mcp:sse          # Production
npm run mcp:sse:dev      # Development mode

# Multi-transport - supports both HTTP and SSE
npm run mcp:multi        # Production
npm run mcp:multi:dev    # Development mode

# Start with Docker Compose
docker-compose up -d

# Check logs
npm run compose:logs

# Stop services
npm run compose:down

# Start development container with hot reload
npm run compose:dev

# View logs
docker-compose logs -f rss-mcp-server-dev

# Build image
npm run docker:build

# Run container
npm run docker:run

# Stop and cleanup
npm run docker:stop
npm run docker:remove

The server will start on port 3000 (or the port specified in the PORT environment variable).

• URL: GET /

• Description: Basic server status check

• Response:

  {
    "message": "RSS MCP Server is running",
    "status": "OK",
    "timestamp": "2025-09-21T11:57:05.000Z"
  }

• URL: GET /health

• Description: Comprehensive health and system information

• Response:

  {
    "status": "healthy",
    "message": "RSS MCP Server is running successfully",
    "timestamp": "2025-09-21T11:57:05.000Z",
    "uptime": {
      "seconds": 3661,
      "formatted": "0d 1h 1m 1s"
    },
    "memory": {
      "usage": {
        "rss": 45.2,
        "heapTotal": 20.1,
        "heapUsed": 15.3,
        "external": 2.1
      },
      "unit": "MB"
    },
    "system": {
      "nodeVersion": "v18.17.0",
      "platform": "darwin",
      "architecture": "x64",
      "pid": 12345
    },
    "performance": {
      "responseTime": 1.23,
      "unit": "ms"
    },
    "endpoints": {
      "available": [
        "GET /",
        "GET /health", 
        "POST /Fetch_RSSfeed"
      ]
    }
  }

• URL: POST /Fetch_RSSfeed

• Description: Aggregates multiple RSS feeds and returns parsed articles

• Request Body:

  {
    "urls": [
      "https://feeds.bbci.co.uk/news/rss.xml",
      "https://rss.cnn.com/rss/edition.rss"
    ]
  }

• Success Response (200):

  {
    "success": true,
    "totalFeeds": 2,
    "totalArticles": 45,
    "feeds": [
      {
        "url": "https://feeds.bbci.co.uk/news/rss.xml",
        "title": "BBC News",
        "description": "BBC News - Home",
        "articles": [
          {
            "title": "Article Title",
            "description": "Article description",
            "link": "https://www.bbc.com/news/article",
            "pubDate": "2025-01-21T10:00:00.000Z",
            "author": "BBC News"
          }
        ]
      }
    ]
  }

• Error Responses:

  • 400 Bad Request: Invalid request format or URLs
  • 500 Internal Server Error: Server error

1. Claude Desktop Configuration:

   Add to your Claude Desktop config:

   {
     "mcpServers": {
       "rss-aggregator": {
         "command": "node",
         "args": ["/path/to/RSS-MCPserver/dist/mcp-server.js"]
       }
     }
   }

2. Other MCP Clients:

   Use the provided mcp-config.json file or configure manually using the server path.

• fetch_rss_feeds: Aggregate multiple RSS feeds
• get_feed_info: Get information about a specific RSS feed

• rss-feed: Access individual RSS feed data via rss://{feedUrl}
• available-feeds: List of popular RSS feeds

• analyze_rss_content: Analyze RSS content for insights
• news_briefing: Generate news briefings from RSS feeds

Using curl:

# Basic health check
curl http://localhost:3000/

# Enhanced health check
curl http://localhost:3000/health

# Fetch RSS feeds
curl -X POST http://localhost:3000/Fetch_RSSfeed \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://feeds.bbci.co.uk/news/rss.xml", "https://rss.cnn.com/rss/edition.rss"]}'

```text
RSS-MCPserver/
├── src/
│   ├── index.ts              # Legacy REST API server file
│   ├── unified-server.ts     # Main unified server (REST + MCP HTTP + SSE)
│   ├── mcp-server.ts         # MCP server implementation (stdio)
│   ├── mcp-server-http.ts    # HTTP transport MCP server (legacy)
│   ├── mcp-server-sse.ts     # SSE transport MCP server (legacy)
│   ├── mcp-server-multi.ts   # Multi-transport MCP server (legacy)
│   ├── services/
│   │   └── rss-service.ts    # RSS aggregation service
│   └── types/
│       └── rss.types.ts      # TypeScript type definitions
├── tests/                    # Test suites
├── dist/                     # Compiled JavaScript (after build)
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── mcp-config.json           # MCP server configuration (stdio)
├── mcp-config-http.json      # HTTP transport configuration (legacy)
├── mcp-config-sse.json       # SSE transport configuration (legacy)
├── mcp-config-multi.json     # Multi-transport configuration (legacy)
├── MCP_SETUP.md              # MCP setup documentation (stdio)
├── README-HTTP.md            # HTTP transport guide
├── README-TRANSPORTS.md      # Transport comparison guide
├── Dockerfile                # Production Docker image (unified server)
├── Dockerfile.dev            # Development Docker image
├── docker-compose.yml        # Docker Compose configuration (single port)
├── .dockerignore            # Docker ignore patterns
└── README.md                # This file

• Base Image: Node.js 18 Alpine (lightweight)
• Security: Non-root user execution
• Health Checks: Built-in health monitoring
• Multi-stage Build: Optimized production image size
• Port: 3000 (configurable via PORT environment variable)

# Docker Compose (Recommended)
npm run compose:up          # Start production services
npm run compose:down        # Stop all services
npm run compose:logs        # View logs
npm run compose:dev         # Start development mode
npm run compose:restart     # Restart services

# Manual Docker Commands
npm run docker:build        # Build image
npm run docker:run          # Run container
npm run docker:stop         # Stop container
npm run docker:remove       # Remove container
npm run docker:clean        # Remove image

• PORT: Server port (default: 3000)
• NODE_ENV: Environment mode (development/production)

Run the comprehensive test suite:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

The project includes 65+ tests covering:

• ✅ Health endpoints
• ✅ RSS aggregation functionality
• ✅ MCP server implementation
• ✅ Integration tests
• ✅ Error handling
• ✅ Input validation

1. Make changes to the MCP server code

2. Build the MCP server:

   npm run mcp:build

3. Test with development mode:

   npm run mcp:dev

4. Run tests to validate:

   npm test

1. Make changes to the REST API code

2. Start development server:

   npm run dev

3. Test endpoints using the Swagger UI or curl

4. Run tests to validate:

   npm test

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

This project is licensed under the MIT License. See the LICENSE file for details.