# MCP Commit Server - Guía de Uso

Servidor MCP que proporciona reglas de commits con formato SemVer y conventional commits para equipos de desarrollo.

## 🚀 Configuración en VS Code

### 1. Requisitos
- Visual Studio Code
- Extensión **GitHub Copilot Chat** (con soporte MCP)

### 2. Configurar el servidor MCP

Hay dos formas de acceder a la configuración:

**Opción A: Comando directo MCP**
- Presiona `Ctrl+Shift+P`
- Escribe: `MCP: Open User Configuration`
- Se abrirá el archivo `mcp.json` directamente
- Agrega la siguiente configuracion:

```json
{
	"servers": {
		"satrack-commits": {
			"url": "https://mcp-dev-commits.satrack.com/sse",
			"type": "http"
		}
	},
	"inputs": []
}
```

**Opción B: Settings de VS Code**
- Presiona `Ctrl+Shift+P`
- Escribe: `Preferences: Open User Settings (JSON)`
- Agrega la sección `mcpServers` si no existe

Agrega la configuración del servidor:

```json
{
  "mcpServers": {
    "satrack-commits": {             // servidor MCP para generación de commits
      "transport": "sse",
      "url": "https://mcp-dev-commits.satrack.com"
    }
  }
}
```

### 3. Configuración de Base de Datos (Opcional pero Recomendado)

El servidor puede guardar reportes de commits en PostgreSQL para métricas y análisis. Esto es **opcional** pero muy útil.

#### Configuración en Producción (Kubernetes/Azure DevOps):

Las credenciales de PostgreSQL se configuran mediante **variables del pipeline de Azure DevOps**:

```yaml
# En devops/vars-azure-pipeline.yml o en el pipeline:
POSTGRES_USER: "tu_usuario"
POSTGRES_PASSWORD: "$(postgres-password)"  # Variable secreta
POSTGRES_HOST: "tu-servidor.postgres.database.azure.com"
POSTGRES_PORT: "5432"
POSTGRES_DB: "mcp_commits"
```

El [deployment.yml](devops/deployment.yml) ya incluye el Secret que usa estas variables:
```yaml
apiVersion: v1
kind: Secret
metadata:
  name: mcp-postgres-credentials
stringData:
  dsn: "postgresql://#{POSTGRES_USER}#:#{POSTGRES_PASSWORD}#@#{POSTGRES_HOST}#:#{POSTGRES_PORT}#/#{POSTGRES_DB}#"
```

#### Configuración Local (Desarrollo):

1. **Copia el archivo de configuración:**
   ```bash
   cp .env.example .env
   ```

2. **Edita `.env` y configura `POSTGRES_DSN`:**
   ```env
   # PostgreSQL local
   POSTGRES_DSN=postgresql://postgres:password@localhost:5432/mcp_commits
   ```

3. **Verificar configuración:**
   ```bash
   python scripts/check_db.py
   ```
   
   Este script verificará:
   - ✅ Que `asyncpg` esté instalado
   - ✅ Que `POSTGRES_DSN` esté configurado
   - ✅ Que la conexión funcione
   - ✅ Que se puedan insertar reportes

**Comportamiento sin PostgreSQL configurado:**
- El servidor funcionará normalmente
- Los reportes solo se guardarán en logs locales (`/var/log/mcp/metrics.jsonl`)
- No habrá registro en base de datos

**Con PostgreSQL configurado:**
- ✅ Reportes guardados en base de datos con UUID único
- ✅ Búsqueda de análisis previos para validación
- ✅ Métricas completas por usuario y proyecto
- ✅ Detección de commits consecutivos sin análisis

### 4. Recarga VS Code
Presiona `Ctrl+Shift+P` → "Developer: Reload Window"

---

## 🧪 Pruebas con Copilot Chat (VS Code)

### Iniciar generación de commit

Abre GitHub Copilot Chat (icono de chat en la barra lateral) y usa:

```
@satrack-commits agent_flow
```

O el alias corto:

```
@satrack-commits validar
```

O simplemente:

```
Generar commit
```

Esto carga las instrucciones obligatorias del flujo de generación de commits.

---

## 🔍 Ejemplo de Flujo Completo

> **Nota:** La identificación del usuario (`identify`) se realiza automáticamente al iniciar la sesión con tu cuenta de Satrack.

### Paso 1: Iniciar generación de commit
```
@satrack-commits validar
```

