Présentation détaillée du projet use-mcp

Aperçu du projet

use-mcp est une bibliothèque de hooks React légère, spécialement conçue pour se connecter aux serveurs Model Context Protocol (MCP). Ce projet simplifie le processus d'authentification et d'appel d'outils du standard MCP dans les systèmes d'IA, offrant aux développeurs une solution d'intégration frontale facile à utiliser.

Caractéristiques du projet

🔄 Gestion automatique de la connexion

• Prise en charge de la reconnexion et des mécanismes de nouvelle tentative automatiques
• Gestion intelligente de l'état de la connexion et des situations exceptionnelles

🔐 Flux d'authentification OAuth

• Gestion complète du flux d'authentification OAuth
• Prise en charge des méthodes d'authentification par fenêtre contextuelle et de secours
• Gestion automatique du stockage des jetons d'authentification

📦 Interface de Hook React concise

• Fournit une API de Hook React intuitive
• Automatisation de la gestion de l'état
• Facile à intégrer dans les applications React existantes

🧰 Prise en charge de TypeScript

• Définitions de type TypeScript complètes
• Saisie semi-automatique et vérification de type dans l'éditeur
• Amélioration de l'efficacité du développement et de la qualité du code

📝 Journalisation complète

• Fonctionnalité de journalisation de débogage détaillée
• Facilite le dépannage et le débogage du développement

🌐 Prise en charge de plusieurs protocoles de transport

• Prise en charge du transport HTTP
• Prise en charge du transport SSE (Server-Sent Events)

Installation

npm install use-mcp
# ou
pnpm add use-mcp
# ou
yarn add use-mcp

Méthode d'utilisation de base

Utilisation du Hook principal

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

function MyAIComponent() {
  const {
    state,        // État de la connexion : 'discovering' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
    tools,        // Outils disponibles fournis par le serveur MCP
    error,        // Message d'erreur en cas d'échec de la connexion
    callTool,     // Fonction pour appeler un outil du serveur MCP
    retry,        // Nouvelle tentative de connexion manuelle
    authenticate, // Déclenchement manuel de l'authentification
    clearStorage, // Effacer les jetons et les informations d'identification stockés
  } = useMcp({
    url: 'https://your-mcp-server.com',
    clientName: 'My App',
    autoReconnect: true,
  })

  // Gérer les différents états de connexion
  if (state === 'failed') {
    return (
      <div>
        <p>Échec de la connexion : {error}</p>
        <button onClick={retry}>Réessayer</button>
        <button onClick={authenticate}>Authentification manuelle</button>
      </div>
    )
  }

  if (state !== 'ready') {
    return <div>Connexion au service d'IA en cours...</div>
  }

  // Utiliser les outils disponibles
  const handleSearch = async () => {
    try {
      const result = await callTool('search', { query: 'example search' })
      console.log('Résultats de la recherche :', result)
    } catch (err) {
      console.error('Échec de l'appel de l'outil :', err)
    }
  }

  return (
    <div>
      <h2>Nombre d'outils disponibles : {tools.length}</h2>
      <ul>
        {tools.map(tool => (
          <li key={tool.name}>{tool.name}</li>
        ))}
      </ul>
      <button onClick={handleSearch}>Rechercher</button>
    </div>
  )
}

Configuration du rappel d'authentification OAuth

Pour gérer le flux d'authentification OAuth, il est nécessaire de configurer un point de terminaison de rappel dans l'application.

Configuration de React Router

// App.tsx avec 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>Authentification en cours...</h1>
      <p>Cette fenêtre devrait se fermer automatiquement.</p>
    </div>
  )
}

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

Configuration de Next.js

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

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

  return (
    <div>
      <h1>Authentification en cours...</h1>
      <p>Cette fenêtre devrait se fermer automatiquement.</p>
    </div>
  )
}

Référence de l'API

Hook useMcp

function useMcp(options: UseMcpOptions): UseMcpResult

Options de configuration (UseMcpOptions)

Option	Type	Description
url	string	Obligatoire. URL du serveur MCP
clientName	string	Nom du client lors de l'enregistrement OAuth
clientUri	string	URI du client lors de l'enregistrement OAuth
callbackUrl	string	URL de rappel personnalisée pour la redirection OAuth (par défaut, /oauth/callback du domaine actuel)
storageKeyPrefix	string	Préfixe de la clé de stockage des données OAuth dans localStorage (par défaut, "mcp:auth")
clientConfig	object	Configuration personnalisée de l'identité du client MCP
debug	boolean	Activer la journalisation de débogage détaillée
autoRetry	boolean | number	Nouvelle tentative automatique en cas d'échec de la connexion initiale, peut être configurée avec un délai en millisecondes
autoReconnect	boolean | number	Reconnexion automatique en cas de perte de connexion établie, peut être configurée avec un délai en millisecondes (par défaut : 3000)

Valeurs de retour (UseMcpResult)

Propriété	Type	Description
state	string	État actuel de la connexion : 'discovering', 'authenticating', 'connecting', 'loading', 'ready', 'failed'
tools	Tool[]	Outils disponibles fournis par le serveur MCP
error	string | undefined	Message d'erreur en cas d'échec de la connexion
authUrl	string | undefined	URL d'authentification manuelle lorsque la fenêtre contextuelle est bloquée
log	LogEntry[]	Tableau de messages de journal
callTool	(name: string, args?: Record<string, unknown>) => Promise<any>	Fonction pour appeler un outil du serveur MCP
retry	() => void	Tentative manuelle de reconnexion
disconnect	() => void	Déconnexion du serveur MCP
authenticate	() => void	Déclenchement manuel de l'authentification
clearStorage	() => void	Effacer toutes les données d'authentification stockées

Exemples d'applications concrètes

Démonstrations en ligne

• MCP Inspector - Outil d'inspection MCP
• Cloudflare Workers AI Playground - Terrain de jeu Cloudflare Workers AI

Conclusion

use-mcp fournit aux développeurs React une solution puissante et concise pour intégrer les serveurs Model Context Protocol. Grâce à son interface de Hook intuitive, à sa gestion complète du flux d'authentification et à ses puissantes fonctionnalités de gestion de la connexion, les développeurs peuvent facilement implémenter l'intégration d'outils d'IA dans les applications React, réduisant considérablement la barrière à l'entrée pour l'utilisation du standard MCP.