# Satrack Documentation Generator MCP

MCP (Model Context Protocol) server para generación automática de documentación técnica de proyectos Satrack.

## 🏗️ Arquitectura

Este proyecto está construido siguiendo **Clean Architecture** y aplicando los principios **SOLID**:

```
src/
├── domain/                     # Capa de Dominio (Entidades y Reglas de Negocio)
│   ├── entities/              # Entidades del dominio
│   │   ├── Entity.ts          # Clase base para entidades
│   │   ├── Component.ts       # Entidad de componente
│   │   └── Documentation.ts   # Entidad de documentación
│   ├── value-objects/         # Objetos de valor inmutables
│   │   ├── ValueObject.ts     # Clase base para value objects
│   │   ├── ComponentType.ts   # Tipo de componente
│   │   └── FilePath.ts        # Ruta de archivo
│   ├── repositories/          # Interfaces de repositorios
│   │   ├── IComponentRepository.ts
│   │   └── IDocumentationRepository.ts
│   └── exceptions/            # Excepciones de dominio
│       └── DomainExceptions.ts
│
├── application/               # Capa de Aplicación (Casos de Uso)
│   ├── use-cases/            # Casos de uso
│   │   └── GenerateDocumentationUseCase.ts
│   ├── dtos/                 # Data Transfer Objects
│   │   └── DocumentationDtos.ts
│   └── ports/                # Interfaces para servicios (Puertos)
│       ├── IFileService.ts
│       ├── IComponentAnalyzerService.ts
│       ├── IQualityAnalyzerService.ts
│       ├── IMkDocsService.ts
│       └── IDiagramGeneratorService.ts
│
├── infrastructure/           # Capa de Infraestructura (Implementaciones)
│   └── services/            # Implementaciones de servicios
│       ├── FileService.ts
│       ├── ComponentAnalyzerService.ts
│       ├── QualityAnalyzerService.ts
│       ├── MkDocsService.ts
│       ├── DiagramGeneratorService.ts
│       └── RulesLoaderService.ts
│
└── presentation/            # Capa de Presentación (MCP Server)
    └── mcp/
        ├── server.ts        # MCP Server principal
        └── AppModule.ts     # Módulo de NestJS para DI
```

### Principios SOLID Aplicados

1. **Single Responsibility Principle (SRP)**: Cada clase tiene una única responsabilidad bien definida
2. **Open/Closed Principle (OCP)**: Las entidades están abiertas para extensión pero cerradas para modificación
3. **Liskov Substitution Principle (LSP)**: Los value objects y entidades son intercambiables con sus abstracciones
4. **Interface Segregation Principle (ISP)**: Interfaces específicas y enfocadas en lugar de interfaces monolíticas
5. **Dependency Inversion Principle (DIP)**: Las dependencias apuntan hacia abstracciones, no hacia implementaciones concretas

## 🚀 Instalación

```bash
# Clonar el repositorio
git clone <repository-url>
cd mcp-docs

# Instalar dependencias
npm install

# Compilar el proyecto
npm run build
```

## 📋 Requisitos

- Node.js >= 18
- TypeScript >= 5.3
- Python >= 3.8 (para MkDocs, si quieres compilar los sitios)
- MkDocs (opcional, para compilar sitios de documentación)

```bash
# Instalar MkDocs (opcional)
pip install mkdocs mkdocs-material
```

## 🛠️ Uso

### Como MCP Server

Este servidor implementa el Model Context Protocol y puede ser usado con cualquier cliente compatible con MCP (como Claude Desktop, VS Code con extensiones MCP, etc.)

#### Configuración en Claude Desktop

Agregar en `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "satrack-docs": {
      "command": "node",
      "args": ["/ruta/absoluta/mcp-docs/dist/presentation/mcp/server.js"]
    }
  }
}
```

### Herramientas Disponibles

#### 1. `generate_documentation`

Genera documentación técnica completa para un proyecto Satrack.

