FileAgent

FTP para agentes: un filesystem virtual compartido, cada archivo direccionado y verificado por SHA-256, con metadatos extraídos en la subida.

Los agentes en el mismo FILEAGENT_DATA_DIR (stdio) o en el mismo servidor HTTP ven el mismo acervo. Nada entra o sale sin un hash registrado (ftp_register). Ese access_hash es el canal; el SHA-256 del archivo es la prueba de integridad.

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

Dos agentes con el mismo secret en ftp_register obtienen el mismo access_hash.

Related MCP server: MEFS MCP Server

Herramientas FTP

doc_* continúa para edición colaborativa (lock + doc_commit) del documento ligado al path.

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

Metadatos extraídos

En ftp_put / ftp_stat / ftp_ls:

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

• texto / markdown: título, headings, líneas, palabras, idioma (pt/en)

• JSON: validez, tipo, claves

• CSV: columnas y número de líneas

• PNG / JPEG / GIF: ancho y alto

• PDF: versión, title/author si están presentes en el header

Admin y contraseña

Solo el admin registra access_hash. La contraseña en texto queda solo en el .venv del proyecto (fuera del git):

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

• contraseña: .venv/fileagent_admin.password

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

Panel en el navegador: abre / y entra con esa contraseña para ver todos los archivos de todos los canales. Sin login, la lista no 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"}'

Los clientes no registran hash. Usan el access_hash devuelto en POST /v1/files o ftp_put.

Subir en el aire

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

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

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

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

• Salud: GET /healthz

Skills

• fileagent-send — agentes que envían

• fileagent-receive — agentes que listan/descargan

Instalación

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

Cursor (mismo 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: mismo FILEAGENT_DATA_DIR, FILEAGENT_AGENT_ID distinto.

HTTP

uv run fileagent --http --port 8765

Variables

Los paths private solo el dueño (y grants) los ven. agent_id es coordinación, no autenticación fuerte. La seguridad del contenido es el hash: si los bytes cambian, la lectura falla.

Producción actual (AWS): https://fileagent.54-204-243-102.sslip.io/ — panel con contraseña de admin.

Pruebas

uv run pytest -q