외부 AI 에이전트 연결 (MCP)

코딩 에이전트처럼 MCP(Model Context Protocol)를 지원하는 외부 AI 도구를 reopt QA에 연결할 수 있습니다. 연결된 에이전트는 프로젝트와 테스트, 리포트, AI 세션 상태를 조회할 수 있습니다. 테스트 실행이나 AI 세션 요청은 프로젝트에서 허용한 작업만 할 수 있습니다.

연결은 reopt-qa mcp 명령이 담당합니다. 이 명령은 MCP 클라이언트와 표준 입출력(stdio)으로 통신하고, 요청을 이 컴퓨터에서 실행 중인 reopt QA에만 전달합니다. 다른 컴퓨터의 주소로는 연결하지 않습니다.

현재 reopt-qa mcp는 reopt QA 저장소의 CLI(bin/reopt-qa.mjs)로 제공됩니다. 데스크톱 앱 설치본에는 아직 들어 있지 않습니다. 브리지를 쓰는 동안에는 데스크톱 앱(또는 개발 모드의 pnpm dev)이 실행 중이어야 합니다.

1. 프로젝트 지정은 필수

브리지는 프로젝트를 모르는 채로는 실행되지 않습니다. 아래 셋 중 하나가 필요합니다.

• --project <id>: 연결을 이 프로젝트에 고정합니다. 권장하는 방식입니다.
• 연결된 프로젝트: reopt-qa link로 연결해 둔 디렉터리에서 실행하면 그 프로젝트를 씁니다.
• --unbound: 프로젝트를 고정하지 않겠다고 명시합니다. 앱에서 현재 선택된 프로젝트를 기준으로 동작하며, 여러 프로젝트를 조회할 수 있습니다.

셋 다 없으면 브리지는 앱에 연결하지 않고 오류와 함께 종료합니다(종료 코드 2).

MCP 클라이언트 설정 예:

{
  "mcpServers": {
    "reopt-qa": {
      "command": "reopt-qa",
      "args": ["mcp", "--project", "my-app"]
    }
  }
}

2. 허용할 작업 고르기 (기본값: 모두 꺼짐)

새 프로젝트는 외부 에이전트가 아무 작업도 시작할 수 없는 상태입니다. 조회(프로젝트·테스트 목록·리포트·디버그 정보·세션 상태)만 항상 가능합니다.

작업을 허용하려면 앱에서 프로젝트를 편집해 외부 에이전트(MCP) 허용 작업에서 필요한 항목만 켭니다.

CLI로도 바꿀 수 있습니다.

reopt-qa ai config external-mcp investigate,fix   # 조사·수정 세션만 허용
reopt-qa ai config external-mcp none              # 다시 모두 끄기

허용하지 않은 작업을 요청하면 에이전트는 not_allowed 오류를 받고, 아무 작업도 시작되지 않습니다.

3. 수정은 항상 사람이 승인합니다

외부 에이전트가 시작한 수정 세션은 프로젝트의 승인 모드와 관계없이 수동 승인으로 동작합니다. 자동·조건부 승인이 켜져 있어도 수정안은 파일에 바로 쓰이지 않습니다. 앱의 AI 세션 화면에서 사람이 직접 검토하고 승인해야 적용됩니다.

외부 에이전트는 승인이나 거절, 시나리오 반영을 할 수 없습니다. 이런 결정은 앱에서만 할 수 있습니다.

4. 외부 에이전트가 할 수 있는 일

• 프로젝트 목록, 테스트 목록, 최신 리포트, 디버그 정보 조회
• 허용된 경우 테스트 실행과 AI 세션(탐색·조사·수정) 시작
• 세션 상태 조회. 상태가 바뀔 때까지 최대 20초 기다리는 방식도 지원합니다
• 브라우저 동작 승인이 필요한 세션은 awaiting_input, 수정안 검토를 기다리는 세션은 awaiting_review로 보입니다. 두 경우 모두 앱에서 사람이 응답해야 진행됩니다
• 외부 에이전트가 시작한 세션만 중지. 앱에서 시작한 작업은 중지할 수 없습니다

