agent-bridge-mcp

MCP 서버 및 HTTP 게이트웨이로, Claude Code, Codex, Antigravity (agy) CLI 세션에 코딩 작업을 전달하고, 해당 세션을 추적하며, 선택적으로 실제 저장소에 대해 구현 → 검토 → 검증 루프를 실행합니다.

상태: 실험적. 이 프로젝트는 개인 오케스트레이션 도구로 시작되었으며, 세션 라우팅 및 증거 게이트 부분이 다른 사람들에게 유용하기를 바라며 공개되었습니다. 인터페이스는 변경될 수 있습니다.

기능

• 세션 라우팅 — 프로젝트 및 주제별로 Claude Code / Codex 세션을 시작하고 재개하여 후속 프롬프트가 동일한 컨텍스트에 도달하도록 합니다.

• 작업 추적 — 모든 전달은 상태, 출력 및 종료 코드가 있는 작업이 됩니다.

• 증거 게이트 — 저장소에서 지정한 테스트 명령을 실행하고 변경 사항이 실제로 통과 테스트로 뒷받침되는지 여부를 수락하기 전에 보고합니다.

• 검토 루프 — 구현 에이전트와 검토 에이전트를 차례로 전달하며, 수정 횟수 제한까지 증거 검사에 따라 게이트됩니다.

• 게이트웨이 — HTTP + WebSocket을 통해 동일한 기능을 제공하므로 원격 클라이언트(예: 휴대폰)가 작업을 전달하고 출력을 스트리밍할 수 있습니다.

설치

npm install -g @yukinuma/agent-bridge-mcp

Node.js 20+가 필요하며, 사용하려는 에이전트 CLI(claude, codex, 및/또는 agy)가 이미 설치 및 인증되어 있어야 합니다.

antigravity 에이전트에 대한 참고 사항

agy는 내부 언어 서버를 실행하며 실제 터미널을 필요로 합니다. 일반 파이프에서 시작하면 응답하기 전에 종료되어 호출자 측에서는 중단과 구분할 수 없습니다. 따라서 Windows에서는 이 어댑터가 winpty(Git for Windows에 포함됨) 아래에서 실행하고 호출 기간 동안 stdin을 열어 둡니다.

알아둘 만한 두 가지 결과:

• winpty는 종료 시 자체 어설션에서 중단되므로 종료 코드가 agy가 수행한 작업을 반영하지 않습니다. pty를 통해 실행할 때 어댑터는 종료 코드가 아닌 응답이 돌아왔는지 여부로 성공을 판단하고 캡처된 출력에서 어설션 텍스트를 필터링합니다.

• 타임아웃 시 프로세스 트리는 PID로 종료됩니다. 이미지 이름으로 종료하면 다른 곳에서 열려 있는 대화형 agy까지 종료되므로 의도적으로 수행되지 않습니다.

두 바이너리 중 하나가 비표준 위치에 있는 경우 WINPTY_PATH 또는 AGY_PATH를 설정하세요. 비Windows 플랫폼에서는 agy가 직접 실행되며, 이는 테스트되지 않았습니다.

MCP 서버로 사용

{
  "mcpServers": {
    "agent-bridge": {
      "command": "agent-bridge-mcp",
      "env": {
        "AGENT_BRIDGE_WORKSPACE": "/path/to/your/projects"
      }
    }
  }
}

노출된 도구: agent_send, agent_status, agent_sessions, agent_cancel.

게이트웨이로 사용

export ABC_AUTH_TOKEN="$(openssl rand -hex 24)"
export AGENT_BRIDGE_WORKSPACE="/path/to/your/projects"
agent-bridge-gateway

게이트웨이는 ABC_AUTH_TOKEN 없이 시작을 거부합니다. 기본 토큰은 없습니다.

엔드포인트

/api/dispatch, /api/git/commit-push, 및 /api/review-loop는 명시적 대상을 필요로 합니다 — cwd 또는 워크스페이스 내에서 확인되는 project입니다. 기본 디렉터리로 대체되지 않고 400을 반환하며, 워크스페이스를 벗어나는 project 값은 거부됩니다.

보안

이 서비스는 안전 프롬프트가 꺼진 상태로 코딩 에이전트를 실행합니다. 이것이 무인 전달이 작동하는 이유입니다 — 승인을 요청하기 위해 멈추는 에이전트는 키보드 앞에 아무도 없을 때 단순히 중단됩니다 — 하지만 이는 API에 접근할 수 있는 사람이 게이트웨이를 실행하는 사용자로서 임의의 코드를 실행할 수 있음을 의미합니다.

구체적으로, CLI 어댑터는 다음을 전달합니다:

둘 다 기본적으로 우회합니다. 옵트아웃은 어댑터 수준 옵션입니다. 아직 MCP 도구나 REST API를 통해 연결되지 않았으므로 HTTP를 통한 우회는 현재 무조건적입니다.

이것을 권한 있는 로컬 데몬으로 취급하세요:

• 기본적으로 127.0.0.1에 바인딩됩니다. AGENT_BRIDGE_HOST를 다른 값으로 설정하면 작업 전달, 샌드박스 없는 코드 실행 및 git 푸시가 네트워크에 노출됩니다.

• 인증 토큰은 단일 공유 비밀로, Bearer 헤더 또는 token 쿼리 매개변수로 전송됩니다. 쿼리 매개변수는 로그에 남습니다 — 가능하면 헤더를 선호하세요. 해당 토큰 하나가 손상되면 셸을 넘겨주는 것과 같습니다.

• 워크스페이스 경로 확인 외에는 프로젝트 간 샌드박싱이 없습니다.

• /api/git/commit-push는 대상 저장소가 구성한 원격 저장소로 푸시합니다. 푸시 전에 다시 묻지 않습니다.

이것을 신뢰할 수 없는 네트워크에 노출하지 말고, 작업이 실제로 필요로 하는 것보다 더 많은 액세스 권한을 가진 사용자로 실행하지 마세요.

개발

npm install
npm run typecheck
npm run build

라이선스

MIT