backoffice-agent-mcp

Agente AI di back-office per un'ipotetica piattaforma di ticketing online, realizzato come Project Work (traccia n. 26, CdS Informatica per le Aziende Digitali L-31, Università Pegaso): un server MCP espone le funzioni del sistema informativo come tool, e un harness agentico scritto a mano governa il ciclo del modello linguistico.

Tutti i dati sono sintetici. Il sistema è generico e non riproduce schemi, API o regole di sistemi aziendali reali.

Componenti

• backend/: base dati SQLite (schema.sql), generatore di dati sintetici (seed.py) e funzioni di accesso ai dati (repository/)

• mcp_server/: server MCP con sette tool (quattro di lettura, tre di scrittura), uno per file in tools/

• harness/: ciclo agentico (agent_loop.py), astrazione del modello (llm/, interfaccia LLMProvider con Ollama e API compatibile OpenAI), conferma umana sulle scritture (conferma.py), log JSON Lines (registro.py), client MCP, interfaccia web (web/) e CLI

• tests/: test automatici (modello finto, server MCP vero)

• docs/: diagrammi e documentazione

Related MCP server: humanitix-mcp

Requisiti

• Python 3.13

• Ollama con un modello che supporti la chiamata di tool (provato: qwen2.5:7b)

Installazione

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements-dev.txt
copy .env.example .env
ollama pull qwen2.5:7b
python backend/seed.py

seed.py crea backend/ticketing.db con dati sintetici sempre identici (seme fisso).

Esecuzione

Interfaccia web (avvia da sola il server MCP come processo figlio), poi apri http://127.0.0.1:8000 nel browser:

python -m harness.web

La pagina mostra in tempo reale i passi dell'agente e, accanto alla chat, un pannello di sola lettura con tre schede (eventi, movimenti, registro delle modifiche) per controllare i dati e vedere l'effetto di ogni modifica. Quando l'agente vuole modificare i dati compare una scheda con tool e parametri e l'esecuzione resta ferma finché non premi Conferma o Rifiuta. Il server ascolta solo su 127.0.0.1 (porta modificabile con WEB_PORT) e rifiuta richieste provenienti da altri siti.

In alternativa, chat nel terminale:

python -m harness.cli

Esempi di richieste (valgono per entrambe le interfacce): «quanti posti restano per la Rassegna Rock Club?», «quanti eventi ha comprato Daniele Esposito?», «chiudi le vendite della Serata Cabaret». Prima di ogni modifica ai dati l'agente chiede conferma e mostra tool e parametri. Ogni sessione scrive un log strutturato in logs/*.jsonl.

Il server MCP si può avviare anche da solo, per usarlo con altri client MCP:

python -m mcp_server

Configurazione

Tutto in .env (vedi .env.example). Per cambiare modello basta OLLAMA_MODEL; per usare un altro server compatibile OpenAI, LLM_PROVIDER=openai_compat e OPENAI_BASE_URL. Il codice non cambia.

Controlli dell'harness sulle scritture

Prima di chiedere la conferma per un tool di scrittura l'harness (1) verifica che gli id usati siano stati scritti dall'operatore o letti dai tool, e non inventati dal modello, e (2) chiede al server un'anteprima dell'azione: se le regole la vietano l'operatore non viene disturbato, altrimenti la scheda di conferma mostra che cosa succederà davvero (nomi, numeri, importi). Si possono disattivare con CONTROLLI_HARNESS=0. L'anteprima usa il tool di servizio anteprima_azione del server MCP, che l'harness non mostra al modello.

Test

python -m pytest

I test non richiedono Ollama: usano un modello finto con risposte preparate e il vero server MCP su una copia del database.

Scenari di test

I 18 scenari funzionali (richiesta, esito atteso, esito ottenuto) sono descritti in tests/scenarios/scenari.md e i risultati, con il confronto tra due versioni del prompt, in tests/scenarios/risultati.md. Log e screenshot di ogni esecuzione sono in logs/scenari/ e docs/screenshots/scenari/.

Stato

Work in progress.

Licenza

MIT, vedi LICENSE.