aiwatcher-mcp

# aiwatcher-mcp — Full LLM Corpus

## Overview

aiwatcher-mcp is a FastMCP 3.2 MCP server and Starlette ASGI web application
that ingests AI news from RSS/Atom feeds and email newsletters, distills items
using Claude with a domain-specific scoring persona, and delivers digests and
alerts through robofang, speechops TTS, email-mcp, and calibre-mcp.

## Architecture

```
Feeds/Email → Ingestion → SQLite DB → Distillation (Claude) → Scoring
                                                    ↓
                                    Digest (HTML email) → email-mcp / SMTP
                                    Calibre ingest → calibre-mcp
                                    Alerts (urgency ≥ 8.5) → robofang + speechops TTS
```

Transport: FastMCP STDIO + Starlette HTTP (dual transport).
MCP endpoint: `http://localhost:10946/mcp`
REST API: `http://localhost:10946/api/*`
Frontend: `http://localhost:10947`

## Tools (full docstrings)

### poll_feeds
Poll all enabled RSS/Atom feeds for new items.
Manually trigger outside the scheduled interval (default 30 min).
Returns: {total_new: int, by_feed: {name: count}}

### distill_pending(batch_size=20)
Score unprocessed items with Claude claude-sonnet-4-20250514.
Sandra persona: relevance (0-10, how much Sandra cares) + urgency (0-10, time-sensitivity).
Returns: {items_distilled: int}

### check_alerts
Find items scored >= ALERT_THRESHOLD (default 8.5), fire robofang Council POST
and speechops TTS. Falls back to Windows SAPI5 if speechops unreachable.
Returns: {alerted: [title, ...], count: int}

### generate_digest(hours=24)
Generate HTML+text digest of recent scored items with Claude.
Returns: {subject, html_preview, text_body}

### send_digest_now
Force-send digest to EMAIL_RECIPIENTS (default Sandra + Steve).
Uses email-mcp REST if EMAIL_MCP_URL configured, else SMTP.
Returns: {sent: bool, subject: str}

### web_search(query, engine="google", limit=5)
Search the web via the local OpenSERP server (google/bing/duckduckgo/yandex/baidu/ecosia).
Useful when RSS feeds don't cover a story — enriches distillation with live search results.
Requires openserp on localhost:7000 (`npx -y @openserp/mcp`).
Returns: {success, query, engine, results: [{title, url, snippet}], total}

### get_top_items(hours=24, limit=10)
Top items sorted by urgency_score DESC.
Returns: {items: [{title, source, url, urgency, relevance, summary, tags}], count, hours}

### get_feeds_list
All feeds with enabled status, feed_type, last_fetched.
Returns: {feeds: [...], count: int}

### add_feed(name, url, feed_type='rss')
Add a new RSS/Atom feed. Duplicates rejected by UNIQUE constraint.
Returns: {id: int, name, url}

### show_dashboard_card [Prefab UI]
Stats card: active_feeds, total_items, unread_items, critical_items, items_last_24h.
Renders as PrefabApp in Claude Desktop; plain text fallback for other hosts.

### currentai(operation, product_query=, stack_layer=, snapshot_id=, snapshot_id_b=)
[RATIONALE] Consolidated portmanteau for currentai-org/os-ai-map dataset.
Fetches product+scores YAML from GitHub, normalises, stores versioned snapshots.

Operations:
- refresh: Fetch upstream YAML, store snapshot if commit differs from latest.
  Returns {new_snapshot, commit, product_count}. Auto-diffs against previous.
- diff: Compare two most recent snapshots (or two given snapshot_ids).
  Returns {added, removed, openness_reclassified, stage_changed, adoption_changed}.
- query: Lookup by product name (case-insensitive substring) or stack_layer.
  Returns {results, count}.
- gap_report: Per stack_layer counts of open / open-ish / closed products.
- check_dependency: Run watchlist (11 fleet-critical products) against latest
  snapshot. Flags concentration risk (<3 fully-open products in a layer) and
  status changes since previous snapshot. Returns {flags, flagged_count}.

Data: docs/CURRENTAI_RECON.md for full schema and upstream details.

## Prompts

### breaking_news_brief
Last 2 hours of items formatted for verbal delivery.

### portfolio_impact_analysis
Template for Claude to assess portfolio impact of current news items.

## Resources

### aiwatcher://feeds/list
JSON array of all feed rows.

### aiwatcher://stats
JSON object: active_feeds, total_items, unread_items, critical_items, items_last_24h.

## REST API Surface

