Nucleo Docs

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

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

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

Conexión a Claude Code

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

1. MCP Docker Server

claude mcp add --transport http nucleodocs-docker https://docker.nucleoriofrio.com/mcp

2. MCP Gitea Server

claude mcp add --transport http nucleodocs-gitea https://gitea.nucleoriofrio.com/mcp

Verificación

Después de agregar los servidores, puedes verificar que estén configurados correctamente:

# 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

# Dentro de Claude Code, verificar el estado
/mcp

Uso

Una vez agregados, 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

Scopes disponibles

Si quieres compartir estos servidores con todo el equipo, puedes agregarlos con scope project:

# Para compartir con el equipo (crea .mcp.json en el proyecto)
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

O si los quieres disponibles en todos tus proyectos personales:

# Para uso personal en todos los proyectos
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

Desarrollo Local

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