agentic-rss-parser 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 1.0.1
+
+### Added
+
+- from-scratch RSS and Atom parsing with a compatibility layer for `rss-parser`-style usage
+- agentic analysis pipeline with deduplication, enrichment, and provider adapters
+- MCP-ready tooling and CLI entrypoints
+- realistic RSS and Atom fixture coverage
+
+### Changed
+
+- replaced the old XML stack with `fast-xml-parser`
+- updated the public package surface and release metadata
+
+### Notes
+
+- `parseURL()` and `parseString()` are supported for migration purposes
+- `parseFeed()` exposes the agentic workflow for programmatic use

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,71 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- demonstrating empathy and kindness toward other people
+- being respectful of differing opinions, viewpoints, and experiences
+- giving and gracefully accepting constructive feedback
+- accepting responsibility and apologizing to those affected by our mistakes
+- focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- the use of sexualized language or imagery, and sexual attention or advances of any kind
+- trolling, insulting or derogatory comments, and personal or political attacks
+- public or private harassment
+- publishing others' private information, such as a physical or email address, without their explicit permission
+- other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainers.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Enforcement Guidelines
+
+Project maintainers will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+Consequence: A private, written warning from maintainers, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate.
+
+### 2. Warning
+
+Community Impact: A violation through a single incident or series of actions.
+
+Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time.
+
+### 3. Temporary Ban
+
+Community Impact: A serious violation of community standards, including sustained inappropriate behavior.
+
+Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time.
+
+### 4. Permanent Ban
+
+Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+Consequence: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for helping improve `agentic-rss-parser`.
+
+This project follows a lightweight but standard open-source workflow:
+
+- keep changes focused and reviewable
+- add or update tests for behavior changes
+- preserve compatibility unless a breaking change is intentional and documented
+- prefer clear documentation alongside code changes
+- avoid unnecessary dependency growth
+
+## Local setup
+
+```bash
+npm install
+npm test
+```
+
+## Before You Open a PR
+
+- run `npm test`
+- run `npm audit`
+- make sure `README.md` and `CHANGELOG.md` stay accurate if the public surface changes
+- include a concise summary of user impact in the PR description
+
+## What to contribute
+
+- parser improvements
+- provider adapters
+- MCP compatibility
+- feed normalization and deduplication improvements
+- docs, examples, and tests
+
+## Guidelines
+
+- keep the public API stable
+- add tests for behavior changes
+- prefer small, focused changes
+- avoid adding heavyweight dependencies unless they clearly improve the library
+- document any compatibility tradeoffs in the PR
+- follow the existing code style and naming patterns

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bluecarbons / Agentic RSS Parser contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# Agentic RSS Parser
+
+[![CI](https://github.com/bluecarbons/agentic-rss-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/bluecarbons/agentic-rss-parser/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/agentic-rss-parser.svg)](https://www.npmjs.com/package/agentic-rss-parser)
+[![Node.js >= 22.5](https://img.shields.io/badge/node-%3E%3D22.5.0-339933)](./SUPPORT.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Open Source](https://img.shields.io/badge/open%20source-yes-brightgreen)](./LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/bluecarbons/agentic-rss-parser?style=social)](https://github.com/bluecarbons/agentic-rss-parser)
+[![GitHub issues](https://img.shields.io/github/issues/bluecarbons/agentic-rss-parser)](https://github.com/bluecarbons/agentic-rss-parser/issues)
+
+Agentic RSS Parser is a from-scratch Node.js library for parsing RSS and Atom feeds, normalizing them into a familiar `Parser` API, and optionally running agentic analysis on top of feed items.
+
+## Supported Environments
+
+- Node.js `>=22.5.0`
+- ESM-only package
+- Linux, macOS, and Windows
+
+Why Node.js 22.5.0 or newer:
+
+- the project uses the built-in `node:sqlite` module
+- `node:sqlite` was added in Node.js 22.5.0
+- Node.js 20 does not support the current codebase
+
+## Design Goals
+
+- compatible migration path for `rss-parser`-style code
+- small, well-documented public API
+- modern XML parsing with `fast-xml-parser`
+- conservative normalization for compatibility
+- agentic features are opt-in, not forced
+- no dependency on the deprecated `rss-parser` package
+
+## Features
+
+- parses RSS 2.0 and Atom feeds
+- supports `Parser`, `parseURL`, `parseString`, and `parseFile`
+- normalizes output into stable feed and item objects
+- supports callback and promise styles
+- supports `customFields`, `timeout`, `headers`, `maxRedirects`, `requestOptions`, `defaultRSS`, and `xml2js`
+- deduplicates processed items with SQLite
+- enriches summaries with full article text
+- supports provider-backed analysis with OpenAI-compatible and Anthropic-compatible adapters
+- exposes a CLI and MCP tool entrypoint
+
+## Installation
+
+```bash
+npm install agentic-rss-parser
+```
+
+```bash
+pnpm add agentic-rss-parser
+```
+
+## Usage
+
+### Parse a feed
+
+```js
+import Parser from 'agentic-rss-parser';
+
+const parser = new Parser({
+  timeout: 10000,
+  headers: { 'user-agent': 'my-app/1.0' }
+});
+
+const feed = await parser.parseURL('https://news.ycombinator.com/rss');
+console.log(feed.title);
+```
+
+### Use the compatibility API
+
+```js
+import Parser from 'agentic-rss-parser';
+
+const parser = new Parser({
+  customFields: {
+    item: [['dc:creator', 'creator']]
+  }
+});
+
+const feed = await parser.parseString(xml);
+console.log(feed.items[0].creator);
+```
+
+### Callback style
+
+```js
+const parser = new Parser();
+
+parser.parseString(xml, (err, feed) => {
+  if (err) throw err;
+  console.log(feed.title);
+});
+```
+
+### Parse from a file
+
+```js
+import Parser from 'agentic-rss-parser';
+
+const parser = new Parser();
+const feed = await parser.parseFile('./feed.xml');
+```
+
+### Agentic workflow
+
+```js
+import { runAgenticParser } from 'agentic-rss-parser';
+
+const results = await runAgenticParser({
+  feedUrls: ['https://news.ycombinator.com/rss'],
+  dbPath: './data/rss-agent.db',
+  fetchFullArticle: true,
+  model: {
+    provider: 'openai',
+    model: 'gpt-4o-mini'
+  }
+});
+
+for (const entry of results) {
+  if (entry.analysis.decision === 'relevant') {
+    console.log(entry.analysis.summary);
+  }
+}
+```
+
+You can also control concurrent feed processing:
+
+```js
+const results = await runAgenticParser({
+  feedUrls: [
+    'https://news.ycombinator.com/rss',
+    'https://hnrss.org/frontpage'
+  ],
+  dbPath: './data/rss-agent.db',
+  concurrency: 2
+});
+```
+
+## Works With Google ADK And Other Agent Frameworks
+
+Agentic RSS Parser is designed to complement agent frameworks, not replace them.
+
+Use it when you want:
+
+- feed ingestion and normalization
+- `rss-parser`-style compatibility for existing code
+- deduplication and article enrichment
+- a clean, agent-ready tool surface
+
+It fits naturally alongside frameworks like Google ADK, where the framework handles agent orchestration and this package handles RSS and Atom data retrieval, normalization, and enrichment.
+
+Typical integration patterns:
+
+- call the library directly from a Node.js tool or workflow
+- wrap `Parser` or `runAgenticParser` inside an ADK custom tool
+- expose the parser through MCP for agent clients that prefer tool protocols
+
+Mental model:
+
+- ADK decides what to do
+- Agentic RSS Parser gathers, normalizes, deduplicates, and enriches the feed data
+- ADK or another orchestrator uses the structured result to continue the workflow
+
+For a concrete starting point, see:
+
+- [`examples/direct.mjs`](./examples/direct.mjs)
+- [`examples/README.md`](./examples/README.md)
+- [`examples/adk-real.mjs`](./examples/adk-real.mjs)
+- [`examples/adk-tool.mjs`](./examples/adk-tool.mjs)
+
+## Migration From `rss-parser`
+
+Most existing code can switch imports with minimal changes:
+
+```js
+import Parser from 'agentic-rss-parser';
+```
+
+Supported compatibility surface:
+
+- `new Parser(options)`
+- `parseURL(url[, callback])`
+- `parseString(xml[, callback])`
+- `parseFile(path[, callback])`
+- `customFields`
+- `timeout`
+- `headers`
+- `maxRedirects`
+- `requestOptions`
+- `defaultRSS`
+- `xml2js`
+
+Supported XML shapes:
+
+- RSS 2.0 feeds with `<item>` entries
+- Atom feeds with `<entry>` entries
+- namespaced fields like `dc:creator` and `content:encoded`
+- repeated tags, attributes, and CDATA
+
+The compatibility layer normalizes output into familiar feed and item objects while preserving the agentic feature set.
+
+## CLI
+
+```bash
+npx agentic-rss-parser --feed https://news.ycombinator.com/rss
+```
+
+Multiple feeds:
+
+```bash
+npx agentic-rss-parser \
+  --feed https://news.ycombinator.com/rss \
+  --feed https://hnrss.org/frontpage \
+  --db ./data/rss-agent.db
+```
+
+## MCP Tooling
+
+```bash
+npx agentic-rss-mcp --feed https://news.ycombinator.com/rss
+```
+
+## Parallelism
+
+Agentic RSS Parser does not currently run a swarm-style parallel orchestration layer on its own.
+
+What it does support:
+
+- you can call it multiple times from your own code in parallel when that makes sense
+- you can wrap it in an ADK workflow that uses parallel agents or parallel tool calls
+- you can manage concurrency at the orchestration layer instead of inside the parser
+- you can set `concurrency` on `runAgenticParser` to process multiple feeds at once
+
+What it does not do yet:
+
+- automatic swarm scheduling
+- distributed scraping coordination
+- cross-feed task planning
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+```bash
+pnpm install
+pnpm test
+```
+
+## Package Health
+
+- pinned Node.js support is documented in [SUPPORT.md](./SUPPORT.md)
+- dependency updates should be reviewed before release
+- `npm audit` should stay clean before merging
+- release steps are documented in [PUBLISHING.md](./PUBLISHING.md)
+
+## Project Structure
+
+- `src/core/parser.js`: XML parsing and normalization
+- `src/core/http.js`: redirect-aware feed fetching
+- `src/compat.js`: `Parser` compatibility surface
+- `src/parser.js`: agentic feed pipeline
+- `src/adapters/provider.js`: model provider adapters
+- `src/mcp/server.js`: MCP entrypoint
+
+## Security
+
+- only fetch trusted feed URLs
+- keep model-provider API keys out of source control
+- review custom XML feeds before processing them in production
+- see [SECURITY.md](./SECURITY.md) for vulnerability reporting
+
+## Contributing
+
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request.
+
+Please also review the [Code of Conduct](./CODE_OF_CONDUCT.md) before participating.

package/SECURITY.md

@@ -0,0 +1,66 @@
+# Security Policy
+
+## Supported Versions
+
+We support the latest `main` branch and the most recent released version.
+
+## Reporting a Vulnerability
+
+If you discover a security issue, please do not open a public issue.
+
+Instead:
+
+- contact the maintainers privately through the repository's security contact process
+- include a clear description of the issue
+- include reproduction steps if possible
+- include any relevant feed sample or payload, if safe to share
+
+## Security Guidance
+
+- only process feeds from sources you trust
+- prefer HTTPS feed URLs
+- keep API keys and tokens out of source control
+- review custom feed XML before processing untrusted content in production
+- validate feed URLs before use and reject non-HTTP protocols
+- keep MCP servers on least privilege
+- prefer local stdio MCP when possible over exposed remote transports
+- do not trust tool descriptions or tool names from unvetted MCP servers
+- treat feed content as untrusted input, especially when it can influence agent prompts
+
+## Threat Model Notes
+
+### MITM
+
+When fetching feeds over the network, a man-in-the-middle attacker could tamper with XML, inject malicious links, or alter the feed metadata.
+
+Mitigations:
+
+- use HTTPS whenever possible
+- keep request timeouts enabled
+- only allow `http:` and `https:` URLs
+- avoid logging secrets or credentials from fetched content
+
+### MCP Abuse
+
+MCP is a powerful integration surface and can be abused through prompt injection, tool poisoning, insecure transport, or over-privileged tool access.
+
+Mitigations:
+
+- expose only the tools the agent actually needs
+- keep tool descriptions narrow and specific
+- validate all tool arguments before execution
+- avoid connecting untrusted remote MCP servers to privileged data sources
+- prefer explicit user approval for destructive or external side effects
+- apply authentication and authorization controls for any remote MCP deployment
+
+### Agent Orchestration
+
+If you embed this package inside an agent framework, the orchestrator should control concurrency and tool invocation. This package intentionally stays focused on feed retrieval, normalization, deduplication, and enrichment.
+
+## Dependency Updates
+
+We review dependency updates regularly and keep the published package audit-clean before release.
+
+## Disclosure
+
+We aim to acknowledge and address confirmed security issues promptly.

package/SUPPORT.md

@@ -0,0 +1,23 @@
+# Supported Environments
+
+Agentic RSS Parser is supported on:
+
+- Node.js `>=22.5.0`
+- ESM modules only
+- Linux, macOS, and Windows
+
+Why this matters:
+
+- the codebase depends on the built-in `node:sqlite` module
+- `node:sqlite` was introduced in Node.js 22.5.0
+- Node.js 20 is not supported for this package
+
+Recommended CI matrix:
+
+- Node.js 22.x
+- Node.js 24.x
+
+Recommended local setup:
+
+- use `npm install`
+- run `npm test` before opening a pull request

package/agentic-rss-mcp

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './src/mcp/server.js';

package/agentic-rss-parser

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './src/cli.js';

package/examples/README.md

@@ -0,0 +1,14 @@
+# Examples
+
+This folder shows a few common ways to use `agentic-rss-parser`.
+
+## Files
+
+- `direct.mjs`: basic library usage from Node.js
+- `adk-real.mjs`: a more concrete example using `@google/adk`
+
+## Notes
+
+- The ADK examples assume you install `@google/adk` in your own app.
+- The direct example works with only this package installed.
+- The examples are intentionally small and are meant to be copied into your app, not run as-is in production.

package/examples/adk-real.mjs

@@ -0,0 +1,36 @@
+import { FunctionTool, LlmAgent } from '@google/adk';
+import { z } from 'zod';
+import { runAgenticParser } from '../src/index.js';
+
+const fetchRssFeed = new FunctionTool({
+  name: 'fetch_rss_feed',
+  description: 'Fetches, normalizes, deduplicates, and optionally enriches RSS or Atom feeds.',
+  parameters: z.object({
+    url: z.string().url().describe('The RSS or Atom feed URL to fetch.'),
+    fetchFullArticle: z.boolean().default(false).describe('Whether to fetch the full article body.'),
+  }),
+  execute: async ({ url, fetchFullArticle }) => {
+    const results = await runAgenticParser({
+      feedUrls: [url],
+      dbPath: './data/rss-agent.db',
+      fetchFullArticle,
+      concurrency: 2
+    });
+
+    return {
+      status: 'success',
+      feedCount: results.length,
+      items: results.map((entry) => entry.item),
+      analyses: results.map((entry) => entry.analysis)
+    };
+  }
+});
+
+export const rssAgent = new LlmAgent({
+  name: 'rss_ingest_agent',
+  model: 'gemini-flash-latest',
+  description: 'Ingests and summarizes RSS feeds using Agentic RSS Parser.',
+  instruction:
+    'Use fetch_rss_feed when you need normalized feed items, deduplication, or article enrichment.',
+  tools: [fetchRssFeed]
+});

package/examples/direct.mjs

@@ -0,0 +1,18 @@
+import Parser, { runAgenticParser } from '../src/index.js';
+
+const parser = new Parser({
+  timeout: 10000,
+  headers: { 'user-agent': 'example-app/1.0' }
+});
+
+const feed = await parser.parseURL('https://news.ycombinator.com/rss');
+console.log(feed.title);
+console.log(feed.items.slice(0, 3).map((item) => item.title));
+
+const results = await runAgenticParser({
+  feedUrls: ['https://news.ycombinator.com/rss'],
+  dbPath: './data/rss-agent.db',
+  fetchFullArticle: false
+});
+
+console.log(results.length);

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "agentic-rss-parser",
+  "version": "1.0.1",
+  "type": "module",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "description": "An open-source agentic RSS parser and tool server for Node.js.",
+  "keywords": [
+    "rss",
+    "atom",
+    "parser",
+    "agentic",
+    "mcp",
+    "nodejs",
+    "typescript",
+    "feeds",
+    "open-source"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluecarbons/agentic-rss-parser.git"
+  },
+  "homepage": "https://github.com/bluecarbons/agentic-rss-parser#readme",
+  "bugs": {
+    "url": "https://github.com/bluecarbons/agentic-rss-parser/issues"
+  },
+  "bin": {
+    "agentic-rss-parser": "./agentic-rss-parser",
+    "agentic-rss-mcp": "./agentic-rss-mcp"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./cli": "./src/cli.js",
+    "./mcp": "./src/mcp/server.js"
+  },
+  "scripts": {
+    "start": "node ./src/cli.js",
+    "mcp": "node ./src/mcp/server.js",
+    "test": "node --test",
+    "lint": "node --check ./src/cli.js"
+  },
+  "packageManager": "pnpm@9.15.4",
+  "files": [
+    "agentic-rss-parser",
+    "agentic-rss-mcp",
+    "src",
+    "examples",
+    "README.md",
+    "SUPPORT.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "CONTRIBUTING.md"
+  ],
+  "dependencies": {
+    "@ai-sdk/anthropic": "3.0.85",
+    "@ai-sdk/openai": "3.0.73",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ai": "6.0.208",
+    "fast-xml-parser": "5.9.3",
+    "zod": "4.4.3"
+  }
+}

package/src/adapters/index.js

@@ -0,0 +1 @@
+export { createAnalyzer } from './provider.js';