# 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.

## Repo Map
- `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.

## Current Contracts
- 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.

## Editing Rules
- 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.