|
|
@@ -0,0 +1,28 @@
|
|
|
+# 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.
|
