Test MCP Server

간단한 MCP 서버 구현 (FastMCP + LangGraph)

프로젝트 구조

test-mcp/
├── app/
│   ├── core/
│   │   ├── agents/
│   │   │   └── simple_agent.py    # LangGraph 에이전트
│   │   └── config.py               # 설정 관리
│   ├── routers/
│   │   └── tool_router.py          # MCP 도구 등록
│   └── server.py                   # FastMCP 서버
├── entrypoint.py                   # 실행 진입점
├── pyproject.toml                  # 프로젝트 메타데이터
└── .env                            # 환경 변수 (직접 생성 필요)

주요 기능

1. FastMCP 서버: MCP 프로토콜 기반 서버
2. LangGraph 에이전트: OpenAI를 사용한 간단한 AI 에이전트
3. 2개의 도구:
   • ask_question: AI 에이전트에게 질문
   • get_greeting: 인사말 받기

설치 및 실행

1. 환경 설정

# .env 파일 생성
cp .env.example .env

# .env 파일 편집 (OPENAI_API_KEY 필수!)
nano .env

2. 의존성 설치

# Python 3.12 이상 필요
python -m pip install -e .

# 또는 uv 사용 (권장)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

3. 서버 실행

# 직접 실행
python entrypoint.py

# 또는 uv로 실행
uv run python entrypoint.py

MCP 도구 사용법

Claude Desktop과 연동

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "test-agent": {
      "command": "python",
      "args": ["/home/ignakio/project/test-mcp/entrypoint.py"]
    }
  }
}

사용 가능한 도구

1. ask_question

AI 에이전트에게 질문합니다.

파라미터:

• query (str): 질문 내용

예시:

ask_question("Python에서 비동기 프로그래밍이 뭐야?")

2. get_greeting

개인화된 인사말을 받습니다.

파라미터:

• name (str, optional): 이름 (기본값: "User")

예시:

get_greeting("홍길동")
# 출력: "Hello, 홍길동! How can I help you today?"

코드 설명

SimpleAgent (app/core/agents/simple_agent.py)

LangGraph를 사용한 간단한 에이전트:

# 워크플로우
START → call_llm → END

# 상태 정의
class AgentState(TypedDict):
    messages: list[BaseMessage]
    user_query: str
    final_response: str | None

주요 특징

• 단일 LLM 호출: 복잡한 루프 없이 한 번만 호출
• OpenAI 통합: ChatOpenAI 사용
• 비동기 처리: async/await 패턴

환경 변수

변수	기본값	설명
HOST	0.0.0.0	서버 호스트
PORT	8000	서버 포트
AGENT_NAME	test-agent	에이전트 이름
OPENAI_API_KEY	(필수)	OpenAI API 키
OPENAI_MODEL	gpt-4o-mini	사용할 모델
OPENAI_TEMPERATURE	0.7	생성 온도
LOG_LEVEL	INFO	로그 레벨

확장 방법

새로운 도구 추가

app/routers/tool_router.py에 추가:

@mcp.tool()
async def my_new_tool(param: str) -> str:
    """도구 설명

    Args:
        param: 파라미터 설명

    Returns:
        결과 설명
    """
    # 도구 로직
    return result

에이전트에 도구 바인딩

app/core/agents/simple_agent.py 수정:

# LLM에 도구 바인딩
from langchain_core.tools import tool

@tool
def calculator(expression: str) -> float:
    """Calculate mathematical expressions"""
    return eval(expression)

# call_llm 메서드에서
tools = [calculator]
response = await self.llm.bind_tools(tools).ainvoke(messages)

문제 해결

OpenAI API 키 오류

# .env 파일 확인
cat .env | grep OPENAI_API_KEY

의존성 오류

# 재설치
pip install -e . --force-reinstall

로그 확인

# 환경 변수 설정
export LOG_LEVEL=DEBUG
python entrypoint.py

참고 자료

• FastMCP 문서
• LangGraph 튜토리얼
• MCP 프로토콜