Vibe Coder

Un servidor MCP avanzado para enrutamiento semántico, generación de código, flujos de trabajo y desarrollo asistido por IA.

GitHub
103
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Vibe Coder

npm version npm downloads npm total downloads GitHub release Node.js Version License GitHub stars

Vibe Coder es un servidor MCP (Protocolo de Contexto de Modelo) diseñado para potenciar tu asistente de IA (como Cursor, Cline AI o Claude Desktop) con herramientas poderosas para el desarrollo de software. Ayuda con investigación, planificación, generación de requisitos, creación de proyectos iniciales y ¡mucho más!

🆕 Novedades en la Versión 0.3.5

🎉 Última Versión - CLI Mejorado, REPL y Extracción de Parámetros

Mejoras Principales:

  • ✨ Revisión Completa del Matcher Híbrido: Las 15 herramientas MCP ahora tienen extracción integral de parámetros
  • 🚀 Experiencia CLI/REPL: Confirmaciones interactivas, sondeo de estado de trabajos con progreso visual
  • 🔧 Errores Críticos Corregidos: El generador de listas de tareas genera automáticamente historias de usuario, las conversaciones multi-turno funcionan perfectamente
  • 📊 Mejor Coincidencia de Herramientas: Estrategia multi-enfoque (palabras clave 35%, patrones 30%, semántica 15%, LLM 20%)
  • ⚡ Modo Estricto de TypeScript: Cero tipos any, todo tipado explícito, calidad de código de nivel producción

Mejoras en la Experiencia de Usuario:

  • Las coincidencias de baja confianza ahora solicitan confirmación del usuario
  • Indicadores visuales de progreso para trabajos de larga duración
  • Salida más limpia con filtrado de registros JSON en modo interactivo
  • Persistencia de sesión entre comandos
  • Mensajes de error mejorados y retroalimentación de validación

Versiones Anteriores Destacadas

Versión 0.3.1 - Instalación Global y Sincronización

  • Corregidos problemas de sincronización de versiones global/local
  • Proceso de compilación limpio mejorado para instalaciones
  • Flujo de empaquetado mejorado para publicación en NPM

Versión 0.2.8 - Modo Interactivo CLI

  • Corregida la persistencia de configuración en modo interactivo
  • Detección mejorada de raíz de proyecto para usuarios CLI
  • Configuración contextual mejorada

Versión 0.2.3 - REPL Interactivo y Asistente de Configuración

  • Modo REPL Interactivo con interfaz tipo chat y persistencia de sesión
  • Asistente de Configuración Mejorado con detección automática de primera ejecución
  • Plantillas de Configuración en src/config-templates/
  • Mejoras de Rendimiento con uso de memoria optimizado
  • Binario CLI Unificado - comando único vibe para todas las operaciones

🚀 Inicio Rápido

# Install globally (recommended)
npm install -g vibe-coder-mcp@latest

# Run setup wizard on first use
vibe --setup

# Or use instantly with npx (no installation)
npx vibe-coder-mcp@latest --setup

El asistente de configuración:

  1. ✅ Configurará tu clave API de OpenRouter
  2. ✅ Configurará los directorios del proyecto
  3. ✅ Creará archivos de configuración a partir de plantillas
  4. ✅ Validará tu entorno
  5. ✅ ¡Te preparará para usar todas las funciones!

📦 Instalación

npm version npm downloads

# Recommended: Install globally for the 'vibe' command
npm install -g vibe-coder-mcp@latest

# Or run instantly without installation
npx vibe-coder-mcp@latest

Métodos de Instalación

Instalación Global (Recomendada)

npm install -g vibe-coder-mcp@latest

# Use the 'vibe' command anywhere
vibe                                    # Start MCP server
vibe "create a PRD for a todo app"     # CLI mode
vibe --interactive                     # Interactive REPL mode
vibe --setup                           # Setup wizard

Ejecución Rápida con npx

# No installation needed
npx vibe-coder-mcp@latest
npx vibe-coder-mcp@latest "research React best practices"

Instalación Local en el Proyecto

npm install vibe-coder-mcp
npx vibe-coder-mcp "map the codebase structure"

Uso desde Línea de Comandos

# MCP Server Mode (for Claude Desktop, Cursor, etc.)
vibe                                    # Start with stdio transport
vibe --sse                             # Start with Server-Sent Events

# CLI Mode - Natural Language Commands
vibe "research modern JavaScript frameworks"
vibe "create a PRD for an e-commerce platform"
vibe "map the codebase structure" --json
vibe "generate user stories for auth system"

# Interactive REPL Mode
vibe --interactive                     # Chat interface with context retention

# Configuration
vibe --setup                           # Run setup wizard
vibe --help                            # Show all options
vibe --version                         # Show version

Características del Modo Interactivo:

  • Conversación estilo chat con retención de contexto
  • Ejecución de herramientas en vivo con indicadores de progreso
  • Persistencia de sesión e historial
  • Soporte de renderizado Markdown
  • Múltiples temas y personalización
  • Comandos de barra para acciones rápidas

🎯 Integración con Clientes MCP (Claude Desktop, Cursor, Cline AI)

Guía Rápida de Integración

Vibe-Coder MCP se integra perfectamente con cualquier cliente compatible con MCP. Así es como configurarlo:

Opción 1: Usando NPX (Recomendada)

En el diálogo de configuración del servidor de tu cliente MCP:

  • Nombre del Servidor: vibe-coder-mcp
  • Comando/URL: npx
  • Argumentos: vibe-coder-mcp
  • Variables de Entorno:
    • OPENROUTER_API_KEY: Tu clave API de OpenRouter (requerida)
    • VIBE_PROJECT_ROOT: /path/to/your/project (requerida)
    • LOG_LEVEL: info (opcional)
    • NODE_ENV: production (opcional)

Opción 2: Instalación Global

# First install globally
npm install -g vibe-coder-mcp

Luego configura:

  • Comando/URL: vibe
  • Argumentos: (dejar vacío)
  • Variables de Entorno: Igual que la Opción 1

Opción 3: Node con Ruta Completa

  • Comando/URL: node
  • Argumentos: /path/to/node_modules/vibe-coder-mcp/build/index.js
  • Variables de Entorno: Igual que la Opción 1

Configuración Específica para Claude Desktop

Para usuarios de Claude Desktop, agrega esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key",
        "VIBE_PROJECT_ROOT": "/path/to/your/project",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Consulta example_claude_desktop_config.json para ver un ejemplo completo.

Herramientas Disponibles Después de la Integración

Una vez configurado, tu cliente MCP tendrá acceso a:

  • vibe-task-manager: Gestión de tareas nativa de IA con metodología RDD
  • research-manager: Investigación profunda usando integración con Perplexity
  • map-codebase: Análisis avanzado de código (más de 35 lenguajes)
  • curate-context: Curaduría inteligente de contexto para desarrollo de IA
  • generate-prd: Generador de documentos de requisitos de producto
  • generate-user-stories: Generador de historias de usuario
  • generate-task-list: Generador de listas de tareas
  • generate-fullstack-starter-kit: Herramienta de andamiaje de proyectos
  • run-workflow: Ejecución de flujos de trabajo de múltiples pasos

Probando Tu Integración

Después de la configuración, prueba preguntando a tu asistente de IA:

  • "Usa vibe para investigar las mejores prácticas de React"
  • "Mapea el código de este proyecto"
  • "Genera un PRD para una aplicación de gestión de tareas"

🆕 Configuración Unificada de Raíz de Proyecto

Configuración Cero para Usuarios CLI

# Automatic project detection - just run from your project!
cd /path/to/your/project
vibe "map the codebase structure"

Configuración Simple para Clientes MCP

{
  "env": {
    "OPENROUTER_API_KEY": "your_key_here",
    "VIBE_PROJECT_ROOT": "/path/to/your/project"
  }
}
  • Una Variable: VIBE_PROJECT_ROOT reemplaza múltiples configuraciones de directorio
  • Detección Automática: CLI detecta automáticamente la raíz del proyecto
  • Compatibilidad Retroactiva: Las variables heredadas aún son compatibles

🔧 Configuración de Entorno

Requerido: Necesitas una clave API de OpenRouter para usar Vibe Coder MCP.

Obtén Tu Clave API de OpenRouter

  1. Visita openrouter.ai
  2. Crea una cuenta si no tienes una
  3. Navega a la sección de Claves API
  4. Crea una nueva clave API y cópiala

Configura las Variables de Entorno

Opción 1: Usando el Asistente de Configuración (Recomendado para v0.2.3+)

# Run the interactive setup wizard
vibe --setup

# The wizard will:
# • Configure your OpenRouter API key
# • Set up project directories
# • Create configuration files
# • Validate your setup

Opción 2: Variables de Entorno

# Set your OpenRouter API key
export OPENROUTER_API_KEY="your_api_key_here"

# Optional: Set custom directories
export VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
export VIBE_PROJECT_ROOT="/path/to/your/project"

# Legacy variables (still supported for backward compatibility)
export CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"
export VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"

Opción 3: Crear archivo .env (plantillas proporcionadas en v0.2.3+) Crea un archivo .env en tu directorio de trabajo (o cópialo de src/config-templates/.env.template):

# Required: Your OpenRouter API key
OPENROUTER_API_KEY="your_api_key_here"

# Optional: Unified project root configuration
VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
VIBE_PROJECT_ROOT="/path/to/your/project"
VIBE_USE_PROJECT_ROOT_AUTO_DETECTION="true"

# Legacy variables (still supported for backward compatibility)
CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"  
VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"

# Optional: Other settings
OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
GEMINI_MODEL="google/gemini-2.5-flash-preview-05-20"

Configuración de Directorios (Unificada y Simplificada)

