English | 中文

PR-Agent MCP 서버

pr-agent CLI 명령어를 MCP 도구로 노출시키는 MCP (Model Context Protocol) 서버이며, 선택적으로 Gitea 웹훅 통합을 통한 자동 PR 리뷰를 지원합니다. SSE 및 StreamableHTTP 전송 방식을 모두 지원하며, 로컬 또는 Docker에서 실행할 수 있습니다.

기능

• MCP 도구: pr-agent 명령어(review, describe, improve, ask, reflect, update_changelog, generate_labels)를 MCP 도구로 노출.

• 전송 방식: SSE (/sse) 및 StreamableHTTP (/mcp), --transport sse|streamable-http|both로 선택 가능.

• Gitea 웹훅: Gitea에서 새 PR이 열릴 때 자동으로 review, describe, improve 작업을 트리거.

• HMAC 서명 검증: 선택적 웹훅 서명 검증으로 보안 강화.

• 설정 주입: ~/.secrets.toml에서 자격 증명을 자동으로 로드하여 pr-agent 서브프로세스 환경에 주입.

프로젝트 구조

pr-agent-mcp/
├── server.py            # Main MCP server and webhook handler
├── run.ps1              # PowerShell startup script (local run)
├── requirements.txt     # Python dependencies
├── Dockerfile           # Multi-stage Docker image definition
├── docker-compose.yml   # Docker Compose service definition
├── push.ps1             # Build & push image to registry
├── .dockerignore        # Exclude files from Docker build context
├── buggy_samples.py     # Intentional bug samples for pr-agent testing
├── test.http            # HTTP test requests (VS Code REST Client / similar)
├── README.md
├── README.zh-CN.md
└── .gitignore

사전 요구 사항

• Docker와 Docker Compose (권장) 또는 Python 3.11+ (tomllib 사용)

• Gitea 인스턴스 (웹훅 통합 시 선택사항)

• ~/.secrets.toml 파일 (공급자 자격 증명 포함, 아래 참조)

자격 증명 구성

사용자 홈 디렉토리에 ~/.secrets.toml을 생성하여 공급자 및 LLM 자격 증명을 입력하세요:

[gitea]
url = "http://your-gitea-instance:3000"
token = "your-gitea-personal-access-token"

[openai]
key = "sk-your-openai-api-key"

SECRETS_TOML_PATH 환경 변수는 기본 위치(~/.secrets.toml)를 재정의합니다. Docker 이미지에서 바인드 마운트된 파일을 찾는 데 사용됩니다.

Docker 배포 (권장)

1. 로컬에서 빌드 및 시작

docker compose up -d --build

이 명령은 다음을 수행합니다:

1. 이미지 빌드 (멀티 스테이지: venv에 pr-agent 및 mcp 의존성 설치, 런타임에 git 설치).

2. 홈 디렉토리를 읽기 전용으로 컨테이너의 /host-home에 마운트하여 ~/.secrets.toml을 읽을 수 있도록 함.

3. 호스트 포트 9000을 컨테이너 포트 9000에 매핑.

4. SSE 및 StreamableHTTP 전송 방식을 모두 사용하여 서버 시작.

컨테이너는 단일 .secrets.toml 파일 대신 ${USERPROFILE} (전체 홈 디렉토리)를 마운트합니다. 존재하지 않는 호스트 파일을 마운트하면 Docker가 디렉토리를 생성하여 IsADirectoryError가 발생하므로, 상위 디렉토리를 마운트하면 이 문제를 피할 수 있습니다.

2. 프라이빗 레지스트리에 이미지 푸시

# Build + tag + push to the default registry (10.10.11.194:1000/pr-agent-mcp:latest)
.\push.ps1

# Push to another registry / with a version tag / skip rebuild
.\push.ps1 -Registry "192.168.1.100:5000" -Tag "v1.0.0" -NoBuild

3. 다른 머신에서 실행 (예: 테스트 서버)

docker-compose.yml을 대상 머신에 복사하고 build: .를 image: 10.10.11.194:1000/pr-agent-mcp:latest로 변경한 후:

docker pull 10.10.11.194:1000/pr-agent-mcp:latest
docker compose up -d

또는 compose 파일 없이 직접 실행:

docker run -d \
  --name pr-agent-mcp \
  -p 9000:9000 \
  -v $env:USERPROFILE:/host-home:ro \
  -e SECRETS_TOML_PATH=/host-home/.secrets.toml \
  --restart unless-stopped \
  10.10.11.194:1000/pr-agent-mcp:latest

컨테이너 관리

# View logs
docker compose logs -f

# Stop & remove
docker compose down

# Restart
docker compose restart

로컬 실행 (Docker 없이)

1. 의존성 설치

python -m venv mcp_env
mcp_env\Scripts\activate
pip install -r requirements.txt

requirements.txt에는 mcp (MCP 프레임워크)만 포함되어 있습니다. pr-agent는 이 서버의 Python 의존성이 아닙니다 — server.py에 설정된 경로 (또는 PR_AGENT_EXE 환경 변수)를 통해 서브프로세스로 호출됩니다. 머신에 pr-agent가 이미 설치되어 있는지 확인하세요.

2. (선택사항) 웹훅 시크릿 구성

server.py에서 WEBHOOK_SECRET을 Gitea 웹훅 설정에 구성된 것과 동일한 시크릿으로 설정하세요. 비워두면 서명 검증이 비활성화됩니다 (프로덕션 환경에서는 권장하지 않음).

3. 서버 시작

.\run.ps1

또는 직접:

python server.py
python server.py --transport sse        # SSE only
python server.py --transport streamable-http  # StreamableHTTP only

엔드포인트

MCP 도구

Gitea 웹훅 설정

1. Gitea 저장소에서 설정 → 웹훅 → 웹훅 추가로 이동합니다.

2. 대상 URL을 http://<your-server>:9000/webhook로 설정합니다.

3. HTTP 메서드를 POST, 콘텐츠 유형을 application/json으로 설정합니다.

4. 선택적으로 시크릿을 설정합니다 (server.py의 WEBHOOK_SECRET과 일치해야 함).

5. Pull Request 이벤트를 선택하고 Opened 작업을 선택합니다.

PR이 열리면 서버가 자동으로 review, describe, improve 작업을 실행하고 결과를 PR 댓글로 게시합니다.

테스트

포함된 test.http 파일을 VS Code REST 클라이언트 또는 유사한 HTTP 클라이언트와 함께 사용하여 웹훅 엔드포인트를 수동으로 테스트할 수 있습니다.

buggy_samples.py에는 보안, 로직, 동시성, 오류 처리 등 여러 범주에 걸친 의도적인 버그가 포함되어 있어 pr-agent의 코드 리뷰 감지 기능을 테스트할 수 있습니다.

라이선스

비공개 — 내부 전용.