Vercel v0

Genera componentes de interfaz de usuario hermosos usando el sistema de UI generativa v0 de Vercel.

GitHub
19
Prueba este MCPPatrocinado

Documentación

v0-mcp

English | 中文

Servidor MCP de Vercel v0 para Claude Code: genera componentes de interfaz de usuario hermosos usando IA a través del Protocolo de Contexto de Modelo.

✨ Desarrollo colaborativo: Este proyecto se construyó mediante una colaboración innovadora entre Claude Code y Gemini CLI utilizando la metodología Vibe Coding, lo que demuestra el poder de los flujos de trabajo de desarrollo asistidos por IA.

🎯 Características

  • Generar componentes de interfaz: Crea componentes de React a partir de descripciones en lenguaje natural
  • Imagen a interfaz: Convierte imágenes de diseño en código de React funcional
  • Iteración basada en chat: Refina componentes de forma iterativa mediante conversación
  • Múltiples modelos: Soporte para v0-1.5-md, v0-1.5-lg y v0-1.0-md
  • Soporte de TypeScript: Seguridad total de tipos con validación de esquemas Zod
  • Soporte de transmisión: Progreso de generación en tiempo real

🚀 Inicio 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"

🛠 Instalación

1. Clonar o descargar

git clone <repository-url>
cd v0-mcp

2. Instalar dependencias

npm install

3. Configurar el entorno

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

4. Compilar el proyecto

npm run build

⚙️ Configuración

🔑 Obtención de tu clave API de v0

Antes de configurar v0-mcp, necesitarás una clave API de v0:

  1. Visita la documentación de la API del modelo v0
  2. Inicia sesión en tu cuenta de Vercel
  3. Navega a la sección de claves API
  4. Genera una nueva clave API
  5. Copia y guarda tu clave de forma segura

Integración con Claude Code

📖 Guía de configuración rápida: elige el método que mejor se adapte a ti

Método 1: Configuración mediante CLI (Recomendado)

  1. Agrega v0-mcp usando la CLI de 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. Establece tu clave API de v0:

    Opción A: Agrega la clave durante la configuración de la 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

    Opción B: Edita el archivo .claude.json después de la configuración

    Después de ejecutar el comando claude mcp add, edita el archivo .claude.json generado:

    {
  "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"
      }
    }
  }
}

    Opción C: Variable de entorno del sistema (la más 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. Verifica tu configuración:

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

    ✅ Salida 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: Configuración manual (Avanzado)

  1. Crea o edita el archivo de configuración de Claude Code:

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

  2. Agrega la configuración del 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. Reinicia Claude Code para que los cambios surtan efecto.

Verificación

Después de la configuración, deberías ver las herramientas de v0-mcp disponibles en Claude Code:

  • ✅ v0_generate_ui - Genera componentes de interfaz a partir de texto
  • ✅ v0_generate_from_image - Genera interfaz a partir de referencias de imagen
  • ✅ v0_chat_complete - Chat de desarrollo de interfaz iterativo
  • ✅ v0_setup_check - Verifica la conectividad de la API

🔗 ¿Por qué usar MCP (Protocolo de Contexto de Modelo)?

Beneficios de MCP:

  • Integración perfecta: Las herramientas aparecen de forma nativa en Claude sin necesidad de gestionar APIs
  • Contexto mejorado: Claude comprende tu flujo de trabajo de v0 y brinda mejor asistencia
  • Disponibilidad en tiempo real: Las herramientas siempre están accesibles durante tus sesiones de codificación
  • Seguridad de tipos: Validación completa de parámetros y manejo de errores integrado
  • Estado persistente: Mantiene el contexto de conversación entre llamadas de herramientas

Cómo funciona: Cuando mencionas v0-mcp o generación de interfaz en Claude, las herramientas se vuelven disponibles automáticamente. Claude puede elegir inteligentemente la herramienta adecuada según tu solicitud, haciendo que el proceso de desarrollo se sienta natural e integrado.

Integración con Claude Desktop

Agrega a tu 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"
      }
    }
  }
}

