Vibe Coder MCP

Servidor MCP de Vibe Coder

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 potentes herramientas para el desarrollo de software. Te ayuda con la investigación, la planificación, la generación de requisitos, la creación de proyectos iniciales y mucho más.

Descripción general y características

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

• Enrutamiento de solicitudes semánticas : enruta de forma inteligente las solicitudes mediante correspondencia semántica basada en incrustación con alternativas de pensamiento secuencial.
• Arquitectura de registro de herramientas : gestión centralizada de herramientas con herramientas de registro automático.
• Llamadas LLM directas : las herramientas del generador ahora utilizan llamadas LLM directas para lograr una confiabilidad mejorada y un control de salida estructurado.
• Ejecución de flujo de trabajo : ejecuta secuencias predefinidas de llamadas de herramientas definidas en workflows.json .
• Investigación y planificación : realiza investigaciones profundas ( research-manager ) y genera documentos de planificación como PRD ( generate-prd ), historias de usuario ( generate-user-stories ), listas de tareas ( generate-task-list ) y reglas de desarrollo ( generate-rules ).
• Andamiaje de proyectos : genera kits de inicio completos ( generate-fullstack-starter-kit ).
• Generador de mapas de código : escanea recursivamente una base de código, extrae información semántica y genera un índice Markdown denso en contexto y eficiente en tokens con diagramas de sirena o una representación JSON estructurada con rutas de archivo absolutas para importaciones e información de propiedades de clase mejorada ( map-codebase ).
• Ejecución asíncrona : Muchas herramientas de larga duración (generadores, investigación, flujos de trabajo) ahora se ejecutan asíncronamente. Devuelven un ID de trabajo inmediatamente y el resultado final se recupera mediante la herramienta get-job-result .
• Gestión del estado de la sesión : mantiene el estado básico en todas las solicitudes dentro de una sesión (en memoria).
• Manejo de errores estandarizado : patrones de error consistentes en todas las herramientas.

(Consulte las secciones "Documentación detallada de la herramienta" y "Detalles de las funciones" a continuación para obtener más información)

Guía de configuración

Siga estos micropasos para poner en funcionamiento el servidor Vibe Coder MCP y conectarlo a su asistente de inteligencia artificial.

Paso 1: Requisitos previos

1. Comprobar la versión de Node.js:
   • Abra una terminal o un símbolo del sistema.
   • Ejecutar node -v
   • Asegúrese de que la salida muestre v18.0.0 o superior (obligatorio).
   • Si no está instalado o está desactualizado: Descárguelo desde nodejs.org .
2. Comprobar la instalación de Git:
   • Abra una terminal o un símbolo del sistema.
   • Ejecutar git --version
   • Si no está instalado: descargar desde git-scm.com .
3. Obtener la clave API de OpenRouter:
   • Visita openrouter.ai
   • Crea una cuenta si no tienes una.
   • Vaya a la sección Claves API.
   • Crea una nueva clave API y cópiala.
   • Mantenga esta clave a mano para el paso 4.

Paso 2: Obtener el código

1. Crear un directorio de proyecto (opcional):
   • Abra una terminal o un símbolo del sistema.
   • Navegue hasta donde desea almacenar el proyecto:
     cd ~/Documents # Example: Change to your preferred location
2. Clonar el repositorio:
   • Correr:
     git clone https://github.com/freshtechbro/vibe-coder-mcp.git
     (O utilice la URL de su bifurcación si corresponde)
3. Navegar al directorio del proyecto:
   • Correr:
     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 se complete el script (instalará las dependencias, compilará el proyecto y creará los directorios necesarios).
3. Si ve algún mensaje de error, consulte la sección Solución de problemas a continuación.

Para macOS o Linux:

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

El script realiza estas acciones:

• Comprueba la versión de Node.js (v18+)
• Instala todas las dependencias a través de npm
• Crea los subdirectorios VibeCoderOutput/ necesarios (como se define en el script).
• Construye el proyecto TypeScript.
• Copia .env.example a .env si .env no existe. Deberá editar este archivo.
• Establece permisos ejecutables (en sistemas Unix).

Paso 4: Configurar variables de entorno ( .env )

El script de instalación (del paso 3) crea automáticamente un archivo .env en el directorio raíz del proyecto copiando la plantilla .env.example , solo si .env no existe ya .

