# ⚡ NewsPulse MCP — AI Tech News Aggregator

![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)
![License MIT](https://img.shields.io/badge/license-MIT-green.svg)
![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple.svg)
![Amazon Bedrock](https://img.shields.io/badge/Amazon-Bedrock-orange.svg)

**Built by DD** 🚀

A custom MCP (Model Context Protocol) server built from scratch using the AWS Labs FastMCP SDK. Connects to live RSS feeds and exposes them as MCP tools that Kiro, Claude Desktop, or any MCP client can discover and use. Powered by Amazon Bedrock (Nova) for article summarization.

---

## Table of Contents

- [The Problem](#the-problem)
- [What This Does](#what-this-does)
- [Architecture](#architecture)
- [Quick Start (5 Minutes)](#quick-start-5-minutes)
- [Step-by-Step Setup](#step-by-step-setup)
- [Connect to Kiro IDE](#connect-to-kiro-ide)
- [Connect to Claude Desktop](#connect-to-claude-desktop)
- [Web Dashboard](#web-dashboard)
- [MCP Tools Reference](#mcp-tools-reference)
- [RSS Feed Sources](#rss-feed-sources)
- [Amazon Bedrock Setup (Summarization)](#amazon-bedrock-setup-summarization)
- [Docker Deployment](#docker-deployment)
- [Demo Flow](#demo-flow)
- [Project Structure](#project-structure)
- [Environment Variables](#environment-variables)
- [Running Tests](#running-tests)
- [Troubleshooting](#troubleshooting)
- [Future Improvements](#future-improvements)
- [Author](#author)
- [License](#license)

---

## The Problem

Developers spend time visiting multiple websites to stay updated with AWS, AI, DevOps, Python, Kubernetes, and GitHub news. This MCP server solves that by giving your AI assistant direct access to live tech news feeds.

## What This Does

- 🔌 **Custom MCP Server** — 8 tools discoverable by any MCP client
- 📡 **Live RSS Feeds** — Real-time articles from 8 tech news sources
- 🤖 **AI Summarization** — Amazon Bedrock Nova summarizes articles in 3-5 sentences
- 🔍 **Smart Search** — Keyword search with relevance ranking
- 🔥 **Trending Analysis** — Identifies most-discussed technologies
- 🔖 **Bookmarks** — Save articles to local SQLite database
- 📋 **Daily Digest** — Last 24 hours grouped by category
- 🖥️ **Web Dashboard** — Visual interface at localhost:8000

---

## Architecture

### System Architecture

![NewsPulse MCP Architecture](https://images.tomarkdown.dev/uploaded/m0jdb8wgxsan6p72.png)

### Process Flow — How Data Moves

![processflow MCP.drawio.png](https://images.tomarkdown.dev/uploaded/behcdj3cx1d5p3qb.png)

The MCP server and FastAPI dashboard share a common service layer. Both consume the same RSS, search, summarization, bookmark, and digest services keeping behavior consistent regardless of interface.

---

## Quick Start (5 Minutes)

```bash
# 1. Clone
git clone https://github.com/DD-GITH-UB/newspulse-mcp.git
cd newspulse-mcp

# 2. Install
pip install -r requirements.txt

# 3. Configure
copy .env.example .env

# 4. Run MCP Server
python -m newspulse_mcp serve

# 5. Or run the Web Dashboard
python -m newspulse_mcp dashboard
# Open http://localhost:8000
```

> **Note:** Summarization requires AWS credentials. All other tools (news, search, trending, bookmarks) work without any API keys.

---

## Step-by-Step Setup

### Step 1: Prerequisites

| Requirement | Purpose | Required? |
|-------------|---------|-----------|
| Python 3.11+ | Runtime | ✅ Yes |
| pip | Package manager | ✅ Yes |
| AWS CLI | Bedrock credentials | ⚠️ Only for summarization |
| Git | Clone repo | ✅ Yes |

### Step 2: Clone the Repository

```bash
git clone https://github.com/DD-GITH-UB/newspulse-mcp.git
cd newspulse-mcp
```

### Step 3: Install Dependencies

```bash
pip install -r requirements.txt
```

This installs: fastmcp, fastapi, httpx, feedparser, beautifulsoup4, aiosqlite, boto3, structlog, and more.

### Step 4: Create Environment File

```bash
# Windows
copy .env.example .env

# Mac/Linux
cp .env.example .env
```

### Step 5: Configure AWS (Optional — for summarization only)

```bash
aws configure
```

Enter your:
- AWS Access Key ID
- AWS Secret Access Key
- Default region: `us-east-1`
- Output format: `json`

Then enable the model in [Amazon Bedrock Console](https://console.aws.amazon.com/bedrock/home#/modelaccess) → Request access to `Amazon Nova Lite`.

### Step 6: Verify Everything Works

```bash
python -m newspulse_mcp --help
```

Expected output:
```
usage: newspulse-mcp [-h] [{serve,dashboard}]
NewsPulse MCP Server — Technology news aggregation via MCP protocol
```

### Step 7: Run

```bash
# MCP Server (for Kiro/Claude)
python -m newspulse_mcp serve

# Web Dashboard (for browser)
python -m newspulse_mcp dashboard

# Both simultaneously
python -m newspulse_mcp
```

---

## Connect to Kiro IDE

### Option A: Workspace-level config

Create `.kiro/settings/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "newspulse": {
      "command": "python",
      "args": ["-m", "newspulse_mcp", "serve"],
      "cwd": "/path/to/newspulse-mcp"
    }
  }
}
```

### Option B: User-level config (global)

Edit `~/.kiro/settings/mcp.json` and add `newspulse` to the existing `mcpServers`:

```json
{
  "mcpServers": {
    "newspulse": {
      "command": "python",
      "args": ["-m", "newspulse_mcp", "serve"],
      "cwd": "C:\\path\\to\\newspulse-mcp"
    }
  }
}
```

### Usage in Kiro

Once connected, just ask naturally:

| What you say | Tool invoked |
|---|---|
| "Show me today's AWS news" | `latest_news` |
| "Search for Amazon Bedrock articles" | `search_news` |
| "Summarize this article: https://..." | `summarize_article` |
| "What's trending in tech?" | `trending_topics` |
| "Compare AWS Blog vs GitHub Blog on AI" | `compare_sources` |
| "Bookmark that article" | `bookmark_article` |
| "Show my saved articles" | `saved_articles` |
| "Give me today's tech digest" | `daily_digest` |

---

## Connect to Claude Desktop

Edit your Claude Desktop config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "newspulse": {
      "command": "python",
      "args": ["-m", "newspulse_mcp", "serve"],
      "cwd": "C:\\path\\to\\newspulse-mcp"
    }
  }
}
```

Restart Claude Desktop. The 8 tools will appear in the tools menu.

---

## Web Dashboard

```bash
python -m newspulse_mcp dashboard
```

Open **http://localhost:8000** in your browser.

### Pages

| Page | Description |
|------|-------------|
| 🏠 Home | Feature overview with quick links |
| 📰 Latest News | Live articles with category filter (AWS, AI, Python, etc.) |
| 🔍 Search | Keyword search across all feeds |
| 🔥 Trending | Most discussed technologies with frequency |
| 📋 Daily Digest | Last 24 hours grouped by category |
| 🔖 Bookmarks | Your saved articles |
| ⚙️ Settings | Server config, feeds, Bedrock status |

---

## MCP Tools Reference

### `latest_news`
Retrieve latest articles filtered by category.

**Input:** `category` (AWS, AI, Python, DevOps, Kubernetes, GitHub)
**Output:** Articles with title, source, date, summary, URL

### `search_news`
Search all feeds for keyword matches.

**Input:** `keyword` (e.g., "Amazon Bedrock", "Lambda", "MCP")
**Output:** Ranked articles by relevance

### `summarize_article`
Download and summarize an article using Amazon Bedrock Nova.

**Input:** `url` (full article URL)
**Output:** Title, 3-5 sentence summary, reading time, source
**Requires:** AWS credentials with Bedrock access

### `trending_topics`
Analyze all recent articles for frequently mentioned technologies.

**Input:** None
**Output:** Topics with frequency counts, sorted descending

### `compare_sources`
Compare how two news sources cover the same topic.

**Input:** `source_a`, `source_b`, `topic`
**Output:** Similarities and differences in coverage

### `bookmark_article`
Save article metadata to local SQLite database.

**Input:** `title`, `url`, `source_name`, `published_date`
**Output:** Success/already bookmarked message

### `saved_articles`
Retrieve all bookmarked articles.

**Input:** None
**Output:** All bookmarks ordered by save date (newest first)

### `daily_digest`
Generate a digest of articles from last 24 hours.

**Input:** None
**Output:** Articles grouped by category

---

## RSS Feed Sources

| Source | Category | URL |
|--------|----------|-----|
| AWS News Blog | AWS | aws.amazon.com/blogs/aws/feed/ |
| AWS Machine Learning Blog | AI | aws.amazon.com/blogs/machine-learning/feed/ |
| Python Insider | Python | blog.python.org/feeds/posts/default |
| Kubernetes Blog | Kubernetes | kubernetes.io/feed.xml |
| GitHub Blog | GitHub | github.blog/feed/ |
| Hacker News | DevOps | hnrss.org/frontpage |
| InfoQ | DevOps | feed.infoq.com/ |
| DEV Community | Python | dev.to/feed |

**Add your own feeds** by editing `newspulse_mcp/feeds_config.yaml` — no code changes needed.

---

## Amazon Bedrock Setup (Summarization)

The `summarize_article` tool uses Amazon Bedrock's Converse API with Amazon Nova.

### Step 1: Configure AWS CLI

```bash
aws configure
# AWS Access Key ID: your-key
# AWS Secret Access Key: your-secret
# Default region: us-east-1
# Default output: json
```

### Step 2: Enable Model Access

1. Go to [Amazon Bedrock Console](https://console.aws.amazon.com/bedrock/home#/modelaccess)
2. Click "Manage model access"
3. Enable `Amazon Nova Lite` (or Nova Micro/Pro)
4. Wait for access to be granted (~1 minute)

### Step 3: Configure Model (Optional)

Edit `.env` to change the model:

```env
# Available models:
# amazon.nova-micro-v1:0  — Fastest, cheapest (text-only)
# amazon.nova-lite-v1:0   — Good balance (default)
# amazon.nova-pro-v1:0    — Highest quality
BEDROCK_MODEL_ID=amazon.nova-lite-v1:0
BEDROCK_TEMPERATURE=0.3
BEDROCK_MAX_TOKENS=512
```

### No AWS Account?

All other tools work without Bedrock  you'll just see a "summarization disabled" message for that one tool. News, search, trending, bookmarks, and digest all use live RSS feeds directly.

---

## Docker Deployment

### Build and Run

```bash
docker build -t newspulse-mcp .
docker run -p 8000:8000 --env-file .env newspulse-mcp
```

### Docker Compose

```bash
docker-compose up -d
```

Dashboard at `http://localhost:8000`. SQLite data persisted in `./data/`.

---

## Demo Flow

1. `python -m newspulse_mcp dashboard` — Start the dashboard
2. Open `http://localhost:8000` — See the home page
3. Click **Latest News** — Live articles from all RSS feeds
4. Filter by **"AWS"** category — Only AWS articles shown
5. Click **Search** → type "Bedrock" → see matching articles
6. Click **Trending** — See most discussed technologies
7. Click **Bookmark** on any article — Saved to your library
8. Click **Bookmarks** — See your saved articles
9. Click **Daily Digest** — Last 24 hours grouped by category
10. Connect Kiro → Ask "Show today's AI news" → MCP tools invoked automatically

---

## Project Structure

```
newspulse-mcp/
├── newspulse_mcp/
│   ├── main.py              # Entry point (serve/dashboard/both)
│   ├── feeds_config.yaml    # RSS feed configuration
│   ├── config/              # Settings, feed loader, logging
│   ├── models/              # Article, Bookmark, Error dataclasses
│   ├── services/            # RSS, Search, Trending, Summarizer, etc.
│   ├── parser/              # BeautifulSoup article extraction
│   ├── database/            # SQLite connection + bookmark repository
│   ├── mcp_tools/           # FastMCP tool definitions (8 tools)
│   └── dashboard/           # FastAPI app, routes, templates, CSS
├── tests/                   # Unit + integration tests (100+ tests)
├── .env.example             # Environment variable template
├── .kiro/specs/             # Kiro spec files (requirements, design, tasks)
├── Dockerfile               # Container image
├── docker-compose.yml       # Local orchestration
├── requirements.txt         # Python dependencies
├── pyproject.toml           # Project metadata
├── LICENSE                  # MIT License
└── README.md                # This file
```

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
| `BEDROCK_MODEL_ID` | Nova model for summarization | `amazon.nova-lite-v1:0` |
| `BEDROCK_TEMPERATURE` | LLM temperature (0.0–1.0) | `0.3` |
| `BEDROCK_MAX_TOKENS` | Max summary tokens | `512` |
| `BEDROCK_TOP_P` | Nucleus sampling | `0.9` |
| `SUMMARIZATION_ENABLED` | Enable/disable summarization | `true` |
| `DATABASE_PATH` | SQLite file path | `./newspulse.db` |
| `LOG_LEVEL` | Logging level | `INFO` |

---

## Running Tests

```bash
# Run all tests
python -m pytest tests/ --tb=short

# Run with coverage
python -m pytest tests/ --cov=newspulse_mcp --cov-report=term-missing
```

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `ModuleNotFoundError` | Run `pip install -r requirements.txt` |
| `RuntimeError: Already running asyncio` | Make sure you're using the latest `main.py` (fixed) |
| `Summarization disabled` | Run `aws configure` and enable Nova in Bedrock console |
| Dashboard shows raw HTML | Restart the server (`Ctrl+C` then re-run) |
| Can't access `http://0.0.0.0:8000` | Use `http://localhost:8000` instead |
| `404 /favicon.ico` | Harmless — already fixed with inline SVG favicon |
| Kiro doesn't see tools | Check `mcp.json` path and restart Kiro |

---

## Future Improvements

- Article caching layer to reduce redundant feed fetches
- Full-text search with SQLite FTS5
- WebSocket live feed updates
- User-configurable feed lists via dashboard
- Export bookmarks to Markdown/JSON
- Multi-user authentication
- Scheduled digest via email/Slack
- More RSS sources (TechCrunch, The Verge, etc.)

---

## Author

Built by **DD** with [Kiro IDE](https://kiro.dev) and [Amazon Bedrock](https://aws.amazon.com/bedrock/).

---

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.