HEU Legal MCP Server

MCP server (Model Context Protocol) che collega l'API HEU Legal a Claude e a qualsiasi client MCP. Gestisce l'intero ciclo di vita dei documenti con firma elettronica (valida in 180+ paesi) direttamente in conversazione: dalla creazione all'invio in firma, dal sollecito al download del fascicolo legale completo.

Cosa puoi fare

Due famiglie di oggetti:

• Documenti nativi HEU — creati con l'editor in-app della piattaforma (ID a forma di UUID, es. 5135e7b2-196b-...).
• PDF caricati — file PDF con firmatari e campi firma posizionati sopra (ID numerici, es. 68).

Requisiti

• Python ≥ 3.10
• API key HEU Legal — nella UI: Profile → API Keys → Generate API Key (richiede subscription Enterprise; massimo 2 chiavi attive)
• Per i flussi da template: almeno un template creato sulla piattaforma (oppure crealo via API con create_pdf_template)

Installazione

Da PyPI:

pip install heu-mcp

Da sorgenti:

git clone https://github.com/heulegal/heu-mcp.git
cd heu-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configurazione

Claude Desktop

Modifica ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "heu": {
      "command": "heu-mcp",
      "args": [],
      "env": {
        "HEU_API_KEY": "la_tua_api_key_qui"
      }
    }
  }
}

Se installato da sorgenti con venv:

{
  "mcpServers": {
    "heu": {
      "command": "/path/assoluto/heu-mcp/venv/bin/python",
      "args": ["/path/assoluto/heu-mcp/server.py"],
      "env": {
        "HEU_API_KEY": "la_tua_api_key_qui"
      }
    }
  }
}

Riavvia Claude Desktop dopo la modifica.

Claude Code (CLI)

claude mcp add heu heu-mcp -e HEU_API_KEY=la_tua_api_key_qui

Server remoto (multi-utente)

Oltre alla modalità locale (stdio) descritta sopra, il progetto include un server remoto che espone gli stessi 28 tool via HTTPS, così gli utenti si collegano senza installare nulla: inseriscono la propria API key HEU una volta, in un flusso OAuth.

Caratteristiche:

• Transport Streamable HTTP, autenticazione OAuth 2.1 con PKCE S256, Dynamic Client Registration e Client ID Metadata Document
• Multi-utente: ogni connessione usa la API key del proprio utente, conservata cifrata (Fernet) e mai in chiaro nel database
• Refresh token con rotazione e revoca automatica della sessione in caso di riuso sospetto
• I/O di rete asincrono e parsing PDF su threadpool: una richiesta lenta non blocca gli altri utenti

Avvio locale

pip install -e ".[remote]"
export HEU_MCP_SECRET_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
export PUBLIC_URL="http://localhost:8080"
export HEU_MCP_DB="./heu-mcp.db"
heu-mcp-remote

Deploy su Fly.io

fly launch --no-deploy
fly volumes create heu_data --size 1
fly secrets set HEU_MCP_SECRET_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
fly secrets set PUBLIC_URL="https://<nome-app>.fly.dev"
fly deploy

Variabili d'ambiente del server remoto

Endpoint esposti

Variabili d'ambiente

Riferimento completo dei tool (28)

🩺 Health

📄 Documenti nativi HEU

📎 PDF caricati

🧩 Template PDF (gestione via API)

✋ = il tool ha effetti verso l'esterno (crea, invia email, elimina): Claude chiede sempre conferma prima di eseguirlo.

Come si posizionano i placeholder

• position_x / position_y: percentuale della pagina (0–100 esclusi), origine in basso a sinistra (come nell'editor dell'app).
• page_number: parte da 1.
• Tipi: signature, initials, text (richiede text_label), checkbox_optional, checkbox_required.
• I firmatari si collegano ai campi tramite source_id → signer_source_id.
• I PDF ruotati (/Rotate 90/180/270) vengono rifiutati dall'API.

Flussi di lavoro tipici

0. Invio in firma "intelligente": l'AI mappa i campi da sola