🆕 Configuración Unificada (Recomendada)

  • VIBE_PROJECT_ROOT: Variable única para todas las operaciones del proyecto (detección automática habilitada por defecto para CLI)
  • VIBE_USE_PROJECT_ROOT_AUTO_DETECTION: Habilita la detección automática de raíz de proyecto para usuarios CLI (predeterminado: "true")
  • VIBE_CODER_OUTPUT_DIR: Dónde se guardan los archivos generados (predeterminado: ./VibeCoderOutput/)

Configuración Heredada (Aún Compatible)

  • CODE_MAP_ALLOWED_DIR: Límite de seguridad para análisis de código (respaldo si VIBE_PROJECT_ROOT no está configurado)
  • VIBE_TASK_MANAGER_READ_DIR: Límite de seguridad para operaciones del gestor de tareas (respaldo si VIBE_PROJECT_ROOT no está configurado)

Beneficios de la Detección Automática:

  • Configuración Cero: Los usuarios CLI obtienen detección automática de raíz de proyecto
  • Consciente del Contexto: Comportamiento diferente para uso CLI vs cliente MCP
  • Respaldo Inteligente: Cadena de resolución de 5 prioridades asegura operación confiable

🔌 Configuración del Cliente MCP

Configura tu asistente de IA para conectarse a Vibe Coder MCP:

Para Clientes MCP de Cursor AI / Windsurf / VS Code

Agrega esto a tu configuración MCP (generalmente en settings.json):

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Para Claude Desktop

Agrega esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "VIBE_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

💻 Guía de Uso de CLI

Vibe Coder incluye una interfaz de línea de comandos poderosa con múltiples modos para interacción directa con todas las herramientas.

Asistente de Configuración Interactivo (Mejorado en v0.2.3)

# First-time setup (runs automatically on first use)
vibe --setup

# Features:
# • Smart first-run detection
# • OS-specific configuration paths
# • Non-interactive mode for CI/CD
# • Configuration validation
# • Backup system for existing configs

# Reconfigure existing installation
vibe --reconfigure

Modo REPL Interactivo (¡NUEVO en v0.2.3!)

# Start interactive chat session
vibe --interactive

# Or with alias
vibe -i

# Resume a previous session
vibe --resume <session-id>