GET  /api/health            — health check
GET  /api/capabilities      — runtime capability introspection (WEBAPP_STANDARDS §1.4)
GET  /api/stats             — DB stats
GET  /api/feeds             — feed list
POST /api/feeds/add         — add feed {name, url, feed_type}
POST /api/feeds/{id}/toggle — enable/disable feed
GET  /api/items             — items (params: hours, limit)
POST /api/poll              — trigger feed poll
POST /api/distill           — trigger distillation
POST /api/alerts/check      — trigger alert check
GET  /api/digest/preview    — generate digest JSON (param: hours)
GET  /api/digest/html       — rendered HTML digest (param: hours)
POST /api/digest/send       — send digest email

## Scheduler Jobs (APScheduler, UTC)

| Job            | Schedule            | Notes                           |
|----------------|---------------------|---------------------------------|
| poll_feeds     | every 30 min        | FEED_POLL_INTERVAL_MINUTES      |
| gmail          | every 1 hour        | only if GMAIL_ENABLED=true      |
| distill        | every 6 hours       | DISTILLATION_INTERVAL_HOURS     |
| alerts         | daily 04:55 UTC     | ALERT_HOUR_UTC / ALERT_MINUTE   |
| daily_digest   | daily 06:00 UTC     | email + calibre ingest          |

## Integration Notes

### robofang
POST to `{ROBOFANG_BACKEND_URL}/api/v1/events` with payload:
{source, event, urgency, title, url, summary, tags, timestamp}

### speechops
POST to `{SPEECHOPS_HTTP_URL}/api/v1/tts` with {text, provider}.
Falls back to PowerShell SAPI5 if unreachable.

### email-mcp
POST `{EMAIL_MCP_URL}/api/send` with {to, subject, body, html} using HTTP Basic auth
(`EMAIL_MCP_USER` / `EMAIL_MCP_PASSWORD`, defaults `sandra`/`vienna2026`). SMTP fallback
when `EMAIL_MCP_URL` unset or unreachable.

### discord-mcp (digest posting, opt-in)
POST `{DISCORD_MCP_URL}/api/v1/channels/{DISCORD_DIGEST_CHANNEL_ID}/messages` with
{content} (<= 2000 chars, truncated). Skipped when either var is empty.

### Intel Reports Hub
POST `{INTEL_REPORTS_HUB_URL}/api/reports/publish` with {title, source, html, markdown,
summary, tags} using HTTP Basic auth (`INTEL_REPORTS_HUB_USER` / `INTEL_REPORTS_HUB_PASS`,
defaults `fleet`/`intel`).

### calibre-mcp
POST to `{CALIBRE_MCP_URL}/api/v1/books/add_from_html` with {title, authors, tags,
html_content, library, series, pubdate}.

### Gmail (Alpha Signal)
GET `{GMAIL_MCP_URL}/api/v1/messages?q=from:{ALPHASIGNAL_SENDER} is:unread`
Extracts article links from HTML body. Marks messages read after ingestion.

## Database Schema

feeds(id, name, url, feed_type, enabled, last_fetched, created_at)
items(id, feed_id, guid, title, url, summary, content_html, published_at,
      fetched_at, is_read, relevance_score, urgency_score, tags,
      distilled_at, distilled_summary, sent_email, sent_robofang, sent_calibre)
digests(id, created_at, period_from, period_to, html_body, text_body,
        item_count, sent_at, recipients)

## Default Feeds (seeded on first run)

Alpha Signal RSS, The Decoder, Import AI, Reuters AI, HN AI/ML (50+ points),
Anthropic Blog, OpenAI Blog, Google DeepMind, MIT Tech Review AI, VentureBeat AI

## Environment Variables (full list)

See .env.example for all variables with defaults and descriptions.
Key variables: LLM_PROVIDER (ollama), LLM_BASE_URL (http://127.0.0.1:11434/v1),
DISTILLATION_MODEL (deepseek-v4-flash) / DISTILLATION_FLASH_MODEL (gemma-3-1b-it,
only when DISTILLATION_FLASH_ENABLED=true),
DISTILLATION_INTERVAL_HOURS (6), ALERT_THRESHOLD, ALERT_HOUR_UTC,
ROBOFANG_ENABLED, EMAIL_ENABLED, EMAIL_RECIPIENTS, EMAIL_MCP_URL,
EMAIL_MCP_USER, EMAIL_MCP_PASSWORD, DISCORD_MCP_URL, DISCORD_DIGEST_CHANNEL_ID,
INTEL_REPORTS_HUB_URL, INTEL_REPORTS_HUB_USER, INTEL_REPORTS_HUB_PASS,
CALIBRE_ENABLED, GMAIL_ENABLED.