Integración con Cursor

Agrega a tu configuración de MCP de Cursor:

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

🔧 Herramientas disponibles

v0_generate_ui

Genera componentes de interfaz a partir de descripciones de texto.

Parámetros:

  • prompt (obligatorio): Descripción del componente de interfaz
  • model: Modelo de v0 a usar (predeterminado: v0-1.5-md)
  • stream: Habilita la respuesta de transmisión (predeterminado: false)
  • context: Contexto de código existente opcional

v0_generate_from_image

Genera componentes de interfaz a partir de referencias de imagen.

Parámetros:

  • imageUrl (obligatorio): URL de la imagen de referencia
  • prompt: Instrucciones adicionales
  • model: Modelo de v0 a usar (predeterminado: v0-1.5-md)

v0_chat_complete

Desarrollo de interfaz basado en chat con contexto de conversación.

Parámetros:

  • messages (obligatorio): Matriz de mensajes de conversación
  • model: Modelo de v0 a usar (predeterminado: v0-1.5-md)
  • stream: Habilita la respuesta de transmisión (predeterminado: false)

v0_setup_check

Valida la configuración y conectividad de la API de v0.

🔑 Variables de entorno

VariableObligatoriaPredeterminadoDescripción
V0_API_KEY✅-Tu clave API de v0
V0_BASE_URL❌https://api.v0.dev/v1URL base de la API de v0
V0_DEFAULT_MODEL❌v0-1.5-mdModelo predeterminado a usar
V0_TIMEOUT❌60000Tiempo de espera de la API (ms)
MCP_SERVER_NAME❌v0-mcpNombre del servidor MCP
LOG_LEVEL❌infoNivel de registro

🚀 Ejemplos de uso

En Claude Code

Una vez configurado, puedes usar v0-mcp de varias maneras:

Uso directo de v0-mcp

Simplemente menciona v0-mcp en tu solicitud, y Claude seleccionará automáticamente la herramienta adecuada:

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 herramientas específicas

Generar un formulario de inicio de sesión
Use v0_generate_ui to create a modern login form with email, password fields, and a blue submit button with rounded corners.
Convertir diseño a código
Use v0_generate_from_image with this Figma design URL: https://example.com/design.png
Desarrollo iterativo
Use v0_chat_complete to refine the previous login form by adding a "Remember me" checkbox and "Forgot password" link.
Verificar configuración de la API
Use v0_setup_check to verify your v0 API connection and configuration.

Ejemplos de uso avanzado

Crear un componente de panel de control

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."

Construir a partir de un esquema

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."

Refinamiento 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"}
]

🧪 Desarrollo

# 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

🛡️ Características mejoradas

Registro estructurado

  • Registro basado en Winston con formato JSON
  • Información contextual para llamadas de API y uso de herramientas
  • Seguimiento de errores con seguimientos de pila y metadatos
  • Niveles de registro configurables mediante la variable de entorno LOG_LEVEL

Manejo avanzado de errores

  • Tipos de error categorizados (API, Red, Tiempo de espera, Límite de velocidad, etc.)
  • Lógica de reintento con retroceso exponencial para errores transitorios
  • Mensajes de error fáciles de usar con orientación práctica
  • Metadatos completos de errores para depuración

Infraestructura de pruebas

  • Marco de pruebas Jest con soporte de TypeScript
  • Pruebas unitarias completas para todos los componentes principales
  • Informes de cobertura de pruebas con umbrales configurables
  • Implementaciones simuladas para dependencias externas

Fiabilidad mejorada

  • Validación de entrada mediante esquemas Zod
  • Manejo elegante de errores para todos los modos de fallo
  • Monitoreo de rendimiento con medición de tiempo de solicitudes
  • Verificaciones de salud para la conectividad de la API

💖 Apoya este proyecto

Si encuentras útil este proyecto, considera apoyarlo:

Buy Me A Coffee

¡Tu apoyo ayuda a mantener y mejorar v0-mcp!

📄 Licencia

MIT