@brycepelletier/github-app-mcp

GitHub Operator 역할을 위한 단일 MCP stdio 파사드입니다. 활성 작업 공간에 대한 제한된 Git 작업과 GitHub 공식 MCP 서버에 위임된 GitHub API 도구를 결합하며, GitHub App 프라이빗 키나 설치 토큰을 절대 반환하지 않습니다.

아키텍처 및 책임 분담

Software Engineer                    GitHub Operator
       |                                    |
agent-env-mcp                         github-app-mcp
       |                         /-----------+-----------\
source/build/edit            ephemeral Git runtime   official GitHub MCP
.git masked                  real .git               GitHub API
no GitHub credentials        local: no network       fixed toolsets
                             remote: App auth

agent-env-mcp는 엔지니어링 기능 표면으로 남습니다. 해당 엔지니어링 컨테이너는 물리적으로 .git을 마스킹하며 GitHub 자격 증명을 받지 않습니다. 이 패키지는 github-operator.agent.md에 대해 모델에게 노출되도록 의도된 유일한 Git/GitHub 표면입니다.

파사드는 MCP roots/list로 작업 공간을 발견하고, 정확히 하나의 로컬 file: 루트를 요구하며, filesystem 루트를 거부하고, 실제 .git 메타데이터를 요구합니다. 어떤 모델 도구 매개변수도 호스트 경로, PEM, 이미지, 툴셋 또는 Docker 인자를 선택할 수 없습니다.

신뢰 경계 및 Docker 동작

MCP client
   | stdio
host-side trusted launcher (may control Docker; no Docker socket is mounted)
   |-- git_local  -> ephemeral container, workspace mount, network=none, no PEM
   |-- git_remote -> ephemeral container, workspace + read-only PEM, GitHub HTTPS
   `-- API tools  -> ghcr.io/github/github-mcp-server, read-only PEM

로컬 Git과 원격 Git은 서로 다른 실행 모드를 가집니다. git_local은 셸이나 임의의 Git 인자 배열 대신 작업 enum과 타입 필드를 노출합니다. 해당 컨테이너에는 실제 .git이 있지만 네트워크와 자격 증명 자료가 없습니다.

git_remote는 fetch, fast-forward 전용 pull, push, ls_remote만 허용하며 remote/ref 필드는 제한됩니다. 자격 증명이 없는 https://github.com/owner/repository 원격을 요구하고, 해당 구성된 원격에서 리포지토리 ID를 파생하며, contents:write 및 workflows:write 권한으로 해당 리포지토리에만 제한된 설치 토큰을 요청합니다. 토큰은 임시 런타임 내부에서 발급되고, 비공개 askpass 헬퍼를 통해 Git에 제공되며, 출력에서 제거되고, 컨테이너와 함께 폐기됩니다. pull은 먼저 인증된 fetch를 수행한 다음 자격 증명 없는 --ff-only 병합을 수행합니다.

Git 훅, 전역/시스템 구성, 파일 전송, 서브모듈 재귀, 대화형 편집기, GPG 서명 및 터미널 자격 증명 프롬프트는 비활성화됩니다. 출력은 제한되며, GitHub 토큰 패턴과 자격 증명이 포함된 URL은 제거됩니다.

GitHub Issues, 풀 리퀘스트, 리뷰, Actions, Projects 및 검색은 다시 구현되지 않습니다. 이들은 MCP를 통해 다음으로 프록시됩니다:

ghcr.io/github/github-mcp-server

공식 서버는 정확히 다음을 수신합니다:

GITHUB_TOOLSETS=context,issues,pull_requests,actions,projects

관련 없는 툴셋이 조용히 활성화되지 않습니다.

구성 및 출처

런처는 다음을 인식합니다:

• GITHUB_APP_ID — 기본값은 4618233입니다.

• GITHUB_APP_INSTALLATION_ID — 기본값은 154276908입니다.

• GITHUB_APP_PRIVATE_KEY_PATH — 필수이며 절대 경로 또는 확인 가능한 호스트 경로입니다.

두 숫자 기본값은 사용자의 기존 VS Code GitHub MCP 구성과 GitHub App bp-agent-github-app용 이전 compose 설정에 문서화된 작동 값입니다. 이 값들은 설명되지 않은 패키지 전체 비밀이 아니라 기본값이며 재정의할 수 있습니다. GitHub 설치/설정 페이지는 리포지토리 액세스에 대한 진실의 원천으로 남아 있습니다. App은 원래 brycepelletier/environment-controller용으로 설치되었습니다.

이 패키지는 의도적으로 기본 호스트 PEM 파일 이름이 없습니다. 이전 자료는 키가 C:/Users/bryce/.ssh/ 아래 어딘가에 있었다는 것만 확인할 뿐이며, 안전하게 추측하기에는 충분하지 않습니다. 구성된 호스트 파일은 고정 컨테이너 경로 /secrets/github-app.pem에 읽기 전용으로 마운트됩니다. 키는 npm 패키지에 복사되거나, 출력되거나, 도구 입력으로 허용되거나, MCP를 통해 반환되지 않습니다.

호스트 전제 조건 및 MCP 수명 주기

• Node.js 24 LTS 또는 호환되는 Node 24 릴리스

• Linux 컨테이너를 지원하는 Docker

• 신뢰할 수 있는 호스트 측 런처가 읽을 수 있는 GitHub App PEM

• MCP roots를 통해 제공되는 하나의 로컬 Git 작업 공간

• 원격 Git 및 공식 GitHub 컨테이너의 네트워크 액세스

공식 GitHub 하위 서버는 도구가 나열되거나 API 도구가 호출될 때 지연 시작됩니다. Git 런타임 이미지는 첫 번째 Git 작업 시 지연 빌드되며, 패키지 버전/콘텐츠에서 파생된 로컬 태그를 통해 재사용됩니다. Git 작업 컨테이너는 임시(--rm)입니다. SIGINT/SIGTERM은 공식 하위 전송을 닫습니다.

로컬 연결

이 패키지 디렉터리에서 Git Bash로:

npm run link

연결을 해제하려면:

npm run unlink

VS Code 구성

호스트 PEM 경로를 환경 구성으로 제공하고 MCP 항목 하나를 노출합니다:

{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@brycepelletier/github-app-mcp@0.1.0"],
      "env": {
        "GITHUB_APP_PRIVATE_KEY_PATH": "<exact-host-path-to-existing-pem>"
      }
    }
  }
}

작동 중인 App 및 설치 ID는 문서화된 기본값을 재정의하지 않는 한 반복해서 지정할 필요가 없습니다.

github-token-broker에서 마이그레이션

이전 비공개 브로커는 0.0.0.0:8080에서 수신 대기하며, Git credential-helper 형식으로 GET /credential에서 설치 토큰을 반환했습니다. 해당 아키텍처는 폐기되었습니다. 이 패키지에는 HTTP 리스너, 자격 증명 엔드포인트 또는 토큰 응답이 없습니다. 기존 브로커 소스는 감사/마이그레이션 기록을 위해 유지되지만, 이 패키지와 함께 제공되지는 않습니다.

이 패키지가 운영되면 agent-env-mcp에서 Git 서비스와 공개 git_command를 제거하는 후속 작업을 수행하십시오. 이는 의도적으로 이번 변경 범위를 벗어납니다. 엔지니어링 서비스는 실제 .git을 계속 마스킹해야 하며, PEM, 설치 토큰 또는 GitHub MCP 도구를 절대 받아서는 안 됩니다.