MCP RSS

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview MCP RSS is a Model Context Protocol (MCP) server that provides RSS feed management capabilities through a standardized API. The server runs as a stdio-based MCP server that can be integrated with Claude Desktop and other MCP-compatible clients. ## Development Commands ### Build and Development ```bash npm run build # Compile TypeScript to JavaScript (outputs to dist/) npm run watch # Watch mode for development npm run prepare # Pre-publish build step (runs automatically) ``` ### Testing and Debugging ```bash npx @modelcontextprotocol/inspector node dist/index.js # Debug MCP server with inspector ``` ### Database Setup **Using Docker Compose (Recommended)**: ```bash docker-compose up -d # Start PostgreSQL in background docker-compose down # Stop PostgreSQL docker-compose logs -f postgres # View PostgreSQL logs ``` **Using Docker CLI**: ```bash docker run -itd --name postgres-test -p 5433:5432 -e POSTGRES_USER=mcp_user -e POSTGRES_PASSWORD=123456 -e POSTGRES_DB=mcp_rss postgres:16-alpine ``` **Configuration**: - Copy `.env.example` to `.env` and customize settings - Docker Compose reads environment variables from `.env` file - Default credentials: mcp_user/123456 on port 5433 (change for production) ## Architecture ### Core Service Layer Pattern The application follows a three-tier service architecture: 1. **OpmlService** (`src/services/OpmlService.ts`): Handles OPML file parsing and initial feed import - Recursively processes OPML outline elements to handle nested categories - Creates Feed entities from RSS subscriptions found in OPML 2. **RssService** (`src/services/RssService.ts`): Manages RSS feed fetching and article storage - Uses `rss-parser` to fetch and parse RSS feeds - Deduplicates articles by link before saving - Runs on a cron schedule (configurable via `RSS_UPDATE_INTERVAL`) 3. **McpService** (`src/services/McpService.ts`): Exposes MCP tools for client interaction - `get_content`: Query articles with status/source filtering - `get_sources`: List all available RSS feeds - `set_tag`: Mark articles as normal/favorite ### Database Schema TypeORM entities with decorators: - **Feed** (`src/entities/Feed.ts`): RSS feed sources - Fields: id, title, url, htmlUrl, category - Relationship: OneToMany → Article - **Article** (`src/entities/Article.ts`): RSS articles - Fields: id, title, content, link, pubDate, fetchDate, status - Status enum: `normal` | `favorite` - Relationship: ManyToOne → Feed ### MCP Server Flow 1. **Initialization** (`src/index.ts`): - Loads environment variables via dotenv - Initializes PostgreSQL database connection (runs TypeORM sync) - Sets up cron job for periodic RSS fetching - Registers MCP tools (ListToolsRequestSchema, CallToolRequestSchema) - Connects to stdio transport 2. **Cron Execution**: - Parses OPML file to update feed subscriptions - Fetches all RSS feeds and saves new articles - Interval: `*/${RSS_UPDATE_INTERVAL} * * * *` (default: every 1 minute) 3. **Request Handling**: - MCP tool calls are routed to McpService methods - Responses formatted as JSON text content - Error handling returns success: false with error messages ## Environment Configuration All configuration via environment variables (see README.md for defaults): - **Database**: `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD`, `DB_DATABASE` - **RSS**: `OPML_FILE_PATH`, `RSS_UPDATE_INTERVAL` PostgreSQL database is automatically created by Docker Compose on first startup. ## TypeScript Configuration - **Target**: ES5 with CommonJS modules for Node.js compatibility - **Decorators**: Enabled for TypeORM entity decorators (`experimentalDecorators`, `emitDecoratorMetadata`) - **Output**: Compiled to `dist/` with source maps and declarations - **Entry Point**: Shebang in compiled `dist/index.js` for CLI execution ## MCP Tool Design The server exposes three tools designed for conversational RSS management: 1. **get_content**: Returns articles sorted by pubDate (DESC), supports pagination via limit parameter 2. **get_sources**: Required before filtering by source in get_content (provides valid source names) 3. **set_tag**: Manages user's reading workflow (normal → favorite transition) Status values are restricted to enum: `ArticleStatus.NORMAL` | `ArticleStatus.FAVORITE` throughout the codebase. ## Key Implementation Details - **OPML Processing**: Handles nested categories recursively, preserving category hierarchy in Feed.category field - **Article Deduplication**: Link-based uniqueness check prevents duplicate articles across feed updates - **Database Connection**: Single shared AppDataSource from `src/config/database.ts` used across all services - **Error Handling**: Services catch errors and return formatted responses; console errors are commented out for production silence - **Transport**: Stdio-based MCP server suitable for integration with Claude Desktop (no HTTP server)