# 📈 Trends MCP Server — Requirements Spec

## 🎯 Goal

Provide **free, normalized entity intelligence**
for:

* keywords
* entities (BTC, AI, ETFs, etc.)
* topics

👉 This is not a paid trend terminal
👉 It’s an **entity resolution + attention context engine**

## First-order priority

The most reliable value in this project is no longer historical trend curves.
It is **entity normalization**, **topic disambiguation**, and **related-query discovery**.

If Google refuses time-series requests, the MCP should still remain useful by:

* returning Knowledge Graph MID candidates
* resolving canonical entity labels
* surfacing related queries and topics
* providing topic-aware context for downstream MCPs
* keeping a SQLite snapshot history for temporal inspection and later diffing

---

# 🧠 Core Insight

> Markets often move *after* attention increases.

So this MCP helps answer:

* “Is something gaining attention?”
* “Is this narrative heating up?”
* “Is attention diverging from price?”

---

# 🏗️ 1. Internal Architecture

## 📊 Data Sources (`providers/`)

Primary:

* Google Trends (via unofficial APIs like `pytrends`)

Optional later:

* Twitter/X trends
* Reddit mentions
* YouTube search trends

---

## 🔄 Normalization Layer (CRITICAL)

### Problem:

Google Trends data is:

* relative (0–100)
* inconsistent across queries

### Solution:

Normalize across:

* timeframes
* keywords

Techniques:

* anchor keywords (e.g. always compare vs “bitcoin”)
* rescaling across batches

---

## 🧠 Entity Mapping Layer

Map:

* “btc”, “bitcoin”, “bitcoin price” → **BTC**

👉 This is essential for consistency with your other MCPs

---

## 🗃️ Storage / Cache

Cache trend series:

Key:

```id="t1"
trends:{keyword}:{timeframe}
```

TTL:

* 15–60 minutes (trends don’t change second-by-second)

---

# 🧰 2. Agent-Facing Tools

Keep them **interpretive, not raw**

---

## 1. `get_interest_over_time`

> “Show attention trend”

```json id="t2"
{
  "keyword": "bitcoin",
  "timeframe": "7d"
}
```

Output:

```json id="t3"
{
  "series": [12, 18, 25, 40, 65, 80],
  "trend": "rising"
}
```

👉 Include simple interpretation (“rising”, “falling”, “flat”)

---

## 2. `compare_interest`

> “Which topic is hotter?”

```json id="t4"
{
  "keywords": ["bitcoin", "ethereum"],
  "timeframe": "7d"
}
```

Output:

```json id="t5"
{
  "winner": "bitcoin",
  "ratios": {
    "bitcoin": 1.0,
    "ethereum": 0.72
  }
}
```

---

## 3. `detect_trending_entities`

> “What is gaining attention?”

```json id="t6"
{
  "category": "crypto"
}
```

Output:

```json id="t7"
[
  {
    "entity": "Solana",
    "trend_score": 0.91,
    "velocity": "high"
  }
]
```

---

## 4. `get_related_queries`

> “What are people searching around this?”

```json id="t8"
{
  "keyword": "bitcoin"
}
```

Output:

```json id="t9"
[
  "bitcoin etf",
  "bitcoin price prediction",
  "btc news"
]
```

---

## 5. `get_attention_score` (VERY useful)

> “How much attention does X have right now?”

```json id="t10"
{
  "entity": "BTC"
}
```

Output:

```json id="t11"
{
  "score": 0.78,
  "relative_to_baseline": 1.4
}
```

---

# ⚠️ 3. What NOT to expose

Avoid:

* raw Google Trends responses
* overly granular time series
* unnormalized keyword data

❌ Bad:

```id="bad-trends"
get_raw_trends(keyword)
```

---

# 🧠 4. Key Challenges

## 1. Normalization (hardest problem)

Trends are:

* relative per query
* not directly comparable

👉 If you skip normalization:
your MCP becomes misleading

---

## 2. Keyword ambiguity

Example:

* “apple” → company or fruit?

👉 You need:

* context-aware mapping
* or restrict to known entities (better for v1)

---

## 3. Sparse data

Some queries:

* have low volume
* return noisy signals

👉 filter aggressively

---

# ⚡ 5. Signal Engineering (where value comes from)

Raw trend data is weak.

Value comes from:

---

## 📈 Trend direction

* rising / falling / flat

---

## 🚀 Velocity

* how fast attention increases

---

## 🔥 Spike detection

* sudden jumps

---

## ⚖️ Relative strength

* vs other entities

---

# 🧩 6. Relationship to Other MCPs

This is your **early warning system**

Combined with:

* Crypto MCP → confirms movement
* News MCP → explains movement

---

## 🔥 Example synergy:

Trends MCP:
→ “Ethereum ETF” searches spiking

News MCP:
→ few articles yet

Crypto MCP:
→ price still flat

👉 This is:

> **pre-news signal**

---

# 🧭 7. Design Philosophy

Each tool should answer:

> “Where is attention moving?”

---

# 🚀 8. Suggested Build Order

1. basic keyword trend fetch
2. caching
3. simple slope detection (rising/falling)
4. entity mapping (BTC, ETH, etc.)
5. comparison tool

👉 normalization improvements can come later