로드 중
로드 중

이제 MCP 서버가 작동하게 되었으니, 클라이언트 측을 구축할 차례입니다. 클라이언트는 우리 애플리케이션이 MCP 서버와 통신하고 그 기능에 접근할 수 있게 해주는 요소입니다.

클라이언트 아키텍처 이해하기

대부분의 실제 프로젝트에서는 MCP 클라이언트 또는 MCP 서버 중 하나만 구현하게 됩니다 - 둘 다 구현하지는 않습니다. 이 프로젝트에서는 둘이 어떻게 함께 작동하는지 볼 수 있도록 둘 다 구축하고 있습니다.

우리 서버는 MCP 클라이언트를 포함하고 있으며, 이는 별도의 MCP 서버와 양방향으로 통신합니다.

MCP 클라이언트는 두 가지 주요 구성 요소로 이루어져 있습니다:

  • MCP Client - 세션을 더 쉽게 사용하기 위해 우리가 만드는 커스텀 클래스
  • Client Session - 서버로의 실제 연결 (MCP Python SDK의 일부)

mcp_client.py에서 MCP Client는 Client Session에 연결되고, Client Session은 별도의 MCP 서버에 연결됩니다.

클라이언트 세션은 사용을 마쳤을 때 적절한 리소스 정리가 필요합니다. 그래서 우리는 모든 정리 작업을 자동으로 처리하기 위해 이를 커스텀 MCP Client 클래스로 감싸는 것입니다.

클라이언트가 애플리케이션에 맞는 방식

우리 애플리케이션 흐름을 기억하시나요? 우리의 CLI 코드는 MCP 서버와 관련해 두 가지 주요 작업을 수행해야 합니다:

아래 두 단계의 시퀀스 다이어그램: MCP 클라이언트는 ListToolsRequest를 보낸 다음 CallToolRequest를 보내고 각각의 결과를 받습니다.

  1. Claude에게 전달할 사용 가능한 도구 목록 가져오기
  2. Claude가 요청할 때 도구 실행하기

MCP 클라이언트는 우리 애플리케이션 코드가 사용할 수 있는 간단한 메서드 호출을 통해 이러한 기능을 제공합니다.

핵심 메서드 구현하기

클라이언트에서 두 가지 핵심 메서드인 list_tools()와 call_tool()을 구현해야 합니다.

List Tools 메서드

이 메서드는 서버에서 사용 가능한 모든 도구를 가져옵니다:

python
async def list_tools(self) -> list[types.Tool]:
    result = await self.session().list_tools()
    return result.tools

간단합니다 - 우리의 세션(서버로의 연결)에 접근하고, 내장된 list_tools() 함수를 호출한 다음, 결과에서 도구들을 반환합니다.

Call Tool 메서드

이 메서드는 서버에서 특정 도구를 실행합니다:

python
async def call_tool(
    self, tool_name: str, tool_input: dict
) -> types.CallToolResult | None:
    return await self.session().call_tool(tool_name, tool_input)

도구 이름과 입력 매개변수(Claude가 제공)를 서버에 전달하고 결과를 반환합니다.

클라이언트 테스트하기

구현을 테스트하기 위해 클라이언트를 직접 실행할 수 있습니다. 파일 하단에는 간단한 테스트 하네스가 포함되어 있습니다. 새로 만든 메서드 중 하나를 호출하게 하고 결과를 출력해 보세요:

python
async with MCPClient(
    command="uv", args=["run", "mcp_server.py"]
) as client:
    result = await client.list_tools()
    print(result)

이 테스트를 실행하면, 앞서 만든 read_doc_contents와 edit_document 도구를 포함해 우리의 도구 정의가 출력되는 것을 볼 수 있습니다.

모든 것을 종합하기

이제 클라이언트가 도구를 나열하고 호출할 수 있으니, 전체 흐름을 테스트할 수 있습니다. 메인 애플리케이션을 실행하고 Claude에게 문서에 대해 질문하면:

  1. 우리 코드는 클라이언트를 사용해 사용 가능한 도구를 가져옵니다
  2. 이 도구들은 사용자의 질문과 함께 Claude에게 전송됩니다
  3. Claude는 read_doc_contents 도구를 사용하기로 결정합니다
  4. 우리 코드는 클라이언트를 사용해 그 도구를 실행합니다
  5. 결과는 Claude에게 다시 전송되고, Claude는 사용자에게 응답합니다

예를 들어, "report.pdf 문서의 내용은 무엇인가요?"라고 질문하면 Claude가 우리의 문서 읽기 도구를 사용하게 되고, 우리가 서버에 설정했던 20m 응축기 타워 문서에 대한 정보를 돌려받게 됩니다.

클라이언트는 우리 애플리케이션 로직과 MCP 서버 사이의 다리 역할을 하며, 기본 연결 세부 사항에 대해 걱정할 필요 없이 서버 기능에 쉽게 접근할 수 있게 해줍니다.