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 標準の使用ハードルを大幅に下げることができます。