CLI, MCP 및 A2A 연동

Codex와 WorkBuddy 같은 로컬 Agent는 MCP 또는 CLI + Skill로 OpenFiles를 사용할 수 있습니다. A2A와 파일 기능 및 작업 관리를 공유합니다. 일반적인 연결은 아래 설치와 setup만으로 완료됩니다. A2A는 직접 개발하는 클라이언트용이며 /a2a를 MCP URL로 사용할 수 없습니다. 호출 프로세스는 OpenFiles와 같은 컴퓨터에서 실행해야 합니다.

CLI 설치

Node.js 22 이상과 resources/agent가 포함된 OpenFiles 데스크톱 빌드가 필요합니다. CLI는 앱에 포함되며 로컬 폴더에서 한 번만 설치합니다. macOS 기본 설치 위치의 예입니다:

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

Windows에서는 PowerShell을 사용하고 예제 경로를 실제 설치 폴더의 resources\agent로 바꾸세요:

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

소스 개발 시 저장소에서 npm run build를 실행한 후 npm install -g ./dist/agent를 실행합니다. 이후 스크립트 경로 대신 openfiles 명령을 사용할 수 있습니다.

Codex 연결

다음 명령은 OpenFiles를 시작하거나 연결하고, Codex CLI로 MCP를 등록하며, ~/.agents/skills/openfiles에 Skill을 설치합니다. codex 명령을 사용할 수 있어야 합니다. 완료 후 Codex를 다시 시작해 설정을 불러오세요.

openfiles setup codex

WorkBuddy 연결

다음 명령은 OpenFiles를 시작하거나 연결하고 ~/.workbuddy/mcp.json에 서버를 병합합니다. 기존 서버는 유지하고 이전 설정은 백업합니다. 완료 후 WorkBuddy를 다시 시작하세요. CLI + Skill도 필요하면 출력된 skillArchive ZIP을 스킬 업로드 기능으로 가져올 수 있습니다. MCP는 바로 사용할 수 있습니다.

openfiles setup workbuddy

첫 setup은 ~/OpenFilesAgent를 만들고 접근을 허용하며 결과는 output 하위 폴더에 저장합니다. 입력 파일을 넣고 Agent에게 OpenFiles로 CDR의 모든 페이지를 SVG ZIP으로 내보낸 뒤 완료를 기다려 저장 위치를 알려 달라고 요청하세요. 기존 폴더는 --workspace DIR, 출력 폴더는 --output DIR로 지정합니다. --dry-run은 설정 경로만 미리 보여 줍니다.

허용 폴더와 앱 경로는 ~/.openfiles/agent/setup.json에 저장됩니다. 이후 CLI, MCP, 설치된 Skill이 해당 설정으로 앱을 시작하고 현재 주소와 token을 자동으로 읽습니다. 고정 포트나 token을 클라이언트 설정에 넣지 않습니다. 실행 중인 게이트웨이의 허용 폴더를 바꾸려면 OpenFiles를 종료하고 setup을 다시 실행하세요. 기존 작업을 강제 중단하지 않습니다.

공식 설정 문서: Codex MCP · WorkBuddy MCP

연결 확인 및 문제 해결

doctor는 앱을 시작하지 않고 연결을 확인하며 capabilities는 설정된 앱을 시작합니다. schema는 오프라인에서 도구 인수를 보여 줍니다. MCP 연결 표시만으로 파일 서비스가 준비되었다고 볼 수 없으므로 capabilities도 호출하세요.

openfiles doctor
openfiles capabilities
openfiles schema openfiles_convert

앱을 찾지 못하면 setup codex --app /absolute/path/to/OpenFiles로 실행 파일을 지정하고 WorkBuddy에서는 클라이언트 이름을 바꾸세요. Node.js나 앱 위치를 바꾼 뒤에는 CLI를 다시 설치하고 setup을 실행하세요. 폴더 오류는 readRoots / outputRoots를 확인하고, 결과가 불확실한 쓰기는 재요청 전에 tasks로 확인하세요.

게이트웨이 수동 활성화 (선택 사항)

