SQL-MCP-CLAUDE

ddellecasedata/SQL-MCP-CLAUDE

3.2

If you are the rightful owner of SQL-MCP-CLAUDE and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Server MCP Remoto per Inventario Alimentare is a cloud-deployed MCP server designed to manage food inventory from any device using Claude Desktop. It offers automated management of food storage and tasks with a PostgreSQL database.

Tools
5
Resources
0
Prompts
0

🌐 SQL-MCP: MCP-Compliant Food Inventory Server

🎯 Claude-Ready MCP Server

Un server MCP completamente conforme alle specifiche per l'integrazione con Claude Desktop e altri client AI. Supporta sia i transport moderni (Streamable HTTP) che quelli legacy (HTTP+SSE) per massima compatibilità.

🆕 Novità - Server MCP Conforme

  • ✅ SDK MCP Ufficiale: Usa @modelcontextprotocol/sdk
  • ✅ Transport Multipli: Streamable HTTP (moderno) + HTTP+SSE (legacy)
  • ✅ Session Management: Header Mcp-Session-Id conforme alle specifiche
  • ✅ OAuth 2.1 Completo: Con PKCE per sicurezza avanzata
  • ✅ Claude Desktop Ready: Funziona direttamente con Claude

Server MCP completo per la gestione automatizzata tramite LLM del magazzino alimentari e delle attività (TODO list) con database PostgreSQL.

🚀 Caratteristiche

Gestione Magazzino

  • ✅ Aggiunta/modifica/rimozione alimenti
  • 📊 Consultazione giacenze con filtri avanzati
  • ⚠️ Notifiche automatiche per scadenze
  • 📈 Statistiche consumi per periodo
  • 🔄 Scarico alimenti con controllo quantità
  • 📍 Gestione ubicazioni (FRIGO, FREEZER, DISPENSA, CANTINA)

Gestione Task

  • 📝 Creazione e modifica task con priorità
  • 🔄 Task ricorrenti (giornalieri, settimanali, mensili)
  • 📅 Gestione scadenze e assegnazioni
  • 📊 Statistiche completamento
  • ✅ Workflow completo DA_FARE → IN_CORSO → COMPLETATO

Funzionalità Avanzate

  • 🔐 Autenticazione API Key
  • 📋 Logging completo di tutte le operazioni
  • 🐘 Pool di connessioni PostgreSQL ottimizzato
  • 🌐 API REST + protocollo MCP
  • ☁️ Deploy pronto per Render.com
  • 🧪 Test suite completa

📁 Struttura Progetto

SQL-MCP/
├── database/
│   └── schema.sql              # Schema completo PostgreSQL
├── mcp-server.js              # Server principale MCP Node.js conforme
├── auth-routes.js             # OAuth 2.1 + PKCE endpoints
├── tools.js                   # Tutti i 13 tools MCP
├── package.json               # Dipendenze Node.js
├── DEPLOY_RENDER.md          # Guida deploy Render
├── CLAUDE_INTEGRATION.md     # Guida integrazione Claude Cloud
└── README.md                 # Questa documentazione

🛠️ Installazione e Setup

1. Prerequisiti

  • Node.js 18+
  • PostgreSQL 14+
  • Git

2. Setup Locale

# Clone del repository
git clone <your-repo-url>
cd SQL-MCP

# Installazione dipendenze Node.js
npm install

3. Configurazione Database

# Crea database PostgreSQL
createdb inventario_db

# Esegui schema
psql -d inventario_db -f database/schema.sql

4. Variabili d'Ambiente

Crea file .env:

DATABASE_URL=postgresql://user:password@localhost/inventario_db
AUTH_SECRET=your-secure-auth-secret-here
PORT=3000
NODE_ENV=development

5. Avvio Server

# Avvio normale
npm start

# Avvio con auto-reload (development)
npm run dev

Il server sarà disponibile su http://localhost:3000

🌐 Deployment su Render

1. Preparazione Repository

git add .
git commit -m "Initial MCP server setup"
git push origin main

2. Setup Render

  1. Vai su render.com
  2. Connetti il tuo repository GitHub
  3. Il file render.yaml configurerà automaticamente:
    • Web service (server MCP)
    • Database PostgreSQL
    • Variabili d'ambiente

