librechat-personal-files-mcp

MCP-Server, der pro Benutzer persönlichen Dateispeicher, persistente Dokumentation, RAG-Indexierung/-Abruf und die Veröffentlichung undurchsichtiger öffentlicher Links für LibreChat-Agenten bereitstellt.

Funktionen

• Speicher pro Benutzer: Private Dateien unter /data/private/<userId>/ mit vollständigen CRUD-, Listen- und Verschiebeoperationen.

• Dokumentationskatalog: save_documentation / update_documentation schreiben in docs/ und aktualisieren memory-index.json (Schema v2).

• RAG-Integration: index_document sendet Inhalte über POST /embed an rag_api mit Canary-Überprüfung (Issue #305); search_knowledge für semantische Suche; remove_from_knowledge zum Löschen.

• Öffentliche Veröffentlichung: publish_file erstellt kryptografisch zufällige Tokens (≥128 Bit); Dateien werden über Nginx X-Accel-Redirect mit Content-Disposition: attachment, nosniff, no-store ausgeliefert.

• Strikte Sicherheit: Fail-closed bei fehlender/ungültiger X-User-Id; Path-Traversal blockiert; keine absoluten Pfade; keine ..-Segmente; Erkennung von Symlink-Escapes; Schutz reservierter Segmente; atomare Index-Schreibvorgänge mit prozessübergreifender Sperre.

Related MCP server: knowledge_mgmt

Architektur

┌──────────────┐     ┌────────────────────────┐     ┌─────────────┐
│ LibreChat    │────▶│ librechat-personal-files-mcp │──▶│ rag_api     │
│ (Agent)      │ MCP │ (stateless HTTP /mcp)  │     │ (vector DB) │
└──────────────┘     └────────────────────────┘     └─────────────┘
                            │
                            │ GET /files/{token}
                            ▼
                     ┌──────────────┐
                     │ Nginx        │
                     │ (X-Accel)    │
                     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │ /data/private│  (read-only bind)
                     └──────────────┘

Schnellstart (Entwicklung)

cd /opt/LibreChat/mcp-personal-files
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
# Run server
STORAGE_ROOT=/tmp/pf-private JWT_SECRET=$(openssl rand -hex 32) .venv/bin/personal-files-mcp

Produktionsbereitstellung

1. Host-Vorbereitung (einmalig als root ausführen)

cd /opt/LibreChat
groupadd -g 2500 lcfiles 2>/dev/null || true
mkdir -p ./data/private/_system
chown -R 2000:2500 ./data/private
chmod 2770 ./data/private
setfacl -R -m g:2500:rX,d:g:2500:rX ./data/private 2>/dev/null || \
  echo "ACL tools absent; using 644/755 fallback"
grep -q '^JWT_SECRET=' .env || echo "JWT_SECRET=$(openssl rand -hex 32)" >> .env

2. Zu docker-compose.override.yml hinzufügen

Kopieren Sie die Blöcke aus docker-compose.snippet.yml in Ihre vorhandene Override-Datei.

3. LibreChat Admin-Panel konfigurieren

Unter MCP-Einstellungen hinzufügen:

mcpSettings:
  allowedAddresses:
    - 'librechat-personal-files:8080'

mcpServers:
  personal-files:
    type: streamable-http
    url: http://librechat-personal-files:8080/mcp
    timeout: 120000
    chatMenu: false
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'

LibreChat neu starten.

4. Nginx-Konfiguration (zum vorhandenen Serverblock hinzufügen)

limit_req_zone $binary_remote_addr zone=pubfiles:10m rate=5r/s;

location ^~ /files/ {
    limit_req zone=pubfiles burst=10 nodelay;
    limit_req_status 429;
    proxy_pass http://librechat-personal-files:8080/files/;
    proxy_set_header X-Original-URI $request_uri;
    proxy_set_header X-Real-IP $remote_addr;
}

location ^~ /_protected/ {
    internal;
    alias /data/private/;
}

Nginx neu laden.

Umgebungsvariablen

MCP-Tools

Speicher

• list_files(path="", recursive=false, pattern=null) — Dateien/Verzeichnisse auflisten

• read_file(path) — UTF-8-Text lesen; Fehler bei Binärdaten oder >2 MB

• write_file(path, content) — Text (UTF-8) schreiben, erstellt übergeordnete Verzeichnisse

• update_file(path, content) — Vorhandene Datei aktualisieren

• delete_file(path) — Datei oder Verzeichnis löschen

• move_file(src, dst) — Innerhalb des Benutzerstammverzeichnisses verschieben

• get_file_info(path) — Metadaten + Dokumentindex + Veröffentlichungsstatus

Dokumentation

• save_documentation(filename, content, title?, description?, tags?, topics?) — Speichert in docs/, aktualisiert den Index, veröffentlicht oder indexiert nicht

• update_documentation(filename, content, ...) — Vorhandenes Dokument aktualisieren

• get_document_metadata(filename) — Vollständiger Indexeintrag

RAG

• search_knowledge(query, limit=8) — Semantische Suche (über JWT auf den Besitzer beschränkt)

• index_document(path) — Einbetten + Canary-Verifizierung, aktualisiert den Indexstatus

• remove_from_knowledge(path) — Aus rag_api löschen, leert den Index

• get_index_status() — Anzahl + rag_api-Status

Veröffentlichung

• publish_file(path, expires_in_days?) — Öffentlichen Link erstellen/wiederverwenden, gibt Token + URL zurück

• unpublish_file(path_or_token) — Link widerrufen (Datei bleibt privat)

• get_public_link(path) — Aktiver Link für den Pfad

• list_public_links() — Alle Links des Benutzers

Sicherheitsmodell

• Identität: Der X-User-Id-Header wird von LibreChat ({{LIBRECHAT_USER_ID}}) eingefügt. Platzhalter nicht aufgelöst → leere Zeichenfolge → fail-closed.

• Fail-closed: Fehlender/leerer/ungültiger Header → HTTP 403 {"error":"missing_user_identity"} oder {"error":"invalid_user_identity"}.

• Pfadsicherheit: Alle Pfade sind relativ; absolute Pfade und .. werden abgelehnt; Symlink-Escapes werden über Path.resolve() + Präfixprüfung erkannt.

• Isolation: Der Zugriff von rag_api wird über JWT sub/id = userId auf den Besitzer beschränkt (PR #319, gemerged am 15.08.2026).

• Öffentliche Links: Undurchsichtige secrets.token_urlsafe(16)-Tokens; kein Benutzer/Pfad in der URL; Widerruf über 410 Gone; Lazy-Bereinigung abgelaufener Einträge.

Entwicklung

# Run tests
.venv/bin/pytest -q

# Lint
.venv/bin/ruff check .

# Type check (optional)
.venv/bin/mypy src/personal_files_mcp  # if mypy added to deps

Lizenz

MIT