GitHub Model Context Protocol (MCP) 서버 및 도구 호출 평가

읽기 및 확인 게이트가 적용된 쓰기 작업을 노출하는 프로덕션급 FastMCP GitHub 서버로, 도구 선택, 인자 정확도, 파괴적 작업 확인 안전성을 평가하는 30개 케이스 평가 하네스가 함께 제공됩니다.

요약 및 평가 매트릭스

LLM 에이전트의 도구 호출에는 엄격한 안전 경계가 필요합니다. 이 MCP 서버는 모든 변경 작업에 서버 수준 확인 게이팅을 적용합니다. 확인되지 않은 요청은 GitHub에서 변경을 실행하는 대신 드라이런 미리보기를 반환합니다.

벤치마크 성능 (30개 라벨링 시나리오)

표준 도구 호출, 불완전/모호한 쿼리, 파괴적 확인 게이트 작업을 테스트하는 30개 케이스 벤치마크로 평가:

Related MCP server: GitHub MCP Server

도구 아키텍처 및 작업

flowchart TD
    A[User Request] --> B[LLM Tool-Calling Engine]
    B --> C{Tool Category}
    
    C -- Read Tool --> D[Execute GitHub API Call Directly]
    D --> E[Return API Payload]
    
    C -- Write / Destructive --> F{confirm == true ?}
    F -- Yes --> G[Execute State Mutation on GitHub]
    G --> H[Return Success / Number / URL]
    
    F -- No --> I[Return Dry-Run Preview of Mutation]

사용 가능한 도구

읽기 작업 (즉시 실행)

• list_issues(owner, repo, state): 저장소의 열린/닫힌 이슈를 나열합니다.

• get_issue(owner, repo, issue_number): 단일 이슈의 상세 메타데이터를 검색합니다.

• list_pull_requests(owner, repo, state): 저장소의 풀 리퀘스트를 나열합니다.

• get_pull_request(owner, repo, pr_number): PR의 세부 정보와 병합 가능 여부를 검색합니다.

• search_code(query, owner, repo): GitHub 코드베이스를 전역 또는 저장소 범위로 검색합니다.

파괴적 작업 (확인 게이트 적용)

• create_issue(owner, repo, title, body, confirm=False): 확인된 경우에만 이슈를 생성하며, 그 외에는 미리보기를 반환합니다.

• close_issue(owner, repo, issue_number, confirm=False): 확인된 경우에만 이슈를 닫으며, 그 외에는 미리보기를 반환합니다.

• add_comment(owner, repo, issue_number, body, confirm=False): 확인된 경우에만 이슈/PR에 댓글을 달며, 그 외에는 미리보기를 반환합니다.

• merge_pull_request(owner, repo, pr_number, confirm=False): 확인된 경우에만 PR을 병합하며, 그 외에는 미리보기를 반환합니다.

프로젝트 구조

├── app/
│   ├── __init__.py          # Public MCP server & client exports
│   ├── server.py            # FastMCP server definition & tool routing
│   └── github_client.py     # GitHub REST API client with dry-run previews
├── eval/
│   ├── __init__.py          # Evaluation package
│   ├── tool_schemas.py      # OpenAI-compatible function definitions & prompt
│   ├── test_set.json        # 30 labeled evaluation test cases
│   └── run_eval.py          # Benchmark harness scoring tool, args, and confirm flags
├── requirements.txt         # Dependencies (mcp, requests, openai)
├── WRITEUP.md               # Detailed evaluation report & iteration analysis
└── README.md

빠른 시작 및 사용법

1. 설치

git clone https://github.com/vishalmurugan1986/github-mcp-server.git
cd github-mcp-server

pip install -r requirements.txt

2. 환경 구성

export NVIDIA_API_KEY="nvapi-your-key-here"
# Optional: real GitHub write access
export GITHUB_TOKEN="ghp_your_personal_access_token"

3. MCP 서버 실행

python -m app.server

표준 I/O를 통해 MCP 클라이언트(Claude Desktop 또는 사용자 정의 에이전트 등)를 연결합니다.

4. 도구 호출 평가 스위트 실행

python -m eval.run_eval

결과는 eval/results.json에 저장되며 전체 지표 분석과 함께 출력됩니다.

안전 설계 원칙

1. 심층 방어 확인: 프롬프트 지침에만 의존하지 않고, 확인 가드는 app/github_client.py에 직접 하드코딩됩니다. 확인되지 않은 요청은 우발적 변경을 일으킬 수 없습니다.

2. 모호성 거부: 모델은 저장소, 이슈 번호 또는 매개변수가 지정되지 않은 경우 실행을 거부하고 명확한 질문을 하도록 지시되며, 플레이스홀더 환각을 방지합니다.