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이 필요합니다:

1. GitHub Settings > Tokens에서 새 토큰 생성
2. 필요한 권한: repo, user
3. 환경변수 설정:

# .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"
}

사용 예시

파일 생성 및 커밋

1. 새 파일 생성:

{
  "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"
  }
}

2. 파일 수정:

{
  "tool": "createOrUpdateFile",
  "arguments": {
    "owner": "J-nowcow",
    "repo": "github-MCP-practice",
    "path": "README.md",
    "content": "# Updated README\n\nUpdated content here.",
    "message": "Update README"
  }
}

3. 새 브랜치에서 작업:

{
  "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)로 자연어 요청을 보내면:

1. MCP Server(GitHub) 연결 → 사용 가능한 툴 목록 조회
2. LangGraph ReAct Agent → Azure OpenAI 모델로 툴 실행 계획 수립
3. MCP Server → 실제 툴 실행 및 결과 수집
4. 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 서버

🔍 문제 해결

일반적인 문제들

1. MCP 서버 연결 실패

   • MCP 서버가 실행 중인지 확인
   • MCP_SERVER_URL 환경변수 확인

2. Azure OpenAI 인증 실패

   • API 키와 엔드포인트 확인
   • 배포 이름과 API 버전 확인

3. Import 오류

   • 가상 환경이 활성화되었는지 확인
   • pip install -r requirements.txt 실행

로그 확인

서버 실행 시 상세한 로그를 확인할 수 있습니다:

uvicorn mcp_client.main:app --reload --port 8081 --log-level debug

---

🤝 기여

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

📞 지원

문제가 발생하거나 질문이 있으시면:

1. GitHub Issues에 문제를 등록
2. 프로젝트 문서 확인
3. 개발팀에 문의

---

개발팀: MCP GitHub + MCP Client Team
최종 업데이트: 2025-09-04
버전: 0.1.0