# Cauldron Cloud — MCP Server

Collega Claude Desktop (o qualsiasi client MCP) al portale Cauldron.

## Installazione rapida (3 comandi)

```bash
git clone https://git.zerotohero.it/Spaike/cauldron-mcp.git
cd cauldron-mcp
python setup.py
```

Il wizard:
1. Installa le dipendenze automaticamente
2. Apre il browser sulla pagina API Keys del portale
3. Legge la chiave che incolli nel terminale
4. Scrive `claude_desktop_config.json` senza toccare le altre configurazioni

Poi riavvia Claude Desktop — fatto.

---

## Installazione manuale (alternativa)

### Prerequisiti

- Python 3.10+
- pip

### Dipendenze

```bash
pip install mcp httpx
```

### Ottenere la API Key

Accedere al portale Cauldron → menu utente → **API Keys** → "Generate".  
La chiave ha il formato: `cldrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

> La chiave viene mostrata **una sola volta**. Conservarla in modo sicuro.

### Configurazione Claude Desktop

Aprire il file di configurazione:

- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Aggiungere la sezione `mcpServers`:

```json
{
  "mcpServers": {
    "cauldron": {
      "command": "python",
      "args": ["/percorso/assoluto/cauldron-mcp/server.py"],
      "env": {
        "CAULDRON_API_KEY": "cldrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Riavviare Claude Desktop.

## Tool disponibili

| Tool | Descrizione |
|---|---|
| `get_my_profile` | Info sull'utente autenticato e la sua firma |
| `list_deals` | Lista deal con filtri (tipo, stage, industria, paese, testo libero) |
| `get_deal_detail` | Dettaglio completo di un deal |
| `deal_statistics` | Statistiche aggregate (per stage, industria, anno, ecc.) |
| `list_my_requests_for_help` | RFH inviati dalla mia firma al network |
| `list_incoming_requests` | RFH di altre firm diretti a noi (con filtro "senza risposta") |
| `list_deal_stages` | Elenco stage disponibili |
| `list_industries` | Elenco classificazioni industry |
| `list_firms` | Elenco firm visibili |

## Esempi di domande a Claude

```
"Mostrami tutti i deal Sell Side ancora aperti nel settore Automotive"

"Quanti deal abbiamo chiuso nel 2024 per industria?"

"Ci sono Request for Help a cui non abbiamo ancora risposto?"

"Dammi il dettaglio del deal #142"

"Quali deal condivisi nel network riguardano il settore Technology?"

"Statistiche sui nostri deal per anno, dal 2022 ad oggi"
```

## Sicurezza

- La API key identifica univocamente l'utente — trattarla come una password
- La visibilità è identica al portale web: solo i propri deal + quelli condivisi
- I deal cancellati non vengono mai restituiti
- I valori finanziari con flag di confidenzialità vengono mascherati automaticamente
- La chiave è revocabile in qualsiasi momento dal portale

## Permessi MCP vs Portale

| Aspetto | Portale web | MCP |
|---|---|---|
| Admin Portale vede tutti i deal | ✅ | ❌ (firma-scoped) |
| Deal propria firma | ✅ | ✅ |
| Deal condivisi altre firm | ✅ | ✅ |
| Deal cancellati (Attivo=N) | ❌ | ❌ |
| Valori confidenziali | Visibili se autorizzato | Mascherati |

> Il layer MCP è intenzionalmente più restrittivo: nessun utente ottiene visibilità
> super-admin attraverso l'API key, indipendentemente dal proprio ruolo sul portale.