Dicklesworthstone/ultimate_mcp_client

**Model Context Protocol (MCP)**를 위한 포괄적인 비동기(asynchronous) 클라이언트입니다. 이 클라이언트는 Anthropic의 Claude와 같은 강력한 AI 모델과 외부 도구, 로컬/원격 서버, 그리고 문맥 데이터 소스(contextual data sources) 사이의 간극을 메워 복잡하고 상태 유지(stateful)가 가능한 상호작용을 가능하게 합니다.

Jeffrey Emanuel 제작

Model Context Protocol (MCP)는 AI 모델이 외부 기능(도구, 리소스, 프롬프트)과 상호작용하는 방식을 표준화합니다. 이 클라이언트는 MCP를 활용하기 위한 **궁극의 인터페이스(ultimate interface)**를 목표로 하며, 다음과 같은 기능을 제공합니다:

강력한 연결성 (Robust Connectivity): 내장된 회복 탄력성(resilience), 고급 오류 처리(error handling), 지능형 탐색 기능을 통해 다양한 MCP 서버(stdio, sse)에 안정적으로 연결합니다.

풍부한 사용자 경험 (Rich User Experience): 강력한 대화형 CLI와 현대적인 반응형(reactive) Web UI를 모두 제공하여 다양한 워크플로우에서의 사용성을 보장합니다.

고급 상태 관리 (Advanced State Management): 분기 가능한 대화 그래프(forkable conversation graphs), 세션 간 지속적인 상태 유지, 스마트 문맥 최적화(context optimization) 기술을 통해 단순한 채팅 기록 그 이상의 기능을 제공합니다.

개발자 조사 (Developer Introspection): OpenTelemetry 메트릭(metrics) 및 트레이스(traces)를 통해 심층적인 관측성(observability)을 제공하며, 클라이언트와 서버의 상태 및 성능을 모니터링할 수 있는 라이브 대시보드를 제공합니다.

원활한 통합 (Seamless Integration): 로컬 파일 시스템 스크립트, 로컬 네트워크 (mDNS) 서버, 로컬 포트 스캔 결과, 원격 레지스트리 항목, 그리고 Claude Desktop 앱과 같은 기존 도구의 설정까지 쉽게 탐색하고 통합할 수 있습니다.

이 프로젝트는 중요한 엔지니어링 과제들을 해결합니다. 특히 신뢰할 수 있는 stdio 통신, 비동기 상태 관리, 그리고 CLI와 Web 인터페이스 모두에서 일관된 경험을 제공하는 문제를 해결함으로써, 진정으로 포괄적인 MCP 클라이언트 솔루션을 전달하고자 합니다.

이중 인터페이스: Web UI & CLI
Web UI: Alpine.js, DaisyUI, 그리고 Tailwind CSS로 구축된 아름답고 반응성이 뛰어난 인터페이스입니다. WebSockets를 통한 실시간 채팅 스트리밍, 서버/도구 관리 모달, 시각적 대화 분기 뷰 (visual conversation branching view), 설정 구성, 다중 테마 전환 (multiple theme switching) (코드 하이라이팅을 위한 라이트/다크 모드 준수), 그리고 직접적인 도구 실행 기능을 특징으로 합니다.
CLI: 기능이 풍부한 대화형 셸 (/commands, 자동 완성, Rich Markdown 렌더링) 및 Typer를 통한 배치 모드 (batch-mode) 동작을 지원합니다. 모니터링을 위한 라이브 Textual User Interface (TUI) 대시보드를 포함합니다.

견고한 서버 연결 및 관리

• stdio, sse (HTTP Server-Sent Events), 그리고 streaming-http MCP 서버를 지원합니다.
  고급 STDIO 처리 (핵심 엔지니어링 노력): 노이즈가 심하거나 규격에 맞지 않는 stdio 서버를 유연하게 처리하도록 설계된 커스텀 RobustStdioSession을 특징으로 합니다. 여기에는 다음이 포함됩니다:
  노이즈 필터링 (Noise Filtering): 프로토콜을 손상시킬 수 있는 non-JSON-RPC 출력을 무시합니다.
  직접적인 Future 해결 (Direct Future Resolution): 더 빠른 응답 처리를 위해 복잡한 큐잉 (queueing)을 피합니다.
  프로세스 생명주기 관리 (Process Lifecycle Management): stdio 서버 프로세스를 안정적으로 시작, 모니터링, 종료 및 킬 (kill) 합니다.
  핵심 STDIO 안전성 (Critical STDIO Safety): 다층 시스템 (StdioProtectionWrapper, safe_stdout 컨텍스트 매니저, get_safe_console() 함수)을 통해 sys.stdout에 대한 우발적인 쓰기가 stdio 채널을 손상시키는 것을 방지하며, 여러 stdio 서버와 사용자 출력(필요 시 stderr로 리다이렉션됨)의 안전한 공존을 보장합니다. 이는 안정성을 위해 매우 중요했습니다.

