use-mcp Projektdetails

Projektübersicht

use-mcp ist eine schlanke React-Hook-Bibliothek, die speziell für die Verbindung mit Model Context Protocol (MCP)-Servern entwickelt wurde. Dieses Projekt vereinfacht den Authentifizierungs- und Tool-Aufrufprozess des MCP-Standards in KI-Systemen und bietet Entwicklern eine benutzerfreundliche Frontend-Integrationslösung.

Projektmerkmale

🔄 Automatisches Verbindungsmanagement

• Unterstützt automatische Wiederverbindungs- und Wiederholungsmechanismen
• Intelligente Verarbeitung von Verbindungsstatus und Ausnahmesituationen

🔐 OAuth-Authentifizierungsprozess

• Vollständige Verarbeitung des OAuth-Authentifizierungsprozesses
• Unterstützt Popup- und Fallback-Authentifizierungsmethoden
• Automatische Verarbeitung der Speicherung von Authentifizierungstoken

📦 Schlanke React-Hook-Schnittstelle

• Bietet eine intuitive React-Hook-API
• Automatisierte Statusverwaltung
• Einfache Integration in bestehende React-Anwendungen

🧰 TypeScript-Unterstützung

• Vollständige TypeScript-Typdefinitionen
• Intelligente Editor-Vorschläge und Typüberprüfung
• Erhöht die Entwicklungseffizienz und Codequalität

📝 Umfassende Protokollierung

• Detaillierte Debug-Protokollierungsfunktionen
• Erleichtert die Fehlersuche und Entwicklungs-Debugging

🌐 Unterstützung mehrerer Übertragungsprotokolle

• Unterstützt HTTP-Übertragung
• Unterstützt SSE (Server-Sent Events)-Übertragung

Installationsanleitung

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

Grundlegende Verwendung

Haupt-Hook-Verwendung

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

function MyAIComponent() {
  const {
    state,        // Verbindungsstatus: 'discovering' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
    tools,        // Vom MCP-Server bereitgestellte verfügbare Tools
    error,        // Fehlermeldung bei Verbindungsfehler
    callTool,     // Funktion zum Aufrufen von MCP-Server-Tools
    retry,        // Manuelles Wiederholen der Verbindung
    authenticate, // Manuelles Auslösen der Authentifizierung
    clearStorage, // Löschen gespeicherter Token und Anmeldeinformationen
  } = useMcp({
    url: 'https://your-mcp-server.com',
    clientName: 'My App',
    autoReconnect: true,
  })

  // Behandlung verschiedener Verbindungsstatus
  if (state === 'failed') {
    return (
      <div>
        <p>Verbindungsfehler: {error}</p>
        <button onClick={retry}>Wiederholen</button>
        <button onClick={authenticate}>Manuelle Authentifizierung</button>
      </div>
    )
  }

  if (state !== 'ready') {
    return <div>Verbinde mit KI-Dienst...</div>
  }

  // Verwenden der verfügbaren Tools
  const handleSearch = async () => {
    try {
      const result = await callTool('search', { query: 'example search' })
      console.log('Suchergebnisse:', result)
    } catch (err) {
      console.error('Tool-Aufruf fehlgeschlagen:', err)
    }
  }

  return (
    <div>
      <h2>Anzahl der verfügbaren Tools: {tools.length}</h2>
      <ul>
        {tools.map(tool => (
          <li key={tool.name}>{tool.name}</li>
        ))}
      </ul>
      <button onClick={handleSearch}>Suchen</button>
    </div>
  )
}

OAuth-Authentifizierungs-Callback-Einstellungen

Um den OAuth-Authentifizierungsprozess zu verarbeiten, muss in der Anwendung ein Callback-Endpunkt eingerichtet werden.

React Router Konfiguration

// App.tsx mit 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>Authentifizierung läuft...</h1>
      <p>Dieses Fenster sollte sich automatisch schließen.</p>
    </div>
  )
}

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

Next.js Konfiguration

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

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

  return (
    <div>
      <h1>Authentifizierung läuft...</h1>
      <p>Dieses Fenster sollte sich automatisch schließen.</p>
    </div>
  )
}

API-Referenz

useMcp Hook

function useMcp(options: UseMcpOptions): UseMcpResult

Konfigurationsoptionen (UseMcpOptions)

Option	Typ	Beschreibung
url	string	Erforderlich. Die URL des MCP-Servers
clientName	string	Der Clientname bei der OAuth-Registrierung
clientUri	string	Die Client-URI bei der OAuth-Registrierung
callbackUrl	string	Die benutzerdefinierte Callback-URL für die OAuth-Umleitung (standardmäßig /oauth/callback der aktuellen Domain)
storageKeyPrefix	string	Das Speicher-Key-Präfix für OAuth-Daten im localStorage (standardmäßig "mcp:auth")
clientConfig	object	Die benutzerdefinierte Konfiguration der MCP-Clientidentität
debug	boolean	Ob detaillierte Debug-Protokolle aktiviert werden sollen
autoRetry	boolean | number	Automatisches Wiederholen bei anfänglichem Verbindungsfehler, kann die Verzögerung in Millisekunden festlegen
autoReconnect	boolean | number	Automatisches Wiederverbinden bei Verlust einer bestehenden Verbindung, kann die Verzögerung in Millisekunden festlegen (Standard: 3000)

Rückgabewert (UseMcpResult)

Attribut	Typ	Beschreibung
state	string	Der aktuelle Verbindungsstatus: 'discovering', 'authenticating', 'connecting', 'loading', 'ready', 'failed'
tools	Tool[]	Die vom MCP-Server bereitgestellten verfügbaren Tools
error	string | undefined	Die Fehlermeldung bei Verbindungsfehler
authUrl	string | undefined	Die manuelle Authentifizierungs-URL, wenn das Popup blockiert wird
log	LogEntry[]	Ein Array von Protokollmeldungen
callTool	(name: string, args?: Record<string, unknown>) => Promise<any>	Die Funktion zum Aufrufen von MCP-Server-Tools
retry	() => void	Der Versuch, die Verbindung manuell wiederherzustellen
disconnect	() => void	Die Verbindung zum MCP-Server trennen
authenticate	() => void	Manuelles Auslösen der Authentifizierung
clearStorage	() => void	Alle gespeicherten Authentifizierungsdaten löschen

Beispiele für die praktische Anwendung

Online-Demo

• MCP Inspector - MCP-Inspektor-Tool
• Cloudflare Workers AI Playground - Cloudflare Workers AI-Spielplatz

Zusammenfassung

use-mcp bietet React-Entwicklern eine leistungsstarke und schlanke Lösung zur Integration von Model Context Protocol-Servern. Durch seine intuitive Hook-Schnittstelle, die umfassende Verarbeitung des Authentifizierungsprozesses und die leistungsstarken Verbindungsverwaltungsfunktionen können Entwickler die KI-Tool-Integration einfach in React-Anwendungen implementieren und die Nutzung des MCP-Standards erheblich vereinfachen.