FileAgent

FTP für Agenten: ein gemeinsames virtuelles Dateisystem, jede Datei adressiert und verifiziert durch SHA-256, mit extrahierten Metadaten beim Upload.

Agenten im selben FILEAGENT_DATA_DIR (stdio) oder auf demselben HTTP-Server sehen denselben Bestand. Nichts gelangt hinein oder hinaus ohne einen registrierten Hash (ftp_register). Dieser access_hash ist der Kanal; die SHA-256 des Files ist der Integritätsbeweis.

Modell

agente A                         FileAgent                       agente B
   |-- ftp_register() -----------> |                               |
   |<-- access_hash ---------------|                               |
   |---------------- compartilha access_hash --------------------->|
   |-- ftp_put(/inbox/a.md, hash) >|  sha256 + metadata            |
   |                               |<-- ftp_get(/inbox/a.md, hash)-|

Zwei Agenten mit demselben secret in ftp_register erhalten denselben access_hash.

Related MCP server: MEFS MCP Server

FTP-Werkzeuge

doc_* bleibt für kollaboratives Editieren (Sperre + doc_commit) des mit dem Pfad verbundenen Dokuments.

Ressourcen: fileagent://fs, fileagent://docs, fileagent://blob/{hash}.

Extrahierte Metadaten

Bei ftp_put / ftp_stat / ftp_ls:

• Immer: hash, size, mime, kind, filename, extension

• Text / Markdown: Titel, Überschriften, Zeilen, Wörter, Sprache (pt/de)

• JSON: Gültigkeit, Typ, Schlüssel

• CSV: Spalten und Anzahl der Zeilen

• PNG / JPEG / GIF: Breite und Höhe

• PDF: Version, title/author wenn im Header vorhanden

Admin und Passwort

Nur der Administrator registriert access_hash. Das Passwort im Klartext liegt ausschließlich im .venv des Projekts (außerhalb von git):

• Hash: .venv/fileagent_admin.hash (PBKDF2-SHA256)

• Passwort: .venv/fileagent_admin.password

uv run fileagent --init-admin          # gera se ainda não existir
uv run fileagent --rotate-admin        # nova senha

Dashboard im Browser: Öffne / und melde dich mit diesem Passwort an, um alle Dateien aller Kanäle zu sehen. Ohne Login wird die Liste nicht angezeigt.

# cadastrar um canal para clientes
curl -sS -X POST http://127.0.0.1:8765/v1/admin/register \
  -H "Content-Type: application/json" \
  -d '{"admin_password":"<senha>","label":"equipe-a"}'

Clients registrieren keinen Hash. Sie verwenden das access_hash, das in POST /v1/files oder ftp_put zurückgegeben wird.

In Betrieb nehmen

uv run fileagent --http --host 0.0.0.0 --port 8765

• Admin-Panel (Login): http://<host>:8765/

• MCP: http://<host>:8765/mcp

• REST: POST/GET /v1/files mit Header X-Access-Hash

• Gesundheit: GET /healthz

Fähigkeiten

• fileagent-send — Agenten, die senden

• fileagent-receive — Agenten, die auflisten/laden

Installation

cd /Users/naubergois/FileAgent
uv sync --extra dev

Cursor (gemeinsamer Speicher zwischen Agenten)

{
  "mcpServers": {
    "fileagent": {
      "command": "uv",
      "args": ["--directory", "/Users/naubergois/FileAgent", "run", "fileagent"],
      "env": {
        "FILEAGENT_DATA_DIR": "/Users/naubergois/.fileagent",
        "FILEAGENT_AGENT_ID": "cursor",
        "FILEAGENT_OPEN_EDIT": "1"
      }
    }
  }
}

Für jeden Agenten: dasselbe FILEAGENT_DATA_DIR, FILEAGENT_AGENT_ID unterschiedlich.

HTTP

uv run fileagent --http --port 8765

Variablen

private-Pfade – nur der Besitzer (und Grants) sehen sie. agent_id ist Koordination, keine starke Authentifizierung. Die Inhaltsbindlichkeit ist der Hash: Wenn sich die Bytes ändern, schlägt die Lektüre fehl.

Aktuelle Produktion (AWS): https://fileagent.54-204-243-102.sslip.io/ — Panel mit Administrator-Passwort.

Tests

uv run pytest -q