iflow-mcp_teddynote-lab-mcp-tutorial 0.1.0
MCP tutorial project with weather, time, and RAG servers
Requires Python: >=3.11

# 🤖 MCP (Model Context Protocol) Tutorial

입문자를 위한 체계적인 Model Context Protocol 학습 가이드

## 📋 프로젝트 개요

이 튜토리얼은 **Model Context Protocol(MCP)** 을 처음 접하는 개발자들을 위한 실습 중심 학습 자료입니다. LangGraph와 MCP를 통합하여 다양한 외부 도구와 서비스를 활용하는 강력한 AI 에이전트를 구축하는 방법을 단계별로 학습합니다.

### 🎯 학습 목표

- MCP의 핵심 개념과 아키텍처 이해
- FastMCP를 활용한 MCP 서버 개발
- LangGraph와 MCP의 효과적인 통합
- 다중 MCP 서버 관리 및 오케스트레이션
- 실전 RAG 시스템 구현

## 🚀 주요 기능

- **표준화된 프로토콜**: MCP 표준을 따르는 도구 인터페이스 구현
- **다양한 전송 방식**: stdio 및 Streamable HTTP 지원
- **동적 도구 검색**: 런타임 도구 자동 검색 및 로드
- **확장 가능한 아키텍처**: 여러 MCP 서버 동시 연결 지원
- **실습 중심 학습**: Jupyter Notebook을 통한 인터랙티브 학습

## 📁 프로젝트 구조

```
mcp-tutorial/
├── 01-LangGraph-MCP-Tutorial.ipynb  # 메인 튜토리얼 노트북
├── server/                           # MCP 서버 구현체
│   ├── mcp_server_local.py         # 로컬 날씨 서비스 (stdio)
│   ├── mcp_server_remote.py        # 원격 시간 서비스 (HTTP)
│   ├── mcp_server_rag.py           # RAG 서비스 (벡터 검색)
│   └── rag/                        # RAG 관련 유틸리티
│       ├── base.py
│       ├── pdf.py
│       └── utils.py
├── assets/                          # 이미지 및 리소스
├── pyproject.toml                   # 프로젝트 설정
└── .env.example                     # 환경 변수 예시
```

## 🛠 설치 방법

### 사전 요구사항

- Python 3.11 이상
- UV 패키지 매니저 ([설치 가이드](https://docs.astral.sh/uv/))

### 설치 단계

1. **저장소 클론**
```bash
git clone https://github.com/teddynote-lab/mcp-tutorial.git
cd mcp-tutorial
```

2. **환경 변수 설정**
```bash
cp .env.example .env
# .env 파일을 열어 필요한 API 키 입력
```

3. **의존성 설치**
```bash
# UV를 사용한 가상환경 생성 및 패키지 설치
uv sync

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

## 🎓 학습 경로

### Part 1: MCP 기본 개념
- MCP 프로토콜 이해
- 기본 아키텍처 학습

### Part 2: 기본 MCP 서버 생성
- FastMCP를 활용한 서버 구현
- stdio 전송 방식 이해

### Part 3: MultiServerMCPClient 설정
- 다중 서버 관리 방법
- 도구 동적 로드

### Part 4: React Agent와 MCP 통합
- LangGraph React Agent 구성
- MCP 도구 바인딩

### Part 5: ToolNode와 MCP 통합
- 커스텀 워크플로우 구축
- 세밀한 제어 구현

### Part 6: 외부 MCP 서버 활용
- Smithery AI 플랫폼 연동
- 서드파티 도구 통합

### Part 7: Dify MCP 서버 연동
- Dify 플랫폼 활용
- 실전 통합 예제

## 💻 실행 방법

### MCP 서버 실행

```bash
# 로컬 날씨 서버 (stdio)
uv run python server/mcp_server_local.py

# 원격 시간 서버 (HTTP, 포트 8002)
uv run python server/mcp_server_remote.py

# RAG 서버 (문서 검색)
uv run python server/mcp_server_rag.py
```

### MCP Inspector로 테스트

```bash
# 브라우저에서 MCP 서버 테스트
npx @modelcontextprotocol/inspector
```

### 튜토리얼 실행

```bash
# Jupyter Notebook 실행
jupyter notebook 01-LangGraph-MCP-Tutorial.ipynb
```

## 🔧 환경 설정

`.env` 파일에 다음 환경 변수 설정이 필요합니다:

```env
# 필수
OPENAI_API_KEY=your_openai_api_key
TAVILY_API_KEY=your_tavily_api_key

# 선택 (추가 기능)
LANGCHAIN_API_KEY=your_langchain_api_key
CONTEXT7_API_KEY=your_context7_api_key
```

## 📚 핵심 의존성

- **LangGraph**: AI 에이전트 워크플로우 구축
- **FastMCP**: MCP 서버 개발 프레임워크
- **langchain-mcp-adapters**: LangChain-MCP 통합
- **FAISS**: 벡터 스토리지 (RAG용)
- **PyMuPDF**: PDF 문서 처리

## 🤝 기여 방법

이 프로젝트는 교육 목적으로 제작되었습니다. 개선 사항이나 버그를 발견하시면 Issue를 등록해 주세요.

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📖 참고 자료

- [MCP 공식 문서](https://modelcontextprotocol.io/)
- [LangGraph 문서](https://langchain-ai.github.io/langgraph/)
- [FastMCP GitHub](https://github.com/jlowin/fastmcp)
- [Smithery AI](https://smithery.ai/)

## 🎥 학습 리소스

- [테디노트 YouTube 채널](https://www.youtube.com/@teddynote)
- [RAG 심화 온라인 강의](https://teddylee777.github.io/)

## 📄 라이선스

이 프로젝트는 교육 목적으로만 사용 가능합니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

## ✨ 제작

**Made by [TeddyNote LAB](https://github.com/teddynote-lab)**

---

<p align="center">
  <i>MCP와 LangGraph로 차세대 AI 에이전트를 구축하세요! 🚀</i>
</p>