Características del REPL:

  • 🎯 Interfaz de Chat: Flujo de conversación natural con retención de contexto
  • 📝 Entrada Multilínea: Usa """ para mensajes multilínea
  • 🎨 Temas: Múltiples temas de color con el comando /theme
  • 💾 Gestión de Sesiones: Capacidades de guardado automático y reanudación
  • 📊 Renderizado Markdown: Formato de texto enriquecido en las respuestas
  • ⚡ Progreso en Vivo: Retroalimentación de ejecución en tiempo real
  • 🔧 Comandos de Barra: Acciones rápidas como /tools, /history, /save
  • 🎮 Autocompletado: Completado con tabulador para comandos y herramientas

Ejemplos de Comandos CLI

Investigación y Análisis

vibe "research modern React patterns and best practices"
vibe "analyze current trends in microservices architecture"
vibe "research security best practices for Node.js APIs"

Planificación de Proyectos

vibe "create a PRD for an e-commerce platform with user authentication"
vibe "generate user stories for authentication system"
vibe "create development tasks from user stories"

Análisis y Generación de Código

vibe "map the codebase structure"
vibe "create context for implementing authentication"
vibe "generate a fullstack starter kit for e-commerce"
vibe "create coding standards for TypeScript projects"

Gestión de Tareas

vibe "create a new project for building a todo app"
vibe "list all my projects"
vibe "show project status for MyApp"
vibe "create high priority task for implementing OAuth"

Opciones de CLI

# Output formats
vibe "research React hooks" --json
vibe "create PRD for todo app" --yaml

# Verbosity control
vibe "create project MyApp" --verbose
vibe "research Node.js patterns" --quiet

# Interactive REPL mode (NEW!)
vibe --interactive
vibe -i

# Session management (NEW!)
vibe --resume <session-id>
vibe --list-sessions

Comandos del REPL Interactivo (v0.2.3+)

Una vez en modo interactivo (vibe --interactive), usa estos comandos:

# Help and navigation
/help              # Show available commands
/tools             # List all MCP tools
/status            # Show session status

# Session management
/save              # Save current session
/sessions          # List saved sessions
/export [file]     # Export session to markdown

# Conversation control
/clear             # Clear conversation history
/history           # Show conversation history

# Customization
/theme             # Change color theme
/markdown          # Toggle markdown rendering
/config            # Manage configuration

# Exit
/quit or /exit     # Exit interactive mode

Organización de Archivos

Los archivos generados se organizan automáticamente en VibeCoderOutput/:

VibeCoderOutput/
├── research/                    # Research reports
├── prd-generator/              # Product requirements
├── user-stories-generator/     # User stories
├── task-list-generator/        # Development tasks
├── fullstack-starter-kit-generator/  # Project templates
├── map-codebase/              # Code analysis
├── vibe-task-manager/         # Task management data
└── workflow-runner/           # Workflow outputs

🔄 Guía de Migración (v0.2.3)

Cambios Importantes

¡Ninguno! La versión 0.2.3 es totalmente compatible con versiones anteriores. Todas las configuraciones y flujos de trabajo existentes continúan funcionando.

Mejoras Técnicas

  • Arquitectura CLI unificada con punto de entrada único
  • Mejor manejo de errores y recuperación
  • Limpieza de recursos mejorada
  • Seguridad de tipos mejorada en todo el código
  • Prevención de fugas de memoria en sesiones de larga duración
  • Optimización del Pipeline CI/CD:
    • Ejecución 70% más rápida (~3 minutos vs ~10 minutos)
    • Enfocado en verificaciones esenciales: verificación de tipos, lint, compilación
    • Pruebas unitarias movidas al flujo de desarrollo local
    • Consulta la Guía de CI/CD para más detalles
  • Uso de memoria optimizado para bases de código grandes
  • Experiencia de primera ejecución más rápida con detección inteligente

📚 Configuración de Desarrollo (Avanzado)

Si quieres contribuir al desarrollo o ejecutar desde el código fuente, sigue la guía de configuración detallada a continuación.

Resumen y Características

Vibe Coder MCP se integra con clientes compatibles con MCP para proporcionar las siguientes capacidades:

🚀 Arquitectura Principal

  • Soporte de Cuádruple Transporte: Protocolos de transporte stdio, SSE, WebSocket y HTTP para máxima compatibilidad con clientes
  • Asignación Dinámica de Puertos: Gestión inteligente de puertos con resolución de conflictos y degradación elegante
  • Enrutamiento Semántico de Solicitudes: Enruta inteligentemente solicitudes usando coincidencia semántica basada en embeddings con respaldos de pensamiento secuencial
  • Arquitectura de Registro de Herramientas: Gestión centralizada de herramientas con herramientas de auto-registro
  • Protocolo de Comunicación Unificado: Coordinación de agentes a través de todos los mecanismos de transporte con notificaciones en tiempo real
  • Gestión de Estado de Sesión: Mantiene el contexto entre solicitudes dentro de las sesiones

🧠 Gestión de Tareas Nativa de IA

  • Vibe Task Manager: Gestión de tareas lista para producción con 99.9% de tasa de éxito en pruebas e integración integral (Funcional pero en mejora activa)
  • Procesamiento de Lenguaje Natural: 21 intenciones compatibles con reconocimiento multi-estrategia (coincidencia de patrones + respaldo LLM)
  • Diseño de Descomposición Recursiva (RDD): Desglose inteligente de proyectos en tareas atómicas
  • Orquestación de Agentes: Coordinación multi-agente con mapeo de capacidades, balanceo de carga y sincronización de estado en tiempo real
  • Soporte de Agentes Multi-Transporte: Integración completa a través de transportes stdio, SSE, WebSocket y HTTP
  • Integración de Almacenamiento Real: Política de cero código simulado - todas las integraciones de producción
  • Integración de Análisis de Artefactos: Integración perfecta con las salidas del Generador de PRD y el Generador de Listas de Tareas
  • Persistencia de Sesión: Seguimiento de sesión mejorado con disparadores de flujo de trabajo de orquestación
  • CLI Integral: Interfaz de línea de comandos en lenguaje natural con funcionalidad extensa

🔍 Análisis Avanzado de Código y Curación de Contexto

  • Herramienta de Mapa de Código: Soporte para más de 35 lenguajes de programación con optimización de reducción de tokens del 95-97%
  • Herramienta de Curación de Contexto: Detección de proyectos independiente del lenguaje con precisión superior al 95% en más de 35 lenguajes
  • Caché Inteligente de Mapas de Código: Sistema de caché configurable que reutiliza mapas de código recientes para optimizar el rendimiento del flujo de trabajo
  • Resolución de Importaciones Mejorada: Integración de terceros para un mapeo preciso de dependencias
  • Descubrimiento de Archivos Multi-Estrategia: 4 estrategias paralelas para un análisis exhaustivo
  • Optimización de Memoria: Caché sofisticada y gestión de recursos
  • Límites de Seguridad: Validación separada de rutas de lectura/escritura para operaciones seguras

📋 Suite de Investigación y Planificación

  • Herramienta de Investigación: Investigación profunda usando Perplexity Sonar a través de OpenRouter
  • Curación de Contexto: Análisis inteligente de código con pipeline de trabajo de 8 fases y caché inteligente de mapas de código para desarrollo impulsado por IA
  • Generadores de Documentos: PRDs (prd-generator), historias de usuario (user-stories-generator), listas de tareas (task-list-generator), reglas de desarrollo (rules-generator)
  • Andamiaje de Proyectos: Kits de inicio full-stack (fullstack-starter-kit-generator) con generación dinámica de plantillas
  • Ejecución de Flujos de Trabajo: Secuencias predefinidas de llamadas a herramientas definidas en workflows.json

⚡ Rendimiento y Fiabilidad

  • Ejecución Asíncrona: Procesamiento basado en trabajos con seguimiento de estado en tiempo real
  • Rendimiento Optimizado: Tiempos de respuesta <200ms, uso de memoria <400MB
  • Pruebas Exhaustivas: Tasa de éxito de pruebas del 99.9% en más de 2,100 pruebas con validación completa de integración
  • Listo para Producción: Cero implementaciones simuladas, integraciones reales de servicios
  • Manejo de Errores Mejorado: Recuperación avanzada de errores con reintento automático, escalamiento y análisis de patrones
  • Gestión Dinámica de Puertos: Asignación inteligente de puertos con resolución de conflictos y degradación gradual
  • Monitoreo en Tiempo Real: Monitoreo de salud del agente, seguimiento de ejecución de tareas y análisis de rendimiento

(Consulte las secciones "Documentación Detallada de Herramientas" y "Detalles de Funciones" a continuación para más información)

Guía de Configuración para Desarrollo

Para desarrolladores que quieran ejecutar desde el código fuente o contribuir al proyecto.

Paso 1: Requisitos Previos

  1. Verifique la Versión de Node.js:

    • Abra una terminal o símbolo del sistema.
    • Ejecute node -v
    • Asegúrese de que la salida muestre v20.0.0 o superior (requerido).
    • Si no está instalado o está desactualizado: Descargue desde nodejs.org.

  2. Verifique la Instalación de Git:

    • Abra una terminal o símbolo del sistema.
    • Ejecute git --version
    • Si no está instalado: Descargue desde git-scm.com.

  3. Obtenga la Clave API de OpenRouter:

    • Visite openrouter.ai
    • Cree una cuenta si no tiene una.
    • Navegue a la sección de Claves API.
    • Cree una nueva clave API y cópiela.
    • Mantenga esta clave a mano para el Paso 4.

Paso 2: Obtener el Código

  1. Cree un Directorio de Proyecto (opcional):

    • Abra una terminal o símbolo del sistema.
    • Navegue a donde desea almacenar el proyecto: 
      cd ~/Documents     # Example: Change to your preferred location

  2. Clone el Repositorio:

    • Ejecute: 
      git clone https://github.com/freshtechbro/vibe-coder-mcp.git
      (O use la URL de su fork si corresponde)

  3. Navegue al Directorio del Proyecto:

    • Ejecute: 
      cd vibe-coder-mcp

Paso 3: Ejecute el Script de Configuración

Elija el script apropiado para su sistema operativo:

Para Windows:

  1. En su terminal (aún en el directorio vibe-coder-mcp), ejecute: 
    setup.bat
  2. Espere a que el script se complete (instalará dependencias, compilará el proyecto y creará los directorios necesarios).
  3. Si ve algún mensaje de error, consulte la sección de Solución de Problemas a continuación.

Para macOS o Linux:

  1. Haga ejecutable el script: 
    chmod +x setup.sh
  2. Ejecute el script: 
    ./setup.sh
  3. Espere a que el script se complete.
  4. Si ve algún mensaje de error, consulte la sección de Solución de Problemas a continuación.

El script realiza estas acciones:

  • Verifica la versión de Node.js (se requiere v20+)
  • Instala todas las dependencias vía npm
  • Crea los subdirectorios VibeCoderOutput/ necesarios
  • Compila el proyecto TypeScript
  • Crea la configuración a partir de plantillas si no está presente (v0.2.3+)
  • Establece permisos de ejecución (en sistemas Unix)

Nota: El proceso de configuración ahora es más rápido (v0.2.3+) con instalación optimizada de dependencias y proceso de compilación simplificado.

Paso 4: Configure las Variables de Entorno

Nuevo en v0.2.3: Se proporcionan plantillas de configuración en src/config-templates/ para una configuración fácil.

Opción A: Use el Asistente de Configuración (Recomendado)

vibe --setup

El asistente lo guiará a través de la configuración y creará todos los archivos necesarios.

Opción B: Configuración Manual

  1. Copie las plantillas (si el script de configuración no lo hizo ya):

    cp src/config-templates/.env.template .env
cp src/config-templates/llm_config.template.json llm_config.json
cp src/config-templates/mcp-config.template.json mcp-config.json

  2. Edite el archivo .env con su configuración:

    # OpenRouter Configuration (REQUIRED)
OPENROUTER_API_KEY="your_actual_api_key_here"

# Optional configurations
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
GEMINI_MODEL=google/gemini-2.5-flash-preview-05-20

# Project directories (optional - auto-detected for CLI users)
VIBE_PROJECT_ROOT=/path/to/your/project
VIBE_CODER_OUTPUT_DIR=/path/to/output

  3. Configure el Directorio de Salida (Opcional):

    • Para cambiar dónde se guardan los archivos generados (el valor predeterminado es VibeCoderOutput/ dentro del proyecto), agregue esta línea a su archivo .env: 
      VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
    • Reemplace la ruta con su ruta absoluta preferida. Use barras diagonales (/) para las rutas. Si esta variable no está configurada, se usará el directorio predeterminado (VibeCoderOutput/).

  4. 🆕 Configure la Raíz de Proyecto Unificada (Recomendado):

    • Para configurar la nueva raíz de proyecto unificada, agregue esta línea a su archivo .env: 
      VIBE_PROJECT_ROOT=/path/to/your/project/root
    • Reemplace la ruta con la ruta absoluta al directorio raíz de su proyecto.
    • Beneficios: Una sola variable de configuración para todas las herramientas (Generador de Mapas de Código, Administrador de Tareas, Curador de Contexto)
    • Detección Automática: Para usuarios de CLI, la raíz del proyecto se detecta automáticamente desde el directorio de trabajo actual
    • Compatibilidad Retroactiva: Las variables heredadas aún son compatibles si prefiere configuraciones separadas

  5. Configuración de Directorios Heredada (Opcional):

    • Si prefiere configuraciones de directorio separadas, aún puede usar las variables originales: 
      CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory
VIBE_TASK_MANAGER_READ_DIR=/path/to/your/project/source/directory
    • Nota: Estas variables funcionan como respaldo si VIBE_PROJECT_ROOT no está configurado
    • Seguridad: Todas las variables funcionan con la implementación estricta de seguridad del sistema de archivos

  6. Revise Otras Configuraciones (Opcional):

    • Puede agregar otras variables de entorno compatibles con el servidor, como LOG_LEVEL (por ejemplo, LOG_LEVEL=debug) o NODE_ENV (por ejemplo, NODE_ENV=development).

  7. Guarde el Archivo .env.

Paso 5: Integre con su Asistente de IA (Configuración MCP)

Este paso crucial conecta Vibe Coder a su asistente de IA agregando su configuración al archivo de configuración MCP del cliente.

5.1: Localice el Archivo de Configuración MCP de su Cliente

La ubicación varía según su asistente de IA:

  • Cursor AI / Windsurf / RooCode (basado en VS Code):

    1. Abra la aplicación.
    2. Abra la Paleta de Comandos (Ctrl+Shift+P o Cmd+Shift+P).
    3. Escriba y seleccione Preferences: Open User Settings (JSON).
    4. Esto abre su archivo settings.json donde debe residir el objeto mcpServers.

  • Cline AI (Extensión de VS Code):

    • Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
    • macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
    • Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
    • (Nota: Si usa VS Code estándar en lugar de Cursor, reemplace Cursor con Code en la ruta)

  • Claude Desktop:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

5.2: Agregue la Configuración de Vibe Coder

  1. Abra el archivo de configuración identificado anteriormente en un editor de texto.

  2. Encuentre el objeto JSON "mcpServers": { ... }. Si no existe, es posible que deba crearlo (asegúrese de que el archivo general siga siendo JSON válido). Por ejemplo, un archivo vacío podría convertirse en {"mcpServers": {}}.

  3. Agregue el siguiente bloque de configuración dentro de las llaves {} del objeto mcpServers. Si ya hay otros servidores listados, agregue una coma , después de la llave de cierre } del servidor anterior antes de pegar este bloque.

    // This is the unique identifier for this MCP server instance within your client's settings
"vibe-coder-mcp": {
  // Specifies the command used to execute the server. Should be 'node' if Node.js is in your system's PATH
  "command": "node",
  // Provides the arguments to the 'command'. The primary argument is the absolute path to the compiled server entry point
  // !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
  "args": ["/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/build/index.js"],
  // Sets the current working directory for the server process when it runs
  // !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
  "cwd": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
  // Defines the communication transport protocol between the client and server
  "transport": "stdio",
  // Environment variables to be passed specifically to the Vibe Coder server process when it starts
  // API Keys should be in the .env file, NOT here
  "env": {
    // Absolute path to the LLM configuration file used by Vibe Coder
    // !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
    "LLM_CONFIG_PATH": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/llm_config.json",
    // Sets the logging level for the server
    "LOG_LEVEL": "debug",
    // Specifies the runtime environment
    "NODE_ENV": "production",
    // Directory where Vibe Coder tools will save their output files
    // !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
    "VIBE_CODER_OUTPUT_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/VibeCoderOutput",
    // 🆕 Unified project root for all tools (recommended)
    // This single variable configures all tools with the same project boundary
    "VIBE_PROJECT_ROOT": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
    // Legacy variables (optional - used as fallbacks if VIBE_PROJECT_ROOT not set)
    "CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src",
    "VIBE_TASK_MANAGER_READ_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP"
  },
  // A boolean flag to enable (false) or disable (true) this server configuration
  "disabled": false,
  // A list of tool names that the MCP client is allowed to execute automatically
  "autoApprove": [
    "research",
    "rules-generator",
    "user-stories-generator",
    "task-list-generator",
    "prd-generator",
    "fullstack-starter-kit-generator",
    "refactor-code",
    "git-summary",
    "run-workflow",
    "map-codebase"
  ]
}

  4. CRÍTICO: Reemplace todas las rutas de marcador de posición (como /path/to/your/vibe-coder-mcp/...) con las rutas absolutas correctas en su sistema donde clonó el repositorio. Use barras diagonales / para las rutas, incluso en Windows (por ejemplo, C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js). Las rutas incorrectas son la razón más común por la que el servidor no se conecta.

  5. Guarde el archivo de configuración.

  6. Cierre y reinicie completamente su aplicación de asistente de IA (Cursor, VS Code, Claude Desktop, etc.) para que los cambios surtan efecto.

Paso 6: Pruebe su Configuración

  1. Inicie su Asistente de IA:

    • Reinicie completamente su aplicación de asistente de IA.

  2. Pruebe un Comando Simple:

    • Escriba un comando de prueba como: Research modern JavaScript frameworks

  3. Verifique la Respuesta Adecuada:

    • Si funciona correctamente, debería recibir una respuesta de investigación.
    • Si no, consulte la sección de Solución de Problemas a continuación.

Integración con Agentes de IA

El sistema MCP de Vibe Coder incluye instrucciones de sistema integrales diseñadas para ayudar a los agentes de IA y clientes MCP a aprovechar eficazmente todo el ecosistema. Estas instrucciones proporcionan orientación detallada sobre el uso de herramientas, patrones de integración y mejores prácticas.

Archivo de Instrucciones del Sistema

El archivo VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md contiene orientación integral para agentes de IA sobre cómo usar el ecosistema MCP de Vibe Coder de manera efectiva. Este archivo debe integrarse en su entorno de desarrollo de IA para entrenar a sus agentes en el uso óptimo de herramientas.

Integración Específica por Plataforma

Claude Desktop

Coloque las instrucciones del sistema en las instrucciones del sistema o instrucciones personalizadas de su proyecto:

  1. Abra Claude Desktop
  2. Navegue a la configuración del proyecto
  3. Agregue el contenido de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md al campo de instrucciones del sistema
  4. Guarde y reinicie Claude Desktop

ChatGPT

Agregue las instrucciones del sistema a sus instrucciones personalizadas o configuración del proyecto:

  1. Abra la configuración de ChatGPT
  2. Navegue a instrucciones personalizadas o configuración del proyecto
  3. Pegue el contenido de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
  4. Guarde la configuración

Extensiones de VS Code (Cline, Roo Coder, Augment)

Integre las instrucciones del sistema en la configuración de su extensión:

  1. Cline: Coloque en la sección de instrucciones del sistema o memorias
  2. Roo Coder: Agregue a la carpeta de instrucciones del sistema o reglas
  3. Augment: Coloque en instrucciones del sistema o memorias
  4. Otros forks de VS Code: Coloque en la carpeta de instrucciones del sistema o reglas con la configuración "siempre activo"

Clientes MCP Generales

Para otros clientes compatibles con MCP:

  1. Localice la configuración de instrucciones del sistema o reglas
  2. Agregue el contenido de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
  3. Establezca como "siempre activo" o "persistente" si la opción está disponible
  4. Reinicie el cliente para aplicar los cambios

Beneficios Clave de la Integración

  • Conocimiento Integral de Herramientas: Los agentes aprenden sobre las más de 15 herramientas disponibles y sus capacidades
  • Orquestación de Flujos de Trabajo: Orientación sobre cómo encadenar herramientas para flujos de trabajo de desarrollo complejos
  • Protocolo de Sondeo de Trabajos: Instrucciones críticas para manejar operaciones asíncronas correctamente
  • Mejores Prácticas: Estrategias de optimización de rendimiento y manejo de errores
  • Patrones de Integración: Flujos de trabajo comunes para investigación, planificación e implementación

Ejemplos de Uso

Una vez integrado, sus agentes de IA podrán:

# Research-driven development
"Research modern React patterns, then create a PRD and generate user stories"

# Complete project setup
"Set up a new e-commerce project with React frontend and Node.js backend"

# Context-aware development
"Analyze this codebase and suggest improvements with implementation tasks"

# Multi-agent coordination
"Register frontend and backend agents, then distribute authentication tasks"

Verificación

Para verificar la integración exitosa:

  1. Pregunte a su agente de IA sobre las herramientas disponibles de Vibe Coder
  2. Solicite un flujo de trabajo que use múltiples herramientas en secuencia
  3. Verifique que el agente siga los protocolos adecuados de sondeo de trabajos
  4. Confirme que las salidas se guarden en los directorios correctos

🎯 Arquitectura CLI Unificada (v0.2.3+)

La nueva CLI unificada (unified-cli.ts) proporciona un punto de entrada único para todas las operaciones de Vibe Coder:

flowchart TD
    Start[vibe command] --> Detect{First Run?}
    Detect -->|Yes| Setup[Setup Wizard]
    Detect -->|No| Parse[Parse Arguments]
    
    Setup --> Config[Save Configuration]
    Config --> Parse
    
    Parse --> Mode{Mode?}
    Mode -->|--interactive| REPL[Interactive REPL]
    Mode -->|"message"| CLI[CLI Execution]
    Mode -->|none| MCP[MCP Server]
    Mode -->|--setup| Setup
    
    REPL --> Session[Session Management]
    Session --> Chat[Chat Interface]
    Chat --> Tools[Tool Execution]
    
    CLI --> Router[Hybrid Router]
    Router --> Tools
    
    MCP --> Transport{Transport?}
    Transport -->|stdio| Stdio[Stdio Server]
    Transport -->|sse| SSE[SSE Server]

Beneficios de la CLI Unificada:

  • Un solo binario para todas las operaciones (vibe)
  • Interfaz de comandos consistente
  • Gestión de configuración compartida
  • Cambio de modo sin interrupciones
  • Mejor utilización de recursos

Arquitectura del Proyecto

El servidor MCP de Vibe Coder sigue una arquitectura modular de TypeScript ESM con soporte de doble transporte y un ecosistema integral de herramientas:

flowchart TD
    subgraph "Core Architecture"
        Init[index.ts] --> Config[Configuration Loader]
        Config --> Transport{Transport Type}
        Transport --> |stdio| StdioTransport[Stdio Transport]
        Transport --> |sse| SSETransport[SSE Transport]
        StdioTransport --> Server[MCP Server]
        SSETransport --> Server
        Server --> ToolReg[Tool Registry]
        ToolReg --> InitEmbed[Initialize Embeddings]
        InitEmbed --> Ready[Server Ready]
    end

    subgraph "Request Processing"
        Req[Client Request] --> SessionMgr[Session Manager]
        SessionMgr --> Router[Hybrid Router]
        Router --> Semantic[Semantic Matcher]
        Router --> Sequential[Sequential Thinking]
        Semantic --> |High Confidence| Execute[Tool Execution]
        Sequential --> |Fallback| Execute
        Execute --> JobMgr[Job Manager]
        JobMgr --> Response[Response to Client]
    end

    subgraph "Tool Ecosystem"
        Execute --> Research[Research Tool]
        Execute --> TaskMgr[Vibe Task Manager]
        Execute --> CodeMap[Code Map Tool]
        Execute --> FullStack[Fullstack Generator]
        Execute --> PRDGen[PRD Generator]
        Execute --> UserStories[User Stories Generator]
        Execute --> TaskList[Task List Generator]
        Execute --> Rules[Rules Generator]
        Execute --> Workflow[Workflow Runner]
    end

    subgraph "Support Services"
        JobMgr --> AsyncJobs[Async Job Processing]
        Execute --> FileOps[File Operations]
        Execute --> LLMHelper[LLM Integration]
        Execute --> ErrorHandler[Error Handling]
        Execute --> StateManager[Session State]
    end

    subgraph "Configuration & Security"
        Config --> LLMConfig[LLM Config Mapping]
        Config --> MCPConfig[MCP Tool Config]
        Config --> EnvVars[Environment Variables]
        FileOps --> SecurityBoundary[Security Boundaries]
        SecurityBoundary --> ReadOps[Read Operations]
        SecurityBoundary --> WriteOps[Write Operations]
    end

Estructura de Directorios

vibe-coder-mcp/
├── .env                              # Environment configuration
├── .env.example                      # Environment template
├── llm_config.json                   # LLM model mappings
├── mcp-config.json                   # MCP tool configurations
├── package.json                      # Project dependencies
├── README.md                         # This documentation
├── VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md  # System prompt documentation
├── setup.bat                         # Windows setup script
├── setup.sh                          # macOS/Linux setup script
├── tsconfig.json                     # TypeScript configuration
├── vitest.config.ts                  # Vitest (testing) configuration
├── workflows.json                    # Workflow definitions
├── build/                            # Compiled JavaScript (after build)
├── docs/                             # Additional documentation
│   ├── map-codebase/                # Code Map Tool docs
│   ├── handover/                     # Development handover docs
│   └── *.md                          # Various documentation files
├── VibeCoderOutput/                  # Tool output directory
│   ├── research/                    # Research reports
│   ├── rules-generator/              # Development rules
│   ├── prd-generator/                # Product requirements
│   ├── user-stories-generator/       # User stories
│   ├── task-list-generator/          # Task lists
│   ├── fullstack-starter-kit-generator/  # Project templates
│   ├── map-codebase/                # Code maps and diagrams
│   ├── vibe-task-manager/            # Task management data
│   └── workflow-runner/              # Workflow outputs
└── src/                              # Source code
    ├── index.ts                      # Entry point
    ├── logger.ts                     # Logging configuration (Pino)
    ├── server.ts                     # MCP server setup
    ├── services/                     # Core services
    │   ├── routing/                  # Semantic routing system
    │   │   ├── embeddingStore.ts     # Embedding management
    │   │   ├── hybridMatcher.ts      # Hybrid routing logic
    │   │   └── toolRegistry.ts       # Tool registry
    │   ├── sse-notifier/             # SSE notification system
    │   ├── JobManager.ts             # Async job management
    │   └── ToolService.ts            # Tool execution service
    ├── tools/                        # MCP Tools
    │   ├── index.ts                  # Tool registration
    │   ├── sequential-thinking.ts    # Fallback routing
    │   ├── map-codebase/            # Code analysis tool
    │   │   ├── cache/                # Memory management
    │   │   ├── grammars/             # Tree-sitter grammars
    │   │   ├── importResolvers/      # Import resolution adapters
    │   │   └── *.ts                  # Core implementation
    │   ├── fullstack-starter-kit-generator/  # Project scaffolding
    │   ├── prd-generator/            # PRD creation
    │   ├── research/                # Research tool
    │   ├── rules-generator/          # Rule generation
    │   ├── task-list-generator/      # Task list generation
    │   ├── user-stories-generator/   # User story generation
    │   ├── vibe-task-manager/        # AI-native task management
    │   │   ├── __tests__/            # Comprehensive test suite
    │   │   ├── cli/                  # Command-line interface
    │   │   ├── core/                 # Core algorithms
    │   │   ├── integrations/         # Tool integrations
    │   │   ├── prompts/              # LLM prompts (YAML)
    │   │   ├── services/             # Business logic services
    │   │   ├── types/                # TypeScript definitions
    │   │   └── utils/                # Utility functions
    │   └── workflow-runner/          # Workflow execution engine
    ├── types/                        # TypeScript type definitions
    └── utils/                        # Shared utilities
        ├── configLoader.ts           # Configuration management
        ├── errors.ts                 # Error handling
        └── llmHelper.ts              # LLM integration helpers

Sistema de Enrutamiento Semántico

Vibe Coder utiliza un enfoque de enrutamiento sofisticado para seleccionar la herramienta adecuada para cada solicitud:

flowchart TD
    Start[Client Request] --> Process[Process Request]
    Process --> Hybrid[Hybrid Matcher]

    subgraph "Primary: Semantic Routing"
        Hybrid --> Semantic[Semantic Matcher]
        Semantic --> Embeddings[Query Embeddings]
        Embeddings --> Tools[Tool Embeddings]
        Tools --> Compare[Compare via Cosine Similarity]
        Compare --> Score[Score & Rank Tools]
        Score --> Confidence{High Confidence?}
    end

    Confidence -->|Yes| Registry[Tool Registry]

    subgraph "Fallback: Sequential Thinking"
        Confidence -->|No| Sequential[Sequential Thinking]
        Sequential --> LLM[LLM Analysis]
        LLM --> ThoughtChain[Thought Chain]
        ThoughtChain --> Extraction[Extract Tool Name]
        Extraction --> Registry
    end

    Registry --> Executor[Execute Tool]
    Executor --> Response[Return Response]

Patrón de Registro de Herramientas

El Registro de Herramientas es un componente central para gestionar las definiciones y la ejecución de herramientas:

flowchart TD
    subgraph "Tool Registration (at import)"
        Import[Import Tool] --> Register[Call registerTool]
        Register --> Store[Store in Registry Map]
    end

    subgraph "Tool Definition"
        Def[ToolDefinition] --> Name[Tool Name]
        Def --> Desc[Description]
        Def --> Schema[Zod Schema]
        Def --> Exec[Executor Function]
    end

    subgraph "Server Initialization"
        Init[server.ts] --> Import
        Init --> GetAll[getAllTools]
        GetAll --> Loop[Loop Through Tools]
        Loop --> McpReg[Register with MCP Server]
    end

    subgraph "Tool Execution"
        McpReg --> ExecTool[executeTool Function]
        ExecTool --> GetTool[Get Tool from Registry]
        GetTool --> Validate[Validate Input]
        Validate -->|Valid| ExecFunc[Run Executor Function]
        Validate -->|Invalid| ValidErr[Return Validation Error]
        ExecFunc -->|Success| SuccessResp[Return Success Response]
        ExecFunc -->|Error| HandleErr[Catch & Format Error]
        HandleErr --> ErrResp[Return Error Response]
    end

Proceso de Pensamiento Secuencial

El mecanismo de Pensamiento Secuencial proporciona un enrutamiento de respaldo basado en LLM:

flowchart TD
    Start[Start] --> Estimate[Estimate Number of Steps]
    Estimate --> Init[Initialize with System Prompt]
    Init --> First[Generate First Thought]
    First --> Context[Add to Context]
    Context --> Loop{Needs More Thoughts?}

    Loop -->|Yes| Next[Generate Next Thought]
    Next -->|Standard| AddStd[Add to Context]
    Next -->|Revision| Rev[Mark as Revision]
    Next -->|New Branch| Branch[Mark as Branch]
    Rev --> AddRev[Add to Context]
    Branch --> AddBranch[Add to Context]
    AddStd --> Loop
    AddRev --> Loop
    AddBranch --> Loop

    Loop -->|No| Extract[Extract Final Solution]
    Extract --> End[End With Tool Selection]

    subgraph "Error Handling"
        Next -->|Error| Retry[Retry with Simplified Request]
        Retry -->|Success| AddRetry[Add to Context]
        Retry -->|Failure| FallbackEx[Extract Partial Solution]
        AddRetry --> Loop
        FallbackEx --> End
    end

Gestión del Estado de Sesión

flowchart TD
    Start[Client Request] --> SessionID[Extract Session ID]
    SessionID --> Store{State Exists?}

    Store -->|Yes| Retrieve[Retrieve Previous State]
    Store -->|No| Create[Create New State]

    Retrieve --> Context[Add Context to Tool]
    Create --> NoContext[Execute Without Context]

    Context --> Execute[Execute Tool]
    NoContext --> Execute

    Execute --> SaveState[Update Session State]
    SaveState --> Response[Return Response to Client]

    subgraph "Session State Structure"
        State[SessionState] --> PrevCall[Previous Tool Call]
        State --> PrevResp[Previous Response]
        State --> Timestamp[Timestamp]
    end

Motor de Ejecución de Flujos de Trabajo

El sistema de Flujos de Trabajo permite secuencias de múltiples pasos:

flowchart TD
    Start[Client Request] --> Parse[Parse Workflow Request]
    Parse --> FindFlow[Find Workflow in workflows.json]
    FindFlow --> Steps[Extract Steps]

    Steps --> Loop[Process Each Step]
    Loop --> PrepInput[Prepare Step Input]
    PrepInput --> ExecuteTool[Execute Tool via Registry]
    ExecuteTool --> SaveOutput[Save Step Output]
    SaveOutput --> NextStep{More Steps?}

    NextStep -->|Yes| MapOutput[Map Output to Next Input]
    MapOutput --> Loop

    NextStep -->|No| FinalOutput[Prepare Final Output]
    FinalOutput --> End[Return Workflow Result]

    subgraph "Input/Output Mapping"
        MapOutput --> Direct[Direct Value]
        MapOutput --> Extract[Extract From Previous]
        MapOutput --> Transform[Transform Values]
    end

Configuración de Flujos de Trabajo

Los flujos de trabajo se definen en el archivo workflows.json ubicado en el directorio raíz del proyecto. Este archivo contiene secuencias predefinidas de llamadas a herramientas que pueden ejecutarse con un solo comando.

Ubicación y Estructura del Archivo

  • El archivo workflows.json debe colocarse en el directorio raíz del proyecto (mismo nivel que package.json)
  • El archivo sigue esta estructura: 
    {
  "workflows": {
    "workflowName1": {
      "description": "Description of what this workflow does",
      "inputSchema": {
        "param1": "string",
        "param2": "string"
      },
      "steps": [
        {
          "id": "step1_id",
          "toolName": "tool-name",
          "params": {
            "param1": "{workflow.input.param1}"
          }
        },
        {
          "id": "step2_id",
          "toolName": "another-tool",
          "params": {
            "paramA": "{workflow.input.param2}",
            "paramB": "{steps.step1_id.output.content[0].text}"
          }
        }
      ],
      "output": {
        "summary": "Workflow completed message",
        "details": ["Output line 1", "Output line 2"]
      }
    }
  }
}

Plantillas de Parámetros

Los parámetros de los pasos del flujo de trabajo admiten cadenas de plantilla que pueden hacer referencia a:

  • Entradas del flujo de trabajo: {workflow.input.paramName}
  • Salidas de pasos anteriores: {steps.stepId.output.content[0].text}

Activación de Flujos de Trabajo

Utilice la herramienta run-workflow con:

Run the newProjectSetup workflow with input {"productDescription": "A task manager app"}

Documentación Detallada de Herramientas

Cada herramienta en el directorio src/tools/ incluye documentación completa en su propio archivo README.md. Estos archivos cubren:

  • Descripción general y propósito de la herramienta
  • Especificaciones de entrada/salida
  • Diagramas de flujo de trabajo (Mermaid)
  • Ejemplos de uso
  • Prompts de sistema utilizados
  • Detalles de manejo de errores

Consulte estos README individuales para obtener información detallada:

  • src/tools/fullstack-starter-kit-generator/README.md
  • src/tools/prd-generator/README.md
  • src/tools/research/README.md
  • src/tools/rules-generator/README.md
  • src/tools/task-list-generator/README.md
  • src/tools/user-stories-generator/README.md
  • src/tools/workflow-runner/README.md
  • src/tools/map-codebase/README.md

Categorías de Herramientas

Herramientas de Análisis e Información

  • Herramienta de Mapa de Código (map-codebase): Escanea una base de código para extraer información semántica (clases, funciones, comentarios) y genera un mapa Markdown legible con diagramas Mermaid o una representación JSON estructurada con rutas de archivo absolutas para importaciones e información mejorada de propiedades de clases.
  • Herramienta de Curación de Contexto (curate-context): Análisis inteligente de bases de código y curación de paquetes de contexto con un pipeline de trabajo de 8 fases, caché inteligente de mapas de código, detección de proyectos independiente del lenguaje que admite más de 35 lenguajes de programación y descubrimiento de archivos con múltiples estrategias para tareas de desarrollo impulsadas por IA.
  • Herramienta de Investigación (research): Realiza investigaciones profundas sobre temas técnicos utilizando Perplexity Sonar, proporcionando resúmenes y fuentes.

Herramientas de Planificación y Documentación

  • Generador de Reglas (rules-generator): Crea reglas y pautas de desarrollo específicas para el proyecto.
  • Generador de PRD (prd-generator): Genera documentos completos de requisitos de producto.
  • Generador de Historias de Usuario (user-stories-generator): Crea historias de usuario detalladas con criterios de aceptación.
  • Generador de Listas de Tareas (task-list-generator): Construye listas estructuradas de tareas de desarrollo con dependencias.

Herramienta de Andamiaje de Proyectos

  • Generador de Kit de Inicio Fullstack (fullstack-starter-kit-generator): Crea kits de inicio de proyectos personalizados con tecnologías de frontend/backend especificadas, incluidos scripts de configuración básicos y configuración.

Flujo de Trabajo y Orquestación

  • Ejecutor de Flujos de Trabajo (run-workflow): Ejecuta secuencias predefinidas de llamadas a herramientas para tareas comunes de desarrollo.

Almacenamiento de Archivos Generados

De forma predeterminada, las salidas de las herramientas generadoras se almacenan como referencia histórica en el directorio VibeCoderOutput/ dentro del proyecto. Esta ubicación se puede sobrescribir configurando la variable de entorno VIBE_CODER_OUTPUT_DIR en su archivo .env o en la configuración del asistente de IA.

Límites de Seguridad para Operaciones de Lectura y Escritura

Por razones de seguridad, las herramientas MCP de Vibe Coder mantienen límites de seguridad separados para operaciones de lectura y escritura con un enfoque de seguridad por defecto:

  • Operaciones de Lectura:

    • Herramienta de Mapa de Código: Solo lee de directorios explícitamente autorizados a través de la variable de entorno CODE_MAP_ALLOWED_DIR
    • Vibe Task Manager: Solo lee de directorios autorizados a través de la variable de entorno VIBE_TASK_MANAGER_READ_DIR (por defecto process.cwd())
    • Modo de Seguridad: El Vibe Task Manager utiliza por defecto el modo de seguridad 'estricto', que impide el acceso a directorios del sistema como /private/var/spool/postfix/, /System/ y otras rutas no autorizadas
    • Seguridad del Sistema de Archivos: Aplicación integral de listas negras y verificación de permisos para prevenir errores EACCES y acceso no autorizado a archivos

  • Operaciones de Escritura: Todos los archivos de salida se escriben en el directorio VIBE_CODER_OUTPUT_DIR (o sus subdirectorios). Esta separación garantiza que las herramientas solo puedan escribir en ubicaciones de salida designadas, protegiendo su código fuente de modificaciones accidentales.

  • Implementación de Seguridad: El sistema de seguridad del sistema de archivos incluye:

    • Gestión Adaptativa de Tiempos de Espera: Evita que las operaciones se bloqueen indefinidamente con reintentos inteligentes y cancelación
    • Validación de Rutas: Validación integral de todas las rutas de archivos antes del acceso
    • Verificación de Permisos: Verificación proactiva de permisos para prevenir errores de acceso
    • Protección de Directorios del Sistema: Lista negra integrada de directorios del sistema a los que nunca se debe acceder

Estructura de ejemplo (ubicación predeterminada):

VibeCoderOutput/
  ├── research/                # Research reports
  │   └── TIMESTAMP-QUERY-research.md
  ├── rules-generator/          # Development rules
  │   └── TIMESTAMP-PROJECT-rules.md
  ├── prd-generator/            # PRDs
  │   └── TIMESTAMP-PROJECT-prd.md
  ├── user-stories-generator/   # User stories
  │   └── TIMESTAMP-PROJECT-user-stories.md
  ├── task-list-generator/      # Task lists
  │   └── TIMESTAMP-PROJECT-task-list.md
  ├── fullstack-starter-kit-generator/  # Project templates
  │   └── TIMESTAMP-PROJECT/
  ├── map-codebase/            # Code maps and diagrams
  │   └── TIMESTAMP-code-map/
  └── workflow-runner/          # Workflow outputs
      └── TIMESTAMP-WORKFLOW/

Instrucciones del Sistema para Clientes MCP

Para un rendimiento óptimo con asistentes de IA y clientes MCP, utilice las instrucciones completas del sistema proporcionadas en VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md. Este documento contiene pautas detalladas para:

  • Patrones de uso específicos de herramientas y mejores prácticas
  • Estructuras de comandos en lenguaje natural
  • Pautas de sondeo de trabajos asíncronos
  • Flujos de trabajo de integración y ejemplos
  • Manejo de errores y resolución de problemas

Cómo Usar las Instrucciones del Sistema

Para Claude Desktop:

  1. Abra la configuración de Claude Desktop
  2. Navegue a "Instrucciones personalizadas" o "Prompt del sistema"
  3. Copie todo el contenido de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
  4. Péguelo en el campo de instrucciones personalizadas
  5. Guarde la configuración

Para Augment:

  1. Acceda a la configuración/preferencias de Augment
  2. Encuentre "Instrucciones personalizadas" o "Configuración del sistema"
  3. Copie y pegue las instrucciones del sistema
  4. Aplique los cambios

Para Claude Code/Windsurf/Otros Clientes MCP:

  1. Localice la configuración de instrucciones personalizadas o prompt del sistema
  2. Copie el contenido de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
  3. Péguelo en el campo correspondiente
  4. Guarde/aplique la configuración

Beneficios de Usar las Instrucciones del Sistema:

  • Tasa de éxito de operación de herramientas del 98% o más
  • Reconocimiento óptimo de comandos en lenguaje natural
  • Manejo adecuado de trabajos asíncronos
  • Orquestación eficiente de flujos de trabajo
  • Reducción de errores y mejora en la resolución de problemas

Ejemplos de Uso

Mediante CLI (Línea de Comandos Directa)

# Research and analysis
vibe "research modern JavaScript frameworks"
vibe "create development rules for a mobile banking application"

# Project planning
vibe "generate a PRD for a task management application"
vibe "generate user stories for an e-commerce website"
vibe "create a task list for a weather app based on user stories"

# Code generation and analysis
vibe "create a starter kit for a React/Node.js blog application with user authentication"
vibe "map the codebase structure" --json
vibe "curate context for adding authentication to my React app"

# Task management
vibe "create a new project for building a todo app"
vibe "list all my projects"
vibe "show status of my React project"

# Workflow automation
vibe "run workflow newProjectSetup with input {\"projectName\": \"my-new-app\"}"

Mediante Cliente MCP (Integración con Asistente de IA)

Interactúe con las herramientas a través de su asistente de IA conectado:

  • Investigación: Research modern JavaScript frameworks
  • Generar Reglas: Create development rules for a mobile banking application
  • Generar PRD: Generate a PRD for a task management application
  • Generar Historias de Usuario: Generate user stories for an e-commerce website
  • Generar Lista de Tareas: Create a task list for a weather app based on [user stories]
  • Pensamiento Secuencial: Think through the architecture for a microservices-based e-commerce platform
  • Kit de Inicio Fullstack: Create a starter kit for a React/Node.js blog application with user authentication
  • Ejecutar Flujo de Trabajo: Run workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }
  • Mapear Base de Código: Generate a code map for the current project, map-codebase path="./src" o Generate a JSON representation of the codebase structure with output_format="json"
  • Curación de Contexto: Curate context for adding authentication to my React app, Generate context package for refactoring the user service o Analyze this codebase for performance optimization opportunities
  • Vibe Task Manager: Create a new project for building a todo app, List all my projects, Run task authentication-setup, What's the status of my React project?

Vibe Task Manager - Gestión de Tareas Nativa para IA

El Vibe Task Manager es un sistema integral de gestión de tareas diseñado específicamente para agentes de IA y flujos de trabajo de desarrollo. Proporciona descomposición inteligente de proyectos, procesamiento de comandos en lenguaje natural e integración perfecta con otras herramientas de Vibe Coder.

Estado: Funcional y listo para producción con una tasa de éxito de pruebas del 99.9%, pero se está mejorando activamente con nuevas funciones y mejoras.

Características Clave

  • Procesamiento de Lenguaje Natural: Comprende comandos como "Crear un proyecto para construir una aplicación React" o "Mostrarme todas las tareas pendientes"
  • Diseño de Descomposición Recursiva (RDD): Descompone automáticamente proyectos complejos en tareas atómicas y ejecutables
  • Integración de Análisis de Artefactos: Importa sin problemas archivos PRD de VibeCoderOutput/prd-generator/ y listas de tareas de VibeCoderOutput/generated_task_lists/
  • Persistencia de Sesión: Seguimiento de sesión mejorado con activadores de flujos de trabajo de orquestación para operaciones confiables de múltiples pasos
  • CLI Integral: Interfaz de línea de comandos completa con procesamiento de lenguaje natural y comandos estructurados
  • Orquestación de Agentes: Coordina múltiples agentes de IA para la ejecución paralela de tareas
  • Listo para Integración: Funciona perfectamente con la Herramienta de Mapa de Código, la Herramienta de Investigación y otras herramientas
  • Almacenamiento de Archivos: Todos los datos del proyecto se almacenan en VibeCoderOutput/vibe-task-manager/ siguiendo convenciones establecidas

Ejemplos de Inicio Rápido

# Project Management
"Create a new project for building a todo app with React and Node.js"
"List all my projects"
"Show me the status of my web app project"

# Task Management
"Create a high priority task for implementing user authentication"
"List all pending tasks for the todo-app project"
"Run the database setup task"

# Project Analysis (Enhanced with Intelligent Lookup)
"Decompose my React project into development tasks"
"Decompose PID-TODO-APP-REACT-001 into tasks"  # Using project ID
"Decompose \"Todo App with React\" into tasks"  # Using exact name
"Decompose todo into tasks"  # Using partial name (fuzzy matching)
"Refine the authentication task to include OAuth support"
"What's the current progress on my mobile app?"

🎯 Funciones Mejoradas de Búsqueda de Proyectos

  • Análisis Inteligente: Detecta automáticamente IDs de proyectos, nombres o coincidencias parciales
  • Validación Integral: Valida la preparación del proyecto antes de la descomposición
  • Mensajes de Error Mejorados: Proporciona orientación práctica con proyectos disponibles y ejemplos de uso
  • Múltiples Formatos de Entrada: Admite IDs de proyectos, nombres entre comillas, nombres parciales y coincidencias difusas
  • Puntuación de Confianza: Muestra niveles de confianza de análisis para una mejor retroalimentación al usuario

Estructura de Comandos

El Vibe Task Manager admite tanto comandos estructurados como lenguaje natural:

Comandos Estructurados:

  • vibe-task-manager create project "Name" "Description" --options
  • vibe-task-manager list projects --status pending
  • vibe-task-manager run task task-id --force
  • vibe-task-manager status project-id --detailed

Lenguaje Natural (Recomendado):

  • "Crear un proyecto para [descripción]"
  • "Mostrarme todos los proyectos [estado]"
  • "Ejecutar la tarea [nombre de la tarea]"
  • "¿Cuál es el estado de [proyecto]?"
  • "Analizar archivos PRD para [nombre del proyecto]" (NUEVO)
  • "Importar lista de tareas desde [ruta del archivo]" (NUEVO)
  • "Analizar todos los PRD y crear proyectos automáticamente" (NUEVO)

Para documentación completa, consulte src/tools/vibe-task-manager/README.md y las instrucciones del sistema en VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md.

Estado de Implementación y Métricas de Rendimiento

Estado Actual del Epic

El proyecto MCP de Vibe Coder sigue un enfoque de desarrollo basado en epics con seguimiento integral:

gantt
    title Vibe Coder MCP Development Progress
    dateFormat  YYYY-MM-DD
    section Core Infrastructure
    Tool Registry & Routing    :done, epic1, 2024-01-01, 2024-02-15
    MCP Server Implementation  :done, epic2, 2024-01-15, 2024-03-01
    Async Job Management       :done, epic3, 2024-02-15, 2024-03-15

    section Tool Development
    Research & Planning Tools  :done, epic4, 2024-02-01, 2024-04-01
    Code Map Tool              :done, epic5, 2024-03-01, 2024-05-15
    Vibe Task Manager Core     :done, epic6, 2024-04-01, 2024-06-15

    section Advanced Features
    Performance Optimization   :active, epic7, 2024-06-01, 2024-07-15
    Security Implementation    :epic8, 2024-07-01, 2024-08-15
    Analytics & Monitoring     :epic9, 2024-07-15, 2024-09-01

Resumen de Finalización de Epics

  • Epic 1-5: ✅ Completado (100% - Infraestructura central y herramientas básicas)
  • Epic 6.1: ✅ Completado (98.3% de tasa de éxito de pruebas - Integración Profunda de Herramientas MCP)
  • Epic 6.2: 🔄 En Progreso (Optimización de Rendimiento - 75% completado)
  • Epic 7.1: 📋 Planificado (Implementación de Seguridad - Listo para implementación)
  • Epic 8: 📋 Planificado (Analítica Avanzada y Monitoreo - Diseñado)

Objetivos de Rendimiento y Métricas Actuales (v0.2.3)

MétricaObjetivoActualEstado
Tasa de Éxito de Pruebas98%+99.9%✅ Superado
Tiempo de Respuesta (Operaciones de Tareas)<200ms<150ms✅ Superado
Tiempo de Respuesta (Operaciones Síncronas)<500ms<350ms✅ Superado
Tasa de Finalización de Trabajos95%+96.7%✅ Cumplido
Uso de Memoria (Herramienta de Mapa de Código)<512MB<400MB✅ Optimizado
Cobertura de Pruebas Unitarias>70%73%✅ Cumplido
Velocidad del Pipeline CI/CD<5min~3min✅ Optimizado
Sobrecarga de Seguridad<50ms<35ms✅ Optimizado
Política de Cero Código Simulado100%100%✅ Logrado

Estado Específico por Herramienta

Vibe Task Manager

  • Estado: Listo para Producción (Funcional pero en mejora activa)
  • Cobertura de Pruebas: 99.9%
  • Características: Metodología RDD, orquestación de agentes, procesamiento de lenguaje natural, análisis de artefactos, persistencia de sesión, CLI integral
  • Rendimiento: <50ms de tiempo de respuesta para operaciones de tareas
  • Adiciones Recientes: Integración de PRD/listas de tareas, seguimiento de sesión mejorado, flujos de trabajo de orquestación

Herramienta de Mapa de Código

  • Estado: Lista para producción con funciones avanzadas
  • Optimización de memoria: Reducción de tokens del 95-97% lograda
  • Soporte de lenguajes: Más de 35 lenguajes de programación
  • Resolución de importaciones: Mejorada con arquitectura basada en adaptadores

Herramienta de Curación de Contexto

  • Estado: Lista para producción con caché inteligente de mapas de código
  • Soporte de lenguajes: Más de 35 lenguajes de programación con precisión superior al 95%
  • Pipeline de trabajo: Análisis y curación inteligente en 8 fases
  • Detección de proyectos: Independiente del lenguaje con descubrimiento de archivos multiestrategia
  • Optimización de rendimiento: Sistema de caché inteligente que reutiliza mapas de código recientes (configurable de 1 a 1440 minutos)

Herramienta de Investigación

  • Estado: Lista para producción
  • Integración: API Perplexity Sonar
  • Rendimiento: Respuesta promedio de consulta de investigación <2s

Otras Herramientas

  • Generador Fullstack: Listo para producción
  • Generadores de PRD/Historias de Usuario/Listas de Tareas: Listos para producción
  • Ejecutor de Flujos de Trabajo: Listo para producción

Ejecución Local (Opcional)

Si bien el uso principal es la integración con un asistente de IA (usando stdio), puedes ejecutar el servidor directamente para pruebas:

Modos de Ejecución

  • Modo Producción (Stdio):

    npm start
    • Los registros van a stderr (simula el lanzamiento del asistente de IA)
    • Usa NODE_ENV=production

  • Modo Desarrollo (Stdio, Registros Legibles):

    npm run dev
    • Los registros van a stdout con formato legible
    • Requiere nodemon y pino-pretty
    • Usa NODE_ENV=development

  • Modo SSE (Interfaz HTTP):

    # Production mode over HTTP
npm run start:sse

# Development mode over HTTP
npm run dev:sse
    • Usa HTTP en lugar de stdio
    • Configurado mediante PORT en .env (predeterminado: 3000)
    • Accede en http://localhost:3000

Solución de Problemas Detallada

Problemas de Conexión

Servidor MCP No Detectado en el Asistente de IA

  1. Verifica la Ruta de Configuración:

    • Verifica que la ruta absoluta en el arreglo args sea correcta
    • Asegúrate de que todas las barras sean diagonales / incluso en Windows
    • Ejecuta node <path-to-build/index.js> directamente para probar si Node puede encontrarlo

  2. Verifica el Formato de Configuración:

    • Asegúrate de que el JSON sea válido sin errores de sintaxis
    • Comprueba que las comas entre propiedades sean correctas
    • Verifica que el objeto mcpServers contenga tu servidor

  3. Reinicia el Asistente:

    • Cierra completamente (no solo minimices) la aplicación
    • Vuelve a abrir e intenta de nuevo

El Servidor Inicia Pero las Herramientas No Funcionan

  1. Verifica la Bandera de Deshabilitación:

    • Asegúrate de que "disabled": false esté configurado
    • Elimina cualquier comentario // ya que JSON no los admite

  2. Verifica el Arreglo autoApprove:

    • Comprueba que los nombres de las herramientas en el arreglo autoApprove coincidan exactamente
    • Intenta agregar "process-request" al arreglo si usas enrutamiento híbrido

Problemas con Claves de API

  1. Problemas con la Clave de OpenRouter:

    • Vuelve a verificar que la clave esté copiada correctamente
    • Verifica que la clave esté activa en tu panel de OpenRouter
    • Comprueba si tienes créditos suficientes

  2. Problemas con Variables de Entorno:

    • Verifica que la clave sea correcta en ambos:
      • El archivo .env (para ejecuciones locales)
      • El bloque de entorno de configuración de tu asistente de IA

Problemas de Ruta y Permisos

  1. Directorio de Compilación No Encontrado:

    • Ejecuta npm run build para asegurarte de que el directorio de compilación exista
    • Comprueba si la salida de compilación va a un directorio diferente (revisa tsconfig.json)

  2. Errores de Permisos de Archivo:

    • Asegúrate de que tu usuario tenga acceso de escritura al directorio workflow-agent-files
    • En sistemas Unix, verifica si build/index.js tiene permiso de ejecución

Depuración de Registros

  1. Para Ejecuciones Locales:

    • Revisa la salida de la consola para ver mensajes de error
    • Intenta ejecutar con LOG_LEVEL=debug en tu archivo .env

  2. Para Ejecuciones con Asistente de IA:

    • Configura "NODE_ENV": "production" en la configuración de entorno
    • Verifica si el asistente tiene una consola de registro o ventana de salida

Problemas Específicos de Herramientas

  1. Enrutamiento Semántico No Funciona:
    • La primera ejecución puede descargar el modelo de incrustación: verifica los mensajes de descarga
    • Intenta una solicitud más explícita que mencione el nombre de la herramienta

Documentación

Documentación Principal

  • Instrucciones del Sistema: VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md - Guía de uso completa para clientes MCP
  • Guía de CI/CD: CI_CD_GUIDE.md - Documentación de pipeline optimizada (70% más rápida)
  • Guía de Publicación en NPM: NPM_PUBLISHING_GUIDE.md - Proceso de lanzamiento e implementación
  • Arquitectura del Sistema: docs/ARCHITECTURE.md - Arquitectura integral del sistema con diagramas Mermaid
  • Rendimiento y Pruebas: docs/PERFORMANCE_AND_TESTING.md - Métricas de rendimiento, estrategias de prueba y aseguramiento de calidad
  • Vibe Task Manager: src/tools/vibe-task-manager/README.md - Documentación integral de gestión de tareas
  • Herramienta de Curación de Contexto: src/tools/curate-context/README.md - Documentación de análisis de código independiente del lenguaje
  • Herramienta de Mapa de Código: src/tools/map-codebase/README.md - Documentación avanzada de análisis de código

Documentación de Herramientas

  • READMEs de Herramientas Individuales: Cada directorio de herramientas contiene documentación detallada
  • Guías de Configuración: Configuración del entorno y gestión de configuración
  • Referencia de API: Esquemas y parámetros de herramientas documentados en las instrucciones del sistema
  • Ejemplos de Integración: Flujos de trabajo prácticos y patrones de uso

Documentación de Arquitectura

  • Arquitectura del Sistema: Diagramas Mermaid en README e instrucciones del sistema
  • Arquitectura de Herramientas: Diagramas de arquitectura de herramientas individuales
  • Métricas de Rendimiento: Estado actual y estrategias de optimización
  • Directrices de Desarrollo: Contribución y mejores prácticas de desarrollo

Contribuciones

¡Agradecemos las contribuciones! Consulta nuestras pautas de contribución y asegúrate de que todas las pruebas pasen antes de enviar solicitudes de extracción.

Flujo de Trabajo de Desarrollo

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios con pruebas integrales
  4. Asegúrate de que todas las verificaciones pasen localmente: 
    # Run CI checks (REQUIRED before PR - matches GitHub Actions)
npm run type-check    # TypeScript validation (must pass)
npm run lint          # Code quality checks (must pass)
npm run build         # Build verification (must pass)

# Run tests locally (RECOMMENDED before PR)
npm run test:unit     # Fast unit tests (~3 minutes)

# Optional: Thorough testing for major changes
npm run test:integration
npm test              # All tests
  5. Envía una solicitud de extracción con una descripción detallada

Estándares de Calidad

  • Seguridad de Tipos: NO tipos any - TypeScript estricto requerido
  • Pipeline de CI: Debe pasar verificación de tipos, lint y compilación (automatizado)
  • Pruebas: Ejecuta pruebas unitarias localmente antes de enviar la solicitud de extracción
  • Cobertura de Pruebas: Mantén >70% de cobertura para pruebas unitarias
  • Documentación: Actualiza los documentos relevantes para los cambios
  • Rendimiento: Considera el impacto en la velocidad del pipeline de CI (objetivo <5 min)

Solución de Problemas Común

Problemas con la Clave de API de OpenRouter

Problema: Las herramientas fallan con errores de autenticación

  • Solución: Verifica que tu clave de API de OpenRouter esté configurada correctamente en .env
  • Verificación: Asegúrate de que la clave no tenga espacios adicionales ni comillas
  • Comprobación: Prueba tu clave en openrouter.ai
  • Créditos: Asegúrate de tener créditos suficientes en tu cuenta de OpenRouter

Problemas de Configuración de Rutas

Problema: Errores de "Ruta no encontrada" o "Acceso denegado"

  • Solución: Usa rutas absolutas con barras diagonales (/) en todas las configuraciones
  • Windows: Convierte rutas como C:\Users\name a C:/Users/name
  • Permisos: Asegúrate de que el usuario tenga acceso de lectura/escritura a los directorios configurados
  • Variables de Entorno: Verifica que VIBE_CODER_OUTPUT_DIR y VIBE_PROJECT_ROOT estén configuradas correctamente (o las variables heredadas CODE_MAP_ALLOWED_DIR y VIBE_TASK_MANAGER_READ_DIR)

Fallos de Compilación

Problema: Errores de compilación de TypeScript

  • Solución: Ejecuta npm run clean && npm run build
  • Dependencias: Elimina node_modules y package-lock.json, luego ejecuta npm install
  • Versión de Node: Asegúrate de que Node.js v20+ esté instalado (node -v)
  • TypeScript: Verifica errores de sintaxis con npm run lint

Fallos de Pruebas

Problema: Las pruebas fallan localmente o hay errores de verificación de tipos en CI

  • Errores de Tipos: Ejecuta npm run type-check localmente para detectar problemas temprano
  • Problemas de Lint: Usa npm run lint:fix para corregir automáticamente problemas de estilo
  • Entorno: Asegúrate de que el archivo .env exista con OPENROUTER_API_KEY válido
  • Memoria: Las pruebas pueden fallar en sistemas con <4GB de RAM
  • Red: Algunas pruebas requieren conectividad a internet
  • Limpieza: Ejecuta npm run clean antes de ejecutar las pruebas
  • Pipeline de CI: Consulta la Guía de CI/CD para detalles del pipeline

Problemas de Memoria/Rendimiento

Problema: Alto uso de memoria o rendimiento lento

  • Bases de Código Grandes: La Herramienta de Mapa de Código puede consumir memoria significativa para proyectos con >10,000 archivos
  • Solución: Aumenta el límite de memoria de Node.js: NODE_OPTIONS='--max-old-space-size=4096' npm start
  • Caché: Limpia los directorios de caché en VibeCoderOutput/ si crecen demasiado
  • Monitoreo: Usa npm run test:memory para identificar fugas de memoria

Problemas de Conexión del Cliente MCP

Problema: El servidor no es detectado por el asistente de IA

  • Rutas: Verifica que todas las rutas en la configuración de MCP usen barras diagonales y sean absolutas
  • Reinicio: Cierra y reinicia completamente tu aplicación de asistente de IA
  • Registros: Revisa LOG_LEVEL=debug en la configuración para ver mensajes de error detallados
  • Transporte: Asegúrate de que "transport": "stdio" esté configurado correctamente
  • Deshabilitado: Verifica "disabled": false en tu configuración

Problemas Específicos de Herramientas

Vibe Task Manager:

  • Si los comandos en lenguaje natural fallan, intenta usar comandos estructurados
  • Revisa VibeCoderOutput/vibe-task-manager/ para archivos de proyecto
  • Asegúrate de que los nombres de proyectos no contengan caracteres especiales

Herramienta de Mapa de Código:

  • Para errores de permisos, verifica que CODE_MAP_ALLOWED_DIR esté configurado
  • Los repositorios grandes pueden agotar el tiempo de espera: intenta con subdirectorios más pequeños
  • Algunos lenguajes requieren configuración adicional (consulta el README de la herramienta)

Curador de Contexto:

  • Si la generación de mapas de código falla, revisa los mapas de código recientes en la caché
  • Verifica que haya suficiente espacio en disco para paquetes de contexto grandes
  • Revisa los permisos de archivos en los directorios de destino

Problemas de Red y Proxy

Problema: No se pueden alcanzar servicios externos

  • Proxy: Configura las variables de entorno HTTP_PROXY y HTTPS_PROXY si estás detrás de un proxy
  • SSL: Para problemas de SSL, intenta NODE_TLS_REJECT_UNAUTHORIZED=0 (solo desarrollo)
  • Firewall: Asegúrate de que el firewall permita conexiones HTTPS salientes
  • DNS: Intenta usar servidores DNS públicos si la resolución falla

Obtención de Ayuda

Si los problemas persisten:

  1. Revisa los problemas existentes en GitHub Issues
  2. Habilita el registro de depuración: LOG_LEVEL=debug
  3. Recopila mensajes de error y registros
  4. Crea un nuevo problema con:
    • Versión de Node.js (node -v)
    • Sistema operativo
    • Mensajes de error
    • Pasos para reproducir

📅 Registro de Cambios

Versión 0.3.5 (Más Reciente)

  • Matcher Híbrido Mejorado: Extracción completa de parámetros para las 15 herramientas
  • Mejoras CLI/REPL: Confirmaciones interactivas, sondeo de trabajos con progreso
  • Correcciones de Errores: El generador de listas de tareas genera automáticamente historias de usuario, conversaciones multiturno corregidas
  • Modo Estricto de TypeScript: Cero tipos any, calidad de código de nivel producción

Versión 0.3.1

  • Correcciones de sincronización de instalación global
  • Proceso de compilación limpio mejorado
  • Flujo de trabajo de empaquetado NPM mejorado

Versión 0.2.8

  • Persistencia de configuración del modo interactivo CLI
  • Detección mejorada de raíz de proyecto

Versión 0.2.7

  • Archivos de configuración faltantes agregados al paquete npm
  • Errores de carga de configuración resueltos

Versión 0.2.3

  • Modo REPL interactivo con interfaz de chat
  • Asistente de configuración mejorado con autodetección
  • Plantillas de configuración
  • Binario CLI unificado

Para el historial completo de versiones, consulta GitHub Releases

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para más detalles.