ffl-mcp

Dê à IA a capacidade de "enviar arquivo" via P2P (Local-first)

Documentação

ffl-mcp (somente local)

Servidor MCP para ffl. Deixe a IA compartilhar qualquer coisa por você.

Desenvolvido por ffl, que transforma qualquer arquivo/pasta em um link HTTPS.

Este servidor MCP usa a ligação ffl-python localmente. Nenhum conteúdo de arquivo é enviado ao LLM; o modelo apenas aciona o ffl local.

Esta demonstração mostra depuração colaborativa: Claude à esquerda compartilha um ambiente local (banco de dados + logs) via link P2P, Claude à direita baixa e diagnostica o erro. Neste cenário, os dois Claudes representam pessoas diferentes trabalhando em máquinas separadas.

ffl-mcp-demo

Instalação

⚡ URLs curtas para conveniência

Linux/macOS: curl -fsSL https://fastfilelink.com/mcp/install.sh | bash

Windows (script): iwr -useb https://fastfilelink.com/mcp/install.ps1 | iex

🔒 fastfilelink.com/mcp/* é um redirecionamento para o GitHub. Use as URLs diretas do GitHub abaixo se preferir.

Windows — Instalador GUI

Baixe e execute ffl-mcp-setup.exe da versão mais recente.

Ele registra o servidor com Claude Desktop, Claude Code, Codex e Grok Build.

Não é necessário usar a linha de comando — o instalador registra o ffl-mcp com Claude Desktop e Claude Code automaticamente.

Linux / macOS — comando único

curl -fsSL https://raw.githubusercontent.com/nuwainfo/ffl-mcp/refs/heads/main/scripts/Install.sh | bash

Baixa o binário da plataforma da versão mais recente do GitHub e executa ffl-mcp install para registrar com Claude, Codex e Grok Build. Usa uvx automaticamente como fallback se não houver binário disponível para sua plataforma.

Windows — comando único (PowerShell)

iwr -useb https://raw.githubusercontent.com/nuwainfo/ffl-mcp/refs/heads/main/scripts/Install.ps1 | iex

Baixa ffl-mcp.exe da versão mais recente do GitHub e o registra com Claude, Codex e Grok Build.

uvx (sem binário, requer uv)

uvx --from git+https://github.com/nuwainfo/ffl-mcp install

Os alvos podem ser controlados com --target (padrão: todos):

uvx --from git+https://github.com/nuwainfo/ffl-mcp install --target claude-desktop,claude-code,codex,grok-build

uvx --from git+https://github.com/nuwainfo/ffl-mcp install --print

claude-code usa a CLI do Claude Code. codex grava a configuração nativa ~/.codex/config.toml usada pelos clientes Codex. grok-build grava ~/.grok/config.toml, que o Grok Build pode recarregar de /mcps.

Nomes de alvo legados (claude-cli, codex-cli, codex-desktop e grok) continuam aceitos como aliases. O instalador primeiro cria um backup com carimbo de data/hora de qualquer configuração que alterar.

Para caminhos de configuração personalizados, passe o arquivo:

uvx --from git+https://github.com/nuwainfo/ffl-mcp install --config /path/to/claude_desktop_config.json
uvx --from git+https://github.com/nuwainfo/ffl-mcp install --codex-config /path/to/codex/config.toml
uvx --from git+https://github.com/nuwainfo/ffl-mcp install --grok-config /path/to/grok/config.toml

Executar diretamente (desenvolvimento)

Pré-requisito: uv instalado.

# optional safety: restrict file sharing to a directory
export ALLOWED_BASE_DIR="$HOME/Downloads"

# optional: use stdin for text/base64 instead of temp files
export FFL_USE_STDIN=1

uvx --from git+https://github.com/nuwainfo/ffl-mcp ffl-mcp

Configuração MCP (JSON manual)

{
  "mcpServers": {
    "ffl": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/nuwainfo/ffl-mcp", "ffl-mcp"],
      "env": {
        "ALLOWED_BASE_DIR": "/Users/you/Downloads",
        "FFL_USE_STDIN": "1"
      }
    }
  }
}

Ferramentas

Compartilhamento

Ferramenta	Entrada
`fflShareText(text, name?, ...)`	Texto simples
`fflShareBase64(dataB64, name?, ...)`	Dados binários (codificados em base64)
`fflShareFile(path, name?, ...)`	Arquivo ou pasta local único
`fflShareFiles(paths, name?, ...)`	Vários arquivos (ffl os compacta automaticamente em um único download)

Opções comuns para todas as ferramentas de compartilhamento:

Opção	Padrão	Descrição
`e2ee`	`False`	Criptografia de ponta a ponta
`qrInTerminal`	`False`	Retorna arte ASCII QR (`qrCode` na resposta)
`authUser` / `authPassword`	—	Autenticação Básica HTTP para proteger o link
`maxDownloads`	`1`	Para de servir após N downloads (somente P2P)
`timeoutSeconds`	`1800`	Tempo limite de inatividade em segundos (somente P2P)
`recipientAuth`	—	`pickup` (código de 6 dígitos), `pubkey` (RSA), `pubkey+pickup` ou `email` (OTP)
`pickupCode`	auto	Código de coleta específico para o modo `pickup`
`recipientPublicKey`	—	Caminho para o arquivo `.fflpub` para o modo `pubkey`
`recipientEmail`	—	E-mail(s) para o modo OTP `email`, separados por vírgula
`alias`	—	Alias de link personalizado, ex.: `my-release` (requer conta Standard+)
`receipt`	—	Notificação por e-mail quando o destinatário baixa
`receiptConfirm`	—	Exige confirmação do destinatário antes do download; passe uma mensagem ou `""`
`forceRelay`	`False`	Desativa WebRTC, roteia todo o tráfego pelo túnel
`port`	—	Porta do servidor HTTP local (detecção automática por padrão). Útil com túneis fixos.
`invite`	`False`	Abre a página de convite do ffl em um navegador local com o link de compartilhamento gerado.
`enableReporting`	`False`	Ativa o relatório de erros de diagnóstico do ffl. Desativado por padrão.
`upload`	—	Envia para o servidor FFL em vez de P2P — ex.: `"1 day"`, `"6 hours"` (requer conta Standard+)
`resumeUpload`	`False`	Retoma um upload interrompido
`proxy`	—	URL do proxy, ex.: `socks5://127.0.0.1:9050`

Opções adicionais para fflShareFile / fflShareFiles:

Opção	Padrão	Descrição
`preview`	`False`	Acrescenta `?preview=true` ao link retornado, para que a página de download do ffl abra diretamente na visualização de pré-visualização completa em vez do cartão flutuante normal.
`exclude`	—	Padrões glob ou regex para excluir, separados por vírgula — ex.: `*.pyc,__pycache__` ou `re:\.env$`
`pause`	—	Pausa o upload do servidor em uma porcentagem de 1 a 99. Requer `upload`.
`vfs`	`False`	Expõe como servidor VFS (URI `vfs://`) — somente `fflShareFile`
`preferredTunnel`	—	Define o túnel preferido para esta e futuras execuções — `cloudflare`, `ngrok`, `bore`, etc.

preview afeta apenas a string de consulta do link retornado e funciona para qualquer compartilhamento (arquivo único, pasta ou vários arquivos). As rotas sidecar de pré-visualização (/manifest, /file, /thumb — os dados de manifesto/miniatura por trás dessa página de pré-visualização) são um mecanismo separado, sempre ativo: o MCP as inicia automaticamente para compartilhamentos de pasta e de vários arquivos, independentemente de preview, e nunca para compartilhamentos de arquivo único.

Campos de resposta: sessionId, link, pid, qrCode? (arte ASCII quando qrInTerminal=True), debugLogPath?

Download

fflDownload(url, outputPath?, resume?, authUser?, authPassword?,
            recipientAuth?, pickupCode?, recipientPrivateKey?, proxy?,
            enableReporting?)
  -> {ok, returncode, outputPath?, transferMode?, transferInfo?, message?, ...}

Baixa de URLs FastFileLink (WebRTC P2P quando possível, fallback HTTP) ou de qualquer URL HTTP(S) (funciona como wget).

`transferMode`	Significado
`webrtc_p2p`	Peer-to-peer direto via WebRTC (mais rápido)
`p2p_tcp` / `p2p_quic`	Peer-to-peer direto via TCP/QUIC bruto
`http_fallback`	Retransmissão HTTP quando o P2P falha
`http_direct`	Download HTTP normal (URL não FastFileLink)

Para links autenticados: passe recipientAuth + pickupCode (modo de coleta) ou recipientPrivateKey (modo de chave pública). Defina enableReporting=True somente quando quiser optar pelo relatório de erros de diagnóstico do ffl para solução de problemas.

Geração de chaves

fflKeygen(name?) -> {ok, returncode, output}

Gera um par de chaves RSA para autenticação de destinatário sem senha pubkey:

<name>.fflpub — compartilhe com o remetente (passe como recipientPublicKey)
<name>.fflkey — mantenha privado (passe como recipientPrivateKey ao baixar)

Gerenciamento de sessões

fflListSessions() — lista sessões de compartilhamento ativas
fflStopSession(sessionId) — encerra uma sessão
fflGetSession(sessionId) — obtém detalhes da sessão
fflGetSessionEvents(sessionId, limit=50) — recupera eventos de webhook

Notas

FFL_USE_STDIN=1 evita gravar payloads de texto/base64 em disco.
As pré-visualizações de pasta e vários arquivos iniciam um servidor webhook local para que o FFL possa registrar rotas de pré-visualização.
FFL_DEBUG=1 salva a saída do ffl em um arquivo de log temporário; o caminho é retornado como debugLogPath. Defina FFL_DEBUG=/path/to/log.txt para usar um caminho fixo.
ALLOWED_BASE_DIR restringe fflShareFile/fflShareFiles a um diretório específico.

Testes

# Unit + binary tests (no network needed)
python -m unittest discover -s tests -p "*Test.py" -v

# All tests including share/download round-trips (requires network)
FFL_INTEGRATION_TESTS=1 python -m unittest discover -s tests -p "*Test.py" -v