Server MCP per Dolibarr con studio IA

Server MCP per Dolibarr con studio IA: 18 strumenti, 33 modelli, OAuth 2.1, applicazioni React, grafici ECharts e costruttore di moduli

Colleghi un assistente IA al suo Dolibarr — Claude, ChatGPT, Cursor, VS Code, o qualsiasi client che parli il Model Context Protocol — e lo lasci lavorare nei suoi dati come farebbe un collega a cui ha dato un account. Il modulo porta un server MCP completo (JSON-RPC 2.0 su HTTP in flusso, OAuth 2.1 con PKCE), 18 strumenti divisi fra lettura, scrittura, codice e costruzione, e 33 modelli di dati Dolibarr conosciuti a memoria, dal preventivo al pagamento. Poi uno studio per quello che l'assistente costruisce dopo: applicazioni web React, grafici ECharts, e interi moduli Dolibarr consegnati in zip. Il punto attorno a cui gira tutto: un assistente agisce a nome della persona che ha detto di sì, e non vede mai nulla di più di quanto vedrebbe lei. 

Per chi? Titolari che preferiscono fare una domanda ai propri numeri piuttosto che aprire dieci elenchi, contabili che inseguono gli insoluti, commerciali che seguono il proprio portafoglio, capi progetto, magazzinieri — e integratori che vogliono costruire quadri di controllo, portali clienti e moduli Dolibarr senza ripartire da una pagina bianca. Un assistente collegato, o venti: il principio non cambia.

Un server MCP completo dentro Dolibarr

• Protocollo MCP versione 2026-07-28, che risponde ancora alle versioni 2025-06-18, 2025-03-26 e 2024-11-05: i client di oggi e quelli di ieri si collegano senza cambiare nulla.
• JSON-RPC 2.0 su HTTP in flusso: initialize, ping, tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/read, le notifiche e le chiamate raggruppate.
• OAuth 2.1 con PKCE S256, indicatori di risorsa, iscrizione dinamica dei client (RFC 7591), descrizione del server (RFC 8414) e della risorsa (RFC 9728), restituzione dei token (RFC 7009).
• Una pagina di consenso scritta in chiaro: prima di dire di sì, la persona legge l'elenco degli strumenti che l'assistente potrà usare, quanti si limitano a leggere, quanti possono cambiare qualcosa, e che cosa resta vero comunque.
• Un token personale in un minuto per una postazione, senza tutta la cerimonia.
• I token sono custoditi solo come impronta SHA-256: una copia della base non consegna a nessuno un token funzionante.
• Codice di autorizzazione a uso unico: un secondo tentativo revoca tutti i token di quella coppia persona-client, e rende inutile un'intercettazione. Rinnovo per rotazione.
• HTTPS richiesto come impostazione di partenza, salvo dalla macchina stessa. Il modulo avverte da sé quando l'indirizzo che darebbe ai client non andrebbe bene.

Diciotto strumenti, in quattro famiglie

