Integração CLI, MCP e A2A

Agents locais como Codex e WorkBuddy usam o OpenFiles por MCP ou CLI + Skill. Essas interfaces compartilham recursos e tarefas com A2A. Para o uso diário, instale o CLI e execute setup abaixo. A2A é para clientes próprios: /a2a não é uma URL MCP, e o processo deve executar no mesmo computador que o OpenFiles.

Instalar o CLI

É necessário Node.js 22 ou posterior e uma versão desktop com resources/agent. O CLI acompanha o aplicativo; instale uma vez a partir desse diretório local. Para a instalação padrão no macOS:

npm install -g "/Applications/OpenFiles.app/Contents/Resources/agent"

No Windows, use PowerShell e substitua o caminho de exemplo pelo diretório resources\agent da sua instalação:

npm install -g "C:\path\to\OpenFiles\resources\agent"

Para desenvolver a partir do código-fonte, execute npm run build e depois npm install -g ./dist/agent no repositório. Em seguida, use o comando openfiles sem memorizar o caminho do script.

Conectar o Codex

Este comando inicia ou conecta o OpenFiles, registra MCP pelo CLI do Codex e instala o Skill em ~/.agents/skills/openfiles. O comando codex deve estar disponível. Reinicie o Codex para carregar a configuração.

openfiles setup codex

Conectar o WorkBuddy

Este comando inicia ou conecta o OpenFiles e adiciona o servidor a ~/.workbuddy/mcp.json, preservando os outros servidores e uma cópia da configuração anterior. Reinicie o WorkBuddy. Para CLI + Skill, também é possível importar o ZIP skillArchive indicado pela opção de upload de Skills. MCP já está pronto para uso.

openfiles setup workbuddy

O primeiro setup cria e autoriza ~/OpenFilesAgent, com resultados na subpasta output. Coloque os arquivos ali e peça ao Agent, por exemplo, para exportar um CDR com OpenFiles como ZIP de todas as páginas SVG, aguardar a conclusão e informar o caminho. Use --workspace DIR para uma pasta existente e --output DIR para a saída. --dry-run apenas mostra os caminhos de configuração.

As permissões e o caminho do desktop ficam em ~/.openfiles/agent/setup.json. CLI, MCP e o Skill instalado iniciam o desktop com essa configuração e leem automaticamente o endereço e token atuais. Não há porta nem token fixos na configuração do cliente. Para mudar as permissões de um gateway em execução, saia do OpenFiles e repita setup; tarefas não são interrompidas à força.

Referências oficiais: Codex MCP · WorkBuddy MCP

Verificar a conexão e resolver problemas

doctor verifica sem iniciar o aplicativo; capabilities inicia o desktop configurado. schema descreve argumentos offline. O indicador MCP confirma apenas o adaptador; execute capabilities para verificar o serviço de arquivos.

openfiles doctor
openfiles capabilities
openfiles schema openfiles_convert

Se o aplicativo não for encontrado, indique seu executável com setup codex --app /absolute/path/to/OpenFiles, trocando o cliente para WorkBuddy. Ao mover Node.js ou o aplicativo, reinstale o CLI e execute setup novamente. Verifique readRoots / outputRoots em erros de pasta. Consulte tasks antes de repetir uma gravação com resultado incerto.

Ativar o gateway manualmente (opcional)

Use uma versão com resources/agent/openfiles.cjs (em OpenFiles.app/Contents/Resources no macOS) e Node.js 22 ou posterior no cliente. Inicie OpenFiles com --agent-read-root=/absolute/input --agent-output-root=/absolute/output. Ambos os diretórios devem existir; repita as opções para várias permissões. O gateway está desligado por predefinição. Saia e reinicie para alterar permissões. No código-fonte, use:

npm run build-electron
npm run agent -- capabilities
npm run agent -- mcp-config
npm run agent -- skill

Descobrir e executar operações

Consulte primeiro capabilities: conversionFormats lista pares de conversão e metadata.formats os campos editáveis. openfiles_inspect devolve destinos por ficheiro. HTML, Markdown e SVG geram PNG/PDF sem scripts ou recursos externos. CDR gera um ZIP com todas as páginas SVG. openfiles_workflow executa .ofw guardados; sourcePaths substitui entradas de ficheiros, e pastas batch e máscaras também precisam de autorização. PDF/OFD usam metadata.edit ou metadata.remove. Nós IA precisam de ambientes instalados e podem transferir modelos. Guarde isto como request.json, substituindo os caminhos:

JPEG e JPEG radiométrico partilham extensões. Com contentDetectionRequired, os destinos são candidatos e o motor valida o conteúdo na execução.

{"sourcePaths":["/input/design.cdr"],"outputDir":"/output","format":"zip"}

node dist/agent/openfiles.cjs call openfiles_convert --input request.json --wait

Acompanhar e recuperar tarefas

As escritas preservam originais e criam um diretório openfiles-* sob outputDir. Consulte até completed, failed ou canceled e verifique result.paths e erros individuais. --wait espera 300 segundos por predefinição; ajuste com --timeout. A tarefa continua após o limite. Procure o ID com tasks antes de reenviar. A lista aceita --json ou --input com state, contextId, pageSize, pageToken; consulte a tarefa individual para obter saídas. São mantidas até 100 tarefas, com oito em simultâneo. Reiniciar apaga o histórico; cancelar mantém saídas concluídas.

node dist/agent/openfiles.cjs tasks
node dist/agent/openfiles.cjs task TASK_ID --wait
node dist/agent/openfiles.cjs cancel TASK_ID

Ligar MCP e instalar o Skill

mcp-config imprime a configuração sem alterar definições. Registe comando e argumentos no cliente externo. mcp usa JSON-RPC por linhas em stdio; skill imprime o guia incluído. O descritor é ~/.openfiles/agent/connection.json. Um caminho próprio associa --agent-connection=PATH no desktop e --connection PATH no cliente. Mantenha privado o token bearer. Substitua dist/agent/openfiles.cjs pelo caminho do cliente instalado quando necessário. Os servidores MCP de saída da conversa são configurados separadamente.

Chamar A2A

Leia o URL de loopback no descritor e consulte /.well-known/agent-card.json. securityRequirements declara autenticação bearer. Envie o JSON seguinte por POST para /a2a com Content-Type: application/json, A2A-Version: 1.0, Authorization: Bearer <token>. Reutilize ID e mensagem em novas tentativas de transporte. Consulte GetTask com { "id": "TASK_ID" } ou use CancelTask. ListTasks aceita contextId, status, statusTimestampAfter, paginação e includeArtifacts. Não há streaming, notificações push ou planeamento em linguagem natural. Os caminhos pertencem a este computador; editar capturas e instalar plugins continua no desktop.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "unique-request-id",
      "role": "ROLE_USER",
      "parts": [{"data": {"name": "openfiles_capabilities", "arguments": {}}}]
    },
    "configuration": {"returnImmediately": true}
  }
}