MCP GitHub + MCP Client 프로젝트
이 프로젝트는 GitHub MCP Server와 MCP Client (FastAPI + LangGraph) 두 부분으로 구성되어 있습니다.
🏗️ 프로젝트 구조
├── mcp_github/ # GitHub MCP Server (fastMCP 기반)
└── mcp_client/ # MCP Client (FastAPI + LangGraph)
🚀 MCP GitHub Server
GitHub MCP server built with fastMCP.
설치
# 가상환경 활성화
source venv/bin/activate
# 개발 모드로 설치
pip install -e .
환경변수 설정
GitHub API를 사용하려면 Personal Access Token이 필요합니다:
- GitHub Settings > Tokens에서 새 토큰 생성
- 필요한 권한:
repo,user - 환경변수 설정:
# .env 파일 생성 (프로젝트 루트에)
echo "GITHUB_TOKEN=your_token_here" > .env
# 또는 직접 환경변수 설정
export GITHUB_TOKEN=your_token_here
실행
# 가상환경 활성화
source venv/bin/activate
# MCP 서버 실행
python -m mcp_github.server
Cursor 설정
Cursor에서 MCP 서버를 연결하려면 다음 설정을 사용하세요:
{
"mcpServers": {
"github": {
"command": "python",
"args": ["-m", "mcp_github.server"],
"cwd": "/Users/hyunwoo/Desktop/클테코/20250904_githubMCP",
"env": {
"PYTHUB_TOKEN": "your_github_token_here",
"PYTHONPATH": "/Users/hyunwoo/Desktop/클테코/20250904_githubMCP"
}
}
}
}
사용 가능한 도구들
읽기 전용 도구들 (Read Tools)
health
서버 상태 확인
{
"status": "ok"
}
getRepo
GitHub 저장소 정보 조회
{
"owner": "J-nowcow",
"repo": "github-MCP-practice"
}
listPullRequests
Pull Request 목록 조회
{
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"state": "open"
}
getPRDiff
Pull Request의 diff 조회
{
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"number": 1
}
getFile
저장소의 파일 내용 조회
{
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"path": "README.md",
"ref": "main"
}
쓰기 도구들 (Write Tools)
createOrUpdateFile
파일 생성 또는 수정
{
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"path": "new_file.txt",
"content": "Hello, World!",
"message": "Add new file",
"branch": "main",
"committer_name": "Your Name",
"committer_email": "your.email@example.com"
}
deleteFile
파일 삭제
{
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"path": "file_to_delete.txt",
"message": "Delete file",
"branch": "main"
}
createBranch
새 브랜치 생성
{
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"new_branch": "feature-branch",
"base_branch": "main"
}
createCommitWithMultipleFiles
여러 파일을 한 번에 커밋
{
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"files": [
{
"path": "file1.txt",
"content": "Content 1",
"operation": "create"
},
{
"path": "file2.txt",
"content": "Updated content",
"operation": "update"
}
],
"message": "Multiple file changes",
"branch": "main"
}
getRepositoryStatus
저장소 상태 및 최신 커밋 정보 조회
{
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"ref": "main"
}
사용 예시
파일 생성 및 커밋
- 새 파일 생성:
{
"tool": "createOrUpdateFile",
"arguments": {
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"path": "docs/new_feature.md",
"content": "# New Feature\n\nThis is a new feature documentation.",
"message": "Add new feature documentation"
}
}
- 파일 수정:
{
"tool": "createOrUpdateFile",
"arguments": {
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"path": "README.md",
"content": "# Updated README\n\nUpdated content here.",
"message": "Update README"
}
}
- 새 브랜치에서 작업:
{
"tool": "createBranch",
"arguments": {
"owner": "J-nowcow",
"repo": "github-MCP-practice",
"new_branch": "feature/new-ui",
"base_branch": "main"
}
}
🧠 MCP Client (FastAPI + LangGraph)
Azure OpenAI + GitHub MCP Server를 연결하는 MCP Client(FastAPI + LangGraph) 프로젝트입니다.
🎯 프로젝트 개요
이 프로젝트는 사용자가 REST API(/chat)로 자연어 요청을 보내면:
- MCP Server(GitHub) 연결 → 사용 가능한 툴 목록 조회
- LangGraph ReAct Agent → Azure OpenAI 모델로 툴 실행 계획 수립
- MCP Server → 실제 툴 실행 및 결과 수집
- LangGraph 워크플로우 → 최종 응답 생성 및 반환
🏗️ 아키텍처
FastAPI → LangGraph Agent → MCP Server → GitHub
↓ ↓ ↓
/chat → ReAct Workflow → Tools Execution
🚀 빠른 시작
1. 가상 환경 설정
# 가상 환경 생성
python -m venv venv
# 가상 환경 활성화
source venv/bin/activate # macOS/Linux
# 또는
venv\Scripts\activate # Windows
2. 의존성 설치
pip install -r requirements.txt
3. 환경 변수 설정
.env 파일을 프로젝트 루트에 생성하고 다음 내용을 추가하세요:
# MCP Server
MCP_SERVER_URL=http://localhost:3000
# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_DEPLOYMENT=gpt-4o
AZURE_OPENAI_API_VERSION=2025-01-01-preview
OPENAI_TEMPERATURE=0.1
# HTTP
HTTP_TIMEOUT_SEC=30
4. 서버 실행
# 개발 모드로 실행
uvicorn mcp_client.main:app --reload --port 8081
📡 API 엔드포인트
POST /chat
사용자 질문을 처리하고 MCP 도구를 사용하여 응답을 생성합니다.
요청:
{
"query": "GitHub 이슈 생성해줘",
"thread_id": "optional_thread_id"
}
응답:
{
"response": "GitHub 이슈가 생성되었습니다",
"used_tools": [
{
"name": "create_github_issue",
"arguments": {"title": "...", "body": "..."},
"result": {"url": "..."}
}
],
"status": "success",
"trace": {
"tool_names": ["create_github_issue"],
"model_rounds": 2,
"thread_id": "thread_123"
}
}
GET /health
서비스 상태를 확인합니다.
응답:
{
"status": "ok",
"details": {
"mcp_client": {"status": "connected", "tool_count": 5},
"workflow": "ready",
"tools_available": 5
}
}
GET /workflow/info
워크플로우 정보를 조회합니다.
응답:
{
"status": "success",
"workflow_info": {
"model": "gpt-4o",
"temperature": 0.1,
"nodes": ["agent"],
"checkpointer": "MemorySaver"
}
}
🛠️ 핵심 컴포넌트
MCPClientManager (mcp_client/mcp_client.py)
langchain-mcp-adapters의MultiServerMCPClient래퍼 클래스- 비동기 컨텍스트 매니저 구현
- 에러 처리 및 재시도 로직
MCPAgentWorkflow (mcp_client/agent/workflow.py)
- LangGraph의
StateGraph를 사용한 ReAct 에이전트 구성 - Azure OpenAI 모델과 MCP 도구 통합
- 워크플로우 실행 및 결과 처리
🔧 개발
프로젝트 구조
mcp_client/
├── __init__.py
├── main.py # FastAPI 엔트리포인트
├── config.py # 환경변수 설정
├── schemas.py # Pydantic 모델
├── mcp_client.py # MCP 서버 연결 관리
└── agent/
├── __init__.py
└── workflow.py # LangGraph 워크플로우
테스트 실행
# 전체 테스트
pytest
# 특정 테스트
pytest tests/ -v
# 커버리지
pytest --cov=mcp_client
코드 품질
# 린팅
ruff check .
# 포맷팅
ruff format .
# 타입 체크
mypy mcp_client/
📚 기술 스택
- Python 3.11+
- FastAPI - 웹 프레임워크
- LangGraph - 워크플로우 오케스트레이션
- langchain-mcp-adapters - MCP 통합
- langchain-openai - Azure OpenAI 통합
- Pydantic - 데이터 검증
- Uvicorn - ASGI 서버
🔍 문제 해결
일반적인 문제들
-
MCP 서버 연결 실패
- MCP 서버가 실행 중인지 확인
MCP_SERVER_URL환경변수 확인
-
Azure OpenAI 인증 실패
- API 키와 엔드포인트 확인
- 배포 이름과 API 버전 확인
-
Import 오류
- 가상 환경이 활성화되었는지 확인
pip install -r requirements.txt실행
로그 확인
서버 실행 시 상세한 로그를 확인할 수 있습니다:
uvicorn mcp_client.main:app --reload --port 8081 --log-level debug
🤝 기여
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 라이선스
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
📞 지원
문제가 발생하거나 질문이 있으시면:
- GitHub Issues에 문제를 등록
- 프로젝트 문서 확인
- 개발팀에 문의
개발팀: MCP GitHub + MCP Client Team
최종 업데이트: 2025-09-04
버전: 0.1.0