news-mcp

Local Environment

Source the repo-local .venv first when it exists.
Prefer ./tests.sh for offline verification and ./live_tests.sh only for provider-backed smoke checks.
Use ./run.sh to start the server locally; it resolves the repo root and prefers the local Uvicorn binary.

news_mcp/mcp_server_fastmcp.py: MCP tool surface, startup refresh, pruning, and HTTP health endpoints.
news_mcp/jobs/poller.py: feed refresh loop, clustering, enrichment, and cache writes.
news_mcp/storage/sqlite_store.py: SQLite schema, cluster/entity metadata, feed hashes, and prune state.
news_mcp/dedup/cluster.py: topic bucketing and the current fuzzy/embedding clustering path.
news_mcp/enrichment/llm_enrich.py: LLM extraction/summarization and blacklist filtering.
news_mcp/trends_resolution.py and news_mcp/related_entities.py: local Google Trends-based entity resolution and neighborhood lookup.
news_mcp/config.py: env-driven defaults and file paths.

Clusters are the unit of truth, not raw articles.
NEWS_DEFAULT_LOOKBACK_HOURS controls read freshness only.
NEWS_PRUNING_ENABLED, NEWS_RETENTION_DAYS, and NEWS_PRUNE_INTERVAL_HOURS control physical deletion.
Entity aliasing is intentionally conservative; keep config/entity_aliases.json tight.
include_articles=true should keep responses compact and only return minimal article fields.

Keep changes aligned with the docs in README.md, PROJECT.md, and OUTLOOK.md.
Prefer narrow fixes over contract changes unless the user explicitly asks to expand behavior.
Do not run destructive maintenance scripts without a dry run first.
If a change touches storage or pruning, verify it against a temp DB or isolated test fixture rather than the live database.