Un server MCP leggero basato su stdio per operazioni locali sul file system — lettura, scrittura, modifica, ricerca, esecuzione per assistenti AI. Ottimizzato specialmente per Chatbox: bat-bypass per exec (CVE-2026-6130), codifica b64 per eliminare problemi di escaping, e regex multi-pattern per targeting preciso di blocchi di codice.
Server MCP a zero dipendenze per operazioni su file locali. 13 strumenti per il filesystem + 3 meta-strumenti per scoperta progressiva — niente SDK, niente framework, nessun npm install necessario.
Protocollo MCP: 2024-11-05 · Trasporto: stdio + Streamable HTTP · Runtime: Node.js ≥ 22.0.0
local-mcp.mjs — 595 righe, 13 strumenti, punto d'ingresso
lib/mcp-core.mjs — 229 righe, trasporto stdio + HTTP, 9 metodi MCP
lib/config.mjs — 31 righe, configurazione MCP_WORKSPACE/DATA con validazione
Totale: ~855 righe, zero dipendenze runtime.
| Strumento | Descrizione | Annotazione |
|---|---|---|
read | Legge il file con numeri di riga, troncamento opzionale head/tail | readOnlyHint |
search | Ricerca file per nome (glob) poi per contenuto (grep) | readOnlyHint |
ls | Elenco compatto della directory con stat lazy | readOnlyHint |
exec | Esecuzione comandi in streaming con supporto stdin e timeout | destructiveHint |
diff | Differenza tra due file o stringhe di testo (Myers O(ND)) | readOnlyHint |
copy | Copia file o directory | destructiveHint |
move | Sposta o rinomina file/directory | destructiveHint |
batch | Esegue più operazioni in sequenza; rollback atomico, riferimenti $prev | destructiveHint |
file | Unificato: lettura, scrittura, modifica, append, cancellazione, info, mkdir, spostamento | — |
block | Legge/sostituisce/inserisce/elimina blocchi di codice per intervallo o nome funzione | — |
bookmark | Alias di percorso persistenti (aggiungi/ottieni/elenca/elimina) | — |
grep | Formato compatto file:riga:contenuto con concorrenza adattiva | readOnlyHint |
watch | Osserva file/directory per modifiche; massimo 20 osservatori concorrenti | — |
| Strumento | Descrizione |
|---|---|
search_tools | Cerca strumenti disponibili per parola chiave — risparmia ~90% token rispetto all'elenco completo |
describe_tool | Ottiene lo schema completo di input per uno strumento specifico (caricato su richiesta) |
call_tool | Esegue qualsiasi strumento per nome con argomenti |
Invece di inviare tutti i 13 schemi strumento (~3.000 token) in ogni richiesta, la scoperta progressiva con questi 3 meta-strumenti li riduce a ~50 token — ~90% di risparmio di token.
| # | Ottimizzazione | Impatto |
|---|---|---|
| A | Lettura head/tail in streaming | streamHead() evita di leggere interi file. Log da 500MB: 3s → 5ms, memoria: 500MB → pochi KB |
| B | Stat lazy in ls | Chiama statSync solo quando sort=size. Directory con 1000 file: 50ms → 2ms |
| C | Concorrenza adattiva del grep | os.availableParallelism() (max 16, min 4) invece di 16 worker fissi |
| D | Sfratto cache LRU | LRU basato sull'ordine di inserimento della Map — i file piccoli più utilizzati non vengono più rimossi da file grandi freddi |
| E | Protezione byte del grep | MAX_GREP_TOTAL_MB=100 + MAX_GREP_FILES=1000 impediscono OOM |
| F | Notifica di progresso | Passaggio _meta.progressToken per la specifica MCP 2025 (TODO: eventi per esecuzioni lunghe) |
| Area | Dettaglio |
|---|---|
| Cache di lettura | Sfratto in base alla dimensione (max 50 elementi, 10 MB) + TTL 5s |
| Diff Myers | Algoritmo O(ND), usato da edit, block e diff |
| Punteggio ricerca | Prima corrispondenza per nome (nessun I/O), poi stat solo dei primi 50 candidati |
| Formato output | grep: file:riga:contenuto, ls: colonne compatte, read: numeri di riga + suggerimento di troncamento |
| Protocollo | Dispatch Map O(1), short-circuit per gestori sincroni |
# Zero install — no dependencies
node local-mcp.mjs
# With configuration
MCP_WORKSPACE=D:/projects node local-mcp.mjs
{
"mcpServers": {
"local-mcp": {
"command": "node",
"args": ["D:/path/to/local-mcp.mjs"],
"env": {
"MCP_WORKSPACE": "D:/projects"
}
}
}
}
node local-mcp.mjs --http
node local-mcp.mjs --http --port 3456
Supporta POST JSON-RPC 2.0, streaming SSE (Accept: text/event-stream), CORS e GET /tools.
node local-mcp.mjs --help # Mostra l'utilizzo e le variabili d'ambiente
node local-mcp.mjs --list-tools # Stampa gli strumenti disponibili ed esce
node local-mcp.mjs --http # Avvia la modalità HTTP
node local-mcp.mjs --http --port 3456
| Variabile | Predefinito | Descrizione |
|---|---|---|
MCP_WORKSPACE | process.cwd() | Directory di lavoro principale (confine di sicurezza) |
MCP_DATA | {WORKSPACE}/.mcp-data | Directory dati (segnalibri, file temporanei) |
MCP_DIR | {WORKSPACE} | Directory predefinita per comandi tree/ls |
MCP_PORT | 3100 | Porta del server HTTP (in modalità --http) |
MCP_READONLY | false | Impostare a true per bloccare tutte le operazioni di scrittura |
MCP_EXCLUDE | — | Directory extra da escludere dalla ricerca, separate da virgole |
MCP_WORKSPACE e sottodirectory__proto__/constructor/prototype).gitignore e directory di esclusione comuni (node_modules, .git, ecc.)Zero dipendenze runtime. Utilizza solo i moduli built-in di Node.js:
| Modulo | Scopo |
|---|---|
fs | Filesystem + glob (Node 22) |
child_process | Esecuzione shell in streaming |
http | Trasporto HTTP (nessun Express necessario) |
path | Risoluzione percorsi |
os | availableParallelism() per concorrenza adattiva |
readline | Elaborazione riga per riga in streaming |
availableParallelism()streamHead — done definita fuori dal callback Promise# Run tests
node --test test/*.test.mjs
# Adding a tool
# 1. Define schema + handler in local-mcp.mjs
# 2. Register with server.tool()
# 3. Add tests
MIT