1. Localice y abra .env : busque el archivo .env en el directorio principal vibe-coder-mcp y ábralo con un editor de texto.
2. Agregue su clave API de OpenRouter (obligatoria):
   • El archivo contiene una plantilla basada en .env.example :
     # OpenRouter Configuration ## Specifies your unique API key for accessing OpenRouter services. ## Replace "Your OPENROUTER_API_KEY here" with your actual key obtained from OpenRouter.ai. OPENROUTER_API_KEY="Your OPENROUTER_API_KEY here" ## Defines the base URL for the OpenRouter API endpoints. ## The default value is usually correct and should not need changing unless instructed otherwise. OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 ## Sets the specific Gemini model to be used via OpenRouter for certain AI tasks. ## ':free' indicates potential usage of a free tier model if available and supported by your key. GEMINI_MODEL=google/gemini-2.0-flash-thinking-exp:free
   • Es fundamental reemplazar "Your OPENROUTER_API_KEY here" por su clave API de OpenRouter. Elimine las comillas si su clave no las requiere.
3. Configurar 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 la ruta absoluta que prefiera. Use barras diagonales ( / ) para las rutas. Si esta variable no está configurada, se usará el directorio predeterminado ( VibeCoderOutput/ ).
4. Configurar el directorio del generador de mapas de código (opcional):
   • Para especificar qué directorio puede escanear la herramienta generadora de mapas de código, agregue esta línea a su archivo .env :
     CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory
   • Reemplace la ruta con la ruta absoluta al directorio que contiene el código fuente que desea analizar. Esto es un límite de seguridad: la herramienta no accederá a archivos fuera de este directorio.
   • Tenga en cuenta que CODE_MAP_ALLOWED_DIR (para leer el código fuente) y VIBE_CODER_OUTPUT_DIR (para escribir los archivos de salida) son independientes por razones de seguridad. La herramienta generadora de mapas de código utiliza una validación independiente para las operaciones de lectura y escritura.
5. Revisar 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 ).
6. Guarde el archivo .env .

Paso 5: Integración con su asistente de IA (Configuración de MCP)

Este paso crucial conecta Vibe Coder con 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 tu 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 el 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)
• Escritorio de Claude:
  • Ventanas : %APPDATA%\Claude\claude_desktop_config.json
  • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux : ~/.config/Claude/claude_desktop_config.json

5.2: Agregar la configuración de Vibe Coder

1. Abra el archivo de configuración identificado anteriormente en un editor de texto.
2. Busque el objeto JSON "mcpServers": { ... } . Si no existe, puede que tenga que crearlo (asegúrese de que el archivo general siga siendo un 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 , 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", // Directory that the code-map-generator tool is allowed to scan // This is a security boundary - the tool will not access files outside this directory "CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src" }, // 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", "generate-rules", "generate-user-stories", "generate-task-list", "generate-prd", "generate-fullstack-starter-kit", "refactor-code", "git-summary", "run-workflow", "map-codebase" ] }
4. CRUCIAL: Reemplace todas las rutas de marcador de posición (como /path/to/your/vibe-coder-mcp/... ) con las rutas absolutas correctas en el sistema donde clonó el repositorio. Use barras diagonales / para las rutas, incluso en Windows (p. ej., C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js ). Las rutas incorrectas son la causa más común de que el servidor no se conecte.
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.
   • En caso contrario, consulte la sección Solución de problemas a continuación.

Arquitectura del proyecto

El servidor Vibe Coder MCP sigue una arquitectura modular centrada en un patrón de registro de herramientas:

Estructura del directorio

Patrón de registro de herramientas

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

Proceso de pensamiento secuencial

El mecanismo de pensamiento secuencial proporciona una ruta de respaldo basada en LLM:

Gestión del estado de la sesión

Motor de ejecución de flujo de trabajo

El sistema Workflow permite secuencias de varios pasos:

Configuración del flujo 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 se pueden ejecutar con un solo comando.

Ubicación y estructura de los archivos

• El archivo workflows.json debe ubicarse 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 paso del flujo de trabajo admiten cadenas de plantilla que pueden hacer referencia a:

• Entradas de flujo de trabajo: {workflow.input.paramName}
• Resultados del paso anterior: {steps.stepId.output.content[0].text}

Activación de flujos de trabajo

Utilice la herramienta run-workflow con:

Documentación detallada de la herramienta

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

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

Consulte estos archivos README individuales para obtener información detallada:

• src/tools/fullstack-starter-kit-generator/README.md
• src/tools/prd-generator/README.md
• src/tools/research-manager/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/code-map-generator/README.md

Categorías de herramientas

Herramientas de análisis e información

• Generador de mapas 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 por humanos con diagramas de Mermaid o una representación JSON estructurada con rutas de archivos absolutas para importaciones e información de propiedades de clase mejorada.
• Gerente de investigación ( research-manager ) : 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 ( generate-rules ): crea reglas y pautas de desarrollo específicas del proyecto.
• Generador de PRD ( generate-prd ): genera documentos completos de requisitos del producto.
• Generador de historias de usuario ( generate-user-stories ): crea historias de usuario detalladas con criterios de aceptación.
• Generador de listas de tareas ( generate-task-list ): crea listas de tareas de desarrollo estructuradas con dependencias.

Herramienta de andamiaje de proyectos