회복 탄력성 (Resilience): 지수 백오프 (exponential backoff)를 적용한 자동 연결 재시도와 실패하는 서버를 위한 서킷 브레이커 (circuit breakers, @retry_with_circuit_breaker)를 지원합니다. 백그라운드 상태 모니터링 (ServerMonitor)이 서버 응답성을 체크합니다.

현대적인 전송 방식 지원

• Streaming-HTTP: 현대적인 streaming-http 방식에 대한 네이티브 지원

FastMCP 라이브러리를 통한 전송 프로토콜 (transport protocol). 이 전송 방식은 내장된 스트리밍 (streaming) 기능을 통해 HTTP 상에서 효율적인 양방향 통신을 제공하며, 현대적인 MCP 서버 배포에 이상적입니다.

지능형 전송 감지 (Intelligent Transport Detection):
서버 URL 및 탐색 (discovery) 정보를 기반으로 적절한 전송 유형을 자동으로 감지하고 제안합니다:

• 로컬 파일 경로 → stdio
• /sse 또는 /events 경로가 포함된 URL → sse
• 일반 HTTP/HTTPS URL → streaming-http (현대적인 서버의 기본값)

지능형 서버 탐색 (Intelligent Server Discovery)

• 설정된 파일 시스템 경로 내의 로컬 stdio 서버 (Python/JS 스크립트)를 자동 탐색합니다.
• mDNS 탐색 (Zeroconf): 로컬 네트워크 상의 MCP 서버 (_mcp._tcp.local.)를 실시간으로 탐색하고 알림을 보냅니다. LAN 서버 관리를 위한 대화형 명령 (/discover list, /discover connect 등)을 지원합니다.
• 로컬 포트 스캐닝 (Local Port Scanning): initialize 핸드셰이크 (handshake)를 시도하여 설정 가능한 범위의 로컬 포트 (예: 8000-9000)를 능동적으로 스캔하여 MCP 서버를 찾습니다. 모든 전송 유형 (stdio, sse, streaming-http)의 감지를 지원합니다. /config port-scan ... 명령을 통해 설정 가능합니다.
• 레지스트리 통합 (Registry Integration): (설정에 지정된) 원격 MCP 레지스트리에 연결하여 공유 서버를 찾고 추가합니다.
• Claude Desktop 가져오기 (Claude Desktop Import): 프로젝트 루트에 있는 claude_desktop_config.json을 자동으로 감지합니다.
• 지능형 구성 적응 (Intelligently adapts configurations):
  • wsl.exe ... bash -c "cmd" 호출을 직접적인 Linux 셸 실행 (/bin/bash -c "cmd")으로 재매핑합니다.
  • 원활한 통합을 위해 adapt_path_for_platform을 사용하여 인수의 Windows 스타일 경로 (C:\...)를 Linux/WSL 대응 경로 (/mnt/c/...)로 변환합니다.

강력한 AI 통합 및 스트리밍 (Powerful AI Integration & Streaming)

• 공식 anthropic SDK를 통해 Claude 모델과 깊이 있게 통합되어, 멀티 턴 (multi-turn) 도구 사용 시나리오를 지원합니다.
• 실시간 스트리밍 (Real-time Streaming): WebSockets (Web UI) 및 라이브 Rich를 통해 AI 응답과 도구 상태 업데이트를 스트리밍합니다.

rendering (CLI). 구조화된 입력이 필요한 도구를 위한 **부분적 JSON 입력 누적 (input_json_delta)**을 포함한 복잡한 스트리밍 이벤트를 처리합니다.

지능형 도구 라우팅 (Intelligent Tool Routing): 로드된 기능(capabilities)을 기반으로 도구 호출을 올바른 원본 서버로 전달합니다. API 호환성을 위해 정제된 이름을 사용하면서도, 내부적으로는 원래 이름을 추적합니다.

직접 도구 실행 (Direct Tool Execution): /tool 명령(CLI) 또는 전용 모달(Web UI)을 통해 사용자 정의 JSON 파라미터로 특정 도구를 실행합니다.