**Parámetros:**
- `projectPath` (required): Ruta absoluta al directorio raíz del proyecto
- `componentPaths` (optional): Array de rutas de componentes a documentar
- `projectName` (optional): Nombre del proyecto
- `siteName` (optional): Nombre del sitio para MkDocs
- `generateQualityAnalysis` (optional): Generar análisis de atributos de calidad (default: true)
- `skipComponentDocumentation` (optional): Saltar documentación de componentes (default: false)

**Ejemplo:**
```json
{
  "projectPath": "/path/to/project",
  "componentPaths": [
    "/path/to/component1",
    "/path/to/component2"
  ],
  "projectName": "knowledge-my-project",
  "siteName": "kcs-my-project",
  "generateQualityAnalysis": true
}
```

#### 2. `get_documentation_rules`

Obtiene las reglas de documentación (AGENTS.md).

#### 3. `get_autogen_guide`

Obtiene la guía de autogeneración (autogen-guide.md).

#### 4. `get_component_generation_prompt`

Obtiene el prompt para generación de documentación de componentes.

#### 5. `identify`

Registra el usuario VSCode para métricas y tracking.

**Parámetros:**
- `user` (required): Login o email del usuario VSCode
- `ip` (optional): Dirección IP del cliente
- `project` (optional): Nombre del workspace/proyecto actual

#### 6. `report_validation`

Registra un reporte de análisis/validación completado en la base de datos.

**Parámetros:**
- `analysis_type` (required): Tipo de análisis (e.g., "documentation_generation")
- `user` (required): Usuario que realizó el análisis
- `project` (optional): Nombre del proyecto
- `files_analyzed` (required): Lista de archivos analizados
- `findings` (required): Hallazgos del análisis
- `summary` (required): Resumen ejecutivo
- `stack` (optional): Stack/framework detectado
- `stack_version` (optional): Versión del stack
- `recommendations` (optional): Lista de recomendaciones

#### 7. `publish_documentation`

Publica la documentación MkDocs directamente a Azure Storage (Knowledge Center).

**⚠️ Requisitos:**

