Implementing MCP Servers in Python: An AI Shopping Assistant with Gradio

🖼️ 인포그래픽

Implementing MCP Servers in Python: An AI Shopping Assistant with Gradio 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Gradio의 MCP 통합을 이용해 웹 탐색 도구와 IDM-VTON 가상 피팅 모델을 연결하고, VS Code AI 채팅에서 사용할 수 있는 개인용 AI 쇼핑 도우미를 구현하는 방법을 설명한다.

📌 핵심 요약

Gradio는 Python 함수와 API 엔드포인트를 이름·설명·입력 스키마를 갖춘 MCP 도구로 자동 변환하며, 함수의 독스트링을 도구와 매개변수 설명에 활용한다.
예제 쇼핑 도우미는 LLM의 일반적인 추론 능력, Playwright의 웹 탐색 기능, Hugging Face의 IDM-VTON 가상 피팅 기능을 결합한다.
핵심 함수인 vton_generation은 사람 사진과 의류 이미지를 받아 IDM-VTON Space의 /tryon API를 호출하고, 해당 인물이 선택한 옷을 입은 것처럼 생성된 이미지를 반환한다.
Gradio 인터페이스를 mcp_server=True로 실행한 뒤 VS Code의 mcp.json에 로컬 Gradio MCP 서버와 Playwright MCP 서버를 등록하면 AI 채팅에서 두 도구를 사용할 수 있다.
사용자는 자신의 사진 URL과 쇼핑 조건을 자연어로 제시해 온라인 상점의 상품 검색부터 여러 의류의 가상 착용 결과 생성까지 하나의 대화 흐름으로 요청할 수 있다.

🧩 주요 포인트

Gradio는 Python 함수와 API 엔드포인트를 이름·설명·입력 스키마를 갖춘 MCP 도구로 자동 변환하며, 함수의 독스트링을 도구와 매개변수 설명에 활용한다.
예제 쇼핑 도우미는 LLM의 일반적인 추론 능력, Playwright의 웹 탐색 기능, Hugging Face의 IDM-VTON 가상 피팅 기능을 결합한다.
핵심 함수인 vton_generation은 사람 사진과 의류 이미지를 받아 IDM-VTON Space의 /tryon API를 호출하고, 해당 인물이 선택한 옷을 입은 것처럼 생성된 이미지를 반환한다.
Gradio 인터페이스를 mcp_server=True로 실행한 뒤 VS Code의 mcp.json에 로컬 Gradio MCP 서버와 Playwright MCP 서버를 등록하면 AI 채팅에서 두 도구를 사용할 수 있다.
사용자는 자신의 사진 URL과 쇼핑 조건을 자연어로 제시해 온라인 상점의 상품 검색부터 여러 의류의 가상 착용 결과 생성까지 하나의 대화 흐름으로 요청할 수 있다.

🧠 상세 정리

1. Gradio MCP 통합이 제공하는 기능

글은 LLM의 일반적인 추론 능력에 Hugging Face Hub의 전문 AI 모델과 Space를 연결하면 단순한 텍스트 응답을 넘어 실제 작업을 수행할 수 있다고 설명한다. Gradio의 MCP 통합은 Gradio 앱의 각 API 엔드포인트를 이름, 설명, 입력 스키마를 갖춘 LLM용 도구로 자동 변환하며, Python 함수의 독스트링을 도구와 매개변수 설명 생성에 사용한다. 또한 MCP 클라이언트로 진행 상황을 실시간 스트리밍하므로 개발자가 별도의 상태 알림 기능을 직접 구현하지 않아도 된다. 공개 URL과 여러 파일 형식을 포함한 파일 업로드도 자동으로 처리해, 이미지 같은 입력이 필요한 AI 모델을 MCP 도구로 노출하는 과정을 단순화한다.

2. 개인용 AI 스타일리스트의 목표와 구성

예제의 목표는 쇼핑에 드는 시간과 직접 옷을 입어보는 번거로움을 줄이는 AI 쇼핑 도우미를 만드는 것이다. 이 도우미는 온라인 의류 매장을 탐색해 사용자가 원하는 조건의 상품을 찾고, 선택한 옷을 사용자의 사진에 가상으로 입혀 결과를 보여준다. 구성 요소는 사진 속 인물의 의상을 바꾸는 IDM-VTON 확산 모델, AI 웹 애플리케이션과 MCP 서버를 만드는 Gradio, 임의의 MCP 서버를 추가할 수 있는 VS Code AI 채팅이다. LLM은 VS Code의 대화 인터페이스에서 요청을 이해하고, 웹 탐색과 가상 피팅에 필요한 전문 도구를 호출하는 역할을 맡는다.

3. IDM-VTON 호출 함수 구현