• Claude 모델과의 심층적인 통합 (공식 SDK 사용)

고급 대화 관리 (Advanced Conversation Management)

분기 (Branching): 분기 가능한 대화 그래프 (ConversationGraph)를 통해 히스토리를 잃지 않고 다양한 상호작용 경로를 탐색할 수 있습니다. Web UI에서 시각적으로 표현되며 탐색이 가능합니다.

지속성 (Persistence): 대화 그래프(모든 분기 및 메시지 포함)는 설정 디렉토리의 JSON 파일로 자동 저장되어 세션 간 상태를 보존합니다.

컨텍스트 최적화 (Context Optimization): 컨텍스트 제한 내에 머물 수 있도록 지정된 AI 모델(설정 가능)을 사용하여 긴 대화 기록을 자동 또는 수동으로 요약 (/optimize)합니다.

동적 프롬프트 (Dynamic Prompts): /prompt 명령을 사용하여 서버로부터 가져온 사전 정의된 프롬프트 템플릿을 현재 대화 컨텍스트에 주입합니다.

가져오기/내보내기 (Import/Export): 공유 또는 백업을 위해 전체 대화 분기를 휴대 가능한 JSON 형식으로 쉽게 저장 (/export)하고 불러올 (/import) 수 있습니다.

관측 가능성 및 모니터링 (Observability & Monitoring)

OpenTelemetry: 클라이언트 작업, 서버 요청 및 도구 실행 성능을 모니터링하기 위해 통합된 메트릭(counter, opentelemetry-sdk를 사용한 histogram) 및 트레이싱(span)을 제공합니다. 디버깅을 위해 콘솔 익스포터(Console exporters)를 활성화할 수 있습니다.

라이브 대시보드 (Live Dashboards):

CLI: Rich로 구축된 실시간 TUI 대시보드 (/dashboard)를 통해 서버 상태, 도구 사용 통계 및 클라이언트 정보를 보여줍니다.

Web UI: 서버 상태, 상태 지표(health indicators) 및 기능(capability) 수를 동적으로 업데이트합니다.

스마트 캐싱 (Smart Caching)

• 선택적 디스크 캐싱 (diskcache)

) 및 도구 결과에 대한 인메모리 캐싱 (in-memory caching)을 통해 속도를 향상시키고 비용을 절감합니다. - 도구 카테고리별(예: weather, filesystem)로 설정 가능한 Time-To-Live (TTL). 의존성 추적 (Dependency Tracking): 도구 간의 관계를 정의합니다. 하나의 도구 캐시(예: stock:lookup)를 무효화하면 종속된 캐시(예: stock:analyze)도 자동으로 무효화할 수 있습니다. /cache dependencies를 통해 그래프를 확인할 수 있습니다.

Ultimate MCP Client의 인터페이스를 살짝 살펴보겠습니다:

참고: 일부 스크린샷에는 llm_gateway:generate_completion과 같은 도구가 포함되어 있습니다. 이는 동일한 저자가 만든 또 다른 프로젝트인 LLM Gateway MCP Server에서 제공하는 것입니다. 이 서버는 MCP 네이티브 게이트웨이 역할을 하여, (이 클라이언트에서 사용하는) Claude와 같은 고급 에이전트가 다양한 다른 LLM(예: Gemini, GPT-4o-mini)에 작업을 지능적으로 위임할 수 있도록 하며, 종종 비용과 성능을 최적화합니다.

Python 3.13 이상이 필요합니다.

먼저, uv(권장되는 빠른 Python 패키지 설치 도구)를 설치하세요:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
...

그 다음 리포지토리를 클론하고, Python 3.13+를 사용하여 가상 환경을 설정한 뒤 패키지를 설치하세요:

git clone https://github.com/Dicklesworthstone/ultimate_mcp_client
cd ultimate_mcp_client
# uv를 사용하여 venv 생성 (권장)
...

Anthropic API 키를 환경 변수로 설정하세요:

export ANTHROPIC_API_KEY="sk-ant-..."
# 또는 프로젝트 루트의 .env 파일에 ANTHROPIC_API_KEY="sk-ant-..."를 추가하세요

또는 대화형 CLI에서 /config api-key ... 명령어를 사용하거나 Web UI 설정 패널을 통해 나중에 설정할 수도 있습니다.

mcpclient run --webui

그 다음 브라우저에서 http://127.0.0.1:8017 (또는 설정된 호스트/포트)을 여세요.

호스트와 포트를 사용자 정의할 수 있습니다:

