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 .
• Generación de código : crea fragmentos de código y código repetitivo ( generate-code-stub ).
• Refactorización de código : mejora y modifica fragmentos de código existentes ( refactor-code ).
• Análisis de dependencia : enumera las dependencias de los archivos de manifiesto ( analyze-dependencies ).
• Integración de Git : resume los cambios actuales de Git ( git-summary ).
• 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 ).
• 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 directorios de archivos de agente de flujo de trabajo necesarios
• Construye el proyecto TypeScript
• Crea un archivo .env predeterminado si no existe ninguno (lo completarás a continuación).
• Establece permisos ejecutables (en sistemas Unix)

Paso 4: Configurar variables de entorno ( .env )

1. Localice el archivo .env :
   • Busque el archivo .env creado por el script de instalación en el directorio principal vibe-coder-mcp .
   • Ábrelo con cualquier editor de texto.
2. Agregue su clave API de OpenRouter:
   • Encuentre la línea: OPENROUTER_API_KEY=your_openrouter_api_key_here
   • Reemplace your_openrouter_api_key_here con su clave API de OpenRouter real.
   • No agregue comillas alrededor de la clave.
3. Configurar directorio de salida (opcional):
   • Para cambiar dónde se guardan los archivos generados (el valor predeterminado es workflow-agent-files/ dentro del proyecto), agregue esta línea:
     VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
   • Reemplace la ruta con la ruta absoluta que prefiera. Use barras diagonales ( / ). Si esta variable no está configurada, se usará el directorio predeterminado.
4. Revisar otras configuraciones (opcional):
   • Revise los nombres de los modelos ( GEMINI_MODEL , PERPLEXITY_MODEL ) para asegurarse de que estén disponibles en su plan de OpenRouter. El archivo llm_config.json proporciona un control más detallado por tarea, si es necesario.
   • Verifique LOG_LEVEL (predeterminado: información): las opciones incluyen: 'fatal', 'error', 'advertencia', 'información', 'depuración', 'rastreo'.
5. Guarde el archivo .env .

Paso 5: Integración con su asistente de IA

Este paso crucial conecta Vibe Coder con tu asistente de IA. Cada entorno requiere una configuración ligeramente diferente.

5.1: Encuentra la ruta absoluta de tu proyecto

Necesita la ruta completa y absoluta al archivo build/index.js :

Para Windows:

1. En su terminal, navegue hasta el directorio de compilación:
   cd build
2. Obtener la ruta absoluta:
   echo %cd%\index.js
3. Copiar la salida (por ejemplo, C:\Users\YourName\Projects\vibe-coder-mcp\build\index.js )

Para macOS/Linux:

1. En su terminal, navegue hasta el directorio de compilación:
   cd build
2. Obtener la ruta absoluta:
   pwd
3. Agregue /index.js a la salida y copie el resultado (por ejemplo, /Users/YourName/Projects/vibe-coder-mcp/build/index.js )

5.2: Preparar el bloque de configuración

Cree un bloque de configuración mediante:

