MCP: Come Claude Interagisce Intelligentemente con i Tuoi File Locali.

Il Model Context Protocol (MCP) offre un framework sicuro per consentire alle applicazioni di interagire con i filesystem tramite operazioni sandboxed. Questa guida spiega come funziona MCP, le sue caratteristiche principali e illustra un esempio pratico utilizzando il MCP Filesystem Server.

Cos’è il Model Context Protocol (MCP)?

Il Model Context Protocol (MCP) è un potente framework di sicurezza progettato per abilitare interazioni controllate tra applicazioni (come assistenti AI) e sistemi esterni, in particolare i filesystem. Agendo come un ponte sicuro, MCP consente agli strumenti di eseguire operazioni come la lettura, la scrittura o la ricerca di file in un ambiente sandboxed guidato dai permessi.

Il protocollo è particolarmente prezioso per gli sviluppatori che desiderano integrare operazioni sul filesystem in applicazioni come VS Code, Claude Desktop o altri ambienti di sviluppo, mantenendo confini di sicurezza robusti.

Caratteristiche Principali di MCP

• Operazioni Sandboxed: Tutte le attività avvengono all’interno di directory predefinite, proteggendo le aree sensibili del tuo filesystem.
• API Standardizzata: Un set coerente di strumenti (read_file, write_file, ecc.) accessibile tramite un’interfaccia unificata.
• Design Sicurezza-centrico: Operazioni limitate alle directory consentite con funzionalità come i mount in sola lettura.
• Integrazione Flessibile: Compatibile con vari ambienti inclusi Docker, NPX, VS Code e Claude Desktop.

Il MCP Filesystem Server Spiegato

Il MCP Filesystem Server è un’implementazione Node.js costruita specificamente per operazioni sul filesystem all’interno del framework Model Context Protocol. Fornisce un set completo di strumenti per interagire con file e directory in modo controllato.

Strumenti Disponibili nel MCP Filesystem Server

Ecco una panoramica delle funzionalità principali:

• read_file: Legge i contenuti di un file usando la codifica UTF-8
• read_multiple_files: Elabora più file contemporaneamente, continuando nonostante i fallimenti individuali
• write_file: Crea nuovi file o sovrascrive quelli esistenti
• edit_file: Permette modifiche selettive con pattern matching, inclusi dry run e output diff in stile Git
• create_directory: Crea directory con opzione di creazione delle directory genitrici
• list_directory: Mostra i contenuti della directory con prefissi chiari [FILE] o [DIR]
• move_file: Sposta o rinomina file e directory
• search_files: Cerca ricorsivamente corrispondenze supportando pattern di esclusione
• get_file_info: Recupera i metadati inclusi dimensione, data creazione e permessi
• list_allowed_directories: Visualizza tutte le directory accessibili per trasparenza

Tutti questi strumenti sono accessibili tramite la risorsa file://system, che funge da interfaccia per le operazioni filesystem MCP.

Utilizzare MCP con Claude

Per illustrare come funziona MCP nella pratica, vediamo un esempio reale di utilizzo del MCP Filesystem Server con Claude, un assistente AI, per eseguire operazioni comuni sul filesystem.

Passo 1: Elenco delle Directory Consentite

Il primo passo è stato determinare quali directory Claude potesse accedere. Abbiamo utilizzato lo strumento list_allowed_directories, che ha mostrato due posizioni autorizzate:

• /Users/arshia/Desktop
• /Users/arshia/Downloads

Questo ha confermato che le operazioni di Claude erano limitate solo a queste directory, mantenendo il resto del filesystem sicuro.

Passo 2: Esplorazione dei Contenuti delle Directory

Successivamente, abbiamo usato lo strumento list_directory per vedere quali file fossero disponibili. I risultati mostravano:

Per /Users/arshia/Desktop:

• [FILE] DS_Store
• [FILE] localized

Per /Users/arshia/Downloads:

• [FILE] DS_Store
• [FILE] localized
• [DIR] Visual Studio Code.app
• [FILE] shrek.txt
• [FILE] claudes diary.pages
• [FILE] diary.pdf

Questo ha rivelato la presenza di un file chiamato shrek.txt nella directory Downloads, insieme ad altri file e a una directory per Visual Studio Code.

Screenshot che mostra le richieste e risposte list_directory per le directory Desktop e Downloads

Passo 3: Tentativo di Lettura di un File

Identificato shrek.txt, abbiamo tentato di leggerne il contenuto utilizzando lo strumento read_file. Inizialmente, abbiamo fornito solo il nome del file shrek.txt, presumendo che lo strumento cercasse nelle directory consentite.

