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:

HU cargada	Archivo generado
HU-016 Conexión WhatsApp	HU-016-conexion-whatsapp-SPEC.md
HU-023 Gestión de Pedidos	HU-023-gestion-de-pedidos-SPEC.md
US-005 Login con Google	US-005-login-con-google-SPEC.md

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

Formato	Extensión	Cómo entregarlo
Word	.docx	Ruta absoluta al archivo
PDF	.pdf	Ruta absoluta al archivo
Markdown	.md	Ruta absoluta al archivo
Texto plano	.txt	Ruta absoluta al archivo

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/.

Parámetro	Requerido	Descripción
file_path	Uno de los dos	Ruta absoluta a un archivo .docx, .pdf, .md o .txt
user_story_text	Uno de los dos	Texto plano del documento de HU
hu_name	No	Nombre de la HU para el archivo (ej. HU-016-whatsapp). Si se omite, se extrae automáticamente
feature_slug	No	Slug del nombre de la carpeta (ej. pagos-online). Si se omite, se usa el mismo que hu_name
spec_number	No	Número de 3 dígitos (ej. 007). Si se omite, usa el siguiente disponible

Usa file_path o user_story_text, no ambos.

Formatos de archivo soportados:

Formato	Extensión
Word	.docx
PDF	.pdf
Markdown	.md
Texto plano	.txt

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.

Parámetro	Requerido	Descripción
folder	Sí	Nombre de la carpeta (ej. 004-whatsapp)

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