리소스 정의하기

MCP 서버의 리소스는 일반적인 HTTP 서버의 GET 요청 핸들러와 유사하게 클라이언트에 데이터를 노출할 수 있게 해줍니다. 작업을 수행하기보다는 정보를 가져와야 하는 상황에 적합합니다.

리소스 이해하기

리소스를 문자열, JSON, 바이너리 파일 등 어떤 유형의 데이터든 반환할 수 있는 읽기 전용 엔드포인트라고 생각하세요. 'mime_type'을 설정하여 클라이언트에게 반환하는 데이터의 종류에 대한 힌트를 제공합니다.

리소스는 클라이언트가 요청할 수 있는 URI(URL과 유사)를 정의하여 작동합니다. 클라이언트가 데이터가 필요할 때 특정 URI와 함께 ReadResourceRequest를 전송하면, 서버는 데이터를 포함한 ReadResourceResult로 응답합니다.

두 가지 유형의 리소스

생성할 수 있는 리소스에는 두 가지 주요 유형이 있습니다:

• 직접 리소스(Direct Resources) - 매개변수를 포함하지 않는 정적 URI를 가집니다(예: "docs://documents")
• 템플릿 리소스(Templated Resources) - URI에 매개변수를 포함하며, 이는 파싱되어 함수에 전달됩니다(예: "docs://documents/{doc_id}")

템플릿 리소스의 경우, Python SDK가 URI에서 매개변수를 자동으로 파싱하여 함수에 키워드 인자로 전달합니다. URI의 매개변수 이름은 함수의 매개변수 이름과 정확히 일치해야 합니다.

리소스 생성하기

두 가지 유형의 리소스를 구현하는 방법은 다음과 같습니다:

@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

MCP Python SDK는 반환하는 모든 것을 자동으로 직렬화합니다. 데이터를 수동으로 JSON 문자열로 변환할 필요 없이, Python 객체를 그대로 반환하면 SDK가 변환을 처리합니다.

리소스 테스트하기

MCP Inspector를 사용하여 리소스를 테스트할 수 있습니다. 다음 명령으로 서버를 시작하세요:

uv run mcp dev mcp_server.py

그런 다음 브라우저에서 inspector에 연결합니다. 두 개의 섹션이 표시됩니다:

• Resources - 직접/정적 리소스 목록을 표시합니다
• Resource Templates - 템플릿 리소스를 표시합니다

리소스를 클릭하여 테스트하세요. 템플릿 리소스의 경우 매개변수 값을 제공해야 합니다. Inspector는 mime type과 직렬화된 데이터를 포함하여 클라이언트가 받게 될 정확한 응답 구조를 보여줍니다.

실용적인 사용 사례

리소스는 채팅 애플리케이션에서 문서 멘션과 같은 기능을 구현하는 데 이상적입니다. 예를 들어, 사용자가 문서를 멘션하기 위해 "@"를 입력할 때 다음과 같이 할 수 있습니다:

1. 직접 리소스를 사용하여 자동완성을 위한 사용 가능한 모든 문서 목록을 가져옵니다
2. 템플릿 리소스를 사용하여 멘션된 특정 문서의 내용을 가져옵니다

이 접근 방식을 사용하면 AI가 정보를 가져오기 위해 도구를 사용할 필요 없이 문서 내용을 프롬프트에 미리 주입할 수 있습니다.