mcp-tools-for-agents

Dê mãos ao seu agente de IA. Um binário, nenhuma instalação.

Um servidor MCP local, em Rust, que entrega ao seu agente ferramentas reais de vídeo, áudio e arquivos. Sem API, sem UI, sem runtime. São 36 tools compiladas em um executável único: baixe o mcp-tools da sua plataforma, aponte o host MCP para ele e pronto.

Funciona com Claude Code, Claude Desktop, Cursor e qualquer host MCP.

Por que Rust

O servidor precisa de um arquivo:

• Binário único por plataforma. Linux (x86_64, arm64), macOS (Intel, Apple Silicon) e Windows. Sem runtime, sem dependência de sistema.

• FFmpeg e yt-dlp sob demanda. Se não estiverem no PATH nem ao lado do binário, o servidor baixa os builds estáticos oficiais na primeira chamada e guarda em uma pasta de cache. Desligue com MCP_AUTO_DOWNLOAD=false.

• Fonte e modelos embutidos. A DejaVu Sans Bold (para texto e legenda), o YuNet (detector de rosto do OpenCV Zoo) e o Silero VAD (detector de fala) vão dentro do executável.

• Transcrição, visão e fala nativas. transcribe_audio usa o whisper.cpp (whisper-rs); smart_crop roda o YuNet e remove_silence e add_background_music rodam o Silero VAD no tract, runtime ONNX em Rust puro. Nada de OpenCV ou onnxruntime instalado.

• Mesmos princípios. Erro que ensina ({error, code, hint}), workspace como fronteira, jobs em background, resposta sempre tipada, um arquivo por tool.

Related MCP server: DJAI Tools MCP

Em 60 segundos

Baixe o pacote da sua plataforma na página de releases (ou compile, abaixo), descompacte e rode:

WORKSPACE_DIR=/dados/videos ./mcp-tools     # servidor no ar, via stdio

Na primeira tool que precisar de FFmpeg (ou de yt-dlp) o binário é baixado para o cache. Se preferir, coloque ffmpeg, ffprobe e yt-dlp ao lado do mcp-tools ou no PATH: eles têm prioridade e nada é baixado.

Compilar do fonte

cargo build --release --features full   # binário completo (transcrição + visão + fala)
cargo build --release                   # binário leve, sem os extras

Requisitos de build: Rust estável (1.85+); com --features full, também cmake e um compilador C++ (o whisper.cpp é compilado e linkado estaticamente). O executável fica em target/release/mcp-tools (~24 MB). No Linux ele depende só da glibc e da libstdc++ do sistema, presentes em qualquer distribuição.

Plugar no agente

{
  "mcpServers": {
    "mcp-tools-for-agents": {
      "command": "/caminho/mcp-tools",
      "env": { "WORKSPACE_DIR": "/dados/videos" }
    }
  }
}

Cole isso no .mcp.json (Claude Code), no claude_desktop_config.json (Claude Desktop) ou no equivalente do seu host. Pronto: peça "corta os 10 primeiros segundos do intro.mp4" e veja acontecer.

Claude Code neste repositório

Abrindo este repositório no Claude Code nada precisa ser compilado: o hook SessionStart em .claude/settings.json roda scripts/install-mcp-tools.sh, que baixa o mcp-tools da última release para bin/ (pasta ignorada pelo git), e o .mcp.json sobe o servidor por scripts/mcp-tools-run.sh, que espera esse download terminar (ou baixa sozinho) antes de executar bin/mcp-tools. Para atualizar à mão ou fixar uma versão:

sh scripts/install-mcp-tools.sh                        # última release
MCP_TOOLS_VERSION=v0.1.0 sh scripts/install-mcp-tools.sh   # versão fixa
MCP_TOOLS_FORCE=true sh scripts/install-mcp-tools.sh   # baixa de novo

Publicar uma release

Automático. A cada merge em producao, o workflow .github/workflows/release.yml cria a próxima tag vX.Y.Z, compila o binário completo (--features full) para Linux x86_64 e arm64, macOS Intel e Apple Silicon e Windows, e anexa os pacotes à release.

Tools

Ative só o que precisa com MCP_DOMAINS=video,files.

O que é baixado, e quando

O binário não traz FFmpeg nem yt-dlp dentro (são ~150 MB e ~30 MB, com licenças próprias). Ele os procura nesta ordem e para na primeira que encontrar:

1. o caminho em FFMPEG_BIN, FFPROBE_BIN ou YTDLP_BIN, se for um caminho;

2. a pasta onde o mcp-tools está;

3. o PATH;

4. a pasta de cache (MCP_CACHE_DIR);

