local-code-agent

Ein lokaler MCP-Server, entwickelt mit FastMCP: Ermöglicht externen KIs (ChatGPT, Claude usw.) durch Cloudflare Tunnel einen sicheren Fernzugriff auf das lokale Arbeitsverzeichnis – Datei-Lesen/Schreiben/Bearbeiten, Suchen, Shell-Befehle, Git-Operationen – und bietet Bearer-Token-Authentifizierung, Sandbox-Isolation und Audit-Logs.

Dieses Projekt enthält keine AI/LLM-Logik, sondern nur Tool-Schicht-Dienste und Tunnel-Konfiguration.

Umgebungsanforderungen

• Python 3.10+ (zwingend für FastMCP)

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

Schnellstart

# 1. 安装依赖
pip install -r requirements.txt
set MCP_AUTH_TOKEN=your_long_random_token
set MCP_WORKSPACE=D:\projects\my-project

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

# 3. 公网穿透（临时域名）
cloudflared tunnel --url http://127.0.0.1:8000

# 固定域名（绑定自有域名）
cloudflared tunnel --url http://127.0.0.1:8000 --hostname mcp.yourdomain.com

Gesundheitscheck: GET http://127.0.0.1:8000/health (standardmäßig ohne Authentifizierung; andere Endpunkte müssen Bearer-Token mitführen).

Grafische Oberfläche (optional)

Auch ohne Kommandozeile nutzbar. tkinter gehört zur Python-Standardbibliothek, keine zusätzliche Installation erforderlich.

python -m gui.app

Konsolenfunktionen:

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

• Authentifizierungs-Token: Beim Start wird automatisch ein zufälliges Token generiert, das über „Neu generieren“ ausgetauscht werden kann. Dieses Token muss im KI-Client als Authorization: Bearer ... eingetragen werden.

• Port / Nur-Lesen-Modus: Legen Sie den Überwachungsport fest; aktivieren Sie den Nur-Lesen-Modus, um Schreib-/Bearbeitungs-/Befehls-Tools zu deaktivieren.

• Dienst starten/stoppen: server.py wird als untergeordneter Prozess ausgeführt; Stoppen beendet den Prozess.

• Statusleiste: Fragt /health ab und zeigt Dienstversion, aktuelles Arbeitsverzeichnis und Laufzeit an; unterstützt auch das Kopieren des Cloudflared-Tunnel-Befehls mit einem Klick.

• Logbereich: Zeigt die Ausgabe des Server-Unterprozesses in Echtzeit an; bei mehr als 600 Zeilen wird automatisch gekürzt.

Die GUI ist nur ein Starter für server.py, verwendet die gleichen Authentifizierungs-, Sandbox- und Audit-Sicherheitsmechanismen; die öffentliche Anbindung erfolgt wie in der Kommandozeile.

Client-Anbindung

ChatGPT Custom Connector: URL auf https://<tunnel-host>/mcp setzen, Header Authorization: Bearer your_long_random_token hinzufügen.

Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "local-code-agent": {
      "url": "https://mcp.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer your_long_random_token" }
    }
  }
}

Werkzeugliste

Sicherheitsmodell

• Sandbox: Alle Pfade werden über realpath aufgelöst und müssen innerhalb des Arbeitsverzeichnis-Roots liegen (verhindert Symlink-Ausbrüche). ../ und absolute Pfade können nicht ausbrechen.

• Authentifizierung: FastMCP DebugTokenVerifier prüft das Bearer-Token. Das Token wird nur aus MCP_AUTH_TOKEN gelesen (für Entwicklung --token). Fehlt es, wird der Start verweigert.

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

• Befehls-Whitelist: In config.yaml die Schlüssel command_allow, command_deny, danger_commands (benötigen x-confirm: true).

• Downloads: Nur http(s)-Hosts aus download_allow_domains erlaubt; Weiterleitungen verboten; über 50 MB wird der Vorgang abgebrochen und die unvollständige Datei gelöscht.

• Audit-Logs: JSON-Zeilenformat, Rotation 10 MB × 5, zeichnet Zeitstempel, Werkzeugname, anonymisierte Parameter, Ergebnis, Dauer auf.

• Nur-Lesen-Modus: python server.py --readonly registriert nur Lese-/Such-/Git-Anzeige-Werkzeuge.

Konfigurationspriorität

Arbeitsverzeichnis: --workspace > Umgebungsvariable MCP_WORKSPACE > config.yaml (Standard .). Alle anderen Konfigurationen stammen aus config.yaml (siehe Datei für Standardwerte).

Projektstruktur

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
command_whitelist.py      # 命令白名单校验
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # 域名白名单下载
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
gui/                      # tkinter 启动器
start.py / start.spec     # GUI 入口 + PyInstaller onedir
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 kompatibel mit 3.8, kann mit python tests/test_core.py überprüft werden.

• Das standardmäßige Timeout von Cloudflare Tunnel liegt bei etwa 100 Sekunden. run_command verwendet SSE-Streaming; maximales Timeout 3600 Sekunden.

• Es wird nur ein einzelnes Arbeitsverzeichnis unterstützt. Mehrere Arbeitsverzeichnisse und sitzungsbezogener Kontext sind noch nicht implementiert (YAGNI).

• Paketierung: pip install -r requirements-build.txt && pyinstaller start.spec, Ausgabe dist/start/start.exe. Die GUI erfordert manuelles Klicken auf „Dienst starten“.