3. Configurazione Variabili

Nel dashboard Render, configura:

  • DATABASE_URL: Auto-generato dal database PostgreSQL
  • API_KEY: Genera una chiave sicura
  • PORT: 10000 (default Render)

4. Deploy

Il deploy avviene automaticamente. Il server sarà disponibile su:

https://your-app-name.onrender.com

📋 API Reference

Endpoint REST

Health Check
GET /health

Response:

{
  "status": "healthy",
  "database": "connected", 
  "timestamp": "2024-01-15T10:30:00"
}
Alimenti

Crea Alimento

POST /api/alimenti
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "nome": "Latte Intero",
  "quantita": 2.0,
  "unita_misura": "LITRI",
  "categoria": "LATTICINI",
  "ubicazione": "FRIGO",
  "data_scadenza": "2024-01-30",
  "prezzo_acquisto": 1.50,
  "fornitore": "Centrale del Latte"
}

Lista Alimenti

GET /api/alimenti?categoria=VERDURE&ubicazione=FRIGO
Authorization: Bearer YOUR_API_KEY

Tool MCP Disponibili

Gestione Alimenti

  1. aggiungere_alimento

    # Parametri richiesti:
nome: str
quantita: float  
unita_misura: "PEZZI|KG|LITRI|GRAMMI"
categoria: "LATTICINI|VERDURE|FRUTTA|CARNE|PESCE|CONSERVE|BEVANDE|ALTRO"
ubicazione: "FRIGO|FREEZER|DISPENSA|CANTINA"

# Parametri opzionali:
data_scadenza: "YYYY-MM-DD"
data_apertura: "YYYY-MM-DD"
prezzo_acquisto: float
fornitore: str
lotto_acquisto: str
modificato_da: str (default: "user")

  2. consultare_giacenze

    # Tutti parametri opzionali per filtri:
categoria: str
ubicazione: str
in_scadenza_giorni: int
quantita_minima: float

  3. scaricare_alimento

    # Registra consumo alimento
alimento_id: int
quantita_consumata: float
motivo: "CONSUMATO|SCADUTO|BUTTATO" (default: "CONSUMATO")
note: str (opzionale)
forza_operazione: bool (default: False)
utente: str (default: "user")

  4. notifiche_scadenza

    giorni_limite: int (default: 3)
# Restituisce alimenti in scadenza

  5. statistiche_consumi

    data_inizio: "YYYY-MM-DD" (default: ultimi 30 giorni)
data_fine: "YYYY-MM-DD" (default: oggi)
gruppo_per: "categoria|motivo|totale" (default: "categoria")
Gestione Task

  1. inserire_task

    titolo: str
descrizione: str (opzionale)
priorita: "ALTA|MEDIA|BASSA" (default: "MEDIA")
data_scadenza: "YYYY-MM-DD" (opzionale)
assegnatario: str (opzionale)
task_ricorrente: bool (default: False)
frequenza_ricorrenza: "GIORNALIERA|SETTIMANALE|MENSILE" (se ricorrente)
creato_da: str (default: "user")

  2. elencare_task

    # Tutti parametri opzionali per filtri:
stato: "DA_FARE|IN_CORSO|COMPLETATO|ANNULLATO"
priorita: "ALTA|MEDIA|BASSA"
assegnatario: str
scadenza_entro_giorni: int
solo_ricorrenti: bool (default: False)

  3. aggiornare_task

    task_id: int
# Tutti gli altri campi opzionali per modifica:
titolo: str
descrizione: str
priorita: "ALTA|MEDIA|BASSA"
stato: "DA_FARE|IN_CORSO|COMPLETATO|ANNULLATO"
data_scadenza: "YYYY-MM-DD"
assegnatario: str
modificato_da: str (default: "user")

  4. completare_task

    task_id: int
modificato_da: str (default: "user")
# Gestisce automaticamente le ricorrenze

  5. statistiche_task

    data_inizio: "YYYY-MM-DD" (default: ultimi 30 giorni)
data_fine: "YYYY-MM-DD" (default: oggi)
gruppo_per: "stato|priorita|assegnatario" (default: "stato")

