Skip to main content
Glama
FileAgent

FileAgent

by naubergois

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

Concept

What it is

Access hash

Credential registered with ftp_register. Without it, put/get fail. Each hash is an isolated channel.

Path

FTP path (/inbox/nota.md) inside the access_hash.

Blob

Immutable bytes. Address = sha256(bytes). Every read recalculates the hash.

Metadata

Extracted from content: mime, kind, title, language, headings, CSV columns, JSON keys, image dimensions, PDF hints.

Document

Mutable pointer behind the path. Serves checkout/commit between agents.

CAS

expected_hash on get/put. Tampered disk → code=tampered.

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: sftp-mcp

FTP Tools

Tool

Usage

ftp_register

Registers the hash. Without it, put/get are refused.

ftp_revoke / ftp_hashes

Revokes or lists hashes from this agent.

ftp_put

Sends. Requires access_hash. Writes SHA-256 + metadata.

ftp_get

Downloads. Requires the same access_hash. Recalculates SHA-256.

ftp_ls

Lists this hash's channel (content + metadata).

ftp_stat / ftp_meta

Metadata only (path or hash).

ftp_verify

Integrity audit.

ftp_find

Search by path, hash, title, kind, columns…

ftp_mkdir / ftp_rm / ftp_mv / ftp_cp

FTP-style navigation.

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

Variable

Default

Function

FILEAGENT_DATA_DIR

~/.fileagent

SQLite + blobs. Same path = same FTP.

FILEAGENT_AGENT_ID

user@host

Who sent / edited.

FILEAGENT_OPEN_EDIT

1

Store agents edit shared paths.

FILEAGENT_HOST / PORT

127.0.0.1 / 8765

--http mode.

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

Available Tools

31 tools
doc_checkoutB

Adquire lock de edição e devolve content + hash + lock_token. Outro agente recebe code=locked.

Inputs: doc_id (required), agent_id, share_token, ttl_seconds. Returns: object

doc_claimB

Resgata um share_token e grava grant permanente para este agente.

Inputs: share_token (required), agent_id. Returns: object

doc_commitA

Grava a edição do checkout. Exige lock_token e expected_hash. Libera o lock salvo keep_lock=true.

Inputs: doc_id (required), lock_token (required), expected_hash (required), content, +4 more. Returns: object

doc_createB

Cria um documento editável. O doc_id padrão é o hash do conteúdo inicial — compartilhe esse id.

Inputs: title (required), mime, tags, doc_id, +4 more. Returns: object

doc_forkC

Cria um documento novo a partir de um doc_id ou de um hash imutável.

Inputs: hash, title, doc_id, agent_id, +1 more. Returns: object

doc_getA

Lê um snapshot imutável pelo hash (ou prefixo único). Não segue o ponteiro do documento.

Inputs: hash (required), agent_id. Returns: object

doc_historyC

Cadeia de versões (hash ← parent_hash) com o agente que commitou cada uma.

Inputs: doc_id (required), limit, agent_id. Returns: object

doc_infoB

Metadados do documento sem o conteúdo (hash atual, versão, lock, dono).

Inputs: doc_id (required), agent_id, share_token. Returns: object

doc_listB

Lista documentos visíveis para este agente. query filtra título, tags, hash e preview.

Inputs: limit, query, agent_id. Returns: object

doc_putB

Guarda um blob imutável e devolve o hash SHA-256. Mesmo conteúdo = mesmo hash.

Inputs: mime, content, agent_id, content_base64. Returns: object

doc_readB

Lê a versão atual de um documento (doc_id) ou um blob (hash). Aceita share_token.

Inputs: hash, doc_id, agent_id, share_token, +1 more. Returns: object

doc_releaseA

Libera o lock sem gravar (checkout abandonado).

Inputs: doc_id (required), lock_token (required), agent_id. Returns: object

doc_shareB

Compartilha para edição. Com to_agent_id concede grant; sem ele gera share_token para outro agente.

Inputs: doc_id (required), role, agent_id, max_uses, +2 more. Returns: object

doc_unshareC

Revoga grant ou share_token. Sem os dois, revoga todos os tokens do documento.

Inputs: doc_id (required), agent_id, share_token, from_agent_id. Returns: object

doc_updateB

Atualiza com compare-and-swap. Falha com code=conflict se expected_hash não for o atual.

