GenSpec MCP Server

Convierte un archivo USER-STORIES.md en documentos README, ROADMAP y SYSTEM-ARCHITECTURE para el flujo de trabajo de GenSpec.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP GenSpec

Un servidor de Model Context Protocol (MCP) que convierte historias de usuario en documentación estructurada, incluyendo documentos README, ROADMAP y SYSTEM-ARCHITECTURE mediante un flujo de trabajo guiado con aprobaciones.

Descripción general

El servidor MCP GenSpec optimiza el proceso de creación de documentación al tomar historias de usuario como entrada y generar tres artefactos de documentación clave:

  • README.md - Descripción general del proyecto e instrucciones de configuración
  • ROADMAP.md - Hoja de ruta de desarrollo e hitos
  • SYSTEM-ARCHITECTURE.md - Documentación de la arquitectura técnica

El servidor utiliza un flujo de trabajo continuo donde cada fase puede ser aprobada o editada antes de pasar a la siguiente fase, garantizando una salida de documentación de alta calidad.

Características

  • Integración MCP - Funciona perfectamente con Claude Desktop, VS Code con la extensión MCP y Cursor
  • Generación basada en plantillas - Utiliza plantillas predefinidas para una estructura de documentación consistente
  • Flujo de aprobación - Ciclo de Generar → Presentar → Aprobar/Editar para cada documento
  • Dependencias entre fases - ROADMAP requiere README, SYSTEM-ARCHITECTURE requiere ambos
  • Múltiples puntos de entrada - Comience desde cualquier fase o ejecute el flujo de trabajo completo
  • Acceso a recursos - Expone plantillas mediante el protocolo de recursos MCP

Instalación

Requisitos previos

  • Node.js 18.0.0 o superior
  • Administrador de paquetes npm o yarn

Instalar desde npm

npm install -g genspec-mcp

Instalar desde el código fuente

git clone <repository-url>
cd genspec-mcp
npm install
npm run build

Integración con clientes MCP

Claude Desktop

Agregue a su archivo de configuración de Claude Desktop:

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