💡 Esempi di Utilizzo con LLM

Scenario 1: Gestione Magazzino

Utente: "Aggiungi 2 litri di latte che scade il 25 gennaio"

LLM chiama: aggiungere_alimento
- nome: "Latte"
- quantita: 2.0
- unita_misura: "LITRI" 
- categoria: "LATTICINI"
- ubicazione: "FRIGO"
- data_scadenza: "2024-01-25"

Scenario 2: Controllo Scadenze

Utente: "Cosa scade nei prossimi 5 giorni?"

LLM chiama: notifiche_scadenza
- giorni_limite: 5

Output: Lista alimenti con giorni rimanenti e ubicazione

Scenario 3: Task Ricorrenti

Utente: "Crea un promemoria settimanale per controllare le scadenze"

LLM chiama: inserire_task
- titolo: "Controllo scadenze alimenti"
- descrizione: "Verificare alimenti in scadenza e pianificare utilizzo"
- priorita: "MEDIA"
- task_ricorrente: True
- frequenza_ricorrenza: "SETTIMANALE"

🧪 Testing

Esecuzione Test

# Test completi
python3 -m pytest tests/ -v

# Test specifici
python3 -m pytest tests/test_inventario_mcp.py::TestAlimenti -v

# Test con coverage
pip install pytest-cov
python3 -m pytest --cov=. tests/

Test Database

Per i test è necessario un database separato:

createdb test_inventario_db
export TEST_DATABASE_URL="postgresql://user:password@localhost/test_inventario_db"

📊 Monitoraggio

Logs

Il server produce log strutturati:

2024-01-15 10:30:00 - INFO - 🔄 POST /api/alimenti - IP: 192.168.1.100
2024-01-15 10:30:01 - INFO - ✅ POST /api/alimenti - 200 - 0.045s

Metriche Database

-- Conteggio alimenti per categoria
SELECT categoria, COUNT(*) FROM alimenti GROUP BY categoria;

-- Task completati ultima settimana  
SELECT COUNT(*) FROM task 
WHERE stato = 'COMPLETATO' 
AND ultima_modifica >= NOW() - INTERVAL '7 days';

-- Log operazioni per tipo
SELECT tipo_operazione, COUNT(*) FROM log_operazioni 
GROUP BY tipo_operazione ORDER BY count DESC;

🔧 Configurazione Avanzata

Pool Connessioni

# In server_complete.py
db_pool = await asyncpg.create_pool(
    DATABASE_URL,
    min_size=2,        # Connessioni minime
    max_size=10,       # Connessioni massime
    command_timeout=30 # Timeout query
)

Rate Limiting (Produzione)

from slowapi import Limiter
limiter = Limiter(key_func=lambda: "global")

@app.post("/api/alimenti")
@limiter.limit("100/minute")
async def create_alimento(...):

🔐 Sicurezza

Raccomandazioni Produzione

  1. API Key: Usa chiavi sicure (min 32 caratteri)
  2. HTTPS: Sempre in produzione
  3. Database: Limita connessioni per IP
  4. Rate Limiting: Implementa limiti per endpoint
  5. Input Validation: Già implementata con Pydantic
  6. Logs: Non loggare dati sensibili

Esempio Chiave Sicura

# Genera API key sicura
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

🚨 Troubleshooting

Errori Comuni

1. Connessione Database

❌ Errore: could not connect to server
✅ Soluzione: Verifica DATABASE_URL e che PostgreSQL sia avviato

2. Import MCP

❌ Errore: ModuleNotFoundError: No module named 'mcp'
✅ Soluzione: pip install -r requirements.txt

3. Autenticazione

❌ Errore: 401 Unauthorized
✅ Soluzione: Verifica header Authorization con API_KEY corretta

Debug Mode

export DEBUG=true
python3 server_complete.py

📞 Supporto

  • Issues: Apri un issue su GitHub
  • Email: [il-tuo-email]
  • Documentazione: Questa README

📄 Licenza

MIT License - vedi file LICENSE per dettagli.

Sviluppato per l'automazione intelligente della gestione inventario tramite LLM 🤖📦