5. download, se MCP_AUTO_DOWNLOAD=true (padrão).

Cache padrão: ~/.cache/mcp-tools-for-agents (Linux), ~/Library/Caches/mcp-tools-for-agents (macOS), %LOCALAPPDATA%\mcp-tools-for-agents (Windows). Para um pacote 100% offline, coloque esses arquivos na pasta do binário (ffmpeg, ffprobe, yt-dlp, models/ggml-base.bin, fonts/DejaVuSans-Bold.ttf).

Download de qualquer fonte

download_video e get_video_info aceitam qualquer URL http(s). São três tentativas, nesta ordem:

1. Extractor nativo do yt-dlp — cobre mais de mil sites.

2. Extractor genérico — lê o HTML da página e procura <video>, <source>, HLS .m3u8, DASH .mpd, players conhecidos e JSON-LD.

3. Varredura própria — o servidor busca a página, junta as mídias diretas e desce um nível nos iframe.

Não há como baixar conteúdo com DRM nem páginas que exigem login. Nesses casos o hint do erro diz para não insistir.

Efeitos sonoros do Freesound

add_sound_effects recebe uma lista de efeitos com o instante em que cada um toca e aplica tudo em um único passo do ffmpeg. Cada efeito vem de query (busca no Freesound), sound_id (resultado de search_sound_effects) ou audio (arquivo do workspace). A chave da API já vem embutida em config.rs; FREESOUND_API_KEY no ambiente substitui.

Features opcionais

Algumas tools dependem de bibliotecas pesadas, ligadas por feature do Cargo:

cargo build --release --features transcribe   # whisper-rs: transcribe_audio
cargo build --release --features vision       # tract + YuNet: smart_crop com mode="face"
cargo build --release --features vad          # tract + Silero VAD: remove_silence e ducking com method="vad"
cargo build --release --features full         # as três (é o que a release publica)

Sem a feature, a tool continua registrada e devolve um erro unavailable explicando como habilitar; smart_crop segue funcionando com mode="center" e remove_silence e add_background_music com o limiar de dB (method="db").

O modelo do Silero VAD em core/models/silero_vad_16k.onnx é o oficial (16 kHz, opset 15) com os nós If resolvidos para forma fixa, que o tract não traduz; scripts/prepare-silero-vad.py regenera o arquivo a partir do original.

Configuração

Todas as variáveis estão em .env.example. As principais:

Como é por dentro

A árvore fica na raiz do crate (o Cargo.toml aponta para a raiz em vez de src/):

server.rs     cria o McpServer, monta o Runtime e registra os domínios
config.rs     único lugar que lê variáveis de ambiente (Settings)
core/         ffmpeg, paths, jobs, errors, binários externos, rede. Não conhece MCP.
domains/      um módulo por área, um arquivo por tool
tests/        espelha a estrutura acima

Uma tool inteira, do jeito que todas são:

pub fn delete_file(runtime: &Runtime, path: &str) -> ToolResult<DeleteFileResult> {
    let target = runtime.workspace.existing(path)?;
    let size = std::fs::metadata(&target).map(|m| m.len()).unwrap_or(0);
    std::fs::remove_file(&target).map_err(|error| {
        ToolError::new(format!("Não foi possível apagar '{path}': {error}"), ErrorCode::NotFound)
    })?;
    Ok(DeleteFileResult { deleted: runtime.workspace.relative(&target), freed_bytes: size })
}

#[derive(Debug, Deserialize, JsonSchema)]
pub struct Params {
    /// Arquivo, relativo ao workspace.
    pub path: String,
}

pub fn register(mcp: &mut McpServer, runtime: &Arc<Runtime>) {
    let runtime = Arc::clone(runtime);
    mcp.tool(
        "delete_file",
        "Apaga permanentemente um arquivo do workspace.\n\n\
         Use para limpar saídas intermediárias. Não há lixeira nem desfazer.",
        move |params: Params| guarded(delete_file(&runtime, &params.path)),
    );
}

Função pura e testável em cima, registro com a description para o agente embaixo. Err(ToolError) vira {error, code, hint} na resposta.

Contribuir

Quer uma tool nova? Copie domains/files/delete.rs, troque o miolo, escreva o teste espelhado em tests/, adicione a linha na tabela acima. As regras completas estão em .claude/rules/arquitetura.md, e se você usa Claude Code, /nova-tool faz o roteiro.

Antes do PR, os três precisam passar:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

Os testes que usam ffmpeg são pulados quando o binário não está instalado.

Licença

MIT. A fonte DejaVu embutida segue a licença Bitstream Vera (core/fonts/LICENSE-DejaVu.txt); o modelo YuNet é MIT (OpenCV Zoo).