GitHub MCP Server

Node.js와 TypeScript로 작성된 MCP 서버로, 호환되는 에이전트가 자연어를 통해 GitHub에서 작업을 실행할 수 있게 해줍니다.

아키텍처

Usuario -> Antigravity (Host) -> MCP Client -> MCP Server -> Octokit -> GitHub API

챗봇은 주로 대화를 유지합니다. AI 어시스턴트는 추가 기능을 사용하여 도움을 제공합니다. AI 에이전트는 목표를 해석하고, 필요한 작업을 결정하며, 이를 달성하기 위해 도구를 사용합니다.

MCP(Model Context Protocol)는 AI Host, MCP 클라이언트, 그리고 도구나 데이터 소스를 노출하는 서버 간의 통신을 표준화합니다. 이 프로젝트에서 전송 방식은 stdio입니다. 프로토콜 메시지는 stdin/stdout을 사용하고 로그는 stderr를 사용합니다.

Related MCP server: GitHub MCP Server

기술

• Node.js 18 이상

• strict: true를 사용하는 TypeScript

• @modelcontextprotocol/sdk

• @octokit/rest

• zod

• dotenv

• Vitest

설치

npm install
npm run build

구성

.env.example을 .env로 복사하고 로컬에서 토큰을 입력하세요:

GITHUB_TOKEN=tu_token_de_github

.env는 .gitignore에 의해 제외되며 절대 커밋해서는 안 됩니다.

토큰에는 필요한 권한만 부여해야 합니다. 비공개 리포지토리의 경우 fine-grained 토큰은 작업에 따라 리포지토리 및 콘텐츠/이슈 접근을 허용해야 합니다. 클래식 PAT는 repo 권한이 필요할 수 있습니다. user 권한은 추가 사용자 작업에만 필요하며, admin:org는 조직이 해당 시나리오를 요구하지 않는 한 현재 다섯 가지 도구에 필요하지 않습니다. 토큰은 예시, 테스트, 로그 또는 MCP 응답에 포함되지 않습니다.

스크립트

npm run dev       # Ejecuta TypeScript directamente
npm run build     # Compila a dist/
npm start         # Ejecuta el JavaScript compilado
npm test          # Ejecuta los tests unitarios

MCP 도구

create_repository

인증된 계정에 새 리포지토리를 생성합니다.

입력: name, description.

리포지토리의 전체 이름과 URL을 반환합니다.

create_issue

기존 리포지토리에 이슈를 생성합니다.

입력: owner, repo, title, body.

이슈의 번호, 제목, URL을 반환합니다.

list_repositories

인증된 사용자의 리포지토리를 나열합니다.

선택적 입력: page, per_page.

전체 이름과 URL이 포함된 요약 목록을 반환합니다.

create_commit

파일을 생성하거나 업데이트하고 Contents API를 통해 커밋을 생성합니다.

입력: owner, repo, path, message, content; branch는 선택 사항입니다.

도구는 먼저 파일을 조회합니다. 파일이 존재하면 해당 SHA를 사용하고, GitHub가 404로 응답하면 SHA 없이 파일을 생성합니다.

list_issues

리포지토리의 열린 이슈를 나열하고 풀 리퀘스트를 제외합니다.

입력: owner, repo; page와 per_page는 선택 사항입니다.

오류 처리

오류는 ValidationError, AuthenticationError, GitHubAPIError 또는 NetworkError로 분류됩니다. MCP 응답에는 실행 가능한 메시지가 포함되며, 자격 증명을 노출할 수 있는 기술 메시지는 전달하지 않습니다.

작업은 rate limiting, 5xx 오류 또는 복구 가능한 네트워크 오류가 발생한 경우에만 최대 세 번까지 재시도합니다. 검증 오류, 인증 오류, 존재하지 않는 리소스 오류는 재시도하지 않습니다.

테스트

테스트는 실제 GitHub를 호출하지 않습니다. 모의 Octokit 클라이언트를 사용하며 다음을 다룹니다:

• 리포지토리 및 이슈의 유효한/유효하지 않은 스키마.

• 리포지토리 및 이슈 생성.

• 리포지토리 및 열린 이슈 목록 조회.

• 새 파일 생성.

• SHA를 사용한 기존 파일 업데이트.

• 오류 변환.

• 백오프를 사용한 재시도.

전체 테스트 스위트를 실행하려면 npm test를 실행하세요.

MCP Inspector

프로젝트를 컴파일하고 Inspector를 통해 서버를 실행하세요:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Inspector를 시작하기 전에 환경에 GITHUB_TOKEN을 설정하세요. 다섯 가지 도구와 해당 설명 및 스키마가 표시되는지 확인하세요. 실제 테스트를 위해서는 테스트 리포지토리를 사용하고 파괴적인 작업은 피하세요.

Antigravity 및 VS Code

.vscode/mcp.json 파일에는 버전 관리되는 자격 증명이 없는 stdio 구성이 포함되어 있습니다. Host에서 서버를 시작하기 전에 npm run build를 사용하세요. 이 구성은 dist/index.js를 실행하고 로컬 환경에서 GITHUB_TOKEN을 가져옵니다.

MCP와 호환되는 다른 Host의 경우 동등한 명령을 등록하세요:

{
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"],
  "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
}

Host가 create_repository, create_issue, list_repositories, create_commit 및 list_issues를 감지하는지 확인하세요.

구조

src/
  errors/       Errores clasificados y sanitizacion
  github/       Cliente Octokit y operaciones GitHub
  schemas/      Schemas Zod y tipos inferidos
  tools/        Handlers MCP individuales
  utils/        Retry, logging, respuestas y ensamblado del servidor
  index.ts      Entrada y transporte stdio
tests/          Tests unitarios con mocks

보안

• 토큰을 하드코딩하지 마세요.

• .env를 커밋하지 마세요.

• 토큰이나 인증 헤더를 출력하지 마세요.

• 프로토콜을 오염시키지 않도록 로그를 stderr에 유지하세요.

• PAT에 최소 권한 원칙을 적용하세요.

• GitHub에 쓰는 도구를 실행하기 전에 변경 사항을 검토하세요.