CLI-, MCP- und A2A-Integration

Lokale Agents wie Codex und WorkBuddy nutzen OpenFiles über MCP oder CLI + Skill. Diese Zugänge teilen Funktionen und Aufgaben mit A2A. Für den Alltag genügen Installation und setup unten. A2A ist für eigene Clients gedacht: /a2a ist keine MCP-URL, und der aufrufende Prozess muss auf demselben Rechner wie OpenFiles laufen.

CLI installieren

Benötigt werden Node.js 22 oder neuer und ein Desktop-Build mit resources/agent. Die CLI wird mit der App geliefert und einmal aus diesem lokalen Ordner installiert. Für den Standardpfad auf macOS:

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

Unter Windows nutze PowerShell und ersetze den Beispielpfad durch resources\agent in deiner Installation:

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

Für die Entwicklung aus Quellcode führe im Repository npm run build und danach npm install -g ./dist/agent aus. Anschließend reicht der Befehl openfiles ohne vollständigen Skriptpfad.

Codex verbinden

Dieser Befehl startet oder verbindet OpenFiles, registriert MCP über die Codex-CLI und installiert den Skill unter ~/.agents/skills/openfiles. Der Befehl codex muss verfügbar sein. Starte Codex danach neu, um die Konfiguration zu laden.

openfiles setup codex

WorkBuddy verbinden

Dieser Befehl startet oder verbindet OpenFiles und ergänzt ~/.workbuddy/mcp.json. Andere Server bleiben erhalten; die vorherige Konfiguration wird gesichert. Starte WorkBuddy danach neu. Für CLI + Skill kannst du zusätzlich die ausgegebene ZIP-Datei skillArchive über den Skill-Import laden. MCP ist bereits nutzbar.

openfiles setup workbuddy

Das erste setup erstellt und autorisiert ~/OpenFilesAgent; Ergebnisse liegen im Unterordner output. Lege Eingaben dort ab und bitte den Agent etwa, mit OpenFiles alle CDR-Seiten als SVG-ZIP zu exportieren, bis zum Abschluss zu warten und den Ausgabepfad zu nennen. --workspace DIR wählt einen bestehenden Ordner, --output DIR den Ausgabeordner. --dry-run zeigt nur die Konfigurationspfade.

Freigaben und Desktop-Pfad werden in ~/.openfiles/agent/setup.json gespeichert. CLI, MCP und installierter Skill starten den Desktop damit und lesen Adresse und Token automatisch. Feste Ports oder Tokens sind in der Clientkonfiguration unnötig. Für neue Freigaben eines laufenden Gateways beende OpenFiles und wiederhole setup; laufende Aufgaben werden nicht zwangsweise abgebrochen.

Offizielle Konfigurationshinweise: Codex MCP · WorkBuddy MCP

Verbindung prüfen und Fehler beheben

doctor prüft ohne App-Start; capabilities startet den eingerichteten Desktop. schema beschreibt Argumente offline. Die MCP-Verbindungsanzeige bestätigt nur den laufenden Adapter: Prüfe mit capabilities auch den Dateidienst.

openfiles doctor
openfiles capabilities
openfiles schema openfiles_convert

Wird die App nicht gefunden, gib mit setup codex --app /absolute/path/to/OpenFiles die ausführbare Datei an; für WorkBuddy ersetze den Clientnamen. Nach einem Umzug von Node.js oder der App installiere die CLI und führe setup erneut aus. Prüfe bei Ordnerfehlern readRoots / outputRoots. Suche mit tasks, bevor du einen Schreibvorgang mit ungewissem Ergebnis erneut sendest.

Gateway manuell aktivieren (optional)

Nutze einen Build mit resources/agent/openfiles.cjs (auf macOS in OpenFiles.app/Contents/Resources) und Node.js 22 oder neuer für den Client. Starte OpenFiles mit --agent-read-root=/absolute/input --agent-output-root=/absolute/output. Beide Verzeichnisse müssen existieren; wiederhole Flags für weitere Freigaben. Das Gateway ist standardmäßig aus. Zum Ändern der Freigaben beende und starte OpenFiles neu. Im Quellcode-Checkout stehen folgende Befehle bereit:

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

Funktionen ermitteln und ausführen

Lies zuerst capabilities: conversionFormats enthält konkrete Konvertierungspaare, metadata.formats bearbeitbare Felder. openfiles_inspect liefert dateispezifische Ziele. HTML, Markdown und SVG können ohne Skripte oder externe Ressourcen als PNG/PDF gerendert werden. CDR wird als ZIP aller SVG-Seiten exportiert. openfiles_workflow führt gespeicherte .ofw aus; sourcePaths ersetzt Dateieingaben, Batch-Ordner und Masken benötigen ebenfalls Freigaben. PDF/OFD-Metadaten verwenden metadata.edit oder metadata.remove. AI-Knoten benötigen installierte Laufzeiten und können Modelle herunterladen. Speichere dies mit angepassten Pfaden als request.json:

JPEG und radiometrisches JPEG teilen Dateiendungen. Bei contentDetectionRequired sind Ziele Kandidaten; der Renderer prüft den Inhalt bei der Ausführung.

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

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

Aufgaben verfolgen und wiederfinden

Schreibvorgänge erhalten Originale und legen unter outputDir ein neues openfiles-*-Verzeichnis an. Frage bis completed, failed oder canceled ab und prüfe result.paths sowie Dateifehler. --wait wartet standardmäßig 300 Sekunden, änderbar mit --timeout. Bei Zeitüberschreitung läuft die Aufgabe weiter. Suche vor erneutem Einreichen mit tasks ihre ID. Listen akzeptieren --json oder --input mit state, contextId, pageSize, pageToken; Ausgaben stehen in der Einzelaufgabe. Bis zu 100 Aufgaben bleiben gespeichert, acht können gleichzeitig laufen. Neustart löscht den Verlauf. Abbruch erhält fertige Ausgaben.

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

MCP verbinden und Skill installieren

mcp-config gibt Einstellungen nur aus; registriere Befehl und Argumente im externen Client. mcp nutzt zeilengetrenntes JSON-RPC über stdio, skill gibt die mitgelieferte Anleitung aus. Die Verbindung steht in ~/.openfiles/agent/connection.json. Eigene Pfade koppeln Desktop --agent-connection=PATH und Client --connection PATH. Halte den Bearer-Token geheim. Ersetze bei Bedarf dist/agent/openfiles.cjs durch den installierten Clientpfad. Ausgehende MCP-Server im Chat werden unabhängig davon konfiguriert.

A2A aufrufen

Lies die Loopback-URL aus der Verbindungsdatei und rufe /.well-known/agent-card.json ab. securityRequirements deklariert Bearer-Authentifizierung. Sende das folgende JSON per POST an /a2a mit Content-Type: application/json, A2A-Version: 1.0, Authorization: Bearer <token>. Verwende bei Transportwiederholungen dieselbe Nachrichten-ID und Nachricht. Frage GetTask mit { "id": "TASK_ID" } ab oder nutze CancelTask. ListTasks unterstützt contextId, status, statusTimestampAfter, Seitennavigation und includeArtifacts. Streaming, Push und Planung in natürlicher Sprache sind nicht verfügbar. Pfade gehören zu diesem Rechner; Screenshot-Bearbeitung und Plugin-Installation bleiben Desktop-Aktionen.

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