GitHub MCP Server

AI 어시스턴트가 안전하고 구조화된 도구를 사용해 GitHub와 대화할 수 있게 해주는 프로젝트입니다.

쉽게 말하면, AI가 GitHub의 작동 방식을 추측하는 대신 이 프로젝트에 "내 저장소 목록 보기", "열린 이슈 표시", "파일 읽기" 같은 명확한 동작 메뉴를 제공하는 것입니다. AI가 올바른 동작을 고르면 이 서버가 GitHub와 통신하고, 그 응답은 AI가 이해할 수 있는 깔끔한 형식으로 돌아옵니다.

어떤 문제를 해결하나요?

챗봇은 언어를 잘 다루지만 여러분의 GitHub 계정에 실시간으로 접근할 수 있는 것은 아닙니다.

이 프로젝트는 다리(bridge) 역할을 만듭니다:

1. 여러분이 평범한 영어로 질문합니다 ("Show open issues in microsoft/vscode").

2. AI 모델(Groq)이 어떤 GitHub 도구를 사용할지 결정합니다.

3. MCP 서버가 그 도구를 실제 GitHub API에 대해 실행합니다.

4. 결과는 정리(정규화)되어 AI에게 반환됩니다.

5. AI가 결과를 쉬운 말로 여러분에게 설명합니다.

MCP는 Model Context Protocol의 약자입니다. 표준 플러그라고 생각하면 됩니다. 호환되는 AI 클라이언트는 모두 이 서버에 연결하여 도구를 사용할 수 있습니다.

Related MCP server: GitHub MCP Server

큰 그림(아키텍처)

You
  ↓
AI Agent (client/agent.py)  ← talks to Groq LLM
  ↓
MCP Server (notebooks/server.py)  ← menu of GitHub tools
  ↓
GitHub Client  ← HTTP calls with your token
  ↓
GitHub REST API
  ↓
GitHub

설계 규칙(중요)

도구는 얇게(thin) 유지합니다:

1. 입력을 확인합니다(저장소 이름이 유효한가?).

2. GitHub 클라이언트를 호출합니다.

3. 응답을 안정적인 형태로 정규화합니다.

4. 정리된 데이터를 에이전트에게 반환합니다.

GitHub의 복잡한 세부 사항은 모두 클라이언트 계층 안에 남습니다 — 도구들에 흩어지지 않습니다.

프로젝트 폴더(각 부분의 역할)

도구로 무엇을 할 수 있나요?

서버는 다양한 GitHub 작업을 제공합니다. 간단히 분류하면:

읽기(살펴봐도 안전)

• 저장소 목록 확인

• 저장소 세부 정보 확인

• 이슈 및 풀 러퀘스트 목록/조회

• PR diff 열람

• 브랜치, 커밋, 라벨 목록

• 저장소 안의 코드 검색에서도 할 수 있습니다. 스타일 코드. 문자열을 번역하지 않습니다.?

  • 저장소에서 코드 검색

• 파일 내용 읽기

• GitHub Actions 워크플로우 실행 목록

쓰기(GitHub를 변경)

• 이슈, 댓글, PR, 브랜치, 라벨 만들기

• 이슈 수정, 라벨 추가/제거

• 이슈 다시 열기

파괴적 작업(문제를 일으킬 가능성 — 보호 대상)

다음 목록은 기본적으로 확인을 추가로 필요로 합니다:

• merge_pull_request

• delete_file

• create_repository

• create_or_update_file

• close_issue

이 작업들에 대해 에이전트는 일반적으로 다음 절차를 따릅니다:

1. dry_run=true로 호출 → 미리보기만

2. confirm=true로 다시 호출 → 실제로 수행

이 규칙은 환경 설정에서 합치거나 완화할 수 있습니다(아래 참조).

정규화된 응답(에이전트가 좋아하는 이유)

원본 GitHub 응답은 크기가 크고 자주 바뀌기 때문에 이 프로젝트는 안정적인 형태를 반환합니다.

목록 도구는 항상 다음과 같은 형태입니다:

{
  "count": 20,
  "items": [ ... ],
  "page": 1,
  "per_page": 20,
  "has_next": true,
  "has_prev": false,
  "next_page": 2,
  "prev_page": null,
  "last_page": 5
}

다음 페이지를 보려면 같은 도구를 page=2(또는 page=next_page)로 다시 호출하세요.

이슈 예시:

{
  "number": 42,
  "title": "Bug in login",
  "state": "open",
  "author": "some-user",
  "labels": ["bug"],
  "comments": 3,
  "html_url": "https://github.com/...",
  "is_pull_request": false
}

또한 get_issues는 풀 러퀘스트를 걸러 (GitHub 이슈 API가 섞여 있기 때문에).

안전 기능

선택 환경 변수:

