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:

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

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

# 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 ya incluye el Secret que usa estas variables:

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:

   cp .env.example .env
   

2. Edita .env y configura POSTGRES_DSN:

   # PostgreSQL local
   POSTGRES_DSN=postgresql://postgres:password@localhost:5432/mcp_commits
   

3. Verificar configuración:

   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:

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

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

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

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

Panel de conteo por usuario:

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:

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

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

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

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

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

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:

  POSTGRES_DSN=postgresql://user:pass@host:5432/db?sslmode=require
  

5. Verificar en Kubernetes

Si el servidor está en Kubernetes:

# 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

# 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