Detalhes do Projeto use-mcp

Visão Geral do Projeto

use-mcp é uma biblioteca leve de hooks React, especializada em conectar-se a servidores Model Context Protocol (MCP). Este projeto simplifica o processo de autenticação e chamada de ferramentas do padrão MCP em sistemas de IA, fornecendo aos desenvolvedores uma solução de integração frontend fácil de usar.

Características do Projeto

🔄 Gerenciamento Automático de Conexão

• Suporte para reconexão e mecanismo de repetição automáticos
• Tratamento inteligente de estados de conexão e situações de exceção

🔐 Fluxo de Autenticação OAuth

• Tratamento completo do fluxo de autenticação OAuth
• Suporte para métodos de autenticação via popup e fallback
• Tratamento automático do armazenamento de tokens de autenticação

📦 Interface de Hook React Concisa

• Fornece uma API de Hook React intuitiva
• Automatização do gerenciamento de estado
• Fácil de integrar em aplicações React existentes

🧰 Suporte a TypeScript

• Definições de tipo TypeScript completas
• Dicas inteligentes e verificação de tipo no editor
• Melhora a eficiência do desenvolvimento e a qualidade do código

📝 Registro Abrangente de Logs

• Funcionalidade detalhada de logs de depuração
• Facilita a resolução de problemas e a depuração do desenvolvimento

🌐 Suporte a Múltiplos Protocolos de Transporte

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

Instalação

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

Uso Básico

Uso do Hook Principal

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

function MyAIComponent() {
  const {
    state,        // Estado da conexão: 'discovering' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
    tools,        // Ferramentas disponíveis fornecidas pelo servidor MCP
    error,        // Informações de erro quando a conexão falha
    callTool,     // Função para chamar ferramentas do servidor MCP
    retry,        // Tentar reconectar manualmente
    authenticate, // Acionar a autenticação manualmente
    clearStorage, // Limpar tokens e credenciais armazenados
  } = useMcp({
    url: 'https://your-mcp-server.com',
    clientName: 'My App',
    autoReconnect: true,
  })

  // Lidar com diferentes estados de conexão
  if (state === 'failed') {
    return (
      <div>
        <p>Conexão falhou: {error}</p>
        <button onClick={retry}>Tentar novamente</button>
        <button onClick={authenticate}>Autenticar manualmente</button>
      </div>
    )
  }

  if (state !== 'ready') {
    return <div>Conectando ao serviço de IA...</div>
  }

  // Usar as ferramentas disponíveis
  const handleSearch = async () => {
    try {
      const result = await callTool('search', { query: 'example search' })
      console.log('Resultado da pesquisa:', result)
    } catch (err) {
      console.error('Falha ao chamar a ferramenta:', err)
    }
  }

  return (
    <div>
      <h2>Número de ferramentas disponíveis: {tools.length}</h2>
      <ul>
        {tools.map(tool => (
          <li key={tool.name}>{tool.name}</li>
        ))}
      </ul>
      <button onClick={handleSearch}>Pesquisar</button>
    </div>
  )
}

Configuração de Callback de Autenticação OAuth

Para lidar com o fluxo de autenticação OAuth, é necessário configurar um endpoint de callback na aplicação.

Configuração com React Router

// App.tsx com 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 janela deve fechar automaticamente.</p>
    </div>
  )
}

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

Configuração com 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 janela deve fechar automaticamente.</p>
    </div>
  )
}

Referência da API

Hook useMcp

function useMcp(options: UseMcpOptions): UseMcpResult

Opções de Configuração (UseMcpOptions)

Opção	Tipo	Descrição
url	string	Obrigatório. URL do servidor MCP
clientName	string	Nome do cliente ao registrar no OAuth
clientUri	string	URI do cliente ao registrar no OAuth
callbackUrl	string	URL de callback personalizada para redirecionamento OAuth (padrão: /oauth/callback no domínio atual)
storageKeyPrefix	string	Prefixo da chave de armazenamento para dados OAuth no localStorage (padrão: "mcp:auth")
clientConfig	object	Configuração personalizada para a identidade do cliente MCP
debug	boolean	Se deve habilitar logs de depuração detalhados
autoRetry	boolean | number	Tentar novamente automaticamente em caso de falha na conexão inicial, pode definir um atraso em milissegundos
autoReconnect	boolean | number	Reconectar automaticamente quando a conexão estabelecida for perdida, pode definir um atraso em milissegundos (padrão: 3000)

Valores de Retorno (UseMcpResult)

Propriedade	Tipo	Descrição
state	string	Estado atual da conexão: 'discovering', 'authenticating', 'connecting', 'loading', 'ready', 'failed'
tools	Tool[]	Ferramentas disponíveis fornecidas pelo servidor MCP
error	string | undefined	Informações de erro quando a conexão falha
authUrl	string | undefined	URL de autenticação manual quando o popup é bloqueado
log	LogEntry[]	Array de mensagens de log
callTool	(name: string, args?: Record<string, unknown>) => Promise<any>	Função para chamar ferramentas do servidor MCP
retry	() => void	Tentar reconectar manualmente
disconnect	() => void	Desconectar do servidor MCP
authenticate	() => void	Acionar a autenticação manualmente
clearStorage	() => void	Limpar todos os dados de autenticação armazenados

Exemplos de Aplicações Reais

Demonstrações Online

• MCP Inspector - Ferramenta de inspeção MCP
• Cloudflare Workers AI Playground - Playground de IA do Cloudflare Workers

Conclusão

use-mcp fornece aos desenvolvedores React uma solução poderosa e concisa para integrar servidores Model Context Protocol. Através de sua interface de Hook intuitiva, tratamento completo do fluxo de autenticação e poderosos recursos de gerenciamento de conexão, os desenvolvedores podem facilmente implementar a integração de ferramentas de IA em aplicações React, reduzindo significativamente a barreira de entrada para o uso do padrão MCP.