mcplocal

Lokaler Datei-MCP-Server, der einem MCP-fähigen Client (einschließlich benutzerdefinierter MCP-Apps für ChatGPT Web, sofern verfügbar) das Lesen, Durchsuchen und Ändern von Dateien in einem explizit konfigurierten Verzeichnis ermöglicht.

Features

• Legacy-HTTP+SSE: GET /sse + POST /messages

• Moderner MCP-HTTP-Endpunkt: /mcp

• Health-Check: /health

• Sandbox: Jeder Dateipfad wird unterhalb von MCP_ROOT aufgelöst

• Optionale Bearer-Authentifizierung

• Lese-/Suchwerkzeuge für die Projektentdeckung

• Schreib-/Bearbeitungswerkzeuge für Codierungs-Workflows

• Löschen ist standardmäßig deaktiviert

• Kein Shell-/CLI-Ausführungswerkzeug

• Keine Abhängigkeit von einer externen Datenbank

• Node.js 20+

Das MCP TypeScript SDK empfiehlt derzeit Streamable HTTP für entfernte Server und behandelt HTTP+SSE als Transport für Abwärtskompatibilität. Dieses Projekt stellt absichtlich beides bereit, damit ältere SSE-Clients weiterhin eine Verbindung herstellen können und neuere Clients /mcp verwenden können.

Related MCP server: FilesystemMCP

1. Ausführen

cp .env.example .env
# edit MCP_ROOT if needed
npm start

Beispiel:

MCP_ROOT=~/Projects
MCP_HOST=127.0.0.1
MCP_PORT=8008
MCP_AUTH_TOKEN=change-me

Dann:

SSE:        http://127.0.0.1:8008/sse
Streamable: http://127.0.0.1:8008/mcp
Health:     http://127.0.0.1:8008/health

2. Womit ChatGPT Web eine Verbindung herstellen kann

ChatGPT Web kann von dem gehosteten Dienst aus nicht direkt auf localhost zugreifen. Ein lokaler MCP-Server muss über den unterstützten Secure MCP Tunnel/Private-Network-Mechanismus erreichbar gemacht werden. Sobald du einen entfernten MCP-Endpunkt hast, füge ihn als benutzerdefinierte MCP-App im ChatGPT-Entwicklermodus hinzu, scanne dessen Tools und aktiviere ihn.

Für einen Tunnel, der den lokalen Dienst abbildet, ist die lokale Origin:

http://127.0.0.1:8008/sse

oder, für moderne Clients:

http://127.0.0.1:8008/mcp

Setze diesen Server nicht ohne Authentifizierung und eine explizite Netzwerkrichtlinie dem öffentlichen Internet aus.

3. Für ChatGPT verwendbare Tools

• list_files(path, recursive)

• read_file(path, startLine, endLine)

• write_file(path, content, createDirs)

• edit_file(path, oldText, newText, replaceAll)

• search_files(query, path, regex, caseSensitive, maxResults)

• create_directory(path)

• file_info(path)

• delete_file(path) dient ausschließlich, wenn MCP_ENABLE_DELETE=true

Typischer Codierungs-Workflow:

1. list_files, um das Projekt zu verstehen.

2. search_files, um Symbole zu lokalisieren.

3. read_file, um den relevanten Code zu untersuchen.

4. edit_file für eine chirurgische Änderung oder write_file für eine neue Datei.

5. read_file erneut, um das Ergebnis zu prüfen.

4. Sicherheitsmodell

MCP_ROOT ist die feste Grenze. ../-Traversierungsversuche und absolute Pfade außerhalb davon werden abgelehnt. Binäre/unlesbare Dateien werden bei der Suche übersprungen. Die Dateigröße wird durch MCP_MAX_FILE_BYTES begrenzt.

Der Server stellt absichtlich keine beliebige Shell-Ausführung bereit. Das bedeutet, ChatGPT kann Code bearbeiten, aber nicht automatisch rm, curl, Paketmanager, Git-Befehle oder beliebige Programme über diesen MCP ausführen.

Auf einem Entwicklungsrechner sollten Sie MCP_HOST=127.0.0.1 beibehalten und den unterstützten Secure MCP Tunnel verwenden, statt den Server an allen Schnittstellen zu binden.

5. Build

npm run build
node dist/server.js

Der Build ist abhängigkeitsfrei und kopiert die Laufzeit nach dist/.

6. Docker

docker build -t mcplocal .
docker run --rm -p 8008:8008 -v "$PWD:/workspace" mcplocal

7. Beispiel-Prompts in ChatGPT

Inspect this local project and tell me where the authentication flow is implemented. Do not modify anything.

Open src/server.js and refactor the error handling. Before changing it, read the relevant code. Then edit only the necessary section and show me what changed.

Search the project for TODO comments and create a report at reports/todos.md.

Lizenz

MIT