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

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

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

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

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

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

{namespace="mcp", app="guidelines-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="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:

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

# 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