GitPilot MCP

GitPilot은 GitHub를 위한 상태 저장형 AI 엔지니어링 제어 평면(control plane)입니다. MCP 도구와 웹 대시보드를 통해 이슈, 승인된 로컬 코드, 영구 프로젝트 메모리, 감사 가능한 검증 실행을 연결합니다.

기능

• 연결된 GitHub ID에 사용 가능한 소유, 협업자, 조직 저장소를 나열합니다.

• 이슈를 생성, 업데이트, 라벨링, 댓글 작성, 닫기, 재오픈합니다.

• AI 세션 간에 저장소 지식을 불러옵니다.

• 고정된 토큰 예산 내에서 순위가 매겨진 코드 스니펫을 검색합니다.

• 제한된 파일 범위를 읽고 정확히 일치하는 편집을 적용합니다.

• 매니페스트에서 파생된 검증 명령만 실행합니다.

• AI 수정 실행을 완료하기 전에 성공적인 검증을 요구합니다.

• 컨텍스트, 읽기, 편집, 검사, 완료에 대한 추가 전용 기록을 유지합니다.

• 저장소 자체의 AI 공급자를 연결하고 구조화된 패치 제안을 생성하며, 명시적 승인 시에만 적용하고, 검증하고, 초안 풀 리퀘스트로 게시합니다 — 보호된 브랜치에는 절대 게시하지 않으며, 게시에 대한 두 번째 명시적 승인 없이는 절대 게시하지 않습니다.

• 선택적으로 GitPilot이 검증 실패 후 자동으로 재시도하도록 허용합니다(제한된 시도 횟수까지). 저장소 전체가 아닌 실패만 전달하며, 위험도가 높거나 신뢰도가 낮은 제안은 여전히 인간 검토를 위해 중단되고, 자체적으로 게시하지 않습니다.

• 저장소 범위의 수동 무-AI 모드를 선택하여 공급자 호출을 차단하면서 제한된 증거, 정확한 편집, 격리된 브랜치, 허용 목록 검증, 감사 기록, 초안 PR 게시를 유지합니다 — AI 경로에서 청구, 할당량 또는 자격 증명 실패 후에도 항상 한 번의 클릭으로 전환할 수 있습니다.

Related MCP server: Agentic CI/CD MCP Orchestrator

설정

cd /d "C:\Projects - Building\GithubPilotMCP"
.venv\Scripts\activate.bat
pip install -r requirements.txt
copy .env.example .env

대시보드를 시작하고 Connect repository & brain에 GitHub 개인 액세스 토큰을 붙여넣습니다. 루프백 전용 로컬 설치에서 GitPilot은 data/.gitpilot-master-key에 비공개 영구 볼트 키를 생성하고, 토큰을 검증하며, 저장 시 암호화하고, 브라우저에 반환하지 않습니다. 프로덕션, 스테이징, 네트워크 노출 배포는 보안 비밀 저장소를 통해 GITPILOT_MASTER_KEY를 설정해야 합니다. 부트스트랩 대안으로 .env에 GITHUB_TOKEN을 설정합니다.

의도한 저장소에만 액세스할 수 있는 세분화된 토큰을 선호합니다. 완전한 진단, 패치, 초안 PR 워크플로를 원할 때 Metadata 읽기, Contents 읽기/쓰기, Issues 읽기/쓰기, Pull requests 읽기/쓰기를 사용합니다. GitHub는 저장소 소유자 또는 조직 관리자의 액세스 승인이 필요할 수 있습니다. GitPilot은 해당 승인을 우회할 수 없습니다.

코드 작업을 위해 승인된 로컬 저장소를 매핑합니다:

GITPILOT_CODE_ROOTS=my-repo=C:\path\to\my-repo

여러 매핑을 세미콜론으로 구분합니다. GitPilot은 토큰에 사용 가능한 모든 저장소를 나열하지만, 명시적으로 매핑된 작업 공간에서만 코드를 읽거나 편집할 수 있습니다.

설정 진단(Setup Doctor)

GitPilot을 Claude에 등록하기 전에 모든 것이 올바르게 구성되었는지 확인합니다:

python setup_doctor.py

