nucleoDocs/README.md

# Nucleo Docs

Sistema de documentación para el ecosistema Nucleo basado en Nuxt 4 con autenticación mediante Authentik Proxy Outpost.

## Instalación de Servidores MCP

Para conectar los servidores MCP a Claude Code, ejecuta los siguientes comandos:

### MCP Docker Server
```bash
claude mcp add --transport http nucleodocs-docker https://docker.nucleoriofrio.com/mcp
```

### MCP Gitea Server
```bash
claude mcp add --transport http nucleodocs-gitea https://gitea.nucleoriofrio.com/mcp
```

### MCP Chrome DevTools
```bash
claude mcp add chrome-devtools npx -- chrome-devtools-mcp@latest --isolated=true
```

### MCP Metabase Server
```bash
claude mcp add --transport http nucleodocs-metabase https://metabase.nucleoriofrio.com/mcp
```

### Scopes Disponibles

**Para compartir con el equipo** (crea .mcp.json en el proyecto):
```bash
claude mcp add --transport http nucleodocs-docker --scope project https://docker.nucleoriofrio.com/mcp
claude mcp add --transport http nucleodocs-gitea --scope project https://gitea.nucleoriofrio.com/mcp
claude mcp add --transport http nucleodocs-metabase --scope project https://metabase.nucleoriofrio.com/mcp
claude mcp add chrome-devtools --scope project npx -- chrome-devtools-mcp@latest --isolated=true
```

**Para uso personal en todos los proyectos**:
```bash
claude mcp add --transport http nucleodocs-docker --scope user https://docker.nucleoriofrio.com/mcp
claude mcp add --transport http nucleodocs-gitea --scope user https://gitea.nucleoriofrio.com/mcp
claude mcp add --transport http nucleodocs-metabase --scope user https://metabase.nucleoriofrio.com/mcp
claude mcp add chrome-devtools --scope user npx -- chrome-devtools-mcp@latest --isolated=true
```

### Verificación
```bash
# Listar todos los servidores configurados
claude mcp list

# Ver detalles de un servidor específico
claude mcp get nucleodocs-docker
claude mcp get nucleodocs-gitea
claude mcp get nucleodocs-metabase
claude mcp get chrome-devtools

# Dentro de Claude Code, verificar el estado
/mcp
```

## Propósito

Este repositorio contiene la documentación del funcionamiento del sistema Nucleo, incluyendo:
- Arquitectura del sistema
- Guías de desarrollo
- Documentación de servicios
- Procedimientos operativos

## Estructura del Proyecto

```
.
├── nuxt4/              # Aplicación Nuxt 4 con la documentación
├── docker-compose.yml  # Configuración de despliegue
└── .gitea/            # Gitea Actions CI/CD
```

## Características

- ✅ Nuxt 4
- ✅ Autenticación con Authentik Proxy Outpost
- ✅ Docker y Docker Compose
- ✅ CI/CD con Gitea Actions
- ✅ Traefik para proxy reverso y SSL
- ✅ Claude Code hooks para monitoreo de Actions
- ✅ MCP Server Docker para gestión de contenedores
- ✅ MCP Server Gitea para API de Gitea
- ✅ MCP Server Metabase para análisis y reportes
- ✅ MCP Server Chrome DevTools para testing e interacción con navegador

## Servicios

### Aplicación Principal (`app`)
Aplicación Nuxt 4 con la documentación del sistema Nucleo, expuesta mediante Traefik con autenticación Authentik.

### MCP Docker Server (`mcp-docker`)
Servidor MCP personalizado construido con TypeScript que expone operaciones Docker a través del protocolo MCP sobre HTTP. Este servicio:
- Implementa 13 herramientas Docker seguras usando dockerode
- Usa el puerto 3000 para comunicación HTTP
- Tiene acceso al socket de Docker del host (solo lectura)
- Se ejecuta en las redes `principal` y `traefik-network`
- **Expuesto públicamente en `docker.nucleoriofrio.com/mcp` SIN autenticación Authentik**
- Prioridad 200 en Traefik para evitar conflictos con otros routers
- Endpoints disponibles:
  - `POST /mcp` - Protocolo MCP para operaciones Docker
  - `GET /health` - Health check del servicio