Copilot te preguntará:
- **¿Es un commit para publicar una nueva versión?**

### Paso 2: (Solo si es release) Calcular y actualizar versión automáticamente

Si respondiste SÍ en el paso 1, la versión se calcula automáticamente según el tipo de commit:

```
@satrack-commits calculate_next_version 
  current_version="0.1.0"
  commit_type="chore"
  is_breaking=false
```

Esto calcula la nueva versión según SemVer:
- `feat` → MINOR: 0.1.0 → 0.2.0
- `fix` → PATCH: 0.1.0 → 0.1.1
- `feat!` o breaking → MAJOR: 0.1.0 → 1.0.0

Luego actualiza el archivo de versión:

```
@satrack-commits update_project_version 
  current_version="0.1.0"
  new_version="0.2.0"
  project_type="app-web"
```

Copilot actualizará automáticamente `package.json`, `pubspec.yaml`, `pom.xml`, etc.

### Paso 3: Obtener reglas de commits
```
@satrack-commits rules
```
(Obtendrás `commit-guidelines.md` con formato SemVer)

### Paso 4: Generar entrada de CHANGELOG

Antes de aplicar el commit, genera el contenido del CHANGELOG.md:

```
@satrack-commits generate_changelog_entry 
  commit_message="feat: [HU-1234] agregar autenticación biométrica"
  commit_type="feat"
  version="1.2.3"
  is_release=false
```

Copilot usará la respuesta para crear/actualizar el archivo `CHANGELOG.md` en la raíz de tu proyecto.

### Paso 4: Copilot genera el commit

Copilot usará las reglas cargadas para generar un mensaje de commit en formato conventional commits.

### Paso 5: Reportar generación de commit
```
@satrack-commits report_validation 
  analysis_type="commit"
  stack="angular"
  stack_version="17.3.0"
  files_analyzed=["src/app/app.component.ts", "src/app/services/auth.service.ts"]
  findings={
    "commit_message": "feat: [HU-1234] agregar autenticación biométrica",
    "is_release": false
  }
  summary="Commit generado para nueva funcionalidad de autenticación"
  recommendations=["Revertir cambios", "Ejecutar ng build"]
```

---

## 📊 Formato del Log Generado

Cuando ejecutas `report_validation`, se genera un log en `/var/log/mcp/metrics.jsonl`:

```json
{
  "timestamp": "2025-12-31T07:46:11.743778-05:00",
  "user": "pedro_picapiedra",
  "mcp_name": "commit",
  "project": "mf-sidenav-izquierdo",
  "report": {
    "stack": "angular",
    "stack_version": "17.3.0",
    "files_analyzed": [
      "src/app/auth/auth.service.ts",
      "src/app/auth/biometric.guard.ts"
    ],
    "total_files": 2,
    "findings": {
      "commit_message": "feat: [HU-1234] agregar autenticación biométrica",
      "is_release": false
    },
    "summary": "Commit generado para nueva funcionalidad de autenticación",
    "recommendations": [
      "Actualizar CHANGELOG.md",
      "Ejecutar tests antes de push"
    ]
  }
}
```

### Tipos de `mcp_name`
- `commit`: Generación de commits con formato SemVer (tipo principal de este servidor)

---

## 🎯 Pruebas con Visual Studio

### Configuración en Visual Studio 2022

1. Instala la extensión **GitHub Copilot**
2. Abre `Tools` → `Options` → `GitHub Copilot` → `MCP Servers`
3. Agrega el servidor:

```json
{
  "mcpServers": {
    "satrack-commits": {
      "transport": "sse",
      "url": "https://mcp-dev-commits.satrack.com/"
    }
  }
}
```

4. Reinicia Visual Studio

### Usar en Visual Studio

Abre el **Copilot Chat** (View → Copilot Chat) y usa los mismos comandos:

```
@satrack-commits validar
```

---

## 📋 Herramientas MCP Disponibles

| Herramienta | Descripción |
|------------|-------------|
| `validar` / `agent_flow` | **Iniciar generación de commit** - Retorna flujo obligatorio de AGENTS.md |
| `rules` | Obtener reglas de commits (commit-guidelines.md) |
| `calculate_next_version` | Calcular automáticamente la siguiente versión según SemVer |
| `generate_changelog_entry` | Generar contenido para actualizar CHANGELOG.md del proyecto |
| `update_project_version` | Generar instrucciones para actualizar versión en archivo de configuración |
| `bootstrap` | Inicialización completa: agent flow + reglas de commits |
| `identify` | Registrar usuario VSCode para métricas |
| `report_validation` | Registrar commit generado en base de datos |
| `detect_stack` | Detectar framework del proyecto (para contexto) |
| `vscode_agents` | Detectar agentes VSCode disponibles |