모든 검사는 평이한 언어 상태, 문제가 있을 경우 정확한 복구 단계, 기계가 읽을 수 있는 세부 정보를 출력합니다. 토큰 값을 출력하지 않습니다. 진단 도구는 암호화된 대시보드 연결과 GITHUB_TOKEN을 모두 인식한 다음 Python, 종속성, GitHub 인증, 저장소 액세스, SQLite, 코드 작업 공간, MCP 준비 상태, 대시보드 포트, Claude CLI 등록 준비 상태를 확인합니다.

대시보드

python dashboard.py

http://127.0.0.1:8765을 엽니다. 이 인터페이스를 localhost에 유지하거나 인증된 TLS 뒤에 배치합니다.

로그인 컨트롤은 Google 없이 기본 이메일/비밀번호 계정을 제공합니다. 계정 생성은 저장소가 아닌 GitHub 프로필 이름을 요청합니다. 각 계정은 고유한 고객 ID를 받습니다. 비밀번호는 scrypt로 솔트 처리되고 단방향 해시됩니다. GitHub 및 AI 자격 증명은 계속 GITPILOT_MASTER_KEY로 암호화되고 해당 고객 ID로 범위가 지정됩니다. 고객은 Account & API access에서 취소 가능한 gp_live_... GitPilot API 키를 만들 수도 있습니다. 일반 텍스트 API 키는 한 번만 표시되고 SHA-256 해시만 저장됩니다.

GitPilot은 GitHub 사용자 이름/비밀번호 조합이나 GitHub OTP를 수집하지 않습니다. GitHub App이 구성된 경우, 계정 생성은 GitHub의 설치 화면으로 계속되어 고객이 정확한 저장소와 권한을 선택합니다. OAuth가 구성된 경우, GitPilot은 상태 검증과 PKCE를 사용하여 GitHub의 인증 코드 흐름으로 리디렉션합니다. GitHub는 github.com에서 로그인과 2단계 인증을 처리한 다음 인증 토큰을 반환합니다. 검증된 개인 액세스 토큰은 로컬 대체 수단으로 유지됩니다. 검증된 GitHub ID는 입력된 프로필 오타를 대체하며, GitPilot은 GitHub가 연결이 액세스할 수 있다고 말하는 저장소만 나열합니다.

저장소 선택은 연결이 검증된 후에 이루어집니다. 고객은 나중에 저장소를 생성하거나, 초대를 수락하거나, 토큰/App 설치를 확장한 후 Select repositories를 다시 실행할 수 있습니다. 별도 소유자 및 조직 저장소는 GitHub의 승인 규칙이 적용됩니다.

로컬 게스트 미리보기는 기본적으로 계속 사용할 수 있습니다. 배포된 고객 서비스의 경우 GITPILOT_REQUIRE_ACCOUNT_LOGIN=true를 설정하고, 영구 GITPILOT_SESSION_SECRET을 구성하고, GITPILOT_HTTPS_ONLY=true를 설정하고, HTTPS를 통해 트래픽을 종료합니다. 한 고객의 비밀을 포함하는 Python 또는 구성 파일을 만들지 마십시오. 자격 증명 기록은 암호화된 소유자 범위 데이터베이스 볼트에 속합니다.

장소 연결성이나 라이브 GitHub 계정에 의존하지 않고 안정적인 프레젠테이션을 위해 http://127.0.0.1:8765/?demo=1을 엽니다. 데모 모드는 명확하게 표시되며 시뮬레이션된 저장소, 이슈, 검색, 메모리, 모델, 비용, GitHub 연결, AI 공급자 연결, Brain Profile 데이터를 사용합니다. 일반 URL은 항상 실제 구성된 서비스를 사용합니다.

저장소 연결 및 Brain 선택

Connect repository & brain을 클릭하여 설정 마법사를 엽니다: GitHub 토큰을 붙여넣고 검증하고, 액세스 가능한 소유/협업자/조직 저장소를 선택하고, DeepSeek, Anthropic, OpenAI 호환/로컬, Google Gemini 또는 xAI Grok을 선택하고, 고객 자체 공급자 키를 연결하고, 모델을 선택하고, 토큰 및 비용 제한을 설정하고, 활성화 전에 모든 것을 검토합니다. 이것은 BYOK(자체 키 가져오기)입니다: GitPilot은 공유 개발자 키를 제공하지 않고, 운영자의 키로 대체하지 않으며, 한 고객의 자격 증명을 다른 고객과 공유하지 않습니다. 공급자 사용량과 요금은 키를 발급한 고객 계정에 속합니다. 액세스 검사기는 별도 소유자 또는 조직이 액세스를 승인해야 하는 시점을 설명하며, 마법사는 GitHub가 발급한 후 보류 중인 저장소 초대를 수락할 수 있습니다. 구성된 GitHub App은 선택적 추가 연결 모드로 유지됩니다. 전체 아키텍처, 데이터 모델, 위협 모델은 docs/BRAIN.md를 참조하십시오.

