Vercel v0

Gere componentes de UI bonitos usando o sistema de UI generativa v0 da Vercel.

GitHub
19
Experimente este MCPPatrocinado

Documentação

v0-mcp

English | 中文

Servidor MCP Vercel v0 para Claude Code - Gere componentes de UI bonitos usando IA através do Model Context Protocol.

✨ Desenvolvimento Colaborativo: Este projeto foi construído através de uma colaboração inovadora entre Claude Code e Gemini CLI usando a metodologia Vibe Coding - demonstrando o poder dos fluxos de trabalho de desenvolvimento assistidos por IA.

🎯 Recursos

  • Gerar Componentes de UI: Crie componentes React a partir de descrições em linguagem natural
  • Imagem para UI: Converta imagens de design em código React funcional
  • Iteração baseada em Chat: Refine componentes iterativamente através de conversa
  • Múltiplos Modelos: Suporte para v0-1.5-md, v0-1.5-lg e v0-1.0-md
  • Suporte a TypeScript: Segurança total de tipos com validação de esquema Zod
  • Suporte a Streaming: Progresso de geração em tempo real

🚀 Início Rápido

# 1. Clone and enter the project
git clone <repository-url> && cd v0-mcp

# 2. Install dependencies
npm install

# 3. Create .env file and add your v0 API key
npm run setup
# Edit .env file with your V0_API_KEY

# 4. Build the project
npm run build

# 5. Add to Claude Code (ensure you are in the project root)
claude mcp add v0-mcp --env V0_API_KEY=$(grep V0_API_KEY .env | cut -d '=' -f2) -- node $(pwd)/dist/main.js

# 6. Start using it in Claude Code!
# Try: "Hey v0-mcp, create a login form with email and password fields"

🛠 Instalação

1. Clonar ou Baixar

git clone <repository-url>
cd v0-mcp

2. Instalar Dependências

npm install

3. Configurar Ambiente

npm run setup
# Edit .env file with your v0 API key

4. Compilar Projeto

npm run build

⚙️ Configuração

🔑 Obtendo Sua Chave de API v0

Antes de configurar o v0-mcp, você precisará de uma chave de API v0:

  1. Visite a documentação da API do Modelo v0
  2. Entre na sua conta Vercel
  3. Navegue até a seção de Chaves de API
  4. Gere uma nova chave de API
  5. Copie e salve sua chave com segurança

Integração com Claude Code

📖 Guia de configuração rápida - escolha o método que funciona melhor para você

Método 1: Configuração via CLI (Recomendado)

  1. Adicione v0-mcp usando o CLI do Claude Code:

    # Navigate to your v0-mcp directory first
cd /path/to/your/v0-mcp

# Add the MCP server using current directory
claude mcp add v0-mcp -- node $(pwd)/dist/main.js

  2. Defina sua chave de API v0:

    Opção A: Adicione a chave durante a configuração do CLI

    # When adding the server, include the API key (run from v0-mcp directory)
claude mcp add v0-mcp --env V0_API_KEY=your_v0_api_key_here -- node $(pwd)/dist/main.js

    Opção B: Edite o arquivo .claude.json após a configuração

    Após executar o comando claude mcp add, edite o arquivo .claude.json gerado:

    {
  "mcpServers": {
    "v0-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/your/v0-mcp/dist/main.js"],
      "env": {
        "V0_API_KEY": "your_v0_api_key_here"
      }
    }
  }
}

    Opção C: Variável de ambiente do sistema (Mais segura)

    # Add to your shell profile (.bashrc, .zshrc, etc.)
echo 'export V0_API_KEY="your_v0_api_key_here"' >> ~/.zshrc

# Reload your shell configuration
source ~/.zshrc

  3. Verifique sua configuração:

    claude mcp list
node scripts/verify-claude-code-setup.js

    ✅ Saída Esperada:

    Verifying v0 API connection...
✓ v0-mcp server found in Claude configuration
✓ API key is configured
✓ Successfully connected to v0 API
Setup is complete! You can now use v0-mcp in Claude Code.

Método 2: Configuração Manual (Avançado)

  1. Crie ou edite o arquivo de configuração do Claude Code:

    • macOS/Linux: ~/.claude.json
    • Windows: %USERPROFILE%\.claude.json

  2. Adicione a configuração do servidor v0-mcp:

{
  "mcpServers": {
    "v0-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/v0-mcp/dist/main.js"],
      "env": {
        "V0_API_KEY": "your_v0_api_key_here"
      }
    }
  }
}
  1. Reinicie o Claude Code para que as alterações tenham efeito.

Verificação

Após a configuração, você deve ver as ferramentas v0-mcp disponíveis no Claude Code:

  • ✅ v0_generate_ui - Gere componentes de UI a partir de texto
  • ✅ v0_generate_from_image - Gere UI a partir de referências de imagem
  • ✅ v0_chat_complete - Chat de desenvolvimento iterativo de UI
  • ✅ v0_setup_check - Verifique a conectividade da API

🔗 Por que usar MCP (Model Context Protocol)?

Benefícios do MCP:

  • Integração Perfeita: As ferramentas aparecem nativamente no Claude sem manipulação de API
  • Contexto Aprimorado: O Claude entende seu fluxo de trabalho v0 e fornece melhor assistência
  • Disponibilidade em Tempo Real: As ferramentas estão sempre acessíveis durante suas sessões de codificação
  • Segurança de Tipos: Validação completa de parâmetros e tratamento de erros integrados
  • Estado Persistente: Mantém o contexto da conversa entre chamadas de ferramentas

Como Funciona: Quando você menciona v0-mcp ou geração de UI no Claude, as ferramentas ficam automaticamente disponíveis. O Claude pode escolher inteligentemente a ferramenta certa com base na sua solicitação, tornando o processo de desenvolvimento natural e integrado.

