# Ahrefs MCP Server

MCP server per Ahrefs API v3 (Site Explorer), pensato per il piano **Lite** (10.000 units/mese, 60 req/min).

Espone 5 tool a Claude Code via il `mcp-gateway` esistente, con **caching SQLite** e **budget tracking** per non sforare la quota.

## Tool disponibili

| Tool | Endpoint | Costo (units) | Cache TTL |
|---|---|---|---|
| `ahrefs_domain_rating` | `/site-explorer/domain-rating` | ~50 | 7 giorni |
| `ahrefs_backlinks_stats` | `/site-explorer/backlinks-stats` | ~50 | 7 giorni |
| `ahrefs_top_organic_keywords` | `/site-explorer/organic-keywords` | 50 + limit×4 (~130 a limit=20) | 24h |
| `ahrefs_top_pages` | `/site-explorer/top-pages` | 50 + limit×3 (base) o 50 + limit×12 (con traffic) | 24h |
| `ahrefs_budget_status` | (locale) | 0 | — |

## Quanto puoi usarlo col piano Lite

10.000 units/mese a budget pieno significa:
- **~200** chiamate di solo `domain_rating` o `backlinks_stats`, **oppure**
- **~90** chiamate di `top_organic_keywords` (limit=20), **oppure**
- **~110** `top_pages` senza traffic (limit=20), **oppure**
- **~34** `top_pages` con `with_traffic=True` (limit=20).

Mix realistico mensile: ~150–250 chiamate utili sfruttando la cache (TTL 7 giorni per metriche stabili, 24h per liste ranked). Usa `ahrefs_budget_status` per verificare il consumo in qualsiasi momento.

## Quickstart locale (sviluppo)

```bash
cd "/mnt/d/NAS/Claude/MCP Ahrefs"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# inserisci AHREFS_API_KEY=...
# (per dev locale puoi puntare cache/budget alla cartella corrente)
echo "AHREFS_CACHE_DB_PATH=./cache.db" >> .env
echo "AHREFS_BUDGET_PATH=./budget.json" >> .env

python ahrefs_server.py
# in altra shell
curl http://localhost:8089/
```

## Smoke test API key

Prima di tutto verifica che la tua chiave Lite funzioni:

```bash
export AHREFS_API_KEY="..."
curl -s -i -H "Authorization: Bearer $AHREFS_API_KEY" \
  "https://api.ahrefs.com/v3/site-explorer/domain-rating?date=$(date +%F)&target=calcolatorigratis.com%2F"
```

Cerca nei response header le righe `X-Api-Units-Cost` e `X-Api-Units-Remaining` — confermano i nomi reali per il client (sono parsati case-insensitive con fallback graceful).

## Deploy su Proxmox CT102

```bash
./deploy/install.sh root@ct102
ssh root@ct102 'nano /opt/ahrefs-mcp/.env'   # imposta AHREFS_API_KEY
ssh root@ct102 'systemctl restart ahrefs-mcp'
ssh root@ct102 'journalctl -u ahrefs-mcp -f'
```

Lo script:
- rsync del progetto in `/opt/ahrefs-mcp`
- crea `/var/lib/ahrefs-mcp` per cache.db e budget.json
- venv + `pip install`
- copia il systemd unit + abilita + restart

## Integrazione con `mcp-gateway`

Sul container che ospita il gateway (CT102), aggiungi `ahrefs-mcp` come upstream con tag `ahrefs`:

- URL upstream: `http://localhost:8089/sse`
- Tag: `ahrefs` (o `ahrefs,seo`)
- Restart `mcp-gateway`

Per accesso cross-sessione Claude Code, aggiorna `~/.claude.json`:

```json
{
  "mcpServers": {
    "mcp-gateway": {
      "type": "http",
      "url": "https://mcp.calcolatorigratis.com/mcp?tags=core,monetizzazione,ahrefs",
      "headers": { "Authorization": "Bearer <gateway-token>" }
    }
  }
}
```

Oppure per i singoli progetti aggiorna i loro `.mcp.json`.

## Struttura

```
ahrefs_server.py    # FastMCP + Starlette + uvicorn (port 8089)
ahrefs_tools.py     # 5 @mcp_server.tool()
ahrefs_client.py    # httpx wrapper + parsing X-Api-Units-*
ahrefs_cache.py     # SQLite TTL cache
ahrefs_budget.py    # Tracker units mensile (warning 8K, hard stop 10K)
deploy/
  ahrefs-mcp.service
  install.sh
.env.example
requirements.txt
```

## Note operative

- **Hard stop a 10.000 units**: il MCP rifiuta nuove chiamate API (le cache hit continuano a funzionare). Reset automatico al cambio mese.
- **Warning a 8.000 units**: appende un suffisso `⚠️` alle risposte ma non blocca.
- **`with_traffic=True` su `top_pages`**: usalo solo quando ti serve davvero, costa ~3x.
- **Cache deterministica**: chiave = SHA256(endpoint + params ordinati). Stesso target+date+limit ⇒ stessa chiave.