agentic-rss-parser

An open-source Node.js library for parsing RSS and Atom feeds with built-in heuristic and LLM-based relevance analysis, deduplication, article enrichment, a CLI, and an MCP server.

Part of the BLUECARBONS Open Source initiative — software components powering agentic and agent-dependent products.

v1.4.1 — Security & cohesion audit: createRequire replaces bare require() in storage.js (ESM correctness), cli.js now imports DEFAULT_DB_PATH from the shared core/db-path.js module, CLI usage message corrected to agentic-rss binary name.

Installation

npm install agentic-rss-parser
# or
pnpm add agentic-rss-parser

Requires Node.js >=22.5.0 (for node:sqlite). On Node 18/20, pass storage: createMemoryStorage() — everything else works unchanged.

Migration from rss-parser

One-line change:

// Before
import Parser from 'rss-parser';

// After — all existing usage unchanged
import Parser from 'agentic-rss-parser';

All parseURL, parseString, parseFile, customFields, and callback-style APIs are preserved exactly.

MCP Server

Exposes fetch_rss_feed and fetch_full_article as MCP tools over stdio.

npx agentic-rss-mcp

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "agentic-rss": {
      "command": "npx",
      "args": ["agentic-rss-mcp"]
    }
  }
}

CLI

npx agentic-rss --feed https://hnrss.org/frontpage
npx agentic-rss --feed https://hnrss.org/frontpage --db ./data/my.db --fetch-full-article

Key Features

• RSS 2.0 & Atom — CDATA, namespaces, HTML entities, dc:creator, media:content, content:encoded
• rss-parser drop-in — zero migration cost
• Heuristic analysis — configurable signal scoring, no API key required
• LLM analysis — OpenAI, Anthropic, local (Ollama)
• Deduplication — SHA-256 item IDs, SQLite-backed across runs
• Article enrichment — fetches and HTML-strips full article body
• MCP server — JSON-RPC 2.0 stdio, works with Claude Desktop, Cursor, Cline
• Pluggable storage — SQLite (Node 22.5+) or in-memory (any Node version)
• Custom analyzer — bring your own ({ item, context }) => AnalysisResult function
• Zero runtime dependencies — minimal supply-chain surface

Security

• XXE / Billion Laughs — iterative state-machine parser, no recursive entity expansion
• XSS — <script>, <style>, <iframe>, <object>, <embed>, <form> stripped from snippets
• Prompt injection — control chars stripped, newlines collapsed before LLM interpolation
• SSRF — file://, javascript://, RFC-1918, loopback, and link-local targets rejected
• Response size cap — feed responses 5 MB max, LLM responses 1 MB max

See SECURITY.md for the vulnerability disclosure policy.

Documentation

Full documentation — installation, quick start, API reference, architecture, configuration, storage adapters, MCP server, CLI, and contributing — is available in the GitHub Wiki.

Development

git clone https://github.com/bluecarbons/agentic-rss-parser.git
cd agentic-rss-parser
pnpm install
pnpm test    # 61 passing
pnpm lint

License

MIT © BLUECARBONS