iflow-mcp_teddynote-lab-mcp-tutorial 0.1.0

MCP tutorial project with weather, time, and RAG servers

🤖 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 패키지 매니저 (설치 가이드)

설치 단계

1. 저장소 클론

git clone https://github.com/teddynote-lab/mcp-tutorial.git
cd mcp-tutorial

2. 환경 변수 설정

cp .env.example .env
# .env 파일을 열어 필요한 API 키 입력

3. 의존성 설치

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

# 로컬 날씨 서버 (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로 테스트

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

튜토리얼 실행

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

🔧 환경 설정

.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 공식 문서
• LangGraph 문서
• FastMCP GitHub
• Smithery AI

🎥 학습 리소스

• 테디노트 YouTube 채널
• RAG 심화 온라인 강의

📄 라이선스

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

✨ 제작

Made by TeddyNote LAB

---

MCP와 LangGraph로 차세대 AI 에이전트를 구축하세요! 🚀