trends-mcp/PROJECT.md

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