Blender Agent - Multi-Server MCP Demo

MCP(Model Context Protocol)를 활용한 다중 서버 통합 데모 프로젝트입니다. FastMCP를 사용하여 여러 서버를 구축하고, LangChain과 LangGraph를 통해 이들을 통합하여 AI 에이전트가 다양한 도구를 사용할 수 있도록 하는 예제를 제공합니다.

📋 목차

• 설치 방법
• 프로젝트 구조
• 코드베이스 알고리즘
• 실행 방법
• API 문서
• 예제 출력

🔧 설치 방법

1. uv 설치

uv는 빠른 Python 패키지 관리자입니다.

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 프로젝트 설정

# 저장소 클론
git clone <repository-url>
cd blender-agent

# 의존성 설치
uv sync

# 환경 변수 설정
cp .env.example .env
# .env 파일에 OpenAI API 키 설정
echo "OPENAI_API_KEY=your_openai_api_key_here" > .env

3. 필요 조건

• Python 3.12 이상
• OpenAI API 키
• 인터넷 연결

🏗️ 프로젝트 구조

blender-agent/
├── main.py                      # 메인 엔트리 포인트 (기본 hello world)
├── math_server.py              # 수학 연산 MCP 서버
├── weather_server.py           # 날씨 정보 MCP 서버
├── client_demo_multi_server.py # 다중 서버 클라이언트 데모
├── pyproject.toml              # 프로젝트 설정 및 의존성
├── .env                        # 환경 변수 (API 키 등)
└── README.md                   # 이 파일

🧮 코드베이스 알고리즘

1. MCP 서버 아키텍처

Math Server (math_server.py)

# FastMCP를 사용한 서버 생성
mcp = FastMCP("Math Server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """두 정수를 더하는 함수"""
    return a + b

@mcp.tool()  
def mul(a: int, b: int) -> int:
    """두 정수를 곱하는 함수"""
    return a * b

알고리즘 흐름:

1. FastMCP 인스턴스 생성
2. @mcp.tool() 데코레이터로 함수를 MCP 도구로 등록
3. stdio transport를 통해 클라이언트와 통신

Weather Server (weather_server.py)

@mcp.tool()
async def get_weather(location: str) -> str:
    """위치별 날씨 정보를 반환하는 Mock 함수"""
    return f"It's always sunny in {location}"

알고리즘 흐름:

1. 비동기 함수로 날씨 정보 Mock 제공
2. SSE(Server-Sent Events) transport 사용
3. HTTP 포트 8000에서 서비스 제공

2. Multi-Server Client 알고리즘

클라이언트 초기화 과정

client = MultiServerMCPClient({
    "math": {
        "command": "python",
        "args": ["./math_server.py"],
        "transport": "stdio",
    },
    "weather": {
        "url": "http://127.0.0.1:8000/sse",
        "transport": "sse",
    }
})

알고리즘 단계:

1. 서버 연결 초기화

   • Math Server: 서브프로세스로 stdio 통신
   • Weather Server: HTTP SSE 연결

2. 도구 수집 및 통합

   tools = await client.get_tools()

   • 각 서버에서 제공하는 도구들을 수집
   • LangChain 호환 도구 형태로 변환

3. LangGraph Agent 생성

   agent = create_react_agent(model, tools)

   • OpenAI GPT-4o-mini 모델 사용
   • ReAct (Reasoning + Acting) 패턴 구현
   • 도구 사용 결정을 위한 추론 과정

4. 질의 처리 알고리즘

   response = await agent.ainvoke({"messages": "what's (3 + 5) x 12?"})

   처리 과정:

   • 사용자 질문 파싱
   • 필요한 도구 식별 (수학 연산 → math server 도구 사용)
   • 도구 호출 및 결과 획득
   • 최종 응답 생성

3. ReAct Agent 동작 원리

1. Reasoning (추론)

   • LLM이 질문을 분석하여 어떤 도구가 필요한지 판단
   • 예: "(3 + 5) x 12" → add 도구와 mul 도구 필요

2. Acting (행동)

   • 식별된 도구를 순차적으로 호출
   • 각 도구의 결과를 다음 단계에 활용

3. Observation (관찰)

   • 도구 실행 결과를 관찰하고 다음 행동 결정
   • 최종 답변 생성까지 반복

🚀 실행 방법

1. 개별 서버 테스트

Math Server 실행:

# 터미널 1에서
python math_server.py

Weather Server 실행:

# 터미널 2에서
python weather_server.py

2. 통합 데모 실행

# 모든 서버를 자동으로 연결하여 실행
python client_demo_multi_server.py

3. 기본 애플리케이션 실행

python main.py

📖 API 문서

Math Server Tools

함수명	매개변수	반환값	설명
add(a, b)	a: int, b: int	int	두 정수의 합
mul(a, b)	a: int, b: int	int	두 정수의 곱

Weather Server Tools

함수명	매개변수	반환값	설명
get_weather(location)	location: str	str	해당 위치의 날씨 정보 (Mock)

📊 예제 출력

Math Query 예제:

질문: "what's (3 + 5) x 12?"

실행 과정:
1. Agent가 질문 분석
2. add(3, 5) 도구 호출 → 결과: 8
3. mul(8, 12) 도구 호출 → 결과: 96
4. 최종 답변: "96"

Weather Query 예제:

질문: "what is the weather in seoul?"

실행 과정:
1. Agent가 질문 분석
2. get_weather("seoul") 도구 호출
3. 결과: "It's always sunny in seoul"

🛠️ 개발 및 디버깅

로그 확인

클라이언트 실행 시 상세한 메시지 정보가 출력됩니다:

• 메시지 타입 및 내용
• 도구 호출 정보
• 도구 실행 결과

환경 변수 설정

# .env 파일 예제
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4o-mini  # 선택사항, 기본값: gpt-4o-mini

트러블슈팅

• Weather Server 연결 실패: Weather Server가 포트 8000에서 실행 중인지 확인
• OpenAI API 오류: .env 파일의 API 키 확인
• 모듈 import 오류: uv sync로 의존성 재설치

🔗 관련 링크

• FastMCP Documentation
• LangChain MCP Adapters
• LangGraph Documentation
• Model Context Protocol