local-code-agent

Ein lokaler MCP-Server, entwickelt mit FastMCP: Ermöglicht externen KI-Systemen (ChatGPT, Claude usw.) die Fernsteuerung des lokalen Arbeitsbereichs über HTTP – Dateien lesen/schreiben/bearbeiten, suchen, Shell-Befehle, Git-Operationen – mit Sandbox-Isolation, Schutz sensibler Dateien und Prüfprotokoll.

Dieses Projekt enthält keine KI-/LLM-Logik, sondern nur die Dienstschicht und Sicherheitskontrollen.

Systemvoraussetzungen

• Python 3.10+ (zwingend erforderlich für FastMCP)

• pip install -r requirements.txt (fastmcp, pyyaml)

Related MCP server: OpenAI Secure MCP Tunnel

Schnellstart

Methode 1: Grafische Oberfläche (empfohlen)

python start.py

Schritte im Konsolenfenster:

1. Arbeitsbereichsordner: Klicken Sie auf „Auswählen…“, um einen Ordner festzulegen. Alle KI-Operationen sind auf diesen Ordner beschränkt (Sandbox). Ein Wechsel des Ordners ändert das Sandbox-Root.

2. Verbindungshinweis: In der Mitte des Fensters befindet sich eine Karte mit dem Verbindungshinweis. Kopieren Sie den Text und senden Sie ihn an die KI auf der Webseite. Die KI bindet dann gemäß der Konfiguration diesen MCP-Server (kein Token erforderlich).

3. Port: Standardmäßig 8000; bei Konflikten änderbar.

4. Schreibgeschützter Modus: Wenn aktiviert, werden alle Schreib-/Bearbeitungs-/Befehls-Tools abgelehnt. Die Umschaltung während des Betriebs wirkt sofort.

5. Klicken Sie auf „Dienst starten“ → Die Statusleiste zeigt Version, Schreibschutzstatus, Arbeitsbereich und Laufzeit an. Das Protokollfenster gibt Echtzeit-Dienstprotokolle aus.

6. Stoppen: Klicken Sie auf „Dienst stoppen“ oder schließen Sie das Fenster (es erfolgt eine Rückfrage).

Methode 2: Befehlszeile

# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动服务（默认监听 127.0.0.1:8000，MCP 路径 /mcp，无需 Token）
python server.py

Optionale Parameter: --workspace D:\projects\my-project (Sandbox-Root-Verzeichnis), --host 0.0.0.0 (ermöglicht LAN-Zugriff), --port 9000. Stoppen mit Strg+C.

Überprüfung und Gesundheitscheck

Nach dem Start des Dienstes aufrufen: GET http://127.0.0.1:8000/health (keine Authentifizierung). Rückgabe:

{ "status": "ok", "service": "local-code-agent", "version": "0.1.0",
  "workspace": "D:\\projects\\my-project", "readonly": false,
  "uptime_seconds": 3 }

Die übrigen Endpunkte (einschließlich /mcp) sind direkt ohne Authentifizierung erreichbar.

LAN-Zugriff

Standardmäßig wird nur 127.0.0.1 abgehört, nur der lokale Rechner kann verbinden. Für andere Geräte im selben LAN:

python server.py --host 0.0.0.0

Client-Verbindungsadresse: http://<Lokale LAN-IP>:8000/mcp (Lokale IP mit ipconfig ermitteln). Die Freigabe im LAN bedeutet, dass alle Geräte im selben Subnetz ohne Authentifizierung zugreifen können – Vorsicht ist geboten.

Es wird nicht empfohlen, den Dienst direkt im Internet freizugeben. Für den öffentlichen Zugang verwenden Sie bitte einen Reverse-Proxy (Nginx + TLS, frp oder andere Tunnel-Tools) und erzwingen Sie HTTPS und Authentifizierung auf der Proxy-Ebene.

Grafische Oberfläche (optional)

Auch ohne Befehlszeile nutzbar. tkinter ist Teil der Python-Standardbibliothek, keine zusätzliche Installation erforderlich.

python start.py

Konsolenfunktionen:

• Arbeitsbereichsordner: Klicken Sie auf „Auswählen…“, um einen Ordner auszuwählen. Es kann immer nur ein Ordner ausgewählt werden. Alle KI-Operationen sind auf diesen Ordner (Sandbox) beschränkt. Ein Wechsel des Ordners ersetzt die aktuelle Auswahl.

