스트림릿으로 MCP 클라이언트 개발해보기: AI 웹 앱 제작

MCP 클라이언트 개발에 스트림릿 사용하기: 인공지능 웹 앱 만들기 이전 글 "MCP 튜토리얼: 6단계로 첫 번째 MCP 서버 구축하기"에서는 MCP 아키텍처와 MCP 서버에 대해 상세히 소개하였습니다. 이번 튜토리얼에서는 스트림릿을 사용하여 대화형 MCP 클라이언트 인터페이스를 구축하는 방법을 살펴보겠습니다. MCP 서버는 다양한 도구와 리소스에 연결하여 기능을 제공하는 반면, MCP 클라이언트는 이러한 기능을 인터페이스를 통해 활용합니다. 스트림릿은 데이터 주도형 대화형 웹 애플리케이션 개발용 가벼운 파이썬 라이브러리로, 개발 주기를 가속화하고 프론트엔드 프레임워크를 추상화하여 빠른 프로토타입 제작과 인공지능 기반 도구의 원활한 배포에 최적화되어 있습니다. 따라서, 최소한의 설정으로 스트림릿 MCP 클라이언트 사용자 인터페이스를 구축하고, 원격 MCP 서버와 연결하여 다양한 AI 기능을 탐색하겠습니다. 프로젝트 개요 사용자가 관심 있는 주제를 입력하고, DeepWiki와 HuggingFace 두 가지 MCP 서버 중 하나를 선택하여 관련 리소스를 제공하는 대화형 웹 앱 프로토타입을 만듭니다. DeepWiki는 코드베이스와 GitHub 저장소를 요약하는 전문 서비스이며, HuggingFace MCP 서버는 사용자의 관심 주제와 관련된 오픈 소스 데이터셋과 모델을 추천합니다. 아래 이미지는 "감성 분석"이라는 주제에 대한 웹 앱 출력 예시입니다. 개발 환경 설정 먼저, 간단한 프로젝트 폴더 구조를 사용하여 프로젝트 디렉토리를 설정합니다. mcp_streamlit_client/ ├── .env # 환경 변수 (API 키) ├── README.md # 프로젝트 문서 ├── requirements.txt # 필요한 라이브러리와 의존성 └── app.py # 주 스트림릿 애플리케이션 필요한 라이브러리를 설치해야 합니다. 웹 인터페이스를 구축하기 위해 스트림릿이 필요하며, OpenAI의 API를 사용하여 MCP와 상호작용할 수 있도록 openai 라이브러리도 설치해야 합니다. bash pip install streamlit openai 또는 requirements.txt 파일을 생성하여 라이브러리 버전을 지정하고 재현 가능한 설치를 수행할 수 있습니다. bash pip install -r requirements.txt 다음으로, API 키를 안전하게 관리하기 위해 환경 변수를 사용해야 합니다. OpenAI와 같은 LLM 공급업체를 사용할 때는 API 키 설정이 필요하며, 이를 직접 스크립트에 하드 코딩하지 않고 환경 변수를 통해 로드하는 것이 가장 좋은 방법입니다. 특히 코드를 공유하거나 애플리케이션을 배포할 계획이 있다면 더욱 그렇습니다. .env 파일에 다음 형식으로 API 키를 추가합니다. OPENAI_API_KEY="여기에_당신의_OpenAI_API_키를_입력하세요" HF_API_KEY="여기에_당신의_Hugging_Face_API_토큰을_입력하세요" 그런 다음 app.py 스크립트에서 dotenv 라이브러리의 load_dotenv() 함수를 사용하여 이 변수들을 애플리케이션 환경에 로드할 수 있습니다. ```python from dotenv import load_dotenv import os load_dotenv() HuggingFace API 키 접근 HF_API_KEY = os.getenv('HF_API_KEY') ``` MCP 서버와 클라이언트 연결 MCP 클라이언트 개발에 앞서, MCP 서버-클라이언트 연결의 기본 사항을 이해해야 합니다. MCP의 인기가 증가하면서 점점 더 많은 LLM 공급업체들이 MCP 클라이언트 구현을 지원하고 있습니다. 예를 들어, OpenAI는 아래 코드를 사용하여 MCP 클라이언트를 간단히 초기화할 수 있습니다. ```python from openai import OpenAI client = OpenAI() ``` 더 자세한 내용은 "클라이언트 개발자를 위한 가이드"를 참조하세요. 이 가이드는 Anthropic MCP 클라이언트 설정 예시를 제공하며, 조금 복잡하지만 세션 및 리소스 관리가 더 효율적입니다. MCP 클라이언트를 서버에 연결하려면, 로컬 MCP 서버의 스크립트 경로 또는 원격 MCP 서버의 URL을 입력으로 받는 연결 메서드를 구현해야 합니다. 로컬 MCP 서버는 로컬 머신에서 실행되는 프로그램이며, 원격 MCP 서버는 온라인에 배포되어 URL을 통해 접근 가능합니다. 예를 들어, "DeepWiki" 원격 MCP 서버에 "https://mcp.deepwiki.com/mcp"를 통해 연결할 수 있습니다. python response = client.responses.create( model="gpt-4.1", tools=[ { "type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp", "require_approval": "never", }, ] ) 더 자세한 내용은 완벽한 "원격 MCP 서버 카탈로그"를 참조하세요. 또한, "클라이언트 개발자를 위한 가이드"는 로컬 MCP 서버 연결 방법도 제공합니다. 스트림릿 MCP 클라이언트 구축 MCP 클라이언트와 서버 사이의 연결 기본 사항을 이해한 후, 사용자 경험을 향상시키기 위해 이러한 기능을 웹 인터페이스 내에 캡슐화합니다. 이 웹 앱은 모듈성을 고려하여 설계되었으며, 여러 요소를 스트림릿 메서드 (예: st.radio(), st.button(), st.info(), st.title(), st.text_area())를 사용하여 구현됩니다. 스트림릿 페이지 초기화 먼저 initialize_page() 함수를 사용하여 페이지 아이콘과 제목을 설정하고, 전체 웹 앱 레이아웃이 중앙에 정렬되도록 layout="centered"를 사용합니다. 이 함수는 페이지 제목 아래에 위젯을 배치할 수 있는 컬럼 객체를 반환합니다. ```python import streamlit as st def initialize_page(): """스트림릿 페이지 구성과 레이아웃 초기화""" st.set_page_config( page_icon="🤖", # 로봇 이모티콘을 페이지 아이콘으로 사용 layout="centered" # 페이지 콘텐츠를 중앙 정렬 ) st.title("스트림릿 MCP 클라이언트") # 앱의 주 제목 설정 # 페이지 제목 아래에 위젯을 배치할 컬럼 객체 반환 return st.columns(1)[0] ``` 사용자 입력 받기 get_user_input() 함수는 사용자가 입력을 제공할 수 있도록 st.text_area() 위젯을 생성합니다. height 매개변수는 입력 박스의 크기를 적절히 조정하며, 플레이스홀더 텍스트는 사용자에게 특정 지침을 제공합니다. python def get_user_input(column): """사용자 입력 처리 및 텍스트 반환""" user_text = column.text_area( "관심 있는 주제를 입력해주세요:", height=100, placeholder="여기에 작성해주세요..." ) return user_text MCP 서버 선택 create_mcp_server_dropdown() 함수는 다양한 MCP 서버를 선택할 수 있도록 하는 유연성을 제공합니다. 이 함수는 MCP 서버의 레이블과 URL을 매핑하는 사전을 정의하고, 스트림릿의 st.radio() 위젯을 사용하여 사용자가 선택할 수 있는 라디오 버튼을 표시합니다. 이 함수는 선택된 서버의 레이블과 URL을 반환하여 다음 단계에서 응답을 생성하는데 사용됩니다. ```python def create_mcp_server_dropdown(): # MCP 서버 목록 정의 mcp_servers = { "deepwiki": "https://mcp.deepwiki.com/mcp", "huggingface": "https://huggingface.co/mcp" } # MCP 서버 선택 라디오 버튼 생성 selected_server = st.radio( "MCP 서버 선택", options=list(mcp_servers.keys()), help="접속할 MCP 서버를 선택하세요" ) # 선택된 서버의 URL 가져오기 server_url = mcp_servers[selected_server] return selected_server, server_url ``` 응답 생성 이전에 client.responses.create()를 사용하여 응답을 생성하는 표준 방법을 살펴보았습니다. 아래 generate_response() 함수는 이 방법을 확장하여 사용자 입력을 LLM에 전송하고, 선택된 MCP 서버를 외부 도구로 활용하여 요청을 수행합니다. 생성된 응답은 스트림릿의 정보 위젯 st.info()를 사용하여 표시되며, 응답이 생성되지 않으면 오류 메시지를 st.error()를 통해 반환합니다. ```python from openai import OpenAI import os load_dotenv() HF_API_KEY = os.getenv('HF_API_KEY') def generate_response(user_text, selected_server, server_url): """OpenAI 클라이언트와 MCP 도구를 사용하여 응답 생성""" client = OpenAI() try: mcp_tool = { "type": "mcp", "server_label": selected_server, "server_url": server_url, "require_approval": "never", } if selected_server == 'huggingface': if HF_API_KEY: mcp_tool["headers"] = {"Authorization": f"Bearer {HF_API_KEY}"} else: st.warning("Hugging Face API 키를 .env에서 찾을 수 없습니다. 일부 기능이 제한될 수 있습니다.") prompt_text = f"이 주제와 관련된 리소스 목록을 알려주세요: {user_text}?" else: prompt_text = f"이 주제와 관련된 코드베이스 내용을 요약해주세요: {user_text}?" response = client.responses.create( model="gpt-3.5-turbo", tools=[mcp_tool], input=prompt_text ) st.info( f""" **응답:** {response.output_text} """ ) return response except Exception as e: st.error(f"응답 생성중 오류 발생: {str(e)}") return None ``` 메인 함수 정의 마지막 단계는 모든 작업을 순차적으로 연결하는 main() 함수를 생성하는 것입니다. 이 함수는 initialize_page(), get_user_input(), create_mcp_server_dropdown()를 차례대로 호출하여 UI를 설정하고 사용자 입력을 수집합니다. 그런 다음, 사용자가 st.button("응답 생성")을 클릭할 때 generate_response()를 트리거하는 조건을 생성합니다. 클릭 시, 입력이 있는지 확인하고 진행 상황을 표시하기 위해 st.spinner()를 사용하며, 응답을 반환합니다. 입력이 제공되지 않으면 불필요한 토큰 사용과 비용 증가를 방지하기 위해 경고 메시지를 표시합니다. ```python def main(): # 1. 페이지 레이아웃 초기화 main_column = initialize_page() # 2. 사용자 입력 받기 user_text = get_user_input(main_column) # 3. 사용자가 MCP 서버를 선택할 수 있도록 함 with main_column: # 메인 컬럼 내에 라디오 버튼 배치 selected_server, server_url = create_mcp_server_dropdown() # 4. 응답 생성을 트리거하는 버튼 추가 if st.button("응답 생성", key="generate_button"): if user_text: with st.spinner("응답 생성 중..."): generate_response(user_text, selected_server, server_url) else: st.warning("주제를 먼저 입력해주세요.") ``` 스트림릿 애플리케이션 실행 마지막으로, 터미널이나 명령 프롬프트를 열고 파일을 저장한 디렉토리로 이동하여 다음 명령어를 실행합니다. bash streamlit run app.py 로컬에서 애플리케이션을 개발 중이라면, 로컬 스트림릿 서버가 시작되고 애플리케이션이 기본 웹 브라우저의 새 탭에서 열립니다. AWS JupyterLab와 같은 클라우드 환경에서 개발 중이라면, URL을 다음 형식으로 변경합니다: https://<APP_ID>.studio.<REGION>.sagemaker.aws/jupyterlab/default/proxy/8501/. "Amazon SageMaker AI Studio에서 스트림릿 앱 구축하기"라는 포스트를 참고하면 도움이 될 것입니다. 마지막으로, "mcp-streamlit-client" GitHub 리포지토리에서 코드를 찾을 수 있으며, 다양한 주제를 시도해 보면서 스트림릿 MCP 클라이언트를 탐색할 수 있습니다. 마무리 메시지 이전 글에서 MCP 아키텍처와 MCP 서버에 대해 소개한 바 있습니다. 이번에는 스트림릿을 사용하여 MCP 클라이언트를 구현하여 원격 MCP 서버의 도구 호출 기능을 강화하는 방법을 살펴보았습니다. 이 가이드는 개발 환경 설정, API 키 보안, 사용자 입력 처리, 원격 MCP 서버 연결, AI 생성 응답 표시 등의 필수 단계를 제공합니다. 애플리케이션을 실제 배포하기 위해 다음 단계를 고려하세요: 보안: API 키를 안전하게 처리하고, 민감한 정보를 노출하지 않도록 주의해야 합니다. 성능 최적화: 응답 시간을 줄이고, 서버와 클라이언트 간의 통신 효율성을 높이는 방법을 탐색하세요. 사용자 경험 향상: UI를 더욱 직관적이고 사용자 친화적으로 만들기 위해 추가적인 위젯과 기능을 구현하세요. 이러한 단계를 통해 MCP 클라이언트를 효과적으로 구축하고, AI 기반 도구의 활용성을 극대화할 수 있을 것입니다.