Ein leichtgewichtiger stdio-basierter MCP-Server für lokale Dateisystemoperationen – Lesen, Schreiben, Bearbeiten, Suchen, Ausführen für KI-Assistenten. Speziell für Chatbox optimiert: bat-Bypass für exec (CVE-2026-6130), b64-Kodierung zur Beseitigung von Escaping-Problemen und Multi-Pattern-Regex für präzises Codeblock-Targeting.
Zero-dependency MCP-Server für lokale Dateioperationen. 13 Dateisystem-Tools + 3 Meta-Tools für progressive Entdeckung — keine SDKs, keine Frameworks, kein npm install erforderlich.
MCP-Protokoll: 2024-11-05 · Transport: stdio + Streamable HTTP · Laufzeit: 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
Insgesamt: ~855 Zeilen, null Laufzeitabhängigkeiten.
| Tool | Beschreibung | Annotation |
|---|---|---|
read | Datei mit Zeilennummern lesen, optionales Kürzen mittels head/tail | readOnlyHint |
search | Dateisuche nach Name (Glob) dann Inhalt (grep) | readOnlyHint |
ls | Kompakte Verzeichnisauflistung mit verzögerter Statusabfrage | readOnlyHint |
exec | Streaming-Befehlsausführung mit stdin-Unterstützung und Zeitüberschreitung | destructiveHint |
diff | Diff zweier Dateien oder Textstrings (Myers O(ND)) | readOnlyHint |
copy | Datei oder Verzeichnis kopieren | destructiveHint |
move | Datei/Verzeichnis verschieben oder umbenennen | destructiveHint |
batch | Mehrere Operationen sequenziell ausführen; atomares Rollback, $prev-Referenzen | destructiveHint |
file | Vereinheitlicht: lesen, schreiben, bearbeiten, anhängen, löschen, info, mkdir, verschieben | — |
block | Codeblöcke nach Bereich oder Funktionsname lesen/ersetzen/einfügen/löschen | — |
bookmark | Dauerhafte Pfad-Aliase (hinzufügen/abrufen/auflisten/löschen) | — |
grep | Kompaktes Datei:Zeile:Inhalt-Format mit adaptiver Nebenläufigkeit | readOnlyHint |
watch | Datei/Verzeichnis auf Änderungen überwachen; max. 20 gleichzeitige Überwachungen | — |
| Tool | Beschreibung |
|---|---|
search_tools | Verfügbare Werkzeuge nach Stichwort durchsuchen — spart ~90% Tokens im Vergleich zur Auflistung aller |
describe_tool | Vollständiges Eingabeschema für ein bestimmtes Werkzeug abrufen (bei Bedarf geladen) |
call_tool | Jedes Werkzeug nach Name mit Argumenten ausführen |
Anstatt alle 13 Werkzeugschemata (~3.000 Tokens) in jeder Anfrage zu senden, reduziert die progressive Entdeckung mit diesen 3 Meta-Tools dies auf ~50 Tokens — ~90% Token-Ersparnis.
| # | Optimierung | Auswirkung |
|---|---|---|
| A | Stream-Kopf/Ende-Lesen | streamHead() vermeidet das Lesen ganzer Dateien. 500MB Logs: 3s → 5ms, Speicher: 500MB → wenige KB |
| B | Verzögerte Statusabfrage in ls | Ruft statSync nur bei sort=size auf. 1000-Dateien-Verzeichnis: 50ms → 2ms |
| C | Adaptive grep-Nebenläufigkeit | os.availableParallelism() (max 16, min 4) anstelle von hartcodierten 16 Workern |
| D | LRU-Cache-Verdrängung | Map-Einfügereihenfolge LRU — heiße kleine Dateien werden nicht mehr durch kalte große Dateien verdrängt |
| E | Grep-Byte-Schutz | MAX_GREP_TOTAL_MB=100 + MAX_GREP_FILES=1000 Schutz verhindert OOM |
| F | Fortschrittsbenachrichtigung | _meta.progressToken Durchleitung für MCP 2025 Spezifikation (TODO: Ereignisse für lange Ausführung) |
| Bereich | Detail |
|---|---|
| Lese-Cache | Größenbewusste Verdrängung (max 50 Elemente, 10 MB) + 5s TTL |
| Myers-Diff | O(ND)-Algorithmus, verwendet von edit, block und diff |
| Suchbewertung | Zuerst Namensabgleich (kein I/O), dann Statusabfrage nur der Top 50 Kandidaten |
| Ausgabeformat | grep: Datei:Zeile:Inhalt, ls: kompakte Spalten, read: Zeilennummern + Kürzungshinweis |
| Protokoll | O(1) Map-Dispatch, Kurzschluss für synchrone Handler |
# 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
Unterstützt JSON-RPC 2.0 POST, SSE-Streaming (Accept: text/event-stream), CORS und 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 | Standard | Beschreibung |
|---|---|---|
MCP_WORKSPACE | process.cwd() | Arbeitsverzeichnis-Root (Sicherheitsgrenze) |
MCP_DATA | {WORKSPACE}/.mcp-data | Datenverzeichnis (Lesezeichen, temporäre Dateien) |
MCP_DIR | {WORKSPACE} | Standardverzeichnis für tree/ls-Befehle |
MCP_PORT | 3100 | HTTP-Server-Port (bei Verwendung von --http) |
MCP_READONLY | false | Auf true setzen, um alle Schreiboperationen zu blockieren |
MCP_EXCLUDE | — | Kommagetrennte zusätzliche Verzeichnisse, die von der Suche ausgeschlossen werden sollen |
MCP_WORKSPACE und Unterverzeichnisse beschränkt__proto__/constructor/prototype-Injektion).gitignore und übliche Ausschlussverzeichnisse (node_modules, .git, etc.) werden respektiertNull Laufzeitabhängigkeiten. Verwendet nur Node.js-Built-ins:
| Modul | Zweck |
|---|---|
fs | Dateisystem + glob (Node 22) |
child_process | Streaming-Shell-Ausführung |
http | HTTP-Transport (kein Express nötig) |
path | Pfadauflösung |
os | availableParallelism() für adaptive Nebenläufigkeit |
readline | Streaming-zeilenweise Verarbeitung |
availableParallelism()streamHead-Gültigkeitsbereichsfehler — done außerhalb von Promise-Callback definiert# 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