서버의 핵심 도구는 사람 이미지와 의류 이미지를 입력받는 vton_generation 함수다. 코드는 gradio_client의 Client를 사용해 freddyaboulton/IDM-VTON Space에 연결하며, 실제 사용 시에는 지정된 위치에 Hugging Face 토큰을 제공해야 한다. 함수는 handle_file로 두 이미지를 처리한 뒤 사람 이미지를 background에, 의류 이미지를 garm_img에 넣어 /tryon API를 호출한다. 예제 호출에는 자동 마스크 사용, 자르기 비활성화, 30회의 디노이즈 단계, 42번 시드 등이 지정되어 있으며, 반환된 결과 중 첫 번째 이미지를 최종 가상 피팅 결과로 돌려준다.

4. Gradio 인터페이스를 MCP 서버로 전환

vton_generation 함수는 두 개의 이미지 입력과 한 개의 이미지 출력을 가진 gr.Interface로 감싸진다. 사람 사진과 의류 사진 입력은 모두 filepath 유형으로 정의되어 URL 또는 파일 기반 이미지가 모델 호출에 전달될 수 있고, 생성 결과 역시 filepath 유형의 이미지로 반환된다. 실행부에서 launch(mcp_server=True)를 지정하면 Gradio가 이 Python 함수를 LLM이 이해하고 호출할 수 있는 MCP 도구로 자동 공개한다. 원래 IDM-VTON Space는 자동 MCP 기능보다 앞선 Gradio 4.x로 구현되었기 때문에, 이 예제는 기존 Space를 직접 바꾸는 대신 별도의 최신 Gradio 인터페이스에서 Gradio API 클라이언트로 원본 Space를 호출하는 구조를 사용한다.

5. VS Code와 웹 탐색 도구 연결

Gradio MCP 서버를 실행한 다음에는 VS Code 명령 패널에서 MCP 사용자 설정 파일인 mcp.json을 열어 서버 정보를 등록한다. vton 서버의 URL은 예제에서 http://127.0.0.1:7860/gradio_api/mcp/로 지정되지만, 실제 값은 앞 단계에서 Gradio가 콘솔에 출력한 주소와 일치해야 한다. 같은 설정에 npx로 실행되는 @playwright/mcp 패키지를 추가하면 AI 도우미가 웹사이트를 탐색할 수 있다. Playwright MCP 서버를 실행하려면 Node가 설치되어 있어야 하며, 이 구성을 통해 VS Code AI 채팅은 상품을 찾는 브라우저 도구와 이미지를 생성하는 가상 피팅 도구를 함께 호출할 수 있다.

6. 대화형 쇼핑 흐름과 결론

설정이 끝나면 사용자는 VS Code에서 새 AI 채팅을 열고 원하는 쇼핑 작업을 자연어로 요청할 수 있다. 글의 예시는 유니클로 웹사이트에서 파란색 티셔츠를 찾아 세 가지 상품을 고른 뒤, 사용자가 제공한 사진 URL을 이용해 각 옷의 가상 착용 모습을 보여 달라는 요청이다. 이 흐름에서 Playwright는 온라인 매장 탐색을 담당하고, Gradio MCP 도구는 찾아낸 의류 이미지와 사용자 사진을 IDM-VTON에 전달해 결과를 생성한다. 글은 Gradio, MCP, IDM-VTON 같은 전문 모델을 결합하면 개발자가 자신이 해결하려는 문제에 맞춘 지능형 도우미를 비교적 간단한 Python 코드와 설정으로 구축할 수 있다고 결론짓는다.

🧾 핵심 주장 / 시사점

이 구현은 LLM이 모든 기능을 직접 수행하게 하지 않고, 요청 해석과 작업 조정은 LLM에 맡기면서 웹 탐색과 이미지 생성은 각각 Playwright와 IDM-VTON에 분리한다.
Gradio에서 함수의 독스트링과 입출력 컴포넌트가 MCP 도구의 설명과 스키마로 자동 변환되므로, Python 함수 정의 자체가 LLM과 전문 모델 사이의 도구 인터페이스 역할을 한다.
기존 모델 Space가 자동 MCP 기능을 지원하지 않더라도 Gradio API 클라이언트로 호출하는 별도 MCP 인터페이스를 앞에 두어 대화형 AI 도구로 활용할 수 있다.

✅ 액션 아이템

Gradio MCP에서 노출할 Python 함수·API를 이름·설명·입력 스키마와 독스트링으로 정리해 도구 인터페이스 일관성을 높인다.
vton_generation을 핵심 함수로 두어 사람 사진 URL과 의류 이미지 URL을 받아 IDM-VTON Space의 /tryon API를 호출한 뒤 결과 이미지를 검증한다.
mcp_server=True로 Gradio MCP를 띄운 뒤 VS Code mcp.json에 로컬 Gradio MCP와 Playwright MCP를 등록해 하나의 채팅 흐름에서 사용하도록 구성한다.