---

## 🔧 Verificar Logs en Kubernetes

Para descargar y ver los logs generados:

```powershell
# Obtener nombre del pod
$podName = kubectl get pods -n mcp -l app=commits-mcp -o jsonpath='{.items[0].metadata.name}'

# Descargar logs
kubectl cp mcp/${podName}:/var/log/mcp/metrics.jsonl ./metrics.jsonl

# Ver contenido
Get-Content ./metrics.jsonl -Tail 20
```

---

## 📈 Visualización en Grafana

Los logs se envían automáticamente a **Loki** y pueden visualizarse en Grafana usando LogQL:

```logql
{namespace="mcp", app="commits-mcp", filename=~".*/metrics.jsonl"}
| json
| line_format "{{.timestamp}} | {{.user}} | {{.project}} | {{.mcp_name}} | {{.report_stack}}"
```

**Panel de conteo por usuario:**
```logql
sum by (user, mcp_name) (
  count_over_time(
    {namespace="mcp", app="commits-mcp", filename=~".*/metrics.jsonl"}
    | json
    [24h]
  )
)
```

---

## 🌍 Categorías Soportadas

El sistema detecta automáticamente el tipo de proyecto y aplica las reglas correspondientes:

- **`mobile`**: Aplicaciones móviles (Flutter, React Native, Android, iOS)
- **`web`**: Aplicaciones web frontend (Angular, React, Vue, Svelte)
- **`api`**: APIs y servicios backend (FastAPI, Django, NestJS, Spring)
- **`service`**: Servicios de infraestructura (Terraform, microservicios, workers)

> La detección se realiza automáticamente analizando los archivos del proyecto (package.json, pubspec.yaml, requirements.txt, etc.).

---

## 📋 Estructura de Reglas

El servidor carga reglas desde el directorio `rules/`:

```
rules/
├── AGENTS.md                    # Flujo obligatorio para generación de commits
├── commit-guidelines.md         # Formato SemVer y conventional commits
├── app-web/
│   └── changelog-guidelines.md  # Reglas de CHANGELOG para apps web
├── app-mobile/
│   └── changelog-guidelines.md  # Reglas de CHANGELOG para apps móviles
├── apis/
│   └── changelog-guidelines.md  # Reglas de CHANGELOG para APIs
└── workers/
    └── changelog-guidelines.md  # Reglas de CHANGELOG para workers/services
```

### Changelog Guidelines por Tipo de Proyecto

Cada tipo de proyecto tiene su propio `changelog-guidelines.md` adaptado:

- **app-web**: Para aplicaciones web (Angular, React, Vue, Next.js)
  - Cambios en componentes, módulos, routing
  - Actualizaciones de dependencias frontend
  - Mejoras de UI/UX

- **app-mobile**: Para aplicaciones móviles (Flutter, React Native)
  - Cambios en pantallas y navegación
  - Permisos y configuraciones nativas
  - Actualizaciones de SDK móvil

- **apis**: Para APIs REST/GraphQL
  - Nuevos endpoints y recursos
  - Cambios en contratos (request/response)
  - Breaking changes en API
  - Rate limiting y seguridad

- **workers**: Para workers/services/jobs
  - Jobs y tareas programadas (cron)
  - Consumers de colas de mensajes
  - Retry policies y timeouts
  - Performance y escalabilidad

> El servidor carga automáticamente todos estos archivos al iniciar y los pone disponibles a través de la herramienta `rules`.

---

## 🗄️ Persistencia en PostgreSQL

El servidor puede guardar automáticamente los reportes de validación en una base de datos PostgreSQL.

### Configuración

Define la variable de entorno `POSTGRES_DSN` con la cadena de conexión:

```bash
# Formato
POSTGRES_DSN="postgresql://user:password@host:port/database"

# Ejemplo
POSTGRES_DSN="postgresql://mcp_user:secret@postgres.satrack.com:5432/mcp_metrics"
```

### Deployment en Kubernetes

Agrega el secret y variable de entorno en el deployment:

