Un serveur MCP léger basé sur stdio pour les opérations sur le système de fichiers local — read, write, edit, search, exec pour les assistants IA. Spécialement optimisé pour Chatbox : bat-bypass pour exec (CVE-2026-6130), encodage b64 pour éliminer les problèmes d'échappement, et regex multi-motifs pour un ciblage précis des blocs de code.
Serveur MCP zéro dépendance pour les opérations sur fichiers locaux. 13 outils de système de fichiers + 3 méta-outils pour la découverte progressive — pas de SDK, pas de framework, pas de npm install nécessaire.
Protocole MCP : 2024-11-05 · Transport : stdio + HTTP streamable · Runtime : Node.js ≥ 22.0.0
local-mcp.mjs — 595 lines, 13 tools, entry point
lib/mcp-core.mjs — 229 lines, stdio + HTTP transport, 9 MCP methods
lib/config.mjs — 31 lines, MCP_WORKSPACE/DATA env config with validation
Total : ~855 lignes, zéro dépendance d'exécution.
| Outil | Description | Annotation |
|---|---|---|
read | Lit un fichier avec numéros de ligne, troncature facultative head/tail | readOnlyHint |
search | Recherche de fichiers par nom (glob) puis par contenu (grep) | readOnlyHint |
ls | Listage compact de répertoire avec stat paresseux | readOnlyHint |
exec | Exécution de commande en streaming avec prise en charge de stdin et délai d'attente | destructiveHint |
diff | Diff de deux fichiers ou chaînes de texte (Myers O(ND)) | readOnlyHint |
copy | Copie un fichier ou un répertoire | destructiveHint |
move | Déplace ou renomme un fichier/répertoire | destructiveHint |
batch | Exécute plusieurs opérations séquentiellement ; rollback atomique, références $prev | destructiveHint |
file | Unifié : lecture, écriture, édition, ajout, suppression, info, mkdir, déplacement | — |
block | Lire/remplacer/insérer/supprimer des blocs de code par plage ou nom de fonction | — |
bookmark | Alias de chemins persistants (ajouter/obtenir/lister/supprimer) | — |
grep | Format compact file:line:content avec concurrence adaptative | readOnlyHint |
watch | Surveille un fichier/répertoire pour les modifications ; max 20 observateurs simultanés | — |
| Outil | Description |
|---|---|
search_tools | Recherche des outils disponibles par mot-clé — économise ~90 % de jetons par rapport à la liste complète |
describe_tool | Obtient le schéma d'entrée complet d'un outil spécifique (chargé à la demande) |
call_tool | Exécute n'importe quel outil par nom avec des arguments |
Au lieu d'envoyer les 13 schémas d'outils (~3 000 jetons) dans chaque requête, la découverte progressive avec ces 3 méta-outils la réduit à ~50 jetons — ~90 % d'économies de jetons.
| # | Optimisation | Impact |
|---|---|---|
| A | Lecture head/tail en streaming | streamHead() évite de lire des fichiers entiers. Journaux de 500 Mo : 3 s → 5 ms, mémoire : 500 Mo → quelques Ko |
| B | Stat paresseux dans ls | N'appelle statSync que lorsque sort=size. Répertoire de 1000 fichiers : 50 ms → 2 ms |
| C | Concurrence adaptative de grep | os.availableParallelism() (max 16, min 4) au lieu de 16 travailleurs codés en dur |
| D | Éviction de cache LRU | Carte LRU par ordre d'insertion — les petits fichiers fréquents ne sont plus éliminés par les gros fichiers froids |
| E | Protection en octets de grep | Les garde-fous MAX_GREP_TOTAL_MB=100 + MAX_GREP_FILES=1000 empêchent les OOM |
| F | Notification de progression | Transmission de _meta.progressToken pour la spec MCP 2025 (TODO : événements pour les exec longues) |
| Domaine | Détail |
|---|---|
| Cache de lecture | Éviction tenant compte de la taille (max 50 éléments, 10 Mo) + TTL de 5 s |
| Diff Myers | Algorithme O(ND), utilisé par edit, block et diff |
| Score de recherche | Correspondance de nom d'abord (sans I/O), puis stat seulement pour les 50 meilleurs candidats |
| Format de sortie | grep : file:line:content, ls : colonnes compactes, read : numéros de ligne + indication de troncature |
| Protocole | Répartition O(1) par Map, court-circuit du gestionnaire synchrone |
# 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
Prend en charge JSON-RPC 2.0 POST, streaming SSE (Accept: text/event-stream), CORS et GET /tools.
node local-mcp.mjs --help # Show usage + env vars
node local-mcp.mjs --list-tools # Print available tools and exit
node local-mcp.mjs --http # Start HTTP mode
node local-mcp.mjs --http --port 3456
| Variable | Défaut | Description |
|---|---|---|
MCP_WORKSPACE | process.cwd() | Racine du répertoire de travail (frontière de sécurité) |
MCP_DATA | {WORKSPACE}/.mcp-data | Répertoire de données (signets, fichiers temporaires) |
MCP_DIR | {WORKSPACE} | Répertoire par défaut pour les commandes tree/ls |
MCP_PORT | 3100 | Port du serveur HTTP (avec --http) |
MCP_READONLY | false | Définir sur true pour bloquer toutes les opérations d'écriture |
MCP_EXCLUDE | — | Répertoires supplémentaires exclus de la recherche, séparés par des virgules |
MCP_WORKSPACE et ses sous-répertoires__proto__/constructor/prototype).gitignore et les répertoires d'exclusion courants (node_modules, .git, etc.) sont respectésZéro dépendance d'exécution. Utilise uniquement les modules intégrés de Node.js :
| Module | Rôle |
|---|---|
fs | Système de fichiers + glob (Node 22) |
child_process | Exécution shell en streaming |
http | Transport HTTP (pas besoin d'Express) |
path | Résolution de chemins |
os | availableParallelism() pour la concurrence adaptative |
readline | Traitement en streaming ligne par ligne |
availableParallelism()streamHead — done défini à l'extérieur du callback de la 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