mcpclient run --webui --host 0.0.0.0 --port 8080

mcpclient run --interactive

mcpclient run --query "What's the weather in New York?"

mcpclient run --dashboard

# 포트 스캐닝 활성화 (비활성화된 경우)
mcpclient config port-scan enable true
# 범위 설정 (예시)
...

# 현재 대화 브랜치(conversation branch)를 기본 파일명으로 내보내기
mcpclient export
# 현재 브랜치를 특정 파일로 내보내기
...

웹 UI (mcpclient run --webui)는 Alpine.js, Tailwind CSS, DaisyUI를 사용하여 구축된 현대적이고 사용자 친화적인 인터페이스를 제공합니다:

실시간 채팅 (Real-time Chat): WebSockets를 통한 Claude의 스트리밍 응답, 풍부한 Markdown 렌더링 (Marked.js 사용), 복사 버튼이 포함된 코드 블록 구문 강조 (highlight.js 사용), 그리고 시스템 메시지 및 상태 업데이트의 명확한 표시를 지원합니다.

도구 상호작용 (Tool Interaction): 채팅 흐름 내에서 도구 호출(인자)과 그 결과(성공 또는 오류)를 시각적으로 분리하여 표시합니다. 모달(modal)을 통해 테스트 및 디버깅을 위한 사용자 정의 JSON 파라미터로 사용 가능한 모든 도구를 직접 실행할 수 있습니다.

서버 관리 (Server Management): 전용 사이드바 탭에 구성된 서버 목록이 표시됩니다. 사용자는 다음을 수행할 수 있습니다:

• 모달 양식을 통해 새로운 서버(STDIO/SSE/Streaming-HTTP) 추가.
• 상태 표시기(로딩 중, 연결됨, 연결 끊김, 오류)와 함께 서버에 연결 또는 연결 해제.
• 서버 활성화/비활성화 (비활성화 시 자동으로 연결 해제됨).
• 서버 설정 제거.
• 각 서버가 제공하는 기본 상태/건강 상태 및 도구의 개수 확인.

탐색 (Discovery): 서버(Servers) 탭의 버튼을 통해 탐색 스캔(로컬 파일 시스템, 원격 레지스트리, mDNS)을 트리거합니다. 탐색된 서버들이 목록에 표시되며, 사용자는 클릭 한 번으로 이를 구성에 추가할 수 있습니다.

대화 브랜칭 (Conversation Branching): 대화(Conversation) 탭의 대화형 트리 뷰(tree view)를 통해 ConversationGraph를 시각화합니다.

사용자는 클릭을 통해 서로 다른 브랜치(branch)를 확인(채팅 뷰 업데이트)하거나, 현재 지점을 포크(fork)하여 새로운 브랜치를 생성할 수 있습니다.컨텍스트 관리(Context Management): 대화(Conversation) 탭의 버튼을 통해 현재 브랜치의 메시지를 삭제(부모/루트 상태로 리셋)하거나, API를 통해 컨텍스트 최적화/요약(context optimization/summarization)을 실행할 수 있습니다.가져오기/내보내기(Import/Export): 대화 탭의 버튼을 통해 현재 브랜치를 JSON 파일로 내보내거나, 파일 선택을 통해 이전에 내보낸 JSON 파일을 가져올 수 있습니다(백엔드로 업로드).설정(Settings): 전용 사이드바 탭을 통해 주요 설정 옵션(API Key, 기본 모델(Default Model), 최대 토큰(Max Tokens), 온도(Temperature), 스트리밍(Streaming), 캐싱(Caching), 자동 검색(Auto-Discovery), mDNS와 같은 기능 토글)을 확인하고 수정할 수 있으며, 이는 서버의 설정 파일에 저장됩니다.테마 전환(Theme Switching): 드롭다운 메뉴를 통해 다양한 DaisyUI 테마를 선택할 수 있습니다. UI는 즉각적으로 적응하며, 코드 하이라이팅(code highlighting)은 선택된 테마에 따라 라이트/다크 스타일로 자동 전환됩니다.상태 표시기(Status Indicators): 헤더에는 실시간 WebSocket 연결 상태 아이콘, 전체 서버 연결 수, 사용 가능한 총 도구(tool) 수가 표시됩니다. 일시적인 상태 메시지(예: "도구 실행 중...(Executing tool...)")는 채팅 입력창 아래에 나타납니다.

--webui 옵션과 함께 실행할 때, FastAPI 서버가 프로그래밍 방식의 접근을 제공합니다: