# Backlink Outreach MCP Server

Server MCP per la discovery e outreach automatizzata di backlink per [calcolatorigratis.com](https://calcolatorigratis.com).

**Stack:** Python 3 + FastMCP + SQLite + httpx  
**Deploy:** CT102 Proxmox (192.168.1.107:8010)  
**Tunnel:** https://backlink.calcolatorigratis.com  
**Dashboard:** https://backlink.calcolatorigratis.com/dashboard

---

## Come ottenere le API Key

Il server utilizza 4 chiavi API esterne. Tutte hanno un **free tier** sufficiente per l'uso del progetto. Le chiavi si inseriscono direttamente dalla **dashboard** (sezione "Chiavi API" in fondo alla pagina) oppure nel file `.env`.

> Le chiavi salvate dalla dashboard hanno priorita su quelle nel `.env`.

---

### 1. Google Custom Search API Key + Engine ID (CX)

Permette di cercare su Google via API ufficiale (100 query/giorno gratis) invece dello scraping HTML.

> **Stato aprile 2026:** La Custom Search JSON API ha due limitazioni importanti:
> - **Chiusa ai nuovi clienti** — se il tuo account Google Cloud non ha mai abilitato questa API, potresti ricevere errore 403. Gli account esistenti possono usarla fino al 1 gennaio 2027.
> - **"Ricerca in tutto il Web" deprecata** — l'opzione per cercare su tutto il web non e piu attivabile. Il motore di ricerca cerca SOLO nei siti/domini che aggiungi manualmente (max 50 domini).
>
> **Cosa significa in pratica:** La CSE resta utile per cercare in un set di domini italiani noti (blog, directory, portali), ma non puo sostituire una ricerca web generica. Per la discovery generica, il server usa lo scraping HTML (20 query/giorno) oppure GSC/Ahrefs MCP.
>
> **Se non riesci ad attivarla, salta questa sezione.** Il server funziona perfettamente senza.

#### Passo 1 — Crea un progetto Google Cloud

1. Vai su [Google Cloud Console](https://console.cloud.google.com)
2. Accedi con il tuo account Google
3. Clicca il menu a tendina dei progetti in alto
4. Clicca **Nuovo progetto**
5. Nome: `Backlink Outreach` (o qualsiasi nome)
6. Clicca **Crea**

#### Passo 2 — Abilita la Custom Search API

1. Nel progetto appena creato, vai su **API e servizi > Libreria**
   - URL diretto: https://console.cloud.google.com/apis/library
2. Cerca **"Custom Search API"**
3. Clicca sul risultato **"Custom Search JSON API"**
4. Clicca **Abilita**
   - Se ricevi errore 403 "PERMISSION_DENIED", il tuo account non ha accesso (API chiusa ai nuovi clienti). Salta questa sezione.

#### Passo 3 — Genera la API Key

1. Vai su **API e servizi > Credenziali**
   - URL diretto: https://console.cloud.google.com/apis/credentials
2. Clicca **+ Crea credenziali > Chiave API**
3. Copia la chiave generata (formato: `AIzaSy...`)
4. *(Consigliato)* Clicca **Limita chiave** e seleziona solo "Custom Search JSON API"

> Questa e la tua **GOOGLE_CSE_API_KEY**. Serve anche per Google PageSpeed Insights (il server la riusa automaticamente).

#### Passo 4 — Crea il Search Engine e ottieni il CX

1. Vai su [Programmable Search Engine](https://programmablesearchengine.google.com/controlpanel/create)
2. **Nome del motore di ricerca:** `Backlink Discovery`
3. **Siti in cui eseguire ricerche:** aggiungi i domini target per la discovery backlink.
   Esempi di pattern utili per il mercato italiano:

   ```
   *.blogspot.com/*
   *.wordpress.com/*
   *.altervista.org/*
   *.medium.com/*
   *.substack.com/*
   ```

   Puoi aggiungere fino a **50 domini distinti**. Aggiungi i portali, blog e directory italiane
   dove vuoi cercare prospect per backlink. Potrai modificarli in seguito.

4. Clicca **Crea**
5. Dopo la creazione, clicca **Personalizza** per aprire il pannello di configurazione
6. Nella pagina **Impostazioni base**, trova l'**ID motore di ricerca** (Search engine ID)
   - E una stringa tipo `a1b2c3d4e5f6g7h8i` (17 caratteri alfanumerici)

> Questo e il tuo **GOOGLE_CSE_CX**.

> **Nota:** L'opzione "Ricerca in tutto il Web" nella sezione "Funzionalita dei risultati di ricerca"
> e deprecata e non puo piu essere attivata. Il motore cerchera solo nei domini che hai inserito.
> Per una ricerca web generica, usa il tool `search_google_prospects` senza CSE (scraping HTML)
> oppure i tool GSC/Ahrefs MCP.

#### Riepilogo

| Chiave | Dove trovarla | Free tier |
|--------|--------------|-----------|
| `GOOGLE_CSE_API_KEY` | Google Cloud Console > Credenziali | 100 query/giorno |
| `GOOGLE_CSE_CX` | Programmable Search Engine > Panoramica | Incluso |

**Riferimenti:**
- [Documentazione ufficiale Custom Search JSON API](https://developers.google.com/custom-search/v1/introduction)
- [Panoramica e limiti](https://developers.google.com/custom-search/v1/overview)
- [Pannello Programmable Search Engine](https://programmablesearchengine.google.com/controlpanel/all)

---

### 2. Hunter.io API Key

Permette di trovare email associate a un dominio (25 ricerche/mese gratis) e verificarle (50 verifiche/mese). Il server funziona anche senza questa chiave (usa solo lo scraping HTML per cercare email visibili nelle pagine).

#### Passo 1 — Registrati

1. Vai su [Hunter.io](https://hunter.io)
2. Clicca **Sign up** in alto a destra
3. Registrati con email e password, oppure con Google/LinkedIn
4. Conferma l'email di verifica

#### Passo 2 — Ottieni la API Key

1. Dopo il login, vai su [API Keys](https://hunter.io/api-keys)
   - Oppure: clicca il tuo avatar > **API** nel menu
2. La chiave API e visibile nella pagina
   - Formato: stringa alfanumerica lunga ~40 caratteri
3. Copia la chiave

> Questa e la tua **HUNTER_API_KEY**.

#### Passo 3 — Verifica il funzionamento (opzionale)

Puoi testare la chiave direttamente nel terminale:

```bash
curl "https://api.hunter.io/v2/account?api_key=LA_TUA_CHIAVE"
```

Se funziona, vedrai il tuo piano e le ricerche rimanenti.

#### Free tier

| Risorsa | Limite mensile |
|---------|---------------|
| Domain Search (ricerca email per dominio) | 25 ricerche |
| Email Verifier (verifica deliverability) | 50 verifiche |
| Email Finder (trova email per nome+dominio) | 25 ricerche |

#### Autenticazione

La chiave puo essere passata in 3 modi (il server usa il primo):
- Parametro query: `?api_key=LA_TUA_CHIAVE`
- Header: `X-API-KEY: LA_TUA_CHIAVE`
- Header: `Authorization: Bearer LA_TUA_CHIAVE`

**Riferimenti:**
- [Panoramica API Hunter.io](https://hunter.io/api)
- [Documentazione API v2](https://hunter.io/api-documentation)
- [Gestione API Keys](https://hunter.io/api-keys)

---

### 3. Open PageRank API Key

Fornisce il PageRank (0-10) e il ranking globale dei domini. Usato per lo scoring automatico dei prospect. Il server funziona anche senza questa chiave (lo score resta manuale).

#### Passo 1 — Registrati

1. Vai su [Open PageRank Signup](https://www.domcop.com/openpagerank/auth/signup)
2. Inserisci nome, email e password
3. Clicca **Sign Up**
4. Conferma l'email di verifica

#### Passo 2 — Ottieni la API Key

1. Dopo il login, vai su [Open PageRank Dashboard](https://www.domcop.com/openpagerank/)
2. La API key e visibile nella dashboard principale
   - Formato: stringa alfanumerica ~40 caratteri
3. Copia la chiave

> Questa e la tua **OPENPAGERANK_API_KEY**.

#### Passo 3 — Verifica il funzionamento (opzionale)

```bash
curl -H "API-OPR: LA_TUA_CHIAVE" "https://openpagerank.com/api/v1.0/getPageRank?domains[]=google.com"
```

Se funziona, vedrai il PageRank di google.com (dovrebbe essere ~10).

#### Free tier

| Risorsa | Limite |
|---------|--------|
| Richieste API | 10.000/ora |
| Domini per richiesta (batch) | fino a 100 |
| Costo | Gratuito, nessun piano a pagamento richiesto |

#### Autenticazione

La chiave va passata nell'header HTTP:

```
API-OPR: LA_TUA_CHIAVE
```

**Riferimenti:**
- [Homepage Open PageRank](https://www.domcop.com/openpagerank/)
- [Documentazione API](https://www.domcop.com/openpagerank/documentation)
- [Pagina registrazione](https://www.domcop.com/openpagerank/auth/signup)

---

## Inserire le chiavi

### Metodo 1 — Dashboard (consigliato)

1. Apri la dashboard: https://backlink.calcolatorigratis.com/dashboard
2. Scorri fino alla sezione **"Chiavi API"** in fondo
3. Per ogni chiave:
   - Incolla il valore nel campo di testo
   - Clicca **Salva**
   - Clicca **Test** per verificare che funzioni
4. Le chiavi salvate dalla dashboard sono attive immediatamente (nessun restart necessario)

### Metodo 2 — File .env

Modifica il file `.env` nella cartella del progetto:

```env
GOOGLE_CSE_API_KEY=AIzaSy...
GOOGLE_CSE_CX=a1b2c3d4e5f6g7h8i
HUNTER_API_KEY=abc123...
OPENPAGERANK_API_KEY=xyz789...
```

Dopo la modifica, rideploya con `bash deploy.sh` per applicare le modifiche.

> Le chiavi inserite dalla dashboard hanno priorita su quelle nel `.env`.

---

## Riepilogo tempi di registrazione

| API | Tempo | Difficolta | Note |
|-----|-------|-----------|------|
| Open PageRank | ~2 minuti | Facile | Solo email + password |
| Hunter.io | ~2 minuti | Facile | Solo email + password |
| Google CSE | ~5 minuti | Media | Richiede progetto Google Cloud |

---

## API gratuite aggiuntive (nessuna chiave richiesta)

Il server usa anche queste API che **non richiedono registrazione**:

| API | Cosa fa | Limite |
|-----|---------|--------|
| [Tranco List](https://tranco-list.eu/) | Ranking dominio top-1M | Illimitato |
| [Wayback Machine CDX](https://web.archive.org/) | Eta dominio (prima archiviazione) | ~15 req/min |
| [RDAP](https://rdap.org/) | WHOIS dominio (registrazione, scadenza) | ~100 req/ora |
| [Google PageSpeed Insights](https://developers.google.com/speed/docs/insights/v5/get-started) | Score performance/SEO | 25.000/giorno |

---

## Struttura file

```
backlink_server.py      — Server ASGI + dashboard + API endpoints
backlink_tools.py       — 20 tool MCP
database.py             — SQLite schema + helpers
google_search.py        — Google CSE API + scraping fallback
domain_metrics.py       — Open PageRank + Tranco + Wayback + RDAP
email_discovery.py      — Hunter.io email finder
tech_detection.py       — CMS detection + PageSpeed Insights
email_client.py         — SMTP/IMAP (Hostinger)
deploy.sh               — Deploy automatico su CT102
.env                    — Configurazione produzione
```