Introducción detallada al proyecto use-mcp

Resumen del proyecto

use-mcp es una biblioteca de hooks de React ligera, diseñada específicamente para conectarse a servidores Model Context Protocol (MCP). Este proyecto simplifica el proceso de autenticación y llamada a herramientas del estándar MCP en sistemas de IA, proporcionando a los desarrolladores una solución de integración frontend fácil de usar.

Características del proyecto

🔄 Gestión automática de conexiones

• Soporte para reconexión y mecanismos de reintento automáticos
• Manejo inteligente del estado de la conexión y situaciones excepcionales

🔐 Flujo de autenticación OAuth

• Manejo completo del flujo de autenticación OAuth
• Soporte para métodos de autenticación mediante ventana emergente y fallback
• Manejo automático del almacenamiento de tokens de autenticación

📦 Interfaz de Hook de React concisa

• Proporciona una API de Hook de React intuitiva
• Automatización de la gestión del estado
• Fácil de integrar en aplicaciones React existentes

🧰 Soporte de TypeScript

• Definiciones de tipo TypeScript completas
• Sugerencias inteligentes y verificación de tipos en el editor
• Mejora la eficiencia del desarrollo y la calidad del código

📝 Registro exhaustivo de logs

• Funcionalidad de registro de logs de depuración detallada
• Facilita la resolución de problemas y la depuración del desarrollo

🌐 Soporte para múltiples protocolos de transporte

• Soporte para transporte HTTP
• Soporte para transporte SSE (Server-Sent Events)

Instalación

npm install use-mcp

pnpm add use-mcp

yarn add use-mcp

Uso básico

Uso del Hook principal

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

function MyAIComponent() {
  const {
    state,        // Estado de la conexión: 'discovering' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
    tools,        // Herramientas disponibles proporcionadas por el servidor MCP
    error,        // Información de error en caso de fallo de conexión
    callTool,     // Función para llamar a las herramientas del servidor MCP
    retry,        // Reintento manual de la conexión
    authenticate, // Activación manual de la autenticación
    clearStorage, // Limpieza de los tokens y credenciales almacenados
  } = useMcp({
    url: 'https://your-mcp-server.com',
    clientName: 'My App',
    autoReconnect: true,
  })

  // Manejo de los diferentes estados de conexión
  if (state === 'failed') {
    return (
      <div>
        <p>Conexión fallida: {error}</p>
        <button onClick={retry}>Reintentar</button>
        <button onClick={authenticate}>Autenticar manualmente</button>
      </div>
    )
  }

  if (state !== 'ready') {
    return <div>Conectando al servicio de IA...</div>
  }

  // Uso de las herramientas disponibles
  const handleSearch = async () => {
    try {
      const result = await callTool('search', { query: 'example search' })
      console.log('Resultados de la búsqueda:', result)
    } catch (err) {
      console.error('Fallo al llamar a la herramienta:', err)
    }
  }

  return (
    <div>
      <h2>Número de herramientas disponibles: {tools.length}</h2>
      <ul>
        {tools.map(tool => (
          <li key={tool.name}>{tool.name}</li>
        ))}
      </ul>
      <button onClick={handleSearch}>Buscar</button>
    </div>
  )
}

Configuración de la devolución de llamada de autenticación OAuth

Para manejar el flujo de autenticación OAuth, es necesario configurar un punto final de devolución de llamada en la aplicación.

Configuración con React Router

// App.tsx con 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>Autenticando...</h1>
      <p>Esta ventana debería cerrarse automáticamente.</p>
    </div>
  )
}

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

Configuración con Next.js

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

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

  return (
    <div>
      <h1>Autenticando...</h1>
      <p>Esta ventana debería cerrarse automáticamente.</p>
    </div>
  )
}

Referencia de la API

Hook useMcp

function useMcp(options: UseMcpOptions): UseMcpResult

Opciones de configuración (UseMcpOptions)

Opción	Tipo	Descripción
url	string	Requerido. URL del servidor MCP
clientName	string	Nombre del cliente durante el registro de OAuth
clientUri	string	URI del cliente durante el registro de OAuth
callbackUrl	string	URL de devolución de llamada personalizada para la redirección de OAuth (por defecto, /oauth/callback en el dominio actual)
storageKeyPrefix	string	Prefijo de la clave de almacenamiento para los datos de OAuth en localStorage (por defecto, "mcp:auth")
clientConfig	object	Configuración personalizada para la identidad del cliente MCP
debug	boolean	Habilita el registro de logs de depuración detallado
autoRetry	boolean | number	Reintento automático en caso de fallo de conexión inicial, puede establecerse un retraso en milisegundos
autoReconnect	boolean | number	Reconexión automática en caso de pérdida de conexión establecida, puede establecerse un retraso en milisegundos (por defecto: 3000)

Valores de retorno (UseMcpResult)

Propiedad	Tipo	Descripción
state	string	Estado actual de la conexión: 'discovering', 'authenticating', 'connecting', 'loading', 'ready', 'failed'
tools	Tool[]	Herramientas disponibles proporcionadas por el servidor MCP
error	string | undefined	Información de error en caso de fallo de conexión
authUrl	string | undefined	URL de autenticación manual en caso de que se bloquee la ventana emergente
log	LogEntry[]	Array de mensajes de log
callTool	(name: string, args?: Record<string, unknown>) => Promise<any>	Función para llamar a las herramientas del servidor MCP
retry	() => void	Intento manual de reconexión
disconnect	() => void	Desconexión del servidor MCP
authenticate	() => void	Activación manual de la autenticación
clearStorage	() => void	Limpieza de todos los datos de autenticación almacenados

Ejemplos de aplicaciones reales

Demostraciones en línea

• MCP Inspector - Herramienta de inspección de MCP
• Cloudflare Workers AI Playground - Playground de Cloudflare Workers AI

Conclusión

use-mcp proporciona a los desarrolladores de React una solución potente y concisa para integrar servidores Model Context Protocol. A través de su interfaz de Hook intuitiva, el manejo completo del flujo de autenticación y las potentes funciones de gestión de conexiones, los desarrolladores pueden implementar fácilmente la integración de herramientas de IA en aplicaciones React, reduciendo en gran medida la barrera de entrada para el uso del estándar MCP.