FileAgent

FTP for agents: a shared virtual filesystem, each file addressed and verified by SHA-256, with metadata extracted on upload.

Agents on the same FILEAGENT_DATA_DIR (stdio) or on the same HTTP server see the same collection. Nothing enters or leaves without a registered hash (ftp_register). That access_hash is the channel; the file's SHA-256 is the proof of integrity.

Model

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)-|

Two agents with the same secret in ftp_register get the same access_hash.

Related MCP server: MEFS MCP Server

FTP Tools

doc_* continues for collaborative editing (lock + doc_commit) of the document linked to the path.

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

Extracted Metadata

On ftp_put / ftp_stat / ftp_ls:

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

• text / markdown: title, headings, lines, words, language (pt/en)

• JSON: validity, type, keys

• CSV: columns and number of rows

• PNG / JPEG / GIF: width and height

• PDF: version, title/author if present in the header

Admin and Password

Only the admin registers access_hash. The plaintext password stays only in the project's .venv (outside git):

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

• password: .venv/fileagent_admin.password

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

Browser panel: open / and enter that password to see all files from all channels. Without login, the list does not appear.

# 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 do not register hashes. They use the access_hash returned in POST /v1/files or ftp_put.

Going Live

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 with header X-Access-Hash

• Health: GET /healthz

Skills

• fileagent-send — agents that send

• fileagent-receive — agents that list/download

Installation

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

Cursor (same store between agents)

{
  "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"
      }
    }
  }
}

Each agent: same FILEAGENT_DATA_DIR, distinct FILEAGENT_AGENT_ID.

HTTP

uv run fileagent --http --port 8765

Variables

private paths are only visible to the owner (and grants). agent_id is coordination, not strong authentication. Content security is the hash: if the bytes change, the read fails.

Current production (AWS): https://fileagent.54-204-243-102.sslip.io/ — panel with admin password.

Tests

uv run pytest -q