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

ftp_register에서 동일한 secret을 사용하는 두 에이전트는 동일한 access_hash를 얻습니다.

Related MCP server: MEFS MCP Server

FTP 도구

doc_*는 경로에 연결된 문서의 공동 편집(lock + doc_commit)을 계속합니다.

리소스: fileagent://fs, fileagent://docs, fileagent://blob/{hash}.

추출된 메타데이터

ftp_put / ftp_stat / ftp_ls에서:

• 항상: hash, size, mime, kind, filename, extension

• 텍스트 / 마크다운: 제목, headings, 줄 수, 단어 수, 언어(pt/en)

• JSON: 유효성, 유형, 키

• CSV: 열 및 행 수

• PNG / JPEG / GIF: 너비 및 높이

• PDF: 버전, 헤더에 있는 경우 title/author

관리자 및 비밀번호

관리자만 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"}'

클라이언트는 해시를 등록하지 않습니다. POST /v1/files 또는 ftp_put에서 반환된 access_hash를 사용합니다.

실행

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

• 관리자 패널(로그인): http://<host>:8765/

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

• REST: X-Access-Hash 헤더와 함께 POST/GET /v1/files

• 상태: 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 경로는 소유자(및 권한이 부여된 사람)만 볼 수 있습니다. agent_id는 조정을 위한 것이지 강력한 인증이 아닙니다. 콘텐츠 보안은 해시입니다: 바이트가 변경되면 읽기가 실패합니다.

프로덕션(AWS): https://fileagent.54-204-243-102.sslip.io/ — 관리자 비밀번호가 있는 패널.

테스트

uv run pytest -q