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

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

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

{
  "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:

{
  "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:

{
  "projectPath": "/path/to/project",
  "siteName": "kcs-my-project"
}

Configuración de Azure Storage:

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

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

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

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

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