FileAgent

FTP para agentes: um filesystem virtual compartilhado, cada arquivo endereçado e verificado por SHA-256, com metadados extraídos no upload.

Agentes no mesmo FILEAGENT_DATA_DIR (stdio) ou no mesmo servidor HTTP vêem o mesmo acervo. Nada entra ou sai sem um hash cadastrado (ftp_register). Esse access_hash é o canal; o SHA-256 do arquivo é a prova de integridade.

Modelo

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

Dois agentes com o mesmo secret em ftp_register obtêm o mesmo access_hash.

Related MCP server: MEFS MCP Server

Ferramentas FTP

doc_* continua para edição colaborativa (lock + doc_commit) do documento ligado ao path.

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

Metadados extraídos

No ftp_put / ftp_stat / ftp_ls:

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

• texto / markdown: título, headings, linhas, palavras, idioma (pt/en)

• JSON: validade, tipo, chaves

• CSV: colunas e número de linhas

• PNG / JPEG / GIF: largura e altura

• PDF: versão, title/author se presentes no header

Admin e senha

Só o admin cadastra access_hash. A senha em texto fica apenas no .venv do projeto (fora do git):

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

• senha: .venv/fileagent_admin.password

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

Painel no navegador: abra / e entre com essa senha para ver todos os arquivos de todos os canais. Sem login, a lista não aparece.

# 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"}'

Clientes não cadastram hash. Usam o access_hash devolvido em POST /v1/files ou ftp_put.

Subir no ar

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

• Painel admin (login): http://<host>:8765/

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

• REST: POST/GET /v1/files com header X-Access-Hash

• Saúde: GET /healthz

Skills

• fileagent-send — agentes que enviam

• fileagent-receive — agentes que listam/baixam

Instalação

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

Cursor (mesmo store entre agentes)

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

Cada agente: mesmo FILEAGENT_DATA_DIR, FILEAGENT_AGENT_ID distinto.

HTTP

uv run fileagent --http --port 8765

Variáveis

Paths private só o dono (e grants) enxergam. agent_id é coordenação, não autenticação forte. A segurança do conteúdo é o hash: se os bytes mudarem, a leitura falha.

Produção atual (AWS): https://fileagent.54-204-243-102.sslip.io/ — painel com senha de admin.

Testes

uv run pytest -q