워크플로 선택에서 AI 자격 증명이나 공급자 호출 없이 운영하려면 Manual / no AI를 선택합니다. 이 선택은 각 저장소에 대해 독립적으로 저장되고 백엔드에서 강제됩니다. AI로 다시 전환하려면 유효한 저장소 Brain Profile을 명시적으로 활성화해야 합니다.

호스팅된 AI 액세스와 채팅 구독은 별도의 제품입니다. ChatGPT Plus/Pro 또는 Codex 액세스는 GitPilot이 수행하는 호출에 대한 OpenAI Platform API 청구를 자동으로 제공하지 않으며, DeepSeek 채팅 구독은 DeepSeek API 자금을 지원하지 않습니다. 마법사는 이 차이를 명시적으로 설명합니다. 호스팅 모델 요금이 없는 경우 Manual / no AI를 사용하거나 OpenAI-compatible / local을 통해 Ollama/vLLM 스타일 로컬 서버를 연결합니다. DeepSeek V4 Flash는 내장 카탈로그에서 가장 저렴한 호스팅 옵션이지만 여전히 DeepSeek Platform API 키와 사용 가능한 잔액이 필요합니다.

API 키가 없는 사용자는 **Use external chat (copy/paste)**을 선택할 수 있습니다. 이는 ChatGPT/Claude 계정 연결이 아닌 별도의 수동 대체 기능입니다: GitPilot은 사용자의 구독에 로그인하거나 운영할 수 없습니다. 선택된 이슈 증거와 허용 목록된 검증 명령만 포함하는 제한된 복사 준비 프롬프트를 구축합니다. 사용자는 해당 프롬프트를 외부 어시스턴트에 붙여넣은 다음 반환된 JSON 제안을 GitPilot에 다시 붙여넣습니다. 가져온 결과는 신뢰할 수 없습니다: API 생성 제안과 동일한 파일 범위, 정확한 일치, 패치 크기, 검증 명령, 제안 해시, 인간 승인, 격리 브랜치, 테스트 게이트를 통과해야 합니다. GitPilot은 공급자 호출을 하지 않으며 이 핸드오프에 대해 모델 비용을 기록하지 않습니다.

저장소의 brain이 활성화되면 이슈에서 안내된 수정을 시작하면 증거 → 진단 → 패치 제안 → 승인 및 적용(격리 브랜치) → 검증 → 승인 및 게시(초안 PR) 단계를 거칩니다 — 모든 단계가 대시보드의 파이프라인 패널에 표시되며, 모든 파일 시스템/GitHub 쓰기는 자체 명시적 인간 승인 뒤에 있습니다. 각 단계에서 AI가 정확히 무엇을 할 수 있고 할 수 없는지에 대한 자세한 내용은 docs/BRAIN.md §16을 참조하십시오.

호스팅 다중 테넌트 로그인(선택 사항, 베타)

기본적으로 대시보드는 로컬 단일 소유자 모드로 실행됩니다 — 로그인 없음, 오늘과 동일합니다. 여러 사람이 자신의 GitHub 계정으로 로그인할 수 있게 하려면:

1. https://github.com/settings/developers에서 GitHub OAuth App을 생성합니다. Authorization callback URL을 http://<your-host>/auth/callback으로 설정합니다.

2. .env에 해당 앱의 GITHUB_OAUTH_CLIENT_ID와 GITHUB_OAUTH_CLIENT_SECRET을 설정합니다.

3. GITPILOT_MASTER_KEY를 생성합니다(.env.example 참조) — 이 키는 로그인한 모든 사용자의 GitHub 토큰을 저장 시 암호화합니다. 배포의 비밀 저장소 외부에 커밋하거나 공유하지 마십시오.