외부 에이전트가 시작한 세션은 앱의 AI 세션 목록에 MCP 배지로 표시되고, 세션 상세의 시작 경로에 외부 에이전트 (MCP)로 나옵니다.

5. 보안상 알아 둘 점

• 연결은 이 컴퓨터 안에서만 이뤄지며, 앱이 발급한 세션 토큰으로 보호됩니다. 브라우저의 웹 페이지는 이 연결을 사용할 수 없습니다.
• 에이전트에게 돌려주는 텍스트에서는 환경과 페르소나에 등록된 비밀번호·토큰 같은 값을 가립니다. 리포트나 페이지에서 가져온 텍스트는 신뢰할 수 없는 데이터로 표시해 전달합니다.
• 동시에 진행할 수 있는 외부 에이전트 세션은 프로젝트당 3개입니다. 같은 idempotencyKey로 요청을 다시 보내면 새 세션을 만들지 않고 기존 세션을 돌려줍니다. 브리지가 재시도할 때도 이 키를 붙이므로 세션이 두 번 시작되지 않습니다.
• 스크린샷 이미지는 가리지 않으므로, 화면에 비밀 값이 표시되는 페이지는 주의하세요.

문제가 생겼을 때

• "reopt QA agent에 연결할 수 없습니다": 데스크톱 앱(또는 pnpm dev)이 실행 중인지 확인하세요. 앱을 다시 시작해 주소가 바뀌어도 브리지가 자동으로 다시 찾습니다.
• not_allowed 오류: 해당 작업이 프로젝트의 외부 에이전트(MCP) 허용 작업에서 켜져 있는지 확인하세요.
• 브리지가 바로 종료됨: --project <id>를 지정했는지, 또는 연결된 프로젝트 디렉터리에서 실행했는지 확인하세요.

실제 협업 흐름

먼저 조회만 가능한 상태로 연결해 다음처럼 요청할 수 있습니다.

이 프로젝트의 테스트 목록과 최신 실패 리포트를 읽고, 확인된 사실과 원인 가설을 구분해서 정리해 줘.

조사와 테스트 실행을 허용했다면 실패 조사 → 앱에서 제안 검토 → 수정 반영 → 재실행 → 최신 결과 확인 순서로 이어 갑니다. 실행 조건과 검증 내용을 약화시키지 않았는지 사람이 확인합니다.

조회 범위

get_report는 임의 기간의 모든 기록을 분석하는 도구가 아닙니다. get_debug_info의 trace 응답도 파일 목록이며 trace 전체를 해석한 결과가 아닙니다. 기간별 추세와 상세 근거는 리포트와 분석에서 확인합니다.

CLI를 전역 설치하지 않은 경우

MCP 클라이언트가 실행할 Node와 저장소 CLI의 절대 경로를 사용할 수 있습니다. 아래 경로와 프로젝트 ID는 실제 값으로 바꿉니다. 클라이언트별 설정 파일의 위치와 형식은 해당 도구의 설정에 맞춥니다.

{
  "mcpServers": {
    "reopt-qa": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/reopt-qa/bin/reopt-qa.mjs", "mcp", "--project", "my-app"]
    }
  }
}

MCP 연결 자체가 정기 실행이나 AI 보고 자동 전송을 설정하지는 않습니다. 정기 실행은 앱의 별도 기능입니다. 외부 AI 클라이언트가 결과를 모델에 전달하는 범위와 비용도 그 클라이언트에서 확인합니다.

제품 구조와 개선 기록 조회

MCP control의 get_product_context로 프로젝트의 기능, 사용자 흐름, 개선 기록을 조회할 수 있습니다. projectId로 대상을 지정하고 offset으로 각 목록의 다음 20개 항목을 읽습니다. hasMore가 참이면 다음 페이지가 있습니다. 이 도구는 저장된 정보를 조회하며 검증을 실행하거나 개선 상태를 변경하지 않습니다.

사용자 흐름의 출처와 확인 여부를 함께 확인하세요. AI 제안은 실제 관찰이나 사용자 확인과 구분됩니다.