agentic-rss-parser

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

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

v1.7.3 — Subpath Tree-Shaking & Socket.dev v2 Policies: added first-class subpath exports (/core, /json, /opml, /agent, /storage, /watcher, /mcp), dedicated TypeScript declarations, safe MCP server initialization, and root socket.yml v2 policy config. See CHANGELOG.md for details.

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.

Tree-Shaking & Granular Subpath Exports

To minimize bundle size in client applications, Edge runtimes (Cloudflare Workers, Next.js Edge, Deno, Bun), or specific pipelines, you can import subpaths directly without loading unused storage or LLM adapters:

// Pure XML RSS/Atom Parser (Pure JS, ~6 KB, zero Node built-ins)
import { parseFeedXml, parseFeedString, stripHtml } from 'agentic-rss-parser/core';

// Pure JSON Feed Parser (~2.5 KB)
import { isJsonFeed, parseJsonFeed } from 'agentic-rss-parser/json';

// Pure OPML Parser (~1.8 KB)
import { parseOpml } from 'agentic-rss-parser/opml';

// Heuristic & LLM Scoring
import { heuristicAnalyze, createAnalyzer } from 'agentic-rss-parser/agent';

// Storage Adapters (SQLite / Memory)
import { createStorage, createMemoryStorage } from 'agentic-rss-parser/storage';

// Continuous Feed Watcher
import { createFeedWatcher } from 'agentic-rss-parser/watcher';

MCP Server

Exposes MCP tools and resources over stdio for Claude Desktop, Cursor, and Cline:

Tools

• fetch_rss_feed — Fetch and agentically analyze an RSS, Atom, or JSON feed. Supports heuristic and LLM providers (openai, anthropic, local).
• fetch_full_article — Fetch and HTML-strip article body for context.
• search_feed_history — Search stored intelligence and analyses by keyword.
• get_feed_statistics — Retrieve metrics on processed feeds and relevance ratios.
• prune_database — Prune items older than TTL days.

Resources

• rss://analyses/latest — Read recent relevant intelligence stored in the SQLite database.

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

# LLM-backed analysis (defaults to the heuristic analyzer when --provider is omitted)
npx agentic-rss --feed https://hnrss.org/frontpage --provider anthropic --api-key sk-ant-...
npx agentic-rss --feed https://hnrss.org/frontpage --provider openai --model gpt-4o-mini
# --api-key can be omitted if OPENAI_API_KEY / ANTHROPIC_API_KEY is set in the environment

Key Features

• RSS 2.0, Atom & JSON Feed — CDATA, namespaces, HTML entities, dc:creator, media:content, content:encoded, and JSON Feed v1/v1.1 (parseJsonFeed)
• Podcast & Media Enclosures — extracts <enclosure>, <media:thumbnail>, and itunes:* metadata
• Persistent HTTP Caching — automatic ETag and If-Modified-Since (HTTP 304) to avoid re-fetching unchanged feeds
• OPML Outline Parser — extract feed URLs and categories from OPML subscriptions (parseOpml)
• Polling Watcher — continuous background watcher event emitter with status listeners (createFeedWatcher)
• Database Search & Analytics — keyword search across past analyses (searchAnalyses) and stats (getStatistics)
• Vector DB Export — format processed analyses directly for vector database ingestion (exportForEmbedding)
• Custom Prompts & Analyzers — configurable systemPrompt and promptTemplate for specialized evaluation
• 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 with tools and resources
• Pluggable storage — SQLite (Node 22.5+) or in-memory (any Node version)
• Zero runtime dependencies — minimal supply-chain surface

Security

• XXE / Billion Laughs — iterative state-machine parser, no recursive entity expansion
• Max Nesting Depth — hard cap (128 levels) prevents stack overflow DoS
• Prototype Pollution — Object.hasOwn traversal and reserved key sanitization
• XSS — <script>, <style>, <iframe>, <object>, <embed>, <form> stripped from snippets
• Prompt injection — control chars stripped, newlines collapsed before LLM interpolation
• SSRF Protection — full IANA private, reserved, multicast, documentation, and 6to4 ranges blocked
• 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    # 96 passing
pnpm lint

License

MIT © BLUECARBONS