makerdojo-it/mcp_server_for_sqlite

Community Chat Server MCP

Un server MCP (Model Context Protocol) completo che integra ChatGPT via llama-index con un database SQLite per analizzare i dati della community e fornire chat intelligenti.

🚀 Caratteristiche

• Chat AI con ChatGPT: Utilizza llama-index per gestire conversazioni con GPT-3.5-turbo
• Database SQLite: Interroga un database di chatters della community
• Analisi Intelligente: Analizza trend e statistiche usando l'AI
• Memory Management: Mantiene la cronologia delle conversazioni
• Strumenti MCP: Espone funzionalità come strumenti MCP

📋 Prerequisiti

• Python 3.8+
• OpenAI API Key
• Database SQLite con dati dei chatters

🛠️ Installazione

1. Clona o scarica i file

   cd /Users/iwan/Downloads/mcp_server
   

2. Installa le dipendenze

   pip install -r requirements.txt
   

   Oppure installa manualmente:

   pip install mcp llama-index openai python-dotenv
   

3. Configura le variabili d'ambiente

   Modifica il file .env:

   OPENAI_API_KEY=your_actual_openai_api_key_here
   MCP_SERVER_NAME=Community Chat Server
   DATABASE_PATH=community.db
   

4. Verifica il database

   Il database community.db deve avere la seguente struttura:

   CREATE TABLE chatters (
       id INTEGER PRIMARY KEY,
       name TEXT NOT NULL,
       messages INTEGER NOT NULL,
       last_message_at TEXT NOT NULL
   );
   

🎯 Utilizzo

Avvio del Server

python community_chat_server.py

Strumenti Disponibili

1. get_top_chatters(limit=10)

Recupera i top chatters della community.

# Esempio di utilizzo
top_chatters = get_top_chatters(5)
# Restituisce: [{"name": "Jordan", "messages": 469, "last_message_at": "2025-04-02 02:08:47"}, ...]

2. search_chatter(name)

Cerca un chatter specifico per nome.

# Esempio di utilizzo
chatter = search_chatter("Jordan")
# Restituisce: {"name": "Jordan", "messages": 469, "last_message_at": "2025-04-02 02:08:47"}

3. get_community_summary()

Ottiene statistiche generali della community.

# Esempio di utilizzo
summary = get_community_summary()
# Restituisce: {
#   "total_chatters": 100,
#   "total_messages": 12500,
#   "average_messages_per_chatter": 125.0,
#   "top_chatter": {"name": "Jordan", "messages": 469}
# }

4. chat_with_ai(message, include_community_context=False)

Chat con ChatGPT usando llama-index.

# Chat semplice
response = chat_with_ai("Ciao! Come va?")

# Chat con contesto della community
response = chat_with_ai(
    "Analizza l'attività della community", 
    include_community_context=True
)

5. analyze_community_trends()

Analisi AI completa dei trend della community.

# Esempio di utilizzo
analysis = analyze_community_trends()
# Restituisce analisi dettagliata basata sui dati

6. reset_chat_memory()

Resetta la memoria della chat per iniziare una nuova conversazione.

# Esempio di utilizzo
result = reset_chat_memory()
# Restituisce: {"message": "Memoria della chat resettata con successo"}

7. get_server_status()

Verifica lo status del server e delle sue componenti.

# Esempio di utilizzo
status = get_server_status()
# Restituisce info su database, OpenAI, etc.

🧪 Test

Esegui il client di test:

python test_client.py

📊 Struttura del Database

Il database community.db contiene i seguenti dati di esempio:

🔧 Configurazione Avanzata

Personalizzazione del LLM

Puoi modificare il modello ChatGPT nel file community_chat_server.py:

llm = OpenAI(
    model="gpt-4",  # Cambia a gpt-4 per maggiore capacità
    api_key=OPENAI_API_KEY,
    temperature=0.7,  # Controlla la creatività (0.0-1.0)
    max_tokens=1500   # Aumenta per risposte più lunghe
)

Memory Buffer

Personalizza la gestione della memoria:

memory = ChatMemoryBuffer.from_defaults(
    token_limit=5000  # Aumenta per conversazioni più lunghe
)

📝 Esempi di Conversazioni

Esempio 1: Analisi Community

User: Analizza l'attività della community e dimmi chi sono i membri più attivi
AI: [con contesto della community] Basandomi sui dati della community con 100 chatters e 12.500 messaggi totali, posso vedere che Jordan è il membro più attivo con 469 messaggi...

Esempio 2: Confronto Chatters

User: Confronta l'attività di Jordan e Taylor
AI: Jordan ha inviato 469 messaggi mentre Taylor ne ha inviati 429. Jordan è più attivo del 9.3% rispetto a Taylor...

Esempio 3: Raccomandazioni

User: Come possiamo migliorare l'engagement della community?
AI: [analizza i dati] Basandomi sulla distribuzione dei messaggi, suggerirei di...

🐛 Troubleshooting

Errore: "OPENAI_API_KEY non trovata"

• Verifica che il file .env contenga la tua API key valida
• Assicurati che il file .env sia nella stessa directory dello script

Errore: "Database non trovato"

• Verifica che community.db esista nella directory
• Controlla i permessi di lettura del file

Errore: "Nessuna risposta da OpenAI"

• Verifica la tua API key OpenAI
• Controlla di avere crediti sufficienti nel tuo account OpenAI
• Verifica la connessione internet

🔐 Sicurezza

• Non committare mai il file .env con la tua API key
• Usa variabili d'ambiente in produzione
• Limita l'accesso al database
• Monitora l'uso dell'API OpenAI per evitare costi eccessivi

📚 Documentazione Tecnica

Architettura

Community Chat Server
├── MCP Protocol Layer (FastMCP)
├── LLM Integration (llama-index + OpenAI)
├── Database Layer (SQLite)
└── Memory Management (ChatMemoryBuffer)

Flusso dei Dati

1. Request: Client MCP invia richiesta
2. Processing: Server elabora con strumenti appropriati
3. AI Integration: Se necessario, consulta ChatGPT via llama-index
4. Database Query: Recupera dati da SQLite se richiesto
5. Response: Restituisce risultato formattato

🤝 Contributi

Per contribuire al progetto:

1. Fai un fork del repository
2. Crea un branch per la tua feature
3. Implementa i cambiamenti
4. Testa accuratamente
5. Invia una pull request

📄 Licenza

Questo progetto è distribuito sotto licenza MIT. Vedi il file LICENSE per i dettagli.

📞 Supporto

Per supporto o domande:

• Apri un issue su GitHub
• Consulta la documentazione di llama-index
• Verifica la documentazione OpenAI API

Nota: Questo è un progetto di esempio. In produzione, considera ulteriori aspetti di sicurezza, scalabilità e monitoraggio.