resources/agent/openfiles.cjs를 포함한 빌드를 사용합니다(macOS는 OpenFiles.app/Contents/Resources 내부). 클라이언트에는 Node.js 22 이상이 필요합니다. OpenFiles 실행 파일을 --agent-read-root=/absolute/input --agent-output-root=/absolute/output와 함께 시작합니다. 두 폴더는 미리 존재해야 하며 여러 권한에는 플래그를 반복합니다. 게이트웨이는 기본으로 꺼져 있습니다. 권한 변경은 종료 후 재시작해야 합니다. 소스 저장소에서는 다음 명령을 사용합니다:

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

기능 확인과 실행

먼저 capabilities를 읽습니다. conversionFormats는 변환 조합, metadata.formats는 편집 가능한 필드를 제공합니다. openfiles_inspect는 파일별 변환 대상을 반환합니다. HTML, Markdown, SVG를 PNG/PDF로 렌더링하며 스크립트와 외부 리소스는 비활성화됩니다. CDR은 모든 페이지의 SVG를 포함한 ZIP으로 변환합니다. 저장된 .ofw는 openfiles_workflow로 실행하고 sourcePaths가 파일 입력을 대체합니다. 저장된 배치 폴더와 마스크에도 권한이 필요합니다. PDF/OFD 메타데이터는 metadata.edit, metadata.remove 노드로 처리합니다. AI 노드는 설치된 런타임이 필요하며 모델을 다운로드할 수 있습니다. 경로를 바꾸고 아래 내용을 request.json으로 저장하세요:

JPEG와 열화상 JPEG는 확장자를 공유합니다. contentDetectionRequired가 반환되면 대상은 후보이며 실행 시 파일 내용으로 검증합니다.

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

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

작업 추적과 복구

쓰기는 원본을 보존하며 outputDir 아래 새 openfiles-* 폴더를 만듭니다. completed, failed, canceled까지 조회한 후 result.paths와 파일별 오류를 확인합니다. --wait는 기본 300초이며 --timeout으로 변경합니다. 시간 초과 후에도 작업은 계속됩니다. 재제출 전 tasks로 ID를 찾으세요. 목록은 --json 또는 --input으로 state, contextId, pageSize, pageToken을 받고 출력은 개별 작업에서 조회합니다. 최대 100개를 보관하고 8개를 동시에 실행하며 재시작 시 기록이 지워집니다. 취소해도 완료된 출력은 남습니다.

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

MCP 연결과 Skill 설치

mcp-config는 설정만 출력합니다. 명령과 인수를 외부 클라이언트에 등록하세요. mcp는 stdio에서 줄바꿈으로 구분된 JSON-RPC를 사용하고 skill은 내장 안내를 출력합니다. 기본 연결 파일은 ~/.openfiles/agent/connection.json입니다. 사용자 지정 경로는 데스크톱의 --agent-connection=PATH와 클라이언트의 --connection PATH를 맞춥니다. bearer token을 공개하지 마세요. 예제의 dist/agent/openfiles.cjs를 설치된 클라이언트 경로로 바꿀 수 있습니다. 채팅의 외부 MCP 서버 설정은 이 게이트웨이와 별개입니다.

A2A 호출

연결 파일의 루프백 주소에서 /.well-known/agent-card.json을 조회합니다. securityRequirements가 bearer 인증을 선언합니다. /a2a에 아래 JSON을 POST하고 Content-Type: application/json, A2A-Version: 1.0, Authorization: Bearer <token>을 보냅니다. 통신 재시도에는 같은 메시지 ID와 내용을 사용합니다. { "id": "TASK_ID" }로 GetTask를 조회하거나 CancelTask를 호출합니다. ListTasks는 contextId, status, statusTimestampAfter, 페이지 나누기, includeArtifacts를 지원합니다. 스트리밍, 푸시 알림, 자연어 계획은 지원하지 않습니다. 경로는 현재 컴퓨터를 가리키며 스크린샷 편집과 플러그인 설치는 데스크톱에서 수행합니다.

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