MCP Spec Generator

Servidor MCP que convierte documentos de Historias de Usuario a archivos .md con el formato SPEC_KIT_TEMPLATE del workspace de alfred-egit.

¿Para qué sirve?

Automatiza el proceso de documentación técnica: tomas cualquier texto con Historias de Usuario (HUs) — ya sea copiado de Notion, un Google Doc, un correo, un PDF o escrito a mano — y el servidor lo transforma en un archivo spec.md estructurado y listo para el equipo de desarrollo.

El archivo generado sigue el formato estándar del proyecto:

workspace/specs/007-nombre-feature/
├── HU-023-nombre-feature-SPEC.md   ← documento generado
└── tasks/
    └── tasks.md                    ← placeholder de tareas

El nombre del archivo toma el identificador de la HU directamente del documento cargado y le agrega el sufijo -SPEC.md. Por ejemplo:

Related MCP server: wassden

Requisitos

• Node.js 22+

• Claude Code CLI

• ANTHROPIC_API_KEY en tu entorno

Instalación

cd ~/mcp-spec-generator
npm install

El servidor ya está registrado en ~/.claude/settings.json. Se activa automáticamente al iniciar Claude Code.

Inputs soportados

El MCP acepta documentos de HU en cualquiera de estas formas:

Archivos

Ejemplo en Claude Code:

"Genera la spec desde este archivo: /Users/openclaw/Desktop/HU-023-pedidos.docx"

Texto directo

Pega el contenido del documento directamente en el chat. Funciona con texto copiado desde:

• Notion

• Google Docs

• Confluence

• Correo electrónico

• Cualquier fuente de texto

Ejemplo en Claude Code:

"Convierte esta HU en spec: [pegar texto aquí]"

Herramientas disponibles

generate_spec

Convierte un documento de Historia de Usuario en un {HU-name}-SPEC.md y lo guarda en workspace/specs/.

Usa file_path o user_story_text, no ambos.

Formatos de archivo soportados:

Prioridad para el nombre del archivo de salida:

1. Valor explícito de hu_name

2. Identificador extraído del texto (HU-XXX, US-XXX)

3. Título del documento generado por Claude como fallback

Ejemplos de uso en Claude Code:

"Genera la spec desde este archivo: /Desktop/HU-023-pedidos.docx"

"Convierte esta Historia de Usuario en una spec: [pegar texto]"

Claude llamará generate_spec automáticamente y guardará el archivo.

list_specs

Lista todas las specs existentes en workspace/specs/ con su estado.

Ejemplo:

- 001-api-gateway (spec.md: ✅)
- 004-whatsapp (spec.md: ✅)
- 007-pagos-online (spec.md: ✅)

get_spec_template

Devuelve el contenido del SPEC_KIT_TEMPLATE vigente. Útil para consultar la estructura sin abrir archivos.

read_spec

Lee el contenido de una spec existente.

Formato de salida (SPEC_KIT_TEMPLATE)

Cada spec generada incluye estas secciones:

1. Contexto de Negocio — problema u oportunidad que motiva el requerimiento

2. Actores del Sistema — usuarios, sistemas y servicios involucrados

3. Flujos Principales — pasos del proceso con diagramas cuando aplica

4. Integraciones — APIs y sistemas externos

5. Criterios de Aceptación — checklist con - [ ] para cada condición

6. Estimación de Complejidad — Baja / Media / Alta con justificación

7. Observaciones Adicionales — notas, restricciones y aclaraciones

Configuración

El servidor lee la variable de entorno SPECS_DIR para saber dónde guardar las specs:

// ~/.claude/settings.json
{
  "mcpServers": {
    "spec-generator": {
      "command": "node",
      "args": ["/Users/openclaw/mcp-spec-generator/index.js"],
      "env": {
        "SPECS_DIR": "/Users/openclaw/alfred-egit/workspace/specs"
      }
    }
  }
}

Para apuntar a otro workspace, cambia SPECS_DIR en ese archivo.

Flujo típico de trabajo

1. Product Owner entrega documento de HUs
   (.docx / .pdf / texto en Notion / correo / etc.)
         ↓
2. En Claude Code, según el formato:

   Archivo:      "Genera la spec desde: /Desktop/HU-023.docx"
   Texto directo: "Convierte esta HU en spec: [pegar texto]"
         ↓
3. El MCP extrae el texto del documento (si es archivo)
   y llama a Claude API para estructurar el contenido
         ↓
4. Se crea: workspace/specs/NNN-feature/HU-023-SPEC.md
           workspace/specs/NNN-feature/tasks/tasks.md
         ↓
5. Revisar, ajustar y aprobar en equipo
         ↓
6. Completar tasks/tasks.md con tareas de implementación