Integración CLI, MCP y A2A

Los agentes locales como Codex y WorkBuddy usan OpenFiles mediante MCP o CLI + Skill. Comparten capacidades y tareas con A2A. Para el uso diario basta con instalar el CLI y ejecutar setup. A2A es para clientes propios: /a2a no es una URL MCP y el proceso debe ejecutarse en el mismo equipo que OpenFiles.

Instalar el CLI

Necesitas Node.js 22 o posterior y una versión de escritorio que incluya resources/agent. El CLI viene con la aplicación; instálalo una vez desde ese directorio local. Para la ubicación predeterminada en macOS:

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

En Windows usa PowerShell y sustituye la ruta de ejemplo por el directorio resources\agent de tu instalación:

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

Para desarrollar desde el código fuente, ejecuta npm run build y después npm install -g ./dist/agent en el repositorio. Luego puedes usar openfiles sin recordar la ruta del script.

Conectar Codex

Este comando inicia OpenFiles o se conecta a él, registra MCP mediante el CLI de Codex e instala el Skill en ~/.agents/skills/openfiles. El comando codex debe estar disponible. Reinicia Codex después para cargar la configuración.

openfiles setup codex

Conectar WorkBuddy

Este comando inicia OpenFiles o se conecta a él y añade el servidor a ~/.workbuddy/mcp.json. Conserva los otros servidores y guarda una copia de la configuración anterior. Reinicia WorkBuddy. Para CLI + Skill, también puedes importar el ZIP skillArchive indicado desde la opción de carga de Skills. MCP ya está disponible.

openfiles setup workbuddy

El primer setup crea y autoriza ~/OpenFilesAgent, con las salidas en output. Coloca allí los archivos y pide al agente, por ejemplo, que exporte un CDR con OpenFiles como ZIP de todas sus páginas SVG, espere a que termine e indique la ruta. Usa --workspace DIR para un directorio existente y --output DIR para la salida. --dry-run solo muestra las rutas de configuración.

Los permisos y la ruta del escritorio se guardan en ~/.openfiles/agent/setup.json. CLI, MCP y el Skill instalado inician el escritorio con esa configuración y leen la dirección y el token actuales automáticamente. No se fijan puertos ni tokens en el cliente. Para cambiar los permisos de una pasarela activa, cierra OpenFiles y repite setup; no se interrumpen tareas por la fuerza.

Referencias oficiales: Codex MCP · WorkBuddy MCP

Comprobar la conexión y resolver problemas

doctor comprueba la conexión sin iniciar la aplicación; capabilities inicia el escritorio configurado. schema describe argumentos sin conexión. El indicador MCP solo confirma el adaptador: llama a capabilities para comprobar el servicio de archivos.

openfiles doctor
openfiles capabilities
openfiles schema openfiles_convert

Si no se encuentra la aplicación, indica el ejecutable con setup codex --app /absolute/path/to/OpenFiles; cambia el nombre del cliente para WorkBuddy. Si mueves Node.js o la aplicación, reinstala el CLI y repite setup. Revisa readRoots / outputRoots ante errores de directorio. Consulta tasks antes de reenviar una escritura cuyo resultado sea incierto.

Activar la pasarela manualmente (opcional)

Usa una compilación con resources/agent/openfiles.cjs (en OpenFiles.app/Contents/Resources en macOS) y Node.js 22 o posterior para el cliente. Inicia OpenFiles con --agent-read-root=/absolute/input --agent-output-root=/absolute/output. Ambos directorios deben existir; repite las opciones para varios permisos. La puerta de enlace está desactivada por defecto. Sal y reinicia para cambiar permisos. Desde el código fuente puedes usar:

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

Descubrir y ejecutar operaciones

Consulta primero capabilities: conversionFormats enumera pares de conversión y metadata.formats los campos editables. openfiles_inspect devuelve destinos por archivo. HTML, Markdown y SVG generan PNG/PDF con scripts y recursos externos desactivados. CDR genera un ZIP con todas las páginas SVG. openfiles_workflow ejecuta .ofw guardados; sourcePaths reemplaza entradas de archivos y las carpetas de lote y máscaras también necesitan permiso. PDF/OFD usan metadata.edit o metadata.remove. Los nodos IA requieren entornos instalados y pueden descargar modelos. Guarda lo siguiente como request.json sustituyendo las rutas:

JPEG y JPEG radiométrico comparten extensiones. Con contentDetectionRequired, los destinos son candidatos y el motor valida el contenido al ejecutar.

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

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

Seguir y recuperar tareas

Las escrituras conservan originales y crean un directorio openfiles-* bajo outputDir. Consulta hasta completed, failed o canceled y revisa result.paths y errores por archivo. --wait espera 300 segundos por defecto; cámbialo con --timeout. La tarea continúa tras el límite. Busca su ID con tasks antes de reenviarla. La lista admite --json o --input con state, contextId, pageSize, pageToken; consulta una tarea para obtener salidas. Se conservan hasta 100 tareas y se ejecutan ocho a la vez. Reiniciar borra el historial; cancelar conserva salidas terminadas.

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

Conectar MCP e instalar el Skill

mcp-config imprime la configuración sin cambiar ajustes. Registra el comando y argumentos en el cliente externo. mcp usa JSON-RPC por líneas en stdio; skill imprime la guía incluida. El descriptor es ~/.openfiles/agent/connection.json. Una ruta personalizada combina --agent-connection=PATH del escritorio y --connection PATH del cliente. Mantén privado el token bearer. Sustituye dist/agent/openfiles.cjs por la ruta del cliente instalado cuando corresponda. Los servidores MCP salientes del chat se configuran por separado.

Invocar A2A

Lee la URL local del descriptor y consulta /.well-known/agent-card.json. securityRequirements declara autenticación bearer. Envía el siguiente JSON por POST a /a2a con Content-Type: application/json, A2A-Version: 1.0, Authorization: Bearer <token>. Reutiliza ID y mensaje en reintentos de transporte. Consulta GetTask con { "id": "TASK_ID" } o usa CancelTask. ListTasks admite contextId, status, statusTimestampAfter, paginación e includeArtifacts. No hay streaming, notificaciones push ni planificación en lenguaje natural. Las rutas son de este equipo; la edición de capturas e instalación de plugins siguen en el escritorio.

{
  "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}
  }
}