4. 대시보드를 다시 시작합니다. 방문자는 이제 "Log in with GitHub" 화면을 볼 수 있습니다.

프로젝트 메모리와 수정 실행 기록은 호스팅 모드에서 로그인한 사용자로 범위가 지정됩니다. 로컬 코드 편집은 호스팅 사용자에게 의도적으로 사용할 수 없습니다. 호스팅 서비스는 고객의 디스크에 안전하게 액세스할 수 없기 때문입니다. 코드 작업은 MCP 클라이언트를 로컬에서 실행하십시오.

네이티브 GitPilot 계정은 선택적 GitHub OAuth 흐름과 독립적입니다. 고객은 먼저 이메일/비밀번호 작업 공간을 만든 다음 세분화된 GitHub 개인 액세스 토큰을 저장소 마법사에 붙여넣을 수 있습니다. OAuth는 로컬 전용 배포에서 비활성화된 상태로 유지될 수 있습니다.

가장 강력한 고객 온보딩을 위해 공개 GitHub App을 구성하고 GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY_PATH를 설정합니다. GitHub Apps는 고객이 특정 저장소를 선택하고 앱이 세분화된 권한과 단기 설치 토큰을 받기 때문에 선호됩니다. OAuth는 지원되는 대체 수단으로 유지됩니다. 암호화된 세분화된 개인 액세스 토큰은 두 통합이 모두 구성되지 않은 로컬 개발에서 계속 사용할 수 있습니다.

선택적 GITPILOT_INPUT_USD_PER_MTOK 및 GITPILOT_OUTPUT_USD_PER_MTOK 값은 실행 전에 표시되는 공급자 중립 계획 추정을 제어합니다. 실제 공급자 청구가 권위 있는 것으로 유지됩니다.

Claude MCP

한 번 등록:

claude mcp add gitpilot -- "C:\Projects - Building\GithubPilotMCP\.venv\Scripts\python.exe" "C:\Projects - Building\GithubPilotMCP\server.py"

예시 프롬프트:

Start an AI fix run for issue #12 in atlas-library-ai. Recall project memory, inspect only the ranked files, make the smallest safe edit, verify it, save the resolution, and only then close the issue.

수동 흐름은 ai_start_issue_fix, ai_read_file, ai_edit_file, ai_verify_fix, ai_complete_issue_fix를 사용합니다. 저장소에 활성 Brain Profile이 있는 경우, 안내된 수정 흐름(ai_generate_patch_proposal, ai_approve_and_apply_patch, ai_verify_fix, ai_publish_fix)은 수동 편집 대신 AI 작성 패치를 통해 동일한 증거 수집 및 인간 승인 경계를 구동합니다. 임의의 셸 명령은 절대 허용되지 않습니다.

수동 정확한 편집은 감사를 위해 해시되고, 전용 gitpilot/fix-* 브랜치에만 적용되며, 동일한 검증된 초안 풀 리퀘스트 게시자를 사용할 수 있습니다. AI 생성 패치는 정확히 검토된 제안 해시를 요구합니다. 이를 생략하면 실패 시 닫힙니다.

Docker

docker compose up --build

이미지는 읽기 전용 파일 시스템을 가진 비루트 사용자로 실행됩니다. SQLite는 data/ 아래에 유지되고 승인된 코드는 별도로 마운트됩니다.

테스트

python -m pytest -q

이것은 전체 오프라인 스위트만 실행합니다 — 모든 라이브 자격 증명 테스트는 선택 사항이며 기본적으로 건너뜁니다(tests/test_live_integration.py, tests/test_live_guided_fix_integration.py). 실제 GitHub App 설치와 실제 AI 공급자를 종단 간 테스트하려면 해당 모듈의 docstring에서 정확한 설정 지침을 참조하십시오.

메모리 모델, 상태 머신, 프로바이더 경계, 프로덕션 지침은 docs/ARCHITECTURE.md를 참조하고, GitHub App 연결, AI 프로바이더 볼트, Repository Brain Profile, guided-fix 패치 파이프라인은 docs/BRAIN.md를 참조하세요. .env 파일을 절대 커밋하지 말고 로그나 스크린샷에 토큰을 노출하지 마세요.