mcp-tutorial

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