• Lettura (6 strumenti, accesi dall'inizio): get_context dice che cos'è questa installazione, list_models e get_model_schema descrivono ciò che è leggibile, search_read e read_record leggono, read_group somma per gruppi.
• Scrittura (4 strumenti, spenti dall'inizio): create_record, update_record, delete_record ed execute_method, che fa a un record quello che gli farebbe Dolibarr — validare un preventivo, approvare un ordine fornitore, chiudere un progetto.
• Codice e script (3 strumenti, spenti dall'inizio): code_search e code_read sulla cartella aperta dall'amministratore, execute_script per il piccolo linguaggio del modulo.
• Costruzione (5 strumenti, spenti dall'inizio): manage_webapp, create_chart, manage_module, search_webapp_code e search_module_code.
• Ogni strumento dichiara al client se si limita a leggere e se può distruggere, così l'assistente sa quando deve chiedere conferma.
• Uno strumento risponde solo se tre cose coincidono: è acceso, l'account ha il diritto Dolibarr corrispondente, e lo strumento gli è aperto. Accendere uno strumento non può quindi mai dare più di quanto Dolibarr abbia già dato.
• Un pulsante — « spegni tutto ciò che scrive » — riporta il server in sola lettura con un solo gesto.

Trentatré modelli di dati Dolibarr

• Vendite: soggetti terzi, contatti, proposte commerciali, ordini clienti, fatture clienti, righe di fattura, contratti, spedizioni.
• Acquisti: ordini e fatture fornitori. Denaro: pagamenti clienti e fornitori, movimenti bancari, conti, note spese, donazioni.
• Prodotti e magazzino: prodotti e servizi, movimenti, magazzini, giacenze. Progetti: progetti, attività, tempo impiegato.
• Persone: utenti, soci, ferie. Quotidiano: eventi, ticket, interventi. Fatto nello studio: applicazioni, grafici, moduli costruiti.
• Ogni modello è descritto in anticipo: la sua tabella, la sua chiave, la colonna di entità, le sue date, e i modi in cui sa essere raggruppato. Un nome di tabella scritto a mano non porta da nessuna parte.
• I modelli il cui modulo Dolibarr è spento presso di lei vengono messi da parte da soli: l'assistente vede solo ciò che esiste davvero.
• Raggruppare per data scrivendo datef:month, datef:quarter, datef:week… e i risultati tornano in ordine di tempo.
• Un raggruppamento su fk_soc restituisce il nome del cliente, non un numero di riga: il modulo riconosce le chiavi esterne che sa unire.
• Nove modelli restano in sola lettura comunque — pagamenti, movimenti bancari, movimenti di magazzino, tempo impiegato, righe di fattura, utenti — perché è lì che Dolibarr tiene una coerenza propria.

Un piccolo linguaggio in gabbia, mai PHP

• Odoo ha safe_eval; PHP non ha nulla di equivalente. Questo modulo ha quindi preso l'altra strada: porta con sé il proprio piccolo linguaggio. Nessun codice scritto da un assistente viene mai eseguito come PHP.
• Variabili, if/else, for … in, while, liste, tabelle, operatore ternario, indici negativi, commenti — e una settantina di funzioni su liste, testo, numeri, date e JSON.
• Lettura della base: db.select, db.first, db.count, db.group, db.fields, db.models, e db.sql in solo SELECT, con i segni {{prefix}} ed {{entity}} e un limite aggiunto d'ufficio.
• Niente import, niente file, niente shell, niente $, niente accenti gravi, niente eval: quelle parole sono rifiutate prima ancora che lo script cominci.
• Tre guardie insieme: un contatore di passi, un orologio, un limite di memoria. Un ciclo senza fine viene fermato dov'è, e Dolibarr continua.
• Nessuna colonna di password, chiave o token è leggibile, e otto tabelle intere sono chiuse a ogni richiesta scritta a mano.
• Il web è irraggiungibile se non quando un amministratore l'ha aperto e ha nominato gli host ammessi. Di partenza è chiuso.

Costruttore di applicazioni web React

• Un'applicazione React 19 custodita dentro Dolibarr: pagine in JSX, componenti riutilizzabili, punti d'accesso, stile e codice comuni, memoria sul server.
• Le pagine girano nel browser; quello che serve loro dalla base lo chiedono ai propri punti d'accesso, ognuno uno script che può solo leggere. La pagina resta libera quanto si vuole, la porta resta stretta.
• Una piccola libreria messa in mano a ogni pagina: Dolibarr.useCall (hook con loading, data, error), Dolibarr.call, Dolibarr.useRoute, Dolibarr.store, Dolibarr.money, Dolibarr.date, e React con i suoi hook.
• Un router in due modi, un menu costruito dalle pagine, e un foglio di stile fornito perché una pagina abbia un aspetto decente senza scrivere CSS.
• Una pagina che solleva un errore mentre si disegna non fa cadere l'applicazione: l'errore si vede dove qualcuno può leggerlo, il resto continua.
• Condivisione con collegamento a tempo, richiudibile in qualsiasi momento, e installazione su telefono a schermo intero.
• React e Babel vengono da un CDN configurabile, o da una copia locale posata nel modulo: un'installazione senza internet funziona per intero.

Costruttore di grafici ECharts

• Venti forme: barre, linea, linea piena, torta, anello, dispersione, radar, indicatore, imbuto, mappa di calore, mappa ad aree, raggiera, flusso, rete, scatola e baffi, candele, fiume, parallele, albero, barre figurate.
• Sei serie di colori e undici aggiunte: percorrere una serie lunga, colorare secondo il valore, cassetta degli attrezzi, linee e aree di riferimento, selezione, calendario, cronologia.
• Il disegno e i numeri restano separati: il disegno è JSON, incapace di fare alcunché da solo; i numeri vengono da uno script che sa solo leggere. Uniti all'apertura, sono sempre aggiornati.
• Il modulo accetta tre forme di risultato e riconosce quale ha ricevuto: un elenco di righe, una tabella di etichette e numeri, o più serie dichiarate.
• Un'opzione ECharts scritta a mano viene ripulita prima di essere custodita: una stringa che cerca di essere una funzione, un tag script, un indirizzo javascript vengono tolti.
• Condivisione con collegamento, i numeri in un pannello sotto il grafico, e aggiornamento automatico per posare un grafico su uno schermo in officina.
• ECharts viene da un CDN o da una copia locale, come React.

Costruttore di moduli Dolibarr

• Descriva un modulo — che cosa contiene, e che cosa ha ogni cosa — e lo studio scrive un modulo Dolibarr intero.
• Ne escono: il descrittore che Dolibarr legge, le tabelle SQL e i loro indici, le classi che estendono CommonObject, le pagine di elenco con ricerca, ordinamento e pagine, le schede con creazione, modifica e cancellazione, i menu, i file di lingua e il README.
• Quattordici generi di campo, quattro dei quali veri legami Dolibarr: un soggetto terzo, un utente, un progetto, un prodotto — con selettore in inserimento e collegamento cliccabile in lettura.
• Ogni oggetto riceve senza chiederlo un riferimento numerato, uno stato, una nota, l'autore, le date e la colonna di entità per il multi-azienda.
• Il codice che ne esce passa php -l, si installa come qualsiasi modulo esterno, crea le sue tabelle, dichiara i suoi diritti, e le sue pagine funzionano davvero: non è un plastico.
• Impacchettato in uno zip scaricabile, per guardare i file prima di installarli. La scrittura diretta nella cartella del codice esiste ma resta spenta di partenza.
• Il numero di modulo viene scelto in modo da non scontrarsi con nessun altro modulo dell'installazione.

Richieste già pronte e risorse

• Sei richieste già pronte: com'è andata la vendita, chi non ha pagato, come sta il magazzino, costruire un piccolo quadro, costruire un modulo, rispondere partendo dai dati.
• Una richiesta pronta è un testo con spazi vuoti che il client va a cercare per nome, riempie, e mette davanti al proprio modello: è il modo di dare a tutta la casa formule collaudate.
• Se ne scrivono altre con due campi: il testo con i suoi {{spazi}}, e l'elenco degli spazi con che cosa sono e se sono obbligatori.
• Quattro risorse offerte in lettura diretta: il contesto dell'installazione, il catalogo dei modelli, quello degli strumenti, e il codice di un'applicazione web.
• Il server consegna al client, già al primo scambio, brevi istruzioni: cominciare dal contesto, poi i modelli, prima di leggere qualsiasi cosa. Un assistente che le segue risponde bene al primo colpo.

Sicurezza: che cosa è possibile e che cosa no

• Non agisce mai se non a nome della persona che ha detto di sì. Ogni token porta un utente Dolibarr, ogni richiesta filtra sulla sua entità. Ciò che quell'account non raggiunge, l'assistente non lo raggiunge.
• Non esegue mai PHP scritto da un assistente.
• Non legge mai una colonna di password, chiave o token, qualunque cosa gli si chieda.
• Da uno script non esegue mai altro che un SELECT.
• Custodisce solo un'impronta di ogni token.
• Annota ogni chiamata: nulla di ciò che un assistente ha fatto resta invisibile dopo.
• Non scrive nulla nella cartella del codice finché un amministratore non l'ha permesso apposta.
• Il server è chiuso all'installazione, e quando lo si apre sono accesi solo i sei strumenti di lettura. Nulla risponde finché non ha deciso che qualcosa debba rispondere.

Amministrazione, diritti e restrizioni

• Otto diritti Dolibarr: leggere, collegare un assistente, costruire applicazioni, grafici, moduli, condividere con un collegamento, leggere il registro, cambiare le impostazioni.
• Le restrizioni tolgono qualcosa: un modello intero, o un campo preciso, in lettura, scrittura o cancellazione — per tutti o per persone e gruppi nominati.
• Un insieme prudente pronto in un clic: gli strumenti tenuti fuori dalla banca, dalle ferie e dalle note spese, e impediti di scrivere nei pagamenti e negli account utente.
• Ogni strumento si apre a tutti o a un elenco di persone e gruppi, indipendentemente dagli altri.
• I client si chiudono o si cancellano; i token si revocano uno a uno; e l'intero server si spegne con una sola impostazione. Tutti e tre hanno effetto subito.
• Una pagina chiavi di servizi custodisce le chiavi API cifrate e non ne mostra mai più degli ultimi quattro caratteri.
• Sette gruppi di impostazioni, ognuno spiegato in una frase, con i limiti che impediscono a una domanda distratta di diventare un Dolibarr lento.

Registro di ogni chiamata

• Ogni chiamata viene annotata: lo strumento, la persona, il client, che cosa è stato mandato, che cosa è tornato, quante righe, quanto tempo, da dove, e com'è finita — risposta, rifiutata o fallita.
• I parametri sono ripuliti prima di essere custoditi: ciò che sembra un segreto è sostituito da asterischi.
• Cinque numeri in cima, un piccolo diagramma delle chiamate per strumento, e un elenco filtrabile per strumento, esito, parola e numero di giorni.
• Il dettaglio di una chiamata mostra che cosa è stato mandato, formattato, e che cosa è tornato.
• Tre usi: capire che cosa la gente fa davvero, regolare le restrizioni partendo dai rifiuti, e rendere conto il giorno in cui qualcuno chiede.
• La manutenzione gira da sola: sfoltisce il registro, getta i token scaduti, chiude i collegamenti vecchi, dimentica le conversazioni abbandonate.

Informazioni tecniche

• Dolibarr 16 e superiore (provato su Dolibarr 23.0.4), PHP da 7.4 a 8.4, MySQL/MariaDB.
• Nessun modulo Dolibarr richiesto: il server legge ciò che è acceso presso di lei e mette da parte il resto.
• Estensioni PHP: JSON e mbstring, più zip per impacchettare un modulo costruito. Nessuna libreria esterna da installare sul server.
• React, Babel ed ECharts vengono da un CDN configurabile o da una copia locale posata nel modulo.
• 24 tabelle llx_mcps_*, un lavoro pianificato di manutenzione, e nulla cambiato nel cuore di Dolibarr.
• Multi-azienda: token, client, applicazioni, grafici, moduli, restrizioni e registro separati per entità.
• Cinque lingue: francese, inglese, italiano, tedesco, spagnolo.
• Consegnato con una documentazione PDF di 43 pagine. Licenza GPL v3. Edito da NEXT GESTION — www.nextgestion.com

Demo del modulo MCP Studio
Login : demo
Password : demo