### MCP Gitea Server (`mcp-gitea`)
Servidor MCP personalizado construido con TypeScript que expone la API de Gitea a través del protocolo MCP sobre HTTP. Este servicio:
- Implementa 5 herramientas optimizadas para Gitea API v1
- Usa el puerto 3000 para comunicación HTTP
- Se conecta a Gitea mediante URL interna (http://gitea:3000)
- Se ejecuta en las redes `principal` y `traefik-network`
- **Expuesto públicamente en `gitea.nucleoriofrio.com/mcp` SIN autenticación Authentik**
- Prioridad 200 en Traefik para evitar conflictos con otros routers
- Herramientas disponibles:
  - `gitea_repos` - Gestión de repositorios
  - `gitea_commits` - Operaciones con commits
  - `gitea_issues` - Manejo de issues
  - `gitea_secrets` - Gestión de secrets para Actions
  - `gitea_variables` - Gestión de variables para Actions
- Endpoints disponibles:
  - `POST /mcp` - Protocolo MCP para operaciones Gitea
  - `GET /health` - Health check del servicio

### MCP Metabase Server (`mcp-metabase`)
Servidor MCP personalizado construido con TypeScript que expone la API de Metabase a través del protocolo MCP sobre HTTP. Este servicio:
- Implementa 9 herramientas para interactuar con Metabase
- Usa el puerto 3000 para comunicación HTTP
- Se conecta a Metabase mediante URL interna y autenticación con API Key
- Se ejecuta en las redes `principal` y `traefik-network`
- **Expuesto públicamente en `metabase.nucleoriofrio.com/mcp` SIN autenticación Authentik**
- Prioridad 200 en Traefik para evitar conflictos con otros routers
- Herramientas disponibles:
  - `metabase_cards` - Listar y buscar cards/questions
  - `metabase_card_info` - Obtener detalles de una card
  - `metabase_execute_card` - Ejecutar cards con parámetros
  - `metabase_create_card` - Crear nuevas cards/questions
  - `metabase_update_card` - Actualizar nombre y descripción de cards
  - `metabase_collections` - Listar colecciones
  - `metabase_databases` - Listar bases de datos
  - `metabase_dashboards` - Listar dashboards
  - `metabase_dashboard_info` - Obtener detalles de un dashboard
- Endpoints disponibles:
  - `POST /mcp` - Protocolo MCP para operaciones Metabase
  - `GET /health` - Health check del servicio

## Ejemplos de Uso

Una vez agregados los servidores MCP, podrás usar las herramientas directamente en Claude Code:

**Para Docker:**
```
> Lista todos los contenedores en ejecución
> Muestra los logs del contenedor nucleodocs-mcp-gitea
> Inspecciona el contenedor de traefik
```

**Para Gitea:**
```
> Lista mis repositorios de Gitea
> Muestra los últimos commits del repo nucleoDocs
> Busca issues abiertos en el repositorio analiticaNucleo
```

**Para Metabase:**
```
> Lista todas las cards de Metabase
> Busca cards que contengan "ventas" en el nombre
> Ejecuta la card 123 con parámetros de fecha
> Crea una nueva card con una query SQL
```

**Para Chrome DevTools:**
```
> Abre https://docs.nucleoriofrio.com y toma un snapshot
> Haz click en el botón de login
> Toma una captura de pantalla de la página actual
```

## Desarrollo Local

```bash
cd nuxt4
npm install
npm run dev
```

## Despliegue

El proyecto se despliega automáticamente en `docs.nucleoriofrio.com` mediante Gitea Actions cuando se hace push a la rama `master`.

Variables y secrets configurados correctamente en Gitea.

## Licencia

MIT