• Verbindungshinweis: Enthält einen bearbeitbaren Hinweistext. Mit einem Klick auf „Hinweis kopieren“ wird der Text kopiert und kann an die KI auf der Webseite gesendet werden, um die MCP-Bindung abzuschließen. Kein Token erforderlich.

• Port / Schreibgeschützter Modus: Legen Sie den Überwachungsport fest; aktivieren Sie den Schreibschutz, um Schreib-/Bearbeitungs-/Befehls-Tools zu deaktivieren.

• Dienst starten/stoppen: Startet FastMCP innerhalb des GUI-Prozesses (Hintergrund-Thread + uvicorn) mit einem eigenen Protokoll-Handler. Beim Stoppen wird auf das Ende des Dienst-Threads gewartet.

• Umschaltung während des Betriebs: Ein Wechsel des Arbeitsbereichs oder das Aktivieren des Schreibschutzes wirkt sofort, ohne Neustart. Eine Portänderung erfordert einen Neustart des Dienstes.

• Statusleiste: Fragt /health ab und zeigt Version, Schreibschutzstatus, aktuellen Arbeitsbereich und Laufzeit an.

• Protokollfenster: Zeigt Dienstausgaben in Echtzeit an, entfernt automatisch ANSI-Escape-Sequenzen, Rechtsklick zum Kopieren, automatische Kürzung bei über 600 Zeilen.

GUI und Befehlszeile verwenden dieselbe Sandbox und Prüfmechanismen; die Anbindung ist identisch.

Client-Anbindung

Lokaler Client: URL http://127.0.0.1:8000/mcp; LAN-Client: http://<Lokale LAN-IP>:8000/mcp (Server muss mit --host 0.0.0.0 gestartet sein). Keine Authentifizierung erforderlich.

claude_desktop_config.json für Claude Desktop:

{
  "mcpServers": {
    "local-code-agent": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Werkzeugliste

Sicherheitsmodell

• Sandbox: Alle Pfade werden mit realpath aufgelöst und müssen innerhalb des Arbeitsbereichs-Root liegen (verhindert Symlink-Eskapaden). ../ und absolute Pfade können nicht ausbrechen.

• Authentifizierung: Keine Token-Authentifizierung. Der Dienst hört standardmäßig nur auf 127.0.0.1; für externe Zugriffe muss auf Reverse-Proxy-Ebene selbst eine Authentifizierung hinzugefügt werden.

• Bestätigung gefährlicher Operationen: Git-Commit wird nur ausgeführt, wenn der Header x-confirm: true gesetzt ist.

• Sensible Dateien: .env, .env.*, *.pem, *.key, id_rsa, .ssh/, .aws/, credentials werden auf jeder Pfadebene blockiert. Es wird einheitlich „access denied“ zurückgegeben, ohne preiszugeben, ob die Datei existiert.

• Downloads: Unterstützt beliebige HTTP(S)-Hosts; keine Weiterleitungen; bei Überschreitung von 50 MB wird abgebrochen und die unvollständige Datei gelöscht.

• Prüfprotokoll: JSON-Zeilenformat, Rotation 10 MB × 5, protokolliert Zeit, Werkzeugname, bereinigte Parameter, Ergebnis, Dauer.

• Schreibgeschützter Modus: python server.py --readonly oder GUI-Auswahl. Schreib-/Befehls-Tools bleiben sichtbar, geben bei Aufruf read-only mode zurück. Umschaltung während des Betriebs möglich.

Konfigurationspriorität

Arbeitsbereich: --workspace > Umgebungsvariable MCP_WORKSPACE > config.yaml (Standard .). Alle anderen Konfigurationen stammen aus config.yaml (siehe Standardwerte in der Datei).

Projektstruktur

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # HTTP(S) 下载（无域名白名单）
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
runtime.py                # 运行时只读标志
gui/                      # tkinter 控制台（进程内服务）
start.py                  # GUI 入口
tests/                    # test_core.py + test_extra.py

Bekannte Einschränkungen

• Python 3.8 kann diesen Dienst nicht ausführen (fastmcp benötigt 3.10+); die Logikmodule sind mit 3.8 kompatibel, überprüfbar mit python tests/test_core.py.

• run_command verwendet SSE-Streaming-Ausgabe, Gesamt-Timeout maximal 3600 Sekunden.

• Es wird nur ein einzelner Arbeitsbereich unterstützt. Mehrere Arbeitsbereiche und sitzungsbezogener Kontext sind noch nicht implementiert (YAGNI).