Claude Academy
로드 중

MCP로 도구 정의하기

강의 5210분

공식 Python SDK를 사용하면 MCP 서버를 구축하는 과정이 훨씬 간단해집니다. 복잡한 JSON 스키마를 직접 작성하는 대신, 데코레이터로 도구를 정의하고 나머지 작업은 SDK가 처리하도록 맡길 수 있습니다.

우리 MCP 서버의 읽기 및 업데이트 도구가 document.pdf, spreadsheet.xlsx, report.txt, spec.md 네 개의 파일에 연결되어 있는 모습.

이 예제에서는 두 가지 핵심 도구를 갖춘 문서 관리 서버를 만들고 있습니다. 하나는 문서를 읽는 도구이고, 다른 하나는 문서를 업데이트하는 도구입니다. 모든 문서는 키가 문서 ID이고 값이 콘텐츠인 간단한 딕셔너리 형태로 메모리에 존재합니다.

MCP 서버 설정하기

Python MCP SDK는 서버 생성을 간단하게 만들어 줍니다. 단 한 줄로 서버를 초기화할 수 있습니다:

python
from mcp.server.fastmcp import FastMCP
from pydantic import Field

mcp = FastMCP("DocumentMCP", log_level="ERROR")

이렇게 하면 도구 정의, 클라이언트 연결, 메시지 라우팅을 처리할 수 있는 완전한 기능을 갖춘 MCP 서버가 생성됩니다.

데코레이터를 이용한 도구 정의

우리 MCP 서버의 읽기 및 업데이트 도구가 document.pdf, spreadsheet.xlsx, report.txt, spec.md 네 개의 파일에 연결되어 있는 모습.

SDK의 데코레이터 방식을 사용하면 JSON 스키마를 수동으로 작성할 필요가 없어집니다. 간단한 도구를 정의하는 방법은 다음과 같습니다:

python
@mcp.tool(
    name="add_ints",
    description="Add two integers together",
)
def tool_fn(
    a=Field(description="First number to add"),
    b=Field(description="Second number to add"),
) -> int:
    return a + b

내부적으로 MCP는 Claude가 도구를 언제 어떻게 사용해야 하는지 이해하는 데 필요한 전체 도구 스키마를 생성합니다.

문서 읽기 도구 구축하기

첫 번째 도구는 ID로 문서 내용을 읽습니다. 문서 식별자를 받아서 메모리에 저장된 딕셔너리에서 해당 콘텐츠를 반환합니다:

python
@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    return docs[doc_id]

이 함수에는 존재하지 않는 문서에 대한 요청을 포착하기 위한 기본적인 오류 처리가 포함되어 있습니다. Claude가 유효한 문서 ID로 이 도구를 호출하면, 전체 문서 콘텐츠를 문자열로 받습니다.

문서 편집 도구 만들기

두 번째 도구는 문서에 대해 간단한 찾기-바꾸기 작업을 수행합니다. 이 도구는 문서 ID, 찾을 텍스트, 바꿀 텍스트 세 가지 매개변수를 필요로 합니다:

python
@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including white space."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

이 구현은 Python의 내장 문자열 replace 메서드를 사용하며, 이 메서드는 공백을 포함하여 정확히 일치해야 합니다. 이 도구는 딕셔너리 내에서 문서를 직접 수정합니다.

SDK 방식의 주요 이점

  • JSON 스키마를 수동으로 작성할 필요가 없음
  • 타입 힌트가 자동으로 매개변수 유효성 검사를 제공함
  • 필드 설명이 Claude가 도구 사용법을 이해하는 데 도움을 줌
  • 오류 처리가 Python 예외와 자연스럽게 통합됨
  • 도구 등록이 데코레이터를 통해 자동으로 이루어짐

MCP Python SDK는 도구 생성을 복잡한 스키마 작성 작업에서 간단한 Python 함수 정의로 바꿔줍니다. 도구는 더 유지보수하기 쉽고 테스트하기 쉬워지며, Claude는 도구를 효과적으로 사용하는 데 필요한 모든 메타데이터를 얻게 됩니다.