# 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:

| 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

```bash
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:

```json
// ~/.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
```