Una de las siguientes opciones de autenticación:
- **Opción 1 (Preferida):** Azure CLI autenticado (\`az login\`) - Recomendado para Azure DevOps
- **Opción 2:** Variable de entorno \`AZURE_STORAGE_CONNECTION_STRING\` - Para Kubernetes/local
- MkDocs instalado (`pip install mkdocs mkdocs-material`)
- `SiteName` configurado en `pipeline/vars-azure-pipeline.yml`

**Parámetros:**
- `projectPath` (required): Ruta absoluta al directorio raíz del proyecto
- `siteName` (optional): Nombre del sitio (se lee de config si no se proporciona)
- `skipBuild` (optional): Saltar `mkdocs build` si la carpeta `site/` ya existe (default: false)

**Ejemplo:**
```json
{
  "projectPath": "/path/to/project",
  "siteName": "kcs-my-project"
}
```

**Configuración de Azure Storage:**

```bash
# Opción 1: Azure CLI (Preferido para Azure DevOps)
az login
# El servicio detecta automáticamente la sesión activa

# Opción 2: Connection String (Para Kubernetes/local)
export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=knowledgecentersatrack;AccountKey=...;EndpointSuffix=core.windows.net"

# Configuración opcional: Forzar método específico
export AZURE_STORAGE_METHOD="auto"  # auto (default) | cli | sdk
```

**Resultado:**
- Detecta automáticamente el método de autenticación disponible
- Compila el sitio con \`mkdocs build\`
- Sube archivos usando Azure CLI (preferido) o SDK
- URL final: `https://knowledgecentersatrack.z20.web.core.windows.net/{SiteName}/`

## 🎯 Proceso de Documentación

El MCP automatiza el siguiente proceso:

1. **Verificación de Configuración**
   - Valida `pipeline/vars-azure-pipeline.yml`
   - Verifica campos requeridos (ProjectName, SiteName)

2. **Verificación de Metadata**
   - Asegura que existe `metadatos_repo/`
   - Verifica archivos JSON de metadata de componentes

3. **Generación de Documentación de Componentes** (si se solicita)
   - Detecta tipo de componente (API, Worker, Frontend)
   - Extrae metadata del código fuente
   - Genera documentación estructurada

4. **Generación de Diagramas**
   - Diagrama de contexto
   - Diagrama de contenedores
   - Diagramas por componente

5. **Análisis de Atributos de Calidad**
   - Lee `docs/quality-attributes-priority.md`
   - Analiza metadata de componentes
   - Genera calificaciones por atributo (1-5)
   - Crea análisis detallado

6. **Configuración de MkDocs**
   - Genera/actualiza `mkdocs.yml`
   - Configura navegación y tema

## 📁 Estructura de Salida

```
project/
├── metadatos_repo/              # Metadata de componentes
│   ├── component1.json
│   └── component2.json
├── docs/                        # Documentación generada
│   ├── index.md                # Página principal con resumen de calidad
│   ├── business-capability-architecture.md
│   ├── quality-attributes-priority.md
│   ├── quality-attributes-analysis.md
│   └── diagrams/
│       ├── context-diagram.md
│       ├── container-diagram.md
│       └── component-*.md
├── pipeline/
│   └── vars-azure-pipeline.yml # Configuración de pipeline
└── mkdocs.yml                  # Configuración de MkDocs
```

## 📤 Publicación de Documentación

Una vez generada la documentación, tienes **dos opciones** para publicarla al Knowledge Center:

### Opción 1: Publicación Directa (MCP Tool)

**Ventajas:**
- ✅ Publicación inmediata (segundos)
- ✅ No requiere configurar Azure DevOps
- ✅ Ideal para revisiones rápidas y desarrollo

**Requisitos:**
```bash
# 1. Instalar MkDocs
pip install mkdocs mkdocs-material

# 2. Configurar credenciales de Azure Storage
export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=knowledgecentersatrack;AccountKey=...;EndpointSuffix=core.windows.net"
```

**Uso:**
```json
// El MCP preguntará automáticamente después de generar la documentación
// O puedes llamar manualmente:
{
  "tool": "publish_documentation",
  "params": {
    "projectPath": "/path/to/project"
  }
}
```

**Flujo automático:**
1. Genera documentación con `generate_documentation`
2. El MCP muestra un prompt preguntando si deseas publicar
3. Confirmas con "Sí" → publicación automática
4. URL disponible en segundos

### Opción 2: Pipeline de Azure DevOps

**Ventajas:**
- ✅ Control de versiones y historial de deployments
- ✅ No requiere credenciales locales
- ✅ Integración con proceso CI/CD
- ✅ Recomendado para producción

**Pasos:**
1. Genera documentación localmente
2. Commit y push al repositorio
3. El pipeline de Azure DevOps detecta cambios
4. Compila y publica automáticamente

**Archivos requeridos:**
- `devops/pipeline.yml` - Pipeline de CI/CD
- `devops/deployment.yml` - Configuración de Kubernetes
- `devops/vars-azure-pipeline.yml` - Variables de configuración
- `pipeline/vars-azure-pipeline.yml` - Configuración del proyecto

### Configuración de `pipeline/vars-azure-pipeline.yml`

```yaml
variables:
  ProjectName: 'knowledge-my-project'
  SiteName: 'kcs-my-project'
  Storage: 'knowledgecentersatrack'
  AzureSubscription: 'knowledge-center'
```

### URLs de Publicación

El sitio será accesible en:
```
https://knowledgecentersatrack.z20.web.core.windows.net/{SiteName}/
```

Ejemplo:
```
https://knowledgecentersatrack.z20.web.core.windows.net/kcs-predrive-checklist/
```

## 🔒 Seguridad y Credenciales

### Variables de Entorno

**Para publicación directa (una de estas dos opciones):**
- **Opción 1 (Preferida):** Azure CLI autenticado (`az login`) - Más seguro, usa Azure AD
- **Opción 2:** `AZURE_STORAGE_CONNECTION_STRING` - Connection string para Kubernetes/local

**Configuración común:**
- `AZURE_STORAGE_ACCOUNT` - Nombre de la cuenta de storage (default: "knowledgecentersatrack")
- `AZURE_STORAGE_METHOD` - Método preferido: "auto" (default), "cli" o "sdk"

**Opcionales:**
- `POSTGRES_DSN` - Conexión a PostgreSQL para persistir reportes
- `METRICS_PATH` - Ruta para archivo de métricas (JSON lines)
- `MCP_USER` - Usuario por defecto para tracking

**Importante:** 
- ✅ Azure CLI es más seguro (no expone credenciales, usa Azure AD)
- ⚠️ Nunca commitear credenciales al repositorio
- ⚠️ Usar variables de entorno o Azure Key Vault
- ⚠️ Las credenciales solo se necesitan localmente para publicación directa
- ⚠️ El pipeline de Azure DevOps usa Service Connections (más seguro)

### Azure DevOps Variable Groups

El pipeline usa estos variable groups:
- `docs-mcp` - Variables comunes
- `dev-docs-mcp` - Variables de desarrollo
- `prod-docs-mcp` - Variables de producción

**Variables requeridas en los variable groups:**

**PostgreSQL (opcional):**
- `POSTGRES_USER` - Usuario de PostgreSQL
- `POSTGRES_PASSWORD` - Contraseña de PostgreSQL
- `POSTGRES_HOST` - Host de PostgreSQL
- `POSTGRES_PORT` - Puerto de PostgreSQL (default: 5432)
- `POSTGRES_DB` - Nombre de la base de datos

**Azure Storage (opcional para publicación automática):**
- `AZURE_STORAGE_ACCOUNT` - Nombre de la cuenta de storage (e.g., "knowledgecentersatrack")
- `AZURE_STORAGE_KEY` - Access Key de la cuenta de storage

**Kubernetes:**
- `NAMESPACE` - Namespace de Kubernetes (e.g., "satrack-mcp")
- `acrName` - Nombre del Azure Container Registry
- `acrServiceConnection` - Service Connection de ACR
- `aksResourceGroup` - Resource Group de AKS
- `aksClusterName` - Nombre del cluster AKS
- `aksServiceConnection` - Service Connection de AKS

**Nota:** Las variables de PostgreSQL y Azure Storage son opcionales. Si no se configuran, esas funcionalidades simplemente no estarán disponibles en el MCP desplegado.

## 🔧 Desarrollo

```bash
# Modo desarrollo con hot-reload
npm run dev

# Ejecutar linter
npm run lint

# Formatear código
npm run format

# Ejecutar tests (cuando se implementen)
npm test
```

## 📚 Reglas de Documentación

Las reglas de documentación están ubicadas en `rules/`:

- `AGENTS.md`: Reglas principales y estructura de documentos
- `autogen-guide.md`: Guía paso a paso del proceso
- `prompts/`: Prompts para generación con IA
- `referencia-metadata/`: Esquemas y ejemplos de metadata

## 🤝 Integración con GitHub Copilot

Este MCP puede ser usado directamente desde GitHub Copilot Chat o Claude:

```
@satrack-docs generate_documentation --projectPath=/path/to/project
```

## 📝 Changelog

### v1.0.0
- ✨ Implementación inicial con Clean Architecture
- 🏗️ Aplicación de principios SOLID
- 🔧 Integración con MCP SDK
- 📊 Generación de diagramas Mermaid
- 📈 Análisis de atributos de calidad
- 🎨 Configuración automática de MkDocs

## 📄 Licencia

MIT

## 👥 Autores

Equipo Satrack

---

**Nota**: Este MCP es una herramienta experimental para acelerar la creación de documentación. La documentación generada debe ser revisada y validada por el equipo técnico.