MCP로 도구 정의하기

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

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

MCP 서버 설정하기

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

from mcp.server.fastmcp import FastMCP

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

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

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

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

@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로 문서 콘텐츠를 읽습니다. 문서 식별자를 받아 메모리 내 딕셔너리에서 해당하는 콘텐츠를 반환합니다:

@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, 찾을 텍스트, 그리고 대체할 텍스트입니다:

@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는 도구를 효과적으로 사용하는 데 필요한 모든 메타데이터를 얻게 됩니다.