```yaml
# k8s/postgres-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: mcp-postgres-credentials
  namespace: mcp
type: Opaque
stringData:
  dsn: "postgresql://mcp_user:secret@postgres-service:5432/mcp_metrics"

---
# En k8s/mcp-server.yaml, agrega:
env:
  - name: POSTGRES_DSN
    valueFrom:
      secretKeyRef:
        name: mcp-postgres-credentials
        key: dsn
```

### Schema de Base de Datos

El servidor crea automáticamente la tabla al iniciar (si tiene permisos):

```sql
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE validation_reports (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    timestamp TIMESTAMPTZ NOT NULL,
    user_name VARCHAR(255) NOT NULL,
    mcp_name VARCHAR(100) NOT NULL,
    project VARCHAR(255) NOT NULL,
    report JSONB NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Índices para consultas comunes
CREATE INDEX idx_validation_reports_timestamp ON validation_reports(timestamp);
CREATE INDEX idx_validation_reports_user ON validation_reports(user_name);
CREATE INDEX idx_validation_reports_project ON validation_reports(project);
CREATE INDEX idx_validation_reports_mcp_name ON validation_reports(mcp_name);
CREATE INDEX idx_validation_reports_report_stack ON validation_reports((report->>'stack'));
```

### Consultas Útiles

```sql
-- Reportes recientes
SELECT id, timestamp, user_name, project, mcp_name, 
       report->>'stack' as stack,
       report->>'summary' as summary
FROM validation_reports
ORDER BY timestamp DESC
LIMIT 20;

-- Estadísticas por usuario
SELECT user_name, mcp_name, COUNT(*) as total
FROM validation_reports
WHERE timestamp > NOW() - INTERVAL '7 days'
GROUP BY user_name, mcp_name
ORDER BY total DESC;

-- Errores críticos por proyecto
SELECT project, 
       COUNT(*) as reports,
       SUM(jsonb_array_length(report->'findings'->'errors')) as total_errors
FROM validation_reports
WHERE timestamp > NOW() - INTERVAL '30 days'
GROUP BY project
ORDER BY total_errors DESC;

-- Ver reporte completo por ID
SELECT id, timestamp, user_name, mcp_name, project,
       jsonb_pretty(report) as report_formatted
FROM validation_reports
WHERE id = 'uuid-here'::uuid;

-- Filtrar por stack específico
SELECT timestamp, user_name, project, report->>'summary' as summary
FROM validation_reports
WHERE report->>'stack' LIKE 'web - %'
ORDER BY timestamp DESC
LIMIT 10;
```

### Comportamiento

- **Opcional**: Si `POSTGRES_DSN` no está configurado, el servidor funciona normalmente (solo logs a archivo).
- **Fail-safe**: Errores de PostgreSQL no interrumpen el flujo; se registran en stderr.
- **Async**: Las inserciones son no-bloqueantes y se ejecutan en background.

---

## 🆘 Troubleshooting

### El servidor no aparece en Copilot Chat
- Verifica que la URL es correcta: `https://mcp-dev-commits.satrack.com/sse`
- Recarga VS Code: `Ctrl+Shift+P` → "Developer: Reload Window"
- Revisa la consola: `Help` → `Toggle Developer Tools` → `Console`

### Error de conexión
- Verifica conectividad a `https://mcp-dev-commits.satrack.com/sse`
- Prueba en navegador: debe responder JSON con metadata MCP

### No se generan logs
- Chequea que el pod tenga el volumen montado: `kubectl describe pod -n mcp`

### No se guardan reportes en PostgreSQL

Si los reportes no se están guardando en la base de datos, sigue estos pasos de diagnóstico:

#### 1. Verificar que PostgreSQL esté configurado

```bash
# Ejecutar script de diagnóstico
python scripts/check_db.py
```

El script mostrará:
- ✅/❌ Si `asyncpg` está instalado
- ✅/❌ Si `POSTGRES_DSN` está configurado
- ✅/❌ Si la conexión funciona
- ✅/❌ Si se puede insertar un reporte de prueba

#### 2. Verificar logs del servidor

Cuando ejecutas `report_validation`, ahora el servidor imprime información de diagnóstico:

```
✅ Reporte guardado en PostgreSQL con ID: 123e4567-e89b-12d3-a456-426614174000
```

O si falla:

```
⚠️  No se guardó reporte en PostgreSQL (DB no habilitada o fallo silencioso)
   - POSTGRES_DSN configurado: False
   - DB habilitada: False
   - Pool conectado: False
```