Questo ha prodotto un errore:
“Accesso negato – percorso fuori dalle directory consentite: /shrek.txt non è in /Users/arshia/Desktop, /Users/arshia/Downloads.”
L’errore si è verificato perché MCP richiede percorsi file completi per motivi di sicurezza.

Immagine 2: Screenshot che mostra il tentativo fallito di read_file con il messaggio di errore

Passo 4: Lettura del File Riuscita

Correggendo l’approccio, abbiamo fornito il percorso completo /Users/arshia/Downloads/shrek.txt allo strumento read_file. Questa volta, l’operazione è riuscita, restituendo il contenuto del file:

Request
{
  `path`: `/Users/arshia/Downloads/shrek.txt`
}
Response

Can you see what im writing here? If you do check this out: 

⢀⡴⠑⡄⠀⠀⠀⠀⠀⠀⠀⣀⣀⣤⣤⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠸⡇⠀⠿⡀⠀⠀⠀⣀⡴⢿⣿⣿⣿⣿⣿⣿⣿⣷⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠑⢄⣠⠾⠁⣀⣄⡈⠙⣿⣿⣿⣿⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⢀⡀⠁⠀⠀⠈⠙⠛⠂⠈⣿⣿⣿⣿⣿⠿⡿⢿⣆⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⢀⡾⣁⣀⠀⠴⠂⠙⣗⡀⠀⢻⣿⣿⠭⢤⣴⣦⣤⣹⠀⠀⠀⢀⢴⣶⣆ 
⠀⠀⢀⣾⣿⣿⣿⣷⣮⣽⣾⣿⣥⣴⣿⣿⡿⢂⠔⢚⡿⢿⣿⣦⣴⣾⠁⠸⣼⡿ 
⠀⢀⡞⠁⠙⠻⠿⠟⠉⠀⠛⢹⣿⣿⣿⣿⣿⣌⢤⣼⣿⣾⣿⡟⠉⠀⠀⠀⠀⠀ 
⠀⣾⣷⣶⠇⠀⠀⣤⣄⣀⡀⠈⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠉⠈⠉⠀⠀⢦⡈⢻⣿⣿⣿⣶⣶⣶⣶⣤⣽⡹⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⠉⠲⣽⡻⢿⣿⣿⣿⣿⣿⣿⣷⣜⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣷⣶⣮⣭⣽⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⣀⣀⣈⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠻⠿⠿⠿⠿⠛⠉

Shrek

• Una domanda che chiede se il lettore riesce a vedere cosa viene scritto
• Arte ASCII che raffigura il volto di Shrek
• Il testo “Shrek” alla fine

L’operazione riuscita ha confermato che MCP può leggere file quando viene fornito il percorso corretto all’interno delle directory consentite.

Lezioni Chiave dal Nostro Esempio

Questo walkthrough pratico evidenzia diversi aspetti importanti dell’utilizzo di MCP:

1. Sono Richiesti Percorsi Completi: Strumenti come read_file necessitano di percorsi file completi, non solo dei nomi file.
2. Il Sandboxing è Efficace: Il fallimento iniziale ha dimostrato che il modello di sicurezza di MCP funziona come progettato.
3. L’Esplorazione Iterativa è la Migliore: Utilizzare strumenti di elenco directory aiuta a navigare correttamente nel filesystem.

Migliori Pratiche per l’Implementazione MCP

Sulla base della nostra esperienza e delle funzionalità del MCP Filesystem Server, raccomandiamo queste best practice:

• Controlla Sempre Prima i Permessi: Usa list_allowed_directories prima di eseguire operazioni.
• Usa Percorsi File Completi: Fornisci percorsi completi per evitare errori e ambiguità.
• Testa le Modifiche in Modalità Dry Run: Quando usi edit_file, visualizza in anteprima le modifiche con dryRun: true prima di applicarle.
• Pianifica Successi Parziali: Strumenti come read_multiple_files continuano nonostante i fallimenti su singoli file.
• Applica il Principio del Minimo Privilegio: Quando configuri il server, usa mount in sola lettura per directory che non devono essere modificate.

Conclusione

Il Model Context Protocol (MCP) e il suo Filesystem Server offrono un approccio robusto e sicuro alle operazioni sul filesystem in ambienti controllati. Il nostro esempio con Claude mostra l’utilizzo pratico di strumenti come list_directory e read_file, evidenziando principi importanti come l’uso di percorsi completi e la comprensione dei confini dei permessi.

Seguendo le best practice qui descritte, puoi sfruttare al meglio MCP per integrare in sicurezza operazioni filesystem nelle tue applicazioni o nei tuoi workflow di sviluppo.

Per gli sviluppatori che desiderano implementare MCP nei propri progetti, la documentazione ufficiale su GitHub offre dettagli completi e guide all’implementazione.