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

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

MCP Gitea Server

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

MCP Chrome DevTools

claude mcp add chrome-devtools npx -- chrome-devtools-mcp@latest --isolated=true

Scopes Disponibles

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
claude mcp add chrome-devtools --scope project npx -- chrome-devtools-mcp@latest --isolated=true

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
claude mcp add chrome-devtools --scope user npx -- chrome-devtools-mcp@latest --isolated=true

Verificación

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

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

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