local-mcp

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

Architektur

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.

Werkzeuge

Dateisystem-Werkzeuge (13)

Meta-Tools (3) — Progressive Entdeckung

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.

Leistungsoptimierungen (v1.1.1)

Zusätzliche Optimierungen

Erste Schritte

# Zero install — no dependencies
node local-mcp.mjs

# With configuration
MCP_WORKSPACE=D:/projects node local-mcp.mjs

stdio-Modus (Standard)

{
  "mcpServers": {
    "local-mcp": {
      "command": "node",
      "args": ["D:/path/to/local-mcp.mjs"],
      "env": {
        "MCP_WORKSPACE": "D:/projects"
      }
    }
  }
}

HTTP-Modus

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.

CLI-Flags

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

Konfiguration

Sicherheit

• Alle Dateioperationen auf MCP_WORKSPACE und Unterverzeichnisse beschränkt
• Prototyp-sichere Lesezeichenschlüssel (blockiert __proto__/constructor/prototype-Injektion)
• Atomare Schreibvorgänge (temp + umbenennen) verhindern partielle Dateischreibvorgänge
• Binärdateierkennung verhindert das Lesen von Nicht-Text-Dateien
• .gitignore und übliche Ausschlussverzeichnisse (node_modules, .git, etc.) werden respektiert

Abhängigkeiten

Null Laufzeitabhängigkeiten. Verwendet nur Node.js-Built-ins:

Änderungsprotokoll

v1.1.1 — Leistungsoptimierungen

• A. Stream-Kopf/Ende-Lesen: 500MB Logs 3s → 5ms
• B. Verzögerte Statusabfrage in ls: 1000-Dateien-Verzeichnis 50ms → 2ms
• C. Adaptive grep-Nebenläufigkeit mit availableParallelism()
• D. LRU-Cache-Verdrängung via Map-Einfügereihenfolge
• E. Grep-Byte-Schutz (100MB / 1000 Dateien)
• F. Fortschrittsbenachrichtigungsdurchleitung für MCP 2025 Spezifikation
• Fix: streamHead-Gültigkeitsbereichsfehler — done außerhalb von Promise-Callback definiert

v1.1.0

• 13 Dateisystemwerkzeuge + 3 Meta-Werkzeuge für progressive Entdeckung
• stdio + Streamable HTTP-Transport
• Myers-Diff-Engine, Lese-Cache, Streaming-Ausführung
• Umgebungsbasierte Konfiguration mit Validierung

Entwicklung

# 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

Mitwirken

1. Null-Abhängigkeits-Beschränkung beibehalten
2. Tests für neue Funktionalität hinzufügen
3. Optimierungstabelle für Leistungsänderungen aktualisieren

Lizenz

MIT