FileAgent

FTP для агентов: общая виртуальная файловая система, каждый файл адресуется и проверяется по SHA-256, с извлечёнными метаданными при загрузке.

Агенты в одном FILEAGENT_DATA_DIR (stdio) или на одном HTTP-сервере видят один и тот же набор файлов. Ничего не входит и не выходит без зарегистрированного хэша (ftp_register). Этот access_hash — канал; SHA-256 файла — доказательство целостности.

Модель

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

Два агента с одним и тем же secret в ftp_register получают один и тот же access_hash.

Related MCP server: MEFS MCP Server

Инструменты FTP

doc_* продолжает использоваться для совместного редактирования (lock + doc_commit) документа, связанного с path.

Ресурсы: fileagent://fs, fileagent://docs, fileagent://blob/{hash}.

Извлечённые метаданные

В ftp_put / ftp_stat / ftp_ls:

• всегда: hash, size, mime, kind, filename, extension

• текст / markdown: заголовок, headings, строки, слова, язык (pt/en)

• JSON: валидность, тип, ключи

• CSV: колонки и количество строк

• PNG / JPEG / GIF: ширина и высота

• PDF: версия, title/author, если присутствуют в header

Администратор и пароль

Только администратор регистрирует access_hash. Пароль в открытом виде хранится только в .venv проекта (вне git):

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

• пароль: .venv/fileagent_admin.password

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

Панель в браузере: откройте / и войдите с этим паролем, чтобы увидеть все файлы всех каналов. Без входа список не отображается.

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

Клиенты не регистрируют хэш. Используют access_hash, возвращённый в POST /v1/files или ftp_put.

Развёртывание

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

• Панель администратора (вход): http://<host>:8765/

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

• REST: POST/GET /v1/files с заголовком X-Access-Hash

• Здоровье: GET /healthz

Навыки

• fileagent-send — агенты, которые отправляют

• fileagent-receive — агенты, которые перечисляют/скачивают

Установка

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

Cursor (общее хранилище между агентами)

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

Каждый агент: одинаковый FILEAGENT_DATA_DIR, отдельный FILEAGENT_AGENT_ID.

HTTP

uv run fileagent --http --port 8765

Переменные

Пути private видит только владелец (и grants). agent_id — это координация, а не строгая аутентификация. Безопасность содержимого — это хэш: если байты изменятся, чтение не удастся.

Текущий продакшн (AWS): https://fileagent.54-204-243-102.sslip.io/ — панель с паролем администратора.

Тесты

uv run pytest -q