Inputs: doc_id (required), expected_hash (required), mime, title, +7 more. Returns: object

ftp_cpC

Copia arquivo dentro do mesmo access_hash.

Inputs: dst (required), src (required), access_hash (required), agent_id. Returns: object

ftp_findB

Busca arquivos deste access_hash por path, hash de conteúdo ou metadados.

Inputs: query (required), access_hash (required), limit, agent_id. Returns: object

ftp_getB

Baixa arquivo. Exige o mesmo access_hash cadastrado usado no put. Recalcula SHA-256.

Inputs: path (required), access_hash (required), agent_id, expected_hash, +1 more. Returns: object

ftp_hashesA

Lista hashes. Com senha admin lista todos; sem ela, só os criados por este agente.

Inputs: agent_id, admin_password. Returns: object

ftp_lsA

Lista o diretório deste access_hash. Cada arquivo vem com hash de conteúdo e metadados.

Inputs: access_hash (required), path, query, agent_id. Returns: object

ftp_metaB

Só metadados extraídos. Exige access_hash. Por path ou pelo hash do conteúdo.

Inputs: access_hash (required), hash, path, agent_id. Returns: object

ftp_mkdirC

Cria diretório neste hash cadastrado.

Inputs: path (required), access_hash (required), agent_id. Returns: object

ftp_mvC

Move/renomeia path dentro do mesmo access_hash.

Inputs: dst (required), src (required), access_hash (required), agent_id. Returns: object

ftp_putB

Envia arquivo. Exige access_hash cadastrado (ftp_register). Grava SHA-256, verifica disco e extrai metadados.

Inputs: path (required), access_hash (required), mime, content, +5 more. Returns: object

ftp_registerA

Admin: cadastra um access_hash. Exige senha do admin. Clientes usam o hash gerado em put/get.

Inputs: admin_password (required), hash, label, secret, +4 more. Returns: object

ftp_revokeA

Admin: revoga um hash cadastrado. put/get com ele passam a falhar.

Inputs: access_hash (required), admin_password (required), agent_id. Returns: object

ftp_rmA

Remove arquivo ou diretório neste hash. Pasta não vazia exige recursive=true.

Inputs: path (required), access_hash (required), agent_id, recursive. Returns: object

ftp_statB

Metadados de um path neste hash cadastrado, sem o conteúdo.

Inputs: path (required), access_hash (required), agent_id. Returns: object

ftp_verifyC

Recalcula SHA-256 no disco. Exige access_hash. Disco alterado → tampered.

Inputs: access_hash (required), hash, path, agent_id. Returns: object

healthB

Saúde do FTP: data_dir, arquivos, hashes cadastrados e identidade deste agente.

Inputs: agent_id. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 31 tools

    Disambiguation2/5

    Several tools have overlapping functionality, making it unclear which to use. For example, ftp_put and doc_put both store content and return a SHA-256 hash, ftp_get and doc_get both retrieve content by hash, and ftp_stat and ftp_meta both retrieve metadata. This redundancy increases the risk of misselection.

    Naming Consistency4/5

    The naming mostly follows a consistent pattern of prefix (ftp_ or doc_) plus a verb (put, get, ls, stat, etc.), with only a few exceptions like ftp_hashes and ftp_register. Overall, the naming is predictable and semantically aligned with the action.

    Tool Count3/5

    With 31 tools, the server is on the higher end but not excessive. However, the count is inflated by redundant operations (e.g., ftp_stat vs. ftp_meta, ftp_ls vs. doc_list) and a clear split between file management and document management, which could be streamlined without loss of functionality.

    Completeness3/5

    The toolset covers CRUD for files and documents, versioning, locking, sharing, and admin functions. However, there is no explicit document deletion tool (doc_delete), and the distinction between immutable blobs and editable documents is not fully addressed (e.g., doc_update exists but no corresponding ftp_update). This leaves minor gaps in lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides AI agents with a persistent, PostgreSQL-backed virtual filesystem, supporting session-isolated file operations, cross-session shared stores, and glob/grep search.
      11
      61 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a browsable, mutable SFTP filesystem for AI agents, supporting file operations like listing, uploading, downloading, moving, and deleting.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that gives AI agents file system access: read, write, search, hash, directory trees — 12 tools, zero dependencies, pure Python stdlib.
      MIT