1. Copia esta plantilla JSON:
   "vibe-coder-mcp": { "command": "node", "args": ["PATH_PLACEHOLDER"], "env": { "NODE_ENV": "production" // API Keys and other sensitive config are now loaded via the .env file // You can optionally set VIBE_CODER_OUTPUT_DIR here if you prefer it over .env // "VIBE_CODER_OUTPUT_DIR": "/absolute/path/to/output" }, "disabled": false, "autoApprove": [ "research", "generate-rules", "generate-prd", "generate-user-stories", "generate-task-list", "generate-fullstack-starter-kit", "generate-code-stub", "refactor-code", "analyze-dependencies", "git-summary", "run-workflow" ] }
2. Reemplace PATH_PLACEHOLDER con la ruta absoluta que obtuvo en el Paso 5.1.
   • Importante: utilice barras diagonales / incluso en Windows (por ejemplo, C:/Users/... )
3. Importante: Ya no incluya su OPENROUTER_API_KEY directamente en este bloque de configuración. Solo debe estar en su archivo .env .

5.3: Configura tu asistente de IA específico

A. Cursor AI / Windsurf (basado en VS Code)

1. Abra la aplicación Cursor o Windsurf.
2. Abrir paleta de comandos:
   • Windows/Linux: Presione Ctrl+Shift+P
   • macOS: Presione Cmd+Shift+P
3. Escriba y seleccione: Preferences: Open User Settings (JSON)
4. En el archivo JSON, busque o agregue el objeto mcpServers :
   • Si no existe, agréguelo: "mcpServers": {}
   • Si existe, localice la llave de cierre de este objeto
5. Agregue su bloque de configuración dentro del objeto mcpServers :
   • Si se enumeran otros servidores, agregue una coma después del último.
   • Pegue el bloque de configuración del paso 5.2
6. Guardar el archivo ( Ctrl+S o Cmd+S )
7. Cierre completamente y reinicie Cursor/Windsurf

Ejemplo de una sección settings.json completa:

B. Cline AI (extensión de VS Code)

1. Localice el archivo de configuración de Cline:
   • Windows : C:\Users\[YourUsername]\AppData\Roaming\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
2. Abra este archivo con un editor de texto.
3. Busque o agregue el objeto mcpServers :
   • Si el archivo está vacío, agregue: {"mcpServers": {}}
   • Si existe pero no tiene mcpServers , agréguelo al nivel raíz
4. Agregue su bloque de configuración dentro del objeto mcpServers :
   • Si se enumeran otros servidores, agregue una coma después del último.
   • Pegue el bloque de configuración del paso 5.2
5. Guarde el archivo.
6. Reinicie VS Code por completo.

C. RooCode (bifurcación de VS Code)

1. Abrir RooCode.
2. Abra la paleta de comandos ( Ctrl+Shift+P o Cmd+Shift+P ).
3. Busque y seleccione Preferences: Open User Settings (JSON) .
4. Siga los mismos pasos que para Cursor AI (sección A anterior).
5. Guarde y reinicie RooCode.

Escritorio de D. Claude

1. Localice el archivo de configuración de Claude Desktop:
   • Windows : C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json
   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux : ~/.config/Claude/claude_desktop_config.json
2. Abra este archivo con un editor de texto.
3. Busque o agregue el objeto mcpServers en el nivel raíz:
   • Si el archivo tiene otro contenido, busque dónde agregar mcpServers
   • Si ya tiene mcpServers , localícelo
4. Agregue su bloque de configuración dentro del objeto mcpServers :
   • Si existen otros servidores, agregue una coma después del último.
   • Pegue el bloque de configuración del paso 5.2
5. Guarde el archivo.
6. Cierre y vuelva a abrir Claude Desktop.

Ejemplo de un claude_desktop_config.json completo:

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

Sistema de enrutamiento semántico

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

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/code-refactor-generator/README.md
• src/tools/code-stub-generator/README.md
• src/tools/dependency-analyzer/README.md
• src/tools/fullstack-starter-kit-generator/README.md
• src/tools/git-summary-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

Categorías de herramientas

Herramientas de generación y refactorización de código

• Generador de código auxiliar ( generate-code-stub ) : Crea código repetitivo (funciones, clases, etc.) basado en una descripción y un lenguaje de destino. Útil para el desarrollo rápido de nuevos componentes.
• Generador de refactorización de código ( refactor-code ) : toma un fragmento de código existente e instrucciones de refactorización (por ejemplo, "convertir a async/await", "mejorar la legibilidad", "agregar manejo de errores") y devuelve el código modificado.

Herramientas de análisis e información

• Analizador de dependencias ( analyze-dependencies ) : analiza archivos de manifiesto como package.json o requirements.txt para enumerar las dependencias del proyecto.
• Generador de resúmenes de Git ( git-summary ) : Proporciona un resumen del estado actual de Git, mostrando los cambios preparados o no preparados (diff). Útil para comprobaciones rápidas antes de confirmar.
• 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.

Estructura de ejemplo (ubicación predeterminada):

Ejemplos de uso

Interactúa con las herramientas a través de tu 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
• Generar código auxiliar: Generate a python function stub named 'calculate_discount' that takes price and percentage
• Código de refactorización: Refactor this code to use async/await: [paste code snippet]
• Analizar dependencias: Analyze dependencies in package.json
• Resumen de Git: Show unstaged git changes
• Ejecutar flujo de trabajo: Run workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }

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
2. **Herramienta de resumen de Git