"Prendi /Users/me/Desktop/Contratto.pdf, trova dove devono firmare le parti e mandalo a cliente@example.com e fornitore@example.com."

Cosa succede dietro le quinte:

1. locate_pdf_text analizza il PDF e trova le ancore: le righe "Firma del Cliente" / "Firma del Fornitore" (o i nomi delle parti) con le loro coordinate esatte in percentuale.
2. Claude propone la mappatura: "Metto il campo firma del cliente a pagina 4, sopra l'etichetta 'Firma del Cliente' (x 17%, y 14%), e quello del fornitore accanto (x 50%, y 14%). Confermi?"
3. Alla conferma, create_pdf_document_from_upload carica il PDF con i placeholder posizionati e invia le email di firma.
4. (Opzionale) preview_pdf_template per un controllo visivo se si è passati da un template.

Le coordinate restituite da locate_pdf_text sono già nel sistema dei placeholder HEU (percentuale, origine in basso a sinistra): nessuna conversione necessaria. Per layout complessi si può chiedere l'intera mappa della pagina con include_all_lines=true, o cercare termini specifici (search_terms=["Il Committente", "Il Prestatore"]).

⚠️ Limite: funziona sui PDF con testo. Le scansioni senza OCR non hanno testo estraibile — in quel caso indicare le posizioni manualmente.

1. Mandare in firma un PDF dal computer (tutto via chat)

"Prendi /Users/me/Desktop/NDA.pdf e mandalo in firma a Mario Rossi (mario@example.com). Campo firma in basso a destra dell'ultima pagina, oggetto email 'NDA da firmare'."

Claude usa create_pdf_document_from_upload → il documento è creato e Mario riceve subito l'email. Poi:

"Mario ha firmato?" → get_pdf_document "Sollecitalo" → prompt_pdf_document_signature "È firmato, scaricami il fascicolo completo" → download_pdf_bundle

2. Contratti ricorrenti con template

"Crea un template dal file Contratto-tipo.pdf con due firmatari: cliente e fornitore. Firma del cliente a pagina 3 in basso." → create_pdf_template "Fammi vedere l'anteprima per controllare le posizioni" → preview_pdf_template "Ora usalo per mandare il contratto ad ACME srl" → create_pdf_document

3. Analisi documentale (l'AI legge i contratti)

"Riassumi il contratto abc-123 e dimmi durata e condizioni di recesso" → read_heu_document "Confronta le clausole di responsabilità dei contratti X e Y" → due read_heu_document "Estrai i dati delle parti: ragione sociale, P.IVA, SDI, PEC" → extract_heu_document_parties

L'estrazione parti è pensata per l'integrazione con flussi di fatturazione elettronica italiana: il codice univoco SDI e la P.IVA estratti dal contratto possono alimentare direttamente l'anagrafica del gestionale.

4. Monitoraggio e amministrazione

"Quali documenti di luglio non sono ancora stati firmati da tutti?" → list_heu_documents con date + have_editors_signed=false "Annulla la richiesta di firma del PDF 42, l'abbiamo mandata alla persona sbagliata" → cancel_pdf_document

Comportamenti e limiti da conoscere

Stati dei documenti

Sicurezza

• L'API key è letta solo da variabile d'ambiente: mai nel codice, mai nelle risposte, mai nei log.
• I tool con effetti esterni (✋) sono istruiti per richiedere sempre conferma esplicita all'utente.
• I file scaricati restano sul filesystem locale.

Sviluppo

git clone https://github.com/heulegal/heu-mcp.git
cd heu-mcp
python3 -m venv venv
source venv/bin/activate
pip install -e .

# Avvio manuale per debug
HEU_API_KEY=... python server.py

La spec OpenAPI di riferimento è pubblicata su https://api.heulegal.com/v1/specs/v1.yaml (docs interattive: https://api.heulegal.com/v1/docs).

Licenza

MIT — vedi LICENSE.

Link

• HEU Legal
• Documentazione API HEU
• Model Context Protocol
• Pacchetto PyPI