Claude Academy
로드 중

MCP로 도구 정의하기

강의 519분

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

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

이 예제에서는 문서 작업을 관리하는 MCP 서버를 만들고 있습니다. 이 서버에는 두 가지 주요 도구가 있습니다. 하나는 문서 내용을 읽는 도구이고, 다른 하나는 문서 내용을 업데이트하는 도구입니다. 모든 문서는 키가 문서 ID이고 값이 내용 문자열인 간단한 딕셔너리 형태로 메모리에 존재합니다.

MCP Python SDK의 장점

MCP 프로젝트는 여러 프로그래밍 언어에 걸쳐 서버와 클라이언트를 구축하기 위한 공식 SDK를 제공합니다. Python SDK를 사용하면 다음과 같은 여러 이점이 있습니다:

  • 최소한의 보일러플레이트 코드로 MCP 서버를 생성합니다
  • Python 함수 시그니처로부터 JSON 스키마를 자동으로 생성합니다
  • 데코레이터를 통해 도구 정의를 단순화합니다
  • 타입 검증과 오류 처리를 처리합니다

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

SDK로 도구를 정의하는 것이 얼마나 쉬운지 살펴보겠습니다. @mcp.tool 데코레이터는 타입 힌트 및 필드 설명과 결합되어, Claude가 이해하고 사용할 수 있는 적절한 도구 스키마를 자동으로 생성합니다.

서버 설정하기

이 과정에서는 MCP Python SDK 버전 1을 사용합니다. 아래의 import는 FastMCP의 이름이 변경된 버전 2에서는 실패합니다. 프로젝트를 직접 설정하는 경우, SDK를 버전 2 미만으로 유지하세요:

bash
uv add "mcp[cli]<2"

pip를 사용하는 경우, 동일한 버전 고정은 pip install "mcp[cli]<2"입니다.

기본적인 서버 설정에는 단 몇 줄만 필요합니다:

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

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

docs = {
    "deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
    "report.pdf": "The report details the state of a 20m condenser tower.",
    "financials.docx": "These financials outline the project's budget and expenditures",
    "outlook.pdf": "This document presents the projected future performance of the system",
    "plan.md": "The plan outlines the steps for the project's implementation.",
    "spec.txt": "These specifications define the technical requirements for the equipment"
}

읽기 도구 구현하기

첫 번째 도구는 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]

이 도구 정의에는 다음이 포함됩니다:

  • 동작을 설명하는 명확한 이름
  • 도구가 하는 일을 설명하는 설명
  • 필드 설명이 포함된 타입이 지정된 매개변수
  • 잘못된 문서 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 whitespace."),
    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)

이 도구는 세 가지 매개변수를 받습니다: 문서 ID, 찾을 텍스트, 그리고 대체할 텍스트입니다. 구현에서는 단순성을 위해 Python에 내장된 문자열 replace() 메서드를 사용합니다.

주요 구현 세부 사항

MCP SDK로 도구를 정의할 때는 다음과 같은 중요한 사항을 기억하세요:

  • 매개변수 설명을 추가하려면 pydantic에서 Field를 import하세요
  • 매개변수 타입을 지정하려면 타입 힌트를 사용하세요
  • 예외 상황에 대한 오류 처리를 포함하세요
  • 명확하고 설명적인 도구 이름과 설명을 작성하세요
  • MCP Python SDK는 함수 시그니처를 적절한 JSON 스키마로 자동 변환합니다

MCP Python SDK는 JSON 스키마를 직접 작성하는 것에 비해 도구를 만드는 복잡성을 극적으로 줄여줍니다. 예전에는 수십 줄의 스키마 정의가 필요했던 작업이 이제는 데코레이터가 적용된 몇 줄의 Python 함수만으로 가능해졌습니다.

@mcp.tool 데코레이터와 시그니처 기반 스키마 생성은 MCP Python SDK에서 제공됩니다. Claude Agent SDK는 커스텀 도구를 정의하기 위한 별도의 @tool 데코레이터를 제공하며, 이는 함수 시그니처에 pydantic Field 어노테이션을 사용하는 대신 명시적인 input_schema 인자를 요구합니다. Python에서 이 스키마는 매개변수 이름을 타입에 매핑하는 딕셔너리로, 예를 들면 {"latitude": float}와 같으며, Agent SDK가 이를 JSON Schema로 자동 변환해 줍니다. 또는 열거형, 범위, 선택적 필드, 중첩 객체가 필요한 경우에는 완전한 JSON Schema 딕셔너리를 사용할 수도 있습니다. 다른 곳에서 도구 코드를 읽을 때는 어떤 SDK를 import하는지 확인하세요. 두 데코레이터는 혼동하기 쉽기 때문입니다.