Model Context Protocol (MCP) 서버 연결을 위한 가벼운 React 훅 라이브러리

use-mcp 프로젝트 상세 소개

프로젝트 개요

use-mcp는 Model Context Protocol (MCP) 서버 연결을 위해 특별히 제작된 경량 React 훅 라이브러리입니다. 이 프로젝트는 AI 시스템에서 MCP 표준의 인증 및 도구 호출 과정을 간소화하여 개발자에게 사용하기 쉬운 프론트엔드 통합 솔루션을 제공합니다.

프로젝트 특징

🔄 자동 연결 관리

• 자동 재연결 및 재시도 메커니즘 지원
• 연결 상태 및 예외 상황을 지능적으로 처리

🔐 OAuth 인증 흐름

• 완전한 OAuth 인증 흐름 처리
• 팝업 및 되돌아가기 인증 방식 지원
• 인증 토큰 저장 자동 처리

📦 간결한 React Hook 인터페이스

• 직관적인 React Hook API 제공
• 상태 관리 자동화
• 기존 React 앱에 쉽게 통합 가능

🧰 TypeScript 지원

• 완전한 TypeScript 타입 정의
• 편집기 스마트 힌트 및 타입 검사
• 개발 효율성 및 코드 품질 향상

📝 포괄적인 로그 기록

• 상세한 디버깅 로그 기능
• 문제 해결 및 개발 디버깅 용이

🌐 다중 전송 프로토콜 지원

• HTTP 전송 지원
• SSE (Server-Sent Events) 전송 지원

설치 방법

npm install use-mcp
# 또는
pnpm add use-mcp
# 또는
yarn add use-mcp

기본 사용 방법

주요 Hook 사용

import { useMcp } from 'use-mcp/react'

function MyAIComponent() {
  const {
    state,        // 연결 상태: 'discovering' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
    tools,        // MCP 서버에서 제공하는 사용 가능한 도구
    error,        // 연결 실패 시 오류 정보
    callTool,     // MCP 서버 도구를 호출하는 함수
    retry,        // 수동으로 연결 재시도
    authenticate, // 수동으로 인증 트리거
    clearStorage, // 저장된 토큰 및 자격 증명 지우기
  } = useMcp({
    url: 'https://your-mcp-server.com',
    clientName: 'My App',
    autoReconnect: true,
  })

  // 다양한 연결 상태 처리
  if (state === 'failed') {
    return (
      <div>
        <p>연결 실패: {error}</p>
        <button onClick={retry}>재시도</button>
        <button onClick={authenticate}>수동 인증</button>
      </div>
    )
  }

  if (state !== 'ready') {
    return <div>AI 서비스에 연결 중...</div>
  }

  // 사용 가능한 도구 사용
  const handleSearch = async () => {
    try {
      const result = await callTool('search', { query: 'example search' })
      console.log('검색 결과:', result)
    } catch (err) {
      console.error('도구 호출 실패:', err)
    }
  }

  return (
    <div>
      <h2>사용 가능한 도구 수: {tools.length}</h2>
      <ul>
        {tools.map(tool => (
          <li key={tool.name}>{tool.name}</li>
        ))}
      </ul>
      <button onClick={handleSearch}>검색</button>
    </div>
  )
}

OAuth 인증 콜백 설정

OAuth 인증 흐름을 처리하려면 애플리케이션에 콜백 엔드포인트를 설정해야 합니다.

React Router 구성

// App.tsx with React Router
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
import { useEffect } from 'react'
import { onMcpAuthorization } from 'use-mcp'

function OAuthCallback() {
  useEffect(() => {
    onMcpAuthorization()
  }, [])

  return (
    <div>
      <h1>인증 중...</h1>
      <p>이 창은 자동으로 닫혀야 합니다.</p>
    </div>
  )
}

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/oauth/callback" element={<OAuthCallback />} />
        <Route path="/" element={<YourMainComponent />} />
      </Routes>
    </Router>
  )
}

Next.js 구성

// pages/oauth/callback.tsx
import { useEffect } from 'react'
import { onMcpAuthorization } from 'use-mcp'

export default function OAuthCallbackPage() {
  useEffect(() => {
    onMcpAuthorization()
  }, [])

  return (
    <div>
      <h1>인증 중...</h1>
      <p>이 창은 자동으로 닫혀야 합니다.</p>
    </div>
  )
}

API 참조

useMcp Hook

function useMcp(options: UseMcpOptions): UseMcpResult

구성 옵션 (UseMcpOptions)

옵션	타입	설명
url	string	필수. MCP 서버의 URL
clientName	string	OAuth 등록 시 클라이언트 이름
clientUri	string	OAuth 등록 시 클라이언트 URI
callbackUrl	string	OAuth 리디렉션의 사용자 정의 콜백 URL (기본값: 현재 도메인의 /oauth/callback)
storageKeyPrefix	string	localStorage에서 OAuth 데이터의 저장 키 접두사 (기본값: "mcp:auth")
clientConfig	object	MCP 클라이언트 ID의 사용자 정의 구성
debug	boolean	상세한 디버깅 로그 활성화 여부
autoRetry	boolean | number	초기 연결 실패 시 자동 재시도, 지연 시간(밀리초) 설정 가능
autoReconnect	boolean | number	이미 설정된 연결이 끊어졌을 때 자동 재연결, 지연 시간(밀리초) 설정 가능 (기본값: 3000)

반환 값 (UseMcpResult)

속성	타입	설명
state	string	현재 연결 상태: 'discovering', 'authenticating', 'connecting', 'loading', 'ready', 'failed'
tools	Tool[]	MCP 서버에서 제공하는 사용 가능한 도구
error	string | undefined	연결 실패 시 오류 정보
authUrl	string | undefined	팝업이 차단되었을 때 수동 인증 URL
log	LogEntry[]	로그 메시지 배열
callTool	(name: string, args?: Record<string, unknown>) => Promise<any>	MCP 서버 도구를 호출하는 함수
retry	() => void	수동으로 재연결 시도
disconnect	() => void	MCP 서버와의 연결 끊기
authenticate	() => void	수동으로 인증 트리거
clearStorage	() => void	저장된 모든 인증 데이터 지우기

실제 응용 예시

온라인 데모

• MCP Inspector - MCP 검사기 도구
• Cloudflare Workers AI Playground - Cloudflare Workers AI 플레이그라운드

요약

use-mcp는 React 개발자에게 Model Context Protocol 서버 통합을 위한 강력하고 간결한 솔루션을 제공합니다. 직관적인 Hook 인터페이스, 완벽한 인증 흐름 처리 및 강력한 연결 관리 기능을 통해 개발자는 React 앱에서 AI 도구 통합을 쉽게 구현하여 MCP 표준 사용 장벽을 크게 낮출 수 있습니다.