# Trends MCP — Project Notes

## Purpose

Turn noisy search/trend data into **clean entity intelligence** that other agents can reason about.

This is not a raw data API. It should answer questions like:
- What entity is this mention most likely referring to?
- What is the canonical Google MID?
- What related queries/topics surround this entity?
- When trend data is available, is interest rising or falling?

The project now keeps a SQLite snapshot history so we can inspect how related-query/topic
surfaces change over time, before wiring anything into news-mcp.

## Core principles

- Prefer **normalized** outputs over raw provider payloads.
- Prefer **semantic tools** over low-level endpoints.
- Keep the response shape compact and predictable.
- Treat entity mapping as foundational, not optional.

## Tech stack

- Python
- FastMCP
- FastAPI
- Uvicorn
- `pytrends` for the first provider

## Current server contract

- host: `0.0.0.0`
- port: `8507`
- transport: FastMCP over SSE
- mount: `/mcp`

## Scripts

- `run.sh` starts the server
- `killserver.sh` stops a PID stored in `server.pid`
- `restart.sh` performs kill + run only

## Initial tool set

- `get_interest_over_time(keyword, timeframe)`
- `compare_interest(keywords, timeframe)`
- `get_attention_score(entity, timeframe)`
- `resolve_entity(keyword)`
- `get_related_queries(keyword)`
- `get_related_topics(keyword)`
- `get_ledger_recent(limit)`
- `get_ledger_summary(limit)`
- `get_entity_history(entity, limit)`
- `prune_history(retention_days)`

## History storage

History is stored in a single SQLite table (`snapshots`) under `data/trends_history.db`.
Each row stores the full normalized tool payload so later analysis can diff change over time,
instead of only counting that a lookup happened.

Pruning is automatic: the history store checks once per day whether retention cleanup is due,
and removes rows older than the configured retention window.

## Recommended build order

1. real provider adapter
2. cache layer
3. entity aliases / normalization
4. trend direction heuristics
5. comparison and spike detection
6. broader trend discovery tools

## Notes for future readers

The right implementation style here is boring on purpose:
- small modules
- predictable data flow
- no heavy abstraction until it earns its keep
- interpretive output, not provider noise