로드 중
로드 중

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

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

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

MCP 서버 설정하기

이 프로젝트는 MCP Python SDK 버전 1을 사용하며, 프로젝트 설정 시 해당 버전이 자동으로 설치됩니다. 직접 프로젝트를 설정하는 경우에는 "mcp[cli]<2"를 설치하세요. 버전 2에서는 FastMCP가 MCPServer로 이름이 바뀌었기 때문에, 아래의 import 구문은 버전 2에서는 실패합니다.

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