Integração com Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "v0-mcp": {
      "command": "node",
      "args": ["/path/to/v0-mcp/dist/main.js"],
      "env": {
        "V0_API_KEY": "your_v0_api_key_here"
      }
    }
  }
}

Integração com Cursor

Adicione à sua configuração MCP do Cursor:

{
  "mcpServers": {
    "v0-mcp": {
      "command": "node",
      "args": ["/path/to/v0-mcp/dist/main.js"],
      "env": {
        "V0_API_KEY": "your_v0_api_key_here"
      }
    }
  }
}

🔧 Ferramentas Disponíveis

v0_generate_ui

Gere componentes de UI a partir de descrições em texto.

Parâmetros:

  • prompt (obrigatório): Descrição do componente de UI
  • model: Modelo v0 a ser usado (padrão: v0-1.5-md)
  • stream: Ativar resposta em streaming (padrão: false)
  • context: Contexto de código existente opcional

v0_generate_from_image

Gere componentes de UI a partir de referências de imagem.

Parâmetros:

  • imageUrl (obrigatório): URL da imagem de referência
  • prompt: Instruções adicionais
  • model: Modelo v0 a ser usado (padrão: v0-1.5-md)

v0_chat_complete

Desenvolvimento de UI baseado em chat com contexto de conversa.

Parâmetros:

  • messages (obrigatório): Matriz de mensagens de conversa
  • model: Modelo v0 a ser usado (padrão: v0-1.5-md)
  • stream: Ativar resposta em streaming (padrão: false)

v0_setup_check

Valide a configuração e conectividade da API v0.

🔑 Variáveis de Ambiente

VariávelObrigatóriaPadrãoDescrição
V0_API_KEY✅-Sua chave de API v0
V0_BASE_URL❌https://api.v0.dev/v1URL base da API v0
V0_DEFAULT_MODEL❌v0-1.5-mdModelo padrão a ser usado
V0_TIMEOUT❌60000Tempo limite da API (ms)
MCP_SERVER_NAME❌v0-mcpNome do servidor MCP
LOG_LEVEL❌infoNível de registro

🚀 Exemplos de Uso

No Claude Code

Uma vez configurado, você pode usar v0-mcp de várias maneiras:

Uso Direto do v0-mcp

Basta mencionar v0-mcp na sua solicitação, e o Claude selecionará automaticamente a ferramenta apropriada:

Hey v0-mcp, create a modern login form with email and password fields

v0-mcp: Generate a dashboard component with charts and KPI cards

@v0-mcp convert this wireframe to a React component: [image URL]

Uso de Ferramenta Específica

Gerar um Formulário de Login
Use v0_generate_ui to create a modern login form with email, password fields, and a blue submit button with rounded corners.
Converter Design em Código
Use v0_generate_from_image with this Figma design URL: https://example.com/design.png
Desenvolvimento Iterativo
Use v0_chat_complete to refine the previous login form by adding a "Remember me" checkbox and "Forgot password" link.
Verificar Configuração da API
Use v0_setup_check to verify your v0 API connection and configuration.

Exemplos de Uso Avançado

Criando um Componente de Dashboard

Use v0_generate_ui with the following prompt:
"Create a modern dashboard component with a sidebar navigation, header with user profile dropdown, and a main content area with grid layout for cards. Include metrics cards showing KPIs with charts. Use shadcn/ui components and Tailwind CSS."

Construindo a partir de um Wireframe

Use v0_generate_from_image with your wireframe image URL and add:
"Convert this wireframe into a fully functional React component. Add proper spacing, modern styling, and make it responsive for mobile devices."

Refinamento Iterativo

Use v0_chat_complete with conversation history:
[
  {"role": "user", "content": "Create a pricing table component"},
  {"role": "assistant", "content": "[Previous pricing table code]"},
  {"role": "user", "content": "Add a popular plan highlight and annual/monthly toggle"}
]

🧪 Desenvolvimento

# Development mode with hot reload
npm run dev

# Type checking
npm run lint

# Run tests
npm test

# Test with coverage
npm run test:coverage

# Test in CI mode
npm run test:ci

# Clean build artifacts
npm run clean

# Test configuration
npm run test:config

# Test basic functionality
npm run test:basic

# Verify Claude Code setup
npm run verify:claude-code

🛡️ Recursos Aprimorados

Registro Estruturado

  • Registro baseado em Winston com formato JSON
  • Informações contextuais para chamadas de API e uso de ferramentas
  • Rastreamento de erros com stack traces e metadados
  • Níveis de registro configuráveis via variável de ambiente LOG_LEVEL

Tratamento Avançado de Erros

  • Tipos de erro categorizados (API, Rede, Tempo Limite, Limite de Taxa, etc.)
  • Lógica de repetição com backoff exponencial para erros transitórios
  • Mensagens de erro amigáveis com orientação acionável
  • Metadados abrangentes de erro para depuração

Infraestrutura de Testes

  • Framework de testes Jest com suporte a TypeScript
  • Testes unitários abrangentes para todos os componentes principais
  • Relatórios de cobertura de testes com limites configuráveis
  • Implementações simuladas para dependências externas

Confiabilidade Aprimorada

  • Validação de entrada usando esquemas Zod
  • Tratamento gracioso de erros para todos os modos de falha
  • Monitoramento de desempenho com tempo de solicitação
  • Verificações de saúde para conectividade da API

💖 Apoie Este Projeto

Se você achar este projeto útil, considere apoiá-lo:

Buy Me A Coffee

Seu apoio ajuda a manter e melhorar o v0-mcp!

📄 Licença

MIT