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

## 설치

```bash
# 가상환경 활성화
source venv/bin/activate

# 개발 모드로 설치
pip install -e .
```

## 환경변수 설정

GitHub API를 사용하려면 Personal Access Token이 필요합니다:

1. [GitHub Settings > Tokens](https://github.com/settings/tokens)에서 새 토큰 생성
2. 필요한 권한: `repo`, `user`
3. 환경변수 설정:

```bash
# .env 파일 생성 (프로젝트 루트에)
echo "GITHUB_TOKEN=your_token_here" > .env

# 또는 직접 환경변수 설정
export GITHUB_TOKEN=your_token_here
```

## 실행

```bash
# 가상환경 활성화
source venv/bin/activate

# MCP 서버 실행
python -m mcp_github.server
```

## Cursor 설정

Cursor에서 MCP 서버를 연결하려면 다음 설정을 사용하세요:

```json
{
  "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
서버 상태 확인
```json
{
  "status": "ok"
}
```

#### getRepo
GitHub 저장소 정보 조회
```json
{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice"
}
```

#### listPullRequests
Pull Request 목록 조회
```json
{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "state": "open"
}
```

#### getPRDiff
Pull Request의 diff 조회
```json
{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "number": 1
}
```

#### getFile
저장소의 파일 내용 조회
```json
{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "path": "README.md",
  "ref": "main"
}
```

### 쓰기 도구들 (Write Tools)

#### createOrUpdateFile
파일 생성 또는 수정
```json
{
  "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
파일 삭제
```json
{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "path": "file_to_delete.txt",
  "message": "Delete file",
  "branch": "main"
}
```

#### createBranch
새 브랜치 생성
```json
{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "new_branch": "feature-branch",
  "base_branch": "main"
}
```

#### createCommitWithMultipleFiles
여러 파일을 한 번에 커밋
```json
{
  "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
저장소 상태 및 최신 커밋 정보 조회
```json
{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "ref": "main"
}
```

## 사용 예시

### 파일 생성 및 커밋

1. 새 파일 생성:
```json
{
  "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. 파일 수정:
```json
{
  "tool": "createOrUpdateFile",
  "arguments": {
    "owner": "J-nowcow",
    "repo": "github-MCP-practice",
    "path": "README.md",
    "content": "# Updated README\n\nUpdated content here.",
    "message": "Update README"
  }
}
```

3. 새 브랜치에서 작업:
```json
{
  "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. 가상 환경 설정

```bash
# 가상 환경 생성
python -m venv venv

# 가상 환경 활성화
source venv/bin/activate  # macOS/Linux
# 또는
venv\Scripts\activate     # Windows
```

### 2. 의존성 설치

```bash
pip install -r requirements.txt
```

### 3. 환경 변수 설정

`.env` 파일을 프로젝트 루트에 생성하고 다음 내용을 추가하세요:

```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. 서버 실행

```bash
# 개발 모드로 실행
uvicorn mcp_client.main:app --reload --port 8081
```

## 📡 API 엔드포인트

### POST /chat
사용자 질문을 처리하고 MCP 도구를 사용하여 응답을 생성합니다.

**요청:**
```json
{
  "query": "GitHub 이슈 생성해줘",
  "thread_id": "optional_thread_id"
}
```

**응답:**
```json
{
  "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
서비스 상태를 확인합니다.

**응답:**
```json
{
  "status": "ok",
  "details": {
    "mcp_client": {"status": "connected", "tool_count": 5},
    "workflow": "ready",
    "tools_available": 5
  }
}
```

### GET /workflow/info
워크플로우 정보를 조회합니다.

**응답:**
```json
{
  "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 워크플로우
```

### 테스트 실행

```bash
# 전체 테스트
pytest

# 특정 테스트
pytest tests/ -v

# 커버리지
pytest --cov=mcp_client
```

### 코드 품질

```bash
# 린팅
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` 실행

### 로그 확인

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

```bash
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