GITHUB_MCP_DESTRUCTIVE_MODE=confirm
GITHUB_MCP_DESTRUCTIVE_ALLOWLIST=merge_pull_request,delete_file

로깅(디버깅용)

서버는 JSON 로그를 stderr에만 씁니다.

왜 stderr인가요? MCP가 프로토콜에 stdout을 사용하기 때문입니다. 거기 로그를 지웠더라면 AI 연결이 끊어집니다.

로그에는 다음이 포함됩니다:

• 요청 메서드와 경로

• HTTP 상태

• 걸린 시간

• 남은 rate-limit

로그에는 절대 넣지 않는 것:

• GitHub 토큰

• Authorization 헤더

• 비밀 정보처럼 보이는 값(PAT, Bearer 토큰 등)

로그 예시:

{"ts":"2026-08-23T12:00:00+00:00","level":"INFO","event":"github_request","method":"GET","path":"/repos/microsoft/vscode/issues","status_code":200,"duration_ms":120.5}

AI 에이전트 (client/agent.py)

에이전트는:

1. MCP 서버를 하위 프로세스로 시작(notebooks/server.py).

2. 서버에서 도구 목록을 요청.

3. 여러분의 질문 + 도구를 Groq에 보내기.

4. Groq가 도구를 원하면 에이전트가 MCP를 통해 그 도구를 호출.

5. 최종 답변을 위해 도구 결과를 다시 Groq에 보내기.

유용한 명령(프로젝트 폴더에서, 가상 온실 켠 상태):

# See all registered tools
python client/agent.py --list-tools

# Only show which tool the AI would pick (no GitHub write)
python client/agent.py --dry-run "list my github repos"

# One real question, then exit
python client/agent.py --once "show open issues for microsoft/vscode"

# Interactive chat
python client/agent.py

# Check tool-picking quality on many sample prompts
python client/test_tool_picking.py

루프 제한(선택사항):

python client/agent.py --max-rounds 5 --once "..."

또는 .env에서:

AGENT_MAX_TOOL_ROUNDS=8
AGENT_MAX_TOOL_CALLS=16
AGENT_MAX_CONSECUTIVE_ERRORS=3

환경 변수

MCP 서버에 필요한 변수

에이전트에 필요한 변수(챗 / 도구 선택)

선택사항

.env.example → .env로 복사하고 실제 값을 채우세요. 자세한 절차는 SETUP.md를 참고하세요.

기술 스택(궁금한 분들을 위한)

• Python 3.13+ (프로젝트는 3.13에서 개발됨)

• MCP(mcp) — Python 패캐지, 도구 서버 프로토콜

• httpx — GitHub용 HTTP 클라이언트

• Pydantic — 스키마/검증

• python-dotenv — .env 파일 로드

• OpenAI 호환 클라이언트 → 에이전트에서 Groq 사용

• Jupyter (선택) — 학습용 노트북

설치 및 실행 방법

친절한 안내서를 따라 하세요:

👉 SETUP.md — Python 설치, 키 생성, .env 설정, 첫 명령 실행하기

짧은 버전(Python을 이미 안다면):

cd "path\to\Github-MCP-server"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# edit .env with your tokens
python client/agent.py --list-tools
python client/agent.py --once "list my github repos"

학습 경로(권장)

1. 이 README를 읽습니다(지금 여기).

2. SETUP.md를 --list-tools가 동작할 때까지 수행.

3. 아키텍처 HLD+LLD 흐름: docs/ARCHITECTURE_HLD_LLD.md

4. 간단한 읽기 전용 질문으로 --dry-run 과 --once 시험.

5. 50개 시나리오 수동 테스트 플랜 실행: tests/MANUAL_TESTING_50_SCENARIOS.md

   • 자동 도구 선택: python client/run_manual_scenarios.py

6. notebooks/01_github_mcp_server.ipynb 파일인 디렉터리 별로 어떻게 만들어졌는지 확인.

7. 가능하다면 dry_run + confirm 절차로 쓰기/파괴 도구를 시도.

문제 해결(요약)

보안 안내

• .env는 절대 커밋하지 마세요.

• GitHub 또는 Groq 토큰은 채팅, 스크린샷, GitHub 이슈에 절대 올리지 마세요.

• 필요한 범위만 가진 GitHub 토큰을 사용하세요.

• 환경이 완전히 신뢰할 수 없다면 GITHUB_MCP_DESTRUCTIVE_MODE=confirm(또는 deny)를 유지하세요.

• 이전 실험에서 server_1.py가 토큰을 출력했다면 해당 디버그 출력을 공유하지 마세요 — server.py를 사용하세요.

라이선스 / 소유

GitHub MCP 서버와 에이전트에 관한 개인 / 학습용 Gen-AI 프로젝트입니다. 공개 배포하기 전에 사용에 맞게 소유권과 라이선스를 조정하세요.