@brycepelletier/github-app-mcp

GitHub Operator 역할을 위한 단일 MCP stdio 파사드입니다. 활성 작업 공간에 대한 제한된 Git 작업과 GitHub API 도구를 GitHub 공식 MCP 서버에 위임하는 기능을 결합합니다. 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: 루트를 요구하며, 파일시스템 루트를 거부하고, 실제 .git 메타데이터를 요구합니다. 어떤 모델 도구 매개변수도 호스트 경로, PEM, 이미지, 도구 세트 또는 Docker 인수를 선택할 수 없습니다.

Related MCP server: github-mcp-tool

신뢰 경계 및 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 인수 배열 대신 작업 열거형과 타입이 지정된 필드를 노출합니다. 해당 컨테이너에는 실제 .git이 있지만 네트워크와 자격 증명 자료가 없습니다.

git_remote는 fetch, fast-forward 전용 pull, push, ls_remote, auth_check, push_dry_run만 허용하며, 원격/ref 필드는 제한됩니다. 자격 증명이 없는 GitHub HTTPS 또는 SSH 원격을 요구하고, 구성된 원격에서 저장소 정체성을 파생하며, .git/config를 변경하지 않고 내부적으로 SSH 형식을 자격 증명 없는 HTTPS로 정규화하고, contents:write 및 workflows:write 권한으로 해당 저장소에 제한된 설치 토큰을 요청합니다. 토큰은 임시 런타임 내부에서 발급되며, 비공개 askpass 헬퍼를 통해 Git에 공급되고, 출력에서 삭제되며, 컨테이너와 함께 폐기됩니다. pull은 먼저 인증된 fetch를 수행한 다음 자격 증명 없는 --ff-only 병합을 수행합니다.

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

인증 검증

git ls-remote는 인증의 증거가 아닙니다. 공개 저장소의 경우 익명으로 성공할 수 있습니다. 대신 auth_check는 저장소 제한 설치 토큰을 발급하고 GitHub의 인증된 저장소 엔드포인트를 호출합니다. 고정된 응답은 API 응답이나 자격 증명을 반환하지 않고 App 인증과 저장소 권한 부여를 확인합니다:

{ "operation": "auth_check", "remote": "origin" }

{
  "authenticated": true,
  "repository_authorized": true,
  "repository": "owner/repository",
  "remote_scheme": "https",
  "permissions": { "contents": "write", "workflows": "write" },
  "credential_exposed": false
}

push_dry_run은 추가로 인증된 Git HTTPS 전송이 push를 협상할 수 있음을 증명합니다. 런타임은 항상 --dry-run을 삽입합니다. 호출자는 Git 인수, 강제 플래그 또는 삭제 refspec을 제공할 수 없습니다. GitHub는 제안된 업데이트를 평가하지만 로컬 및 원격 ref는 모두 변경되지 않습니다.

{ "operation": "push_dry_run", "remote": "origin", "branch": "main" }

{
  "authenticated": true,
  "transport": "https",
  "dry_run": true,
  "exit_code": 0,
  "signal": null,
  "stdout": "",
  "stderr": "Everything up-to-date\n",
  "truncated": false,
  "credential_exposed": false,
  "summary": "Authenticated push dry run succeeded; no refs were changed."
}

이러한 검사에는 요청된 contents:write 및 workflows:write 권한, 저장소 액세스, 네트워크 액세스 및 정확히 구성된 PEM 경로가 있는 설치된 App이 필요합니다. 관련 없는 저장소가 권한이 부여되었음을 증명하지 않으며 GitHub의 dry-run 응답을 넘어 브랜치 보호 결과를 검사하지 않습니다.

npm test로 자동 검사를 실행하거나 npm run validate로 전체 로컬 패키지 검증을 실행합니다. 선택적 실시간 검증은 auth_check 및 push_dry_run 전후에 git ls-remote로 원격 브랜치 객체 ID를 기록한 다음 ID가 일치하고 반환된 모든 credential_exposed 필드가 false인지 확인해야 합니다. 일반 push로 대체하지 마십시오.

GitHub Issues, pull requests, 리뷰, Actions, Projects 및 검색은 재구현되지 않습니다. MCP를 통해 다음으로 프록시됩니다:

ghcr.io/github/github-mcp-server

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

GITHUB_TOOLSETS=context,issues,pull_requests,actions,projects

관련 없는 도구 세트가 자동으로 활성화되지 않습니다.

구성 및 출처

런처는 세 가지 외부 구성 값을 모두 요구하며, 인증된 컨테이너를 시작하기 전에 하나라도 없거나 유효하지 않으면 fail-closed 방식으로 종료합니다:

• GITHUB_APP_ID — 양의 정수 GitHub App 식별자.

• GITHUB_APP_INSTALLATION_ID — 양의 정수 설치 식별자.

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

알려진 작동 값 GITHUB_APP_ID=4618233 및 GITHUB_APP_INSTALLATION_ID=154276908은 사용자의 기존 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 루트를 통해 제공되는 하나의 로컬 Git 작업 공간

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

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

공식 GitHub 컨테이너는 각 파사드 프로세스에 대해 고유한 인프라 생성 이름을 가집니다. MCP stdin EOF/close, SIGINT, SIGTERM, SIGHUP 및 치명적인 프로세스 오류는 멱등 정리를 트리거합니다: 파사드는 하위 전송을 닫은 다음 자체 명명된 컨테이너를 대체 수단으로 명시적으로 제거합니다. 컨테이너 이름과 정리 대상은 MCP 도구 입력에서 수락되지 않으며, 동시 VS Code 세션은 정리 대상을 공유하지 않습니다.

로컬 연결

이 패키지 디렉터리의 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.3.0"],
      "env": {
        "GITHUB_APP_ID": "4618233",
        "GITHUB_APP_INSTALLATION_ID": "154276908",
        "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 0.4.0부터 Git 서비스와 공개 git_command가 제거되었습니다. 엔지니어링 서비스는 실제 .git을 계속 마스킹하며 PEM, 설치 토큰 또는 GitHub MCP 도구를 받지 않습니다.

라이선스

MIT. LICENSE 참조.