# MCP Rules Server - Guía de Uso

Servidor MCP que proporciona reglas de código y validación por stack/framework para equipos de desarrollo.

## 🎯 Optimización de Tokens (Nuevo)

**Ahorro del 90-95% en consumo de tokens** mediante caché inteligente y carga bajo demanda.

📖 **[Guía completa de optimización](docs/TOKEN_OPTIMIZATION.md)** - Cómo reducir costos drásticamente

**Resumen rápido:**
- ✅ Herramientas optimizadas retornan metadata compacta por defecto
- ✅ Nueva herramienta `get_rule_content(stack, kind)` para carga específica
- ✅ `agent_flow()` ahora retorna resumen ejecutivo (~85% menos tokens)
- ✅ `bootstrap()` modo lightweight por defecto (~90% menos tokens)
- ✅ Ahorro estimado: **~$810 USD/mes** (100 consultas/día)

## 🚀 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-code-validator": {
			"url": "https://mcp-dev-rules.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": {
    "mcp-rules-server": {            // nombre original
      "transport": "sse",
      "url": "https://mcp-dev-rules.satrack.com"
    },
    "satrack-code-validator": {     // alias para usar @satrack-code-validator
      "transport": "sse",
      "url": "https://mcp-dev-rules.satrack.com"
    }
  }
}
```

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

---

## 🧪 Pruebas con Copilot Chat (VS Code)

### Iniciar validación de código

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

```
@mcp-rules agent_flow
```

O el alias corto:

```
@mcp-rules validar
```

O simplemente:

```
Validar el codigo
```

Esto carga las instrucciones obligatorias del flujo de validación.

---

## 🔍 Ejemplo de Flujo Completo

> **Nota:** El sistema detecta automáticamente el usuario desde:
> 1. Git config (user.name, user.email)
> 2. Variables de entorno (MCP_USER, VSCODE_USER)
> 3. Usuario del sistema operativo

### Paso 0: (Opcional) Obtener información del usuario
```
@mcp-rules get_user_info
```

Te mostrará:
- `contact_name`: "Carlos Perez"
- `contact_mail`: "carlos_perez@satrack.com"
- `username`: "carlos.perez" (normalizado para reportes)
- `source`: De dónde se obtuvo (git_config, system, etc.)

Esta información se usa automáticamente en los reportes.

### Paso 1: Iniciar validación
```
@mcp-rules validar
```

Copilot te preguntará:
- **¿Análisis solo de archivos modificados o todo el código?**

### Paso 2: Obtener reglas según tu respuesta

Si dijiste "archivos modificados":
```
@mcp-rules rules
```
(Obtendrás `prompt-code-review.md`)

Si dijiste "todo el código":
```
@mcp-rules rules
```
(Obtendrás `prompt-full-code-analysis.md`)

> **Nota:** El sistema detecta automáticamente si tu proyecto es `mobile`, `web`, `api` o `service`.

### Paso 3: Copilot analiza el código

Copilot usará las reglas cargadas para analizar tu código.

### Paso 4: Reportar resultados
```
@mcp-rules report_validation 
  analysis_type="code-review"
  stack="web"
  stack_version="17.3.0"
  files_analyzed=["src/app/app-routing.module.ts", "src/app/app.component.html"]
  findings={
    "errors": [
      {"file": "src/app/app-routing.module.ts", "line": 9, "severity": "Blocker", "message": "Sintaxis incorrecta en imports"}
    ],
    "warnings": [],
    "suggestions": []
  }
  summary="Se detectan 1 error crítico de sintaxis"
  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": "maria_andrade",
  "mcp_name": "code-review",
  "project": "mf-sidenav-izquierdo",
  "report": {
    "stack": "web - angular",
    "stack_version": "17.3.0",
    "files_analyzed": [
      "src/app/app-routing.module.ts",
      "src/app/app.component.html"
    ],
    "total_files": 2,
    "findings": {
      "errors": [
        {
          "file": "src/app/app-routing.module.ts",
          "line": 9,
          "severity": "Blocker",
          "message": "Sintaxis incorrecta en imports del @NgModule"
        }
      ],
      "warnings": [],
      "suggestions": []
    },
    "summary": "Se detectan 1 error crítico de sintaxis que rompe la compilación",
    "recommendations": [
      "Revertir cambios inmediatamente",
      "Ejecutar 'ng build' para validar compilación"
    ]
  }
}
```

### Tipos de `mcp_name`
- `code-review`: Análisis de archivos modificados (partial/PR)
- `full-code-analysis`: Análisis completo del proyecto

---

## 🎯 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": {
    "mcp-rules": {
      "transport": "sse",
      "url": "https://mcp-dev-rules.satrack.com/"
    }
  }
}
```

4. Reinicia Visual Studio

### Usar en Visual Studio

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

```
@mcp-rules validar
```

---

## 📋 Herramientas MCP Disponibles

| Herramienta | Descripción |
|------------|-------------|
| `validar` / `agent_flow` | **Iniciar validación** - Retorna flujo obligatorio de AGENTS.md (resumen ejecutivo) |
| `get_agent_flow_full` | Obtener AGENTS.md completo con instrucciones detalladas |
| `rules(stack, root, include_content)` | Obtener reglas de código para un stack específico (metadata por defecto) |
| `get_rule_content(stack, kind)` | Obtener contenido completo de una regla específica bajo demanda |
| `detect_stack(root)` | Detectar stack/framework del proyecto automáticamente |
| `list_stacks()` | Listar todos los stacks disponibles |
| `bootstrap(root, lightweight)` | Inicialización completa: detecta stack + carga reglas (modo ligero por defecto) |
| `identify(user, ip, project)` | Registrar usuario de VSCode para métricas |
| `get_user_info()` | **Nuevo** - Obtener información del usuario actual automáticamente (nombre, email, username) |
| `report_validation(...)` | Registrar reporte de validación completado |
| `validate_and_report(...)` | Ejecutar validación completa y generar reporte automáticamente |
| `vscode_agents()` | Detectar agentes disponibles de VSCode/GitHub Copilot |

---

## 🔧 Verificar Logs en Kubernetes

Para descargar y ver los logs generados:

```powershell
# Obtener nombre del pod
$podName = kubectl get pods -n mcp -l app=guidelines-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="guidelines-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="guidelines-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.).

---

## 🗄️ 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-rules.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-rules.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`

---

## 📝 Ejemplo Completo de Sesión

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

# 1. Iniciar validación
@mcp-rules validar
# Copilot: "¿Archivos modificados o completo?"
# Usuario: "Solo modificados"

# 2. Detectar categoría
@mcp-rules detect_stack
# Respuesta: "api"

# 3. Obtener reglas
@mcp-rules rules

# 4. Copilot analiza y encuentra 3 errores...

# 5. Reportar
@mcp-rules report_validation 
  analysis_type="code-review"
  stack="api"
  stack_version="0.115.0"
  files_analyzed=["api/routes.py", "api/models.py"]
  findings={"errors": [...], "warnings": [...]}
  summary="3 errores críticos encontrados"
  recommendations=["Corregir imports", "Añadir type hints"]

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

---

## 🔗 Enlaces Útiles

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

---

## 📄 Licencia

Uso interno - SATRACK