• Generador de kits de inicio fullstack ( generate-fullstack-starter-kit ): crea kits de inicio de proyectos personalizados con tecnologías frontend/backend específicas, incluidos scripts de configuración y configuración básicos.

Flujo de trabajo y orquestación

• Ejecutor de flujo de trabajo ( run-workflow ): ejecuta secuencias predefinidas de llamadas de herramientas para tareas de desarrollo comunes.

Almacenamiento de archivos generados

De forma predeterminada, los resultados de las herramientas del generador se almacenan como referencia histórica en el directorio VibeCoderOutput/ del proyecto. Esta ubicación se puede sobrescribir configurando la variable de entorno VIBE_CODER_OUTPUT_DIR en el 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 Vibe Coder MCP mantienen límites de seguridad separados para las operaciones de lectura y escritura:

• Operaciones de lectura : Herramientas como el generador de mapas de código solo leen de directorios autorizados explícitamente mediante la variable de entorno CODE_MAP_ALLOWED_DIR . Esto crea un límite de seguridad claro y evita el acceso no autorizado a archivos fuera del directorio permitido.
• 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 las ubicaciones de salida designadas, protegiendo así el código fuente de modificaciones accidentales.

Estructura de ejemplo (ubicación predeterminada):

Ejemplos de uso

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" }
• Base de código del mapa: 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"

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 realizar pruebas:

Modos de ejecución

• Modo de producción (Stdio):
  npm start
  • Los registros van a stderr (imita el inicio del asistente de IA)
  • Utilice NODE_ENV=producción
• Modo de desarrollo (Stdio, Pretty Logs):
  npm run dev
  • Los registros van a la salida estándar con un formato atractivo
  • Requiere nodemon y pino-pretty
  • Utilice NODE_ENV=desarrollo
• Modo SSE (interfaz HTTP):
  # Production mode over HTTP npm run start:sse # Development mode over HTTP npm run dev:sse
  • Utiliza HTTP en lugar de stdio
  • Configurado a través de PORT en .env (predeterminado: 3000)
  • Acceso en http://localhost:3000

Solución de problemas detallada

Problemas de conexión

El servidor MCP no se detecta en el Asistente de IA

1. Comprobar ruta de configuración:
   • Verifique que la ruta absoluta en la matriz args sea correcta
   • Asegúrese de que todas las barras sean barras diagonales / pares en Windows
   • Ejecute node <path-to-build/index.js> directamente para probar si Node puede encontrarlo
2. Formato de configuración de verificación:
   • Asegúrese de que JSON sea válido sin errores de sintaxis
   • Compruebe que las comas entre propiedades sean correctas
   • Verifique que el objeto mcpServers contenga su servidor
3. Reiniciar el Asistente:
   • Cerrar completamente (no solo minimizar) la aplicación
   • Vuelva a abrir e intente nuevamente

El servidor se inicia pero las herramientas no funcionan

1. Marcar la bandera deshabilitada:
   • Asegúrese de que "disabled": false esté configurado
   • Elimine cualquier comentario // ya que JSON no los admite
2. Verificar la matriz de aprobación automática:
   • Compruebe que los nombres de las herramientas en la matriz autoApprove coincidan exactamente
   • Intente agregar "process-request" a la matriz si usa enrutamiento híbrido

Problemas con la clave API

1. Problemas clave de OpenRouter:
   • Verifique nuevamente que la clave esté copiada correctamente
   • Verifique que la clave esté activa en su panel de control de OpenRouter
   • Comprueba si tienes suficientes créditos
2. Problemas de variables ambientales:
   • Verifique que la clave sea correcta en ambos:
     • El archivo .env (para ejecuciones locales)
     • Bloque de configuración env de su asistente de IA

Problemas de ruta y permisos

1. Directorio de compilación no encontrado:
   • Ejecute npm run build para asegurarse de que exista el directorio de compilación
   • Verifique si la salida de la compilación va a un directorio diferente (verifique tsconfig.json)
2. Errores de permisos de archivos:
   • Asegúrese de que su usuario tenga acceso de escritura al directorio workflow-agent-files
   • En sistemas Unix, verifique si build/index.js tiene permiso de ejecución

Depuración de registros

1. Para carreras locales:
   • Verifique la salida de la consola para ver si hay mensajes de error
   • Intente ejecutar con LOG_LEVEL=debug en su archivo .env
2. Para ejecuciones del Asistente de IA:
   • Establezca "NODE_ENV": "production" en la configuración del entorno
   • Compruebe si el asistente tiene una consola de registro o una ventana de salida

Problemas específicos de las herramientas

1. El enrutamiento semántico no funciona:
   • La primera ejecución puede descargar el modelo de incrustación: verifique los mensajes de descarga
   • Pruebe una solicitud más explícita que mencione el nombre de la herramienta