# Trends MCP Server

A FastMCP-based server for **free entity normalization and attention context**.

This project is intentionally opinionated:
- it exposes **semantic tools**, not raw provider dumps
- it treats Google Knowledge Graph MIDs as canonical entity hints
- it is meant to pair with news and crypto MCPs
- it should remain useful even when historical trend requests are flaky

## What it does

Current tools:
- `resolve_entity` — return candidate entity matches and the best Knowledge Graph MID
- `get_related_queries` — show the search terms surrounding an entity
- `get_related_topics` — show the topic neighborhood around an entity
- `get_ledger_recent` — inspect the newest history entries
- `get_ledger_summary` — summarize what the ledger is saying
- `get_entity_history` — inspect history for one entity or MID
- `prune_history` — delete stored snapshots older than the retention window
- `get_interest_over_time` — show attention over time for a keyword or entity
- `compare_interest` — compare attention between multiple keywords or entities
- `get_attention_score` — compact attention score for a known entity

## Run

### With uv
```bash
uv sync
./run.sh
```

### With pip
```bash
pip install -r requirements.txt
./run.sh
```

## mcporter

If you use `mcporter`, point it at:

```bash
--conf ~/.openclaw/workspace/conf/mcporter.json
```

Example smoke test:

```bash
$ mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_interest_over_time keyword=bitcoin timeframe=7d
```

Entity resolution example:

```bash
$ mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.resolve_entity keyword=bitcoin
```

Related queries example:

```bash
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_related_queries keyword=bitcoin
```

Related topics example:

```bash
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_related_topics keyword=bitcoin
```

History example:

```bash
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_entity_history entity=BTC
```

Suggested smoke tests:

```bash
python -m pytest
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.resolve_entity keyword=bitcoin
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_related_queries keyword=bitcoin
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.get_related_topics keyword=bitcoin
```

Ledger note:

```bash
sqlite3 data/trends_history.db 'select id, ts, tool, keyword, normalized_keyword, mid from snapshots order by id desc limit 20;'
```

Prune history example:

```bash
mcporter --config ~/.openclaw/workspace/config/mcporter.json call trends.prune_history retention_days=30
```

History pruning runs automatically once per day when snapshots are being written.

The server listens on:
- `http://0.0.0.0:8507`
- health: `http://127.0.0.1:8507/health`
- MCP SSE mount: `http://127.0.0.1:8507/mcp`

## Scripts

- `run.sh` — start the server in the background
- `killserver.sh` — stop a PID recorded in `logs/server.pid`
- `restart.sh` — kill, then run again

Logs are written to `logs/server.log`.

## Design notes

The long-term shape of this MCP should be:
1. provider adapters in `providers/`
2. entity normalization and aliasing
3. cache / TTL for recent trend series
4. simple signal heuristics
5. MCP tools that return compact, interpretable outputs

## Next obvious work

- replace the fake series generator with a real Google Trends adapter
- add cache storage
- load aliases from JSON
- add `detect_trending_entities`
- add `get_related_queries`