O con error específico:

```
❌ Error al guardar reporte en PostgreSQL: connection timeout
```

#### 3. Verificar logs de startup

Al iniciar el servidor, verás mensajes que indican el estado:

```
✅ PostgreSQL habilitado - DSN configurado
🔄 Conectando a PostgreSQL...
✅ Pool de conexiones PostgreSQL creado
✅ Schema de PostgreSQL verificado
```

O si hay problemas:

```
⚠️  POSTGRES_DSN no configurado - PostgreSQL deshabilitado
```

```
❌ PostgreSQL connection failed: could not connect to server
```

#### 4. Configuración común de problemas

**Problema: "asyncpg no está instalado"**
```bash
pip install asyncpg>=0.29.0
```

**Problema: "POSTGRES_DSN no configurado"**
1. Copia `.env.example` a `.env`
2. Edita `.env` y configura `POSTGRES_DSN`
3. Reinicia el servidor

**Problema: "Connection refused"**
- Verifica que PostgreSQL esté corriendo
- Verifica host, puerto y credenciales en `POSTGRES_DSN`
- Prueba conexión manual: `psql "postgresql://user:pass@host:port/db"`

**Problema: "SSL connection required"**
- Agrega `?sslmode=require` al final del DSN:
  ```env
  POSTGRES_DSN=postgresql://user:pass@host:5432/db?sslmode=require
  ```

#### 5. Verificar en Kubernetes

Si el servidor está en Kubernetes:

```bash
# Ver logs del pod
kubectl logs -f deployment/commits-mcp -n #{NAMESPACE}#

# Buscar mensajes de PostgreSQL en los logs
kubectl logs deployment/commits-mcp -n #{NAMESPACE}# | grep -E "PostgreSQL|✅|❌|⚠️"

# Verificar variables de entorno
kubectl exec deployment/commits-mcp -n #{NAMESPACE}# -- env | grep POSTGRES

# Verificar el Secret (las credenciales están en el deployment.yml)
kubectl get secret mcp-postgres-credentials -n #{NAMESPACE}# -o yaml

# Decodificar el DSN del Secret
kubectl get secret mcp-postgres-credentials -n #{NAMESPACE}# -o jsonpath='{.data.dsn}' | base64 -d
```

**Configurar variables en Azure DevOps Pipeline:**

1. Ve a tu pipeline en Azure DevOps
2. Edita el pipeline y agrega variables:
   - `POSTGRES_USER`
   - `POSTGRES_PASSWORD` (marca como secreta)
   - `POSTGRES_HOST`
   - `POSTGRES_PORT` (default: 5432)
   - `POSTGRES_DB` (default: mcp_commits)
3. Ejecuta el pipeline nuevamente
4. El deployment.yml reemplazará automáticamente #{POSTGRES_*}# con los valores

---

## 📝 Ejemplo Completo de Sesión

```bash
# La identificación se hace automáticamente al iniciar

# 1. Iniciar generación de commit
@satrack-commits validar
# Copilot: "¿Es un commit para publicar una nueva versión?"
# Usuario: "No, es una nueva funcionalidad"

# 2. Detectar stack (para contexto)
@satrack-commits detect_stack
# Respuesta: "angular"

# 3. Obtener reglas de commits
@satrack-commits rules
# Retorna: commit-guidelines.md (formato SemVer)

# 4. Copilot genera mensaje de commit...

# 5. Reportar commit generado
@satrack-commits report_validation 
  analysis_type="commit"
  stack="angular"
  stack_version="17.3.0"
  files_analyzed=["src/app/auth/auth.service.ts", "src/app/auth/biometric.guard.ts"]
  findings={"commit_message": "feat: [HU-1234] agregar autenticación biométrica", "is_release": false}
  summary="Commit generado para nueva funcionalidad"
  recommendations=["Actualizar CHANGELOG.md", "Ejecutar tests antes de push"]

# 6. Ver logs generados
kubectl cp mcp/commits-mcp-xxx:/var/log/mcp/metrics.jsonl ./metrics.jsonl
```

---

## 🔗 Enlaces Útiles

- **Servidor Dev:** https://mcp-dev-commits.satrack.com/
- **Grafana:** https://grafana.satrack.com/
- **Repositorio:** https://satrack-ts.visualstudio.com/Artificial-Intelligence/_git/mcp-commits

---

## 📄 Licencia

Uso interno - SATRACK