{
  "mcpServers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

VS Code con la extensión MCP

  1. Instale la extensión MCP para VS Code
  2. Agregue a la configuración de VS Code o a la configuración MCP:
{
  "mcp.servers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

Cursor

Agregue a su configuración MCP de Cursor:

{
  "mcpServers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

Uso

El servidor MCP GenSpec proporciona varias formas de iniciar el flujo de trabajo de generación de documentación:

Herramientas disponibles

  • start_genspec - Ejecutar el flujo de trabajo completo: README → ROADMAP → SYSTEM-ARCHITECTURE
  • generate_readme - Generar README, luego continuar con ROADMAP → SYSTEM-ARCHITECTURE
  • generate_roadmap - Generar ROADMAP, luego continuar con SYSTEM-ARCHITECTURE
  • generate_architecture - Generar solo SYSTEM-ARCHITECTURE

Prompts disponibles

  • /start-genspec - Invoca la herramienta start_genspec
  • /start-readme - Invoca la herramienta generate_readme
  • /start-roadmap - Invoca la herramienta generate_roadmap
  • /start-arch - Invoca la herramienta generate_architecture

Métodos de entrada

El servidor acepta historias de usuario en tres órdenes de prioridad:

  1. Texto en línea - Pase historias de usuario directamente como parámetro userStory
  2. Referencia URI - Proporcione userStoryUri para que el cliente lo obtenga mediante MCP ReadResource
  3. Archivo local - Recurre a USER-STORIES.md en el directorio actual

Ejemplo de flujo de trabajo

  1. Iniciar el flujo de trabajo:

    Use the /start-genspec prompt or start_genspec tool

  2. Revisar y aprobar/editar:

    • El documento generado se presenta para revisión
    • Responda con términos de aprobación: "approve", "approved", "ok", "okay", "yes", "y", "lgtm"
    • O proporcione comentarios de edición para regenerar

  3. Continuar a través de las fases:

    • Después de la aprobación, el flujo de trabajo continúa a la siguiente fase
    • Cada fase sigue el mismo ciclo de generar → presentar → aprobar/editar

Estructura de archivos

genspec-mcp/
├── dist/                   # Compiled JavaScript files
├── src/                    # TypeScript source files
│   ├── index.ts           # MCP server entry point
│   ├── server.ts          # GenSpecServer implementation
│   ├── types.ts           # Type definitions and constants
│   └── utils/             # Utility modules (Track B, C, D)
├── templates/              # Generation templates
│   ├── 1-generate-readme.md
│   ├── 2-generate-roadmap.md
│   └── 3-generate-system-architecture.md
├── _ai/docs/              # Generated documentation output
├── package.json           # Package configuration
├── tsconfig.json          # TypeScript configuration
└── README.md              # This file

Salida generada

Todos los documentos generados se guardan en el directorio _ai/docs/:

  • _ai/docs/README.md - README del proyecto generado
  • _ai/docs/ROADMAP.md - Hoja de ruta de desarrollo generada
  • _ai/docs/SYSTEM-ARCHITECTURE.md - Arquitectura del sistema generada

Desarrollo

Compilación

npm run build

Modo de desarrollo

npm run dev

Ejecutar pruebas

npm test

Solución de problemas

Problemas comunes

Problema: El servidor MCP no es detectado por el cliente

  • Solución: Asegúrese de que el servidor esté instalado correctamente y que la sintaxis del archivo de configuración sea correcta
  • Verificación: Reinicie su cliente MCP después de los cambios de configuración

Problema: Error "ERR_MISSING_USER_STORIES"

  • Solución: Proporcione historias de usuario mediante uno de los tres métodos compatibles (en línea, URI o archivo local)
  • Verificación: Asegúrese de que USER-STORIES.md exista si utiliza el método de archivo local

Problema: Error "ERR_MISSING_PREREQUISITES"

  • Solución: Genere primero las fases de requisitos previos (README antes de ROADMAP, README y ROADMAP antes de SYSTEM-ARCHITECTURE)
  • Verificación: Utilice herramientas de flujo de trabajo continuo que incluyan los requisitos previos

Problema: Las plantillas no se cargan

  • Solución: Verifique que el directorio templates/ exista y contenga los archivos de plantilla requeridos
  • Verificación: Asegúrese de que el paquete se haya instalado correctamente con todos los archivos

Problema: Errores de permisos al escribir en _ai/docs/

  • Solución: Asegúrese de que el directorio actual sea escribible y que el directorio _ai/docs/ pueda crearse
  • Verificación: Ejecute desde un directorio donde tenga permisos de escritura

Depuración

Habilite el registro de depuración configurando la variable de entorno DEBUG:

DEBUG=genspec:* npx genspec-mcp

Obtener ayuda

  • Consulte la especificación MCP para detalles del protocolo
  • Revise los archivos de plantilla en el directorio templates/ para la lógica de generación
  • Reporte problemas o solicitudes de funciones en el repositorio del proyecto

Requisitos del sistema

  • Node.js: 18.0.0 o superior
  • Memoria: Mínimo 512MB de RAM disponible
  • Espacio en disco: 50MB para la instalación y archivos generados
  • Red: Conexión a Internet para la instalación de npm

Dependencias

Dependencias de producción

  • @modelcontextprotocol/sdk - Implementación del protocolo MCP
  • typescript - Compilador y entorno de ejecución de TypeScript
  • tsx - Motor de ejecución de TypeScript

Dependencias de desarrollo

  • @types/node - Definiciones de tipos de Node.js

Arquitectura

El servidor MCP GenSpec sigue una arquitectura modular con cinco pistas principales:

Componentes principales

  • GenSpecServer (src/server.ts) - Implementación principal del servidor MCP
  • Sistema de tipos (src/types.ts) - Definiciones de tipos y constantes
  • Sistema de plantillas (src/utils/templates.ts) - Carga y gestión de plantillas
  • Generación de documentos (src/utils/llm.ts) - Interfaz de generación y construcción de contexto
  • Sistema de validación (src/utils/validation.ts) - Validación de entrada y verificación de requisitos previos
  • Sistema de aprobación (src/utils/approval.ts) - Detección de aprobaciones y comentarios de edición
  • Gestión de fases (src/utils/phases.ts) - Ejecución y coordinación del flujo de trabajo

Soporte del protocolo MCP

  • Prompts - Prompts de estilo comando que invocan herramientas
  • Recursos - Acceso a plantillas mediante el esquema URI template://
  • Herramientas - Herramientas del flujo de trabajo de generación de documentos

Gestión del flujo de trabajo

  • Dependencias entre fases - Garantiza el orden correcto de generación
  • Lógica de continuación - Transiciones fluidas entre fases
  • Concurrencia de flujo único - Evita flujos de trabajo conflictivos por espacio de trabajo
  • Ciclos de aprobación - Hasta 5 ciclos de edición por fase antes de abortar

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.