nano-core - Modular Discord Bot Core

                                 █
                                █ █
                            ██████ ███
                                ▓░▓███▓███
                    ▒     ███        ▓░█  █
                          ███  ████▒    ██  █    ▓
                       ██████████▒██████  █    ▒   ████ ██
                  ████████▓██▓███████▓▓███          █████
            ▒███████▓ ▒███▓███      ████████          ███
          ▒██  █▒░▒█████          █         ████     █ ███
       ███▓  ███▓███        █████░░      ░░  ░█████      ██
     █████░░████░█        ░            ▒  ██ █  ███   █  ███
 █▓█▒░█▒░  ░ █░░██       ████  ▒█▒▓██▒       ██ ██▓███ ██░▓█
█░        ███▒░██   █ █  ████  ███████   █   ░  ████   █ █
         ███▒▒██  ██▒  ███     ███ ░██▒  ██ ░   ████  █ ██ ██
         ██▒░█▓     ░████░█    ███  ██▒   ██ ░▓  ███       ██
         █▒ ░█  ▓   █ ██ ▓▓█   ███  ██▒  ▓██  █ ▒███ █  █ ████
          ██░█   ░ █ ███  ▒    ███  ██▒   █      ██ ▒   █  █▒███
           ███ █  █  ████      ███  ██▒  █   ████████▒█   ██ █ █
            ██ ▒█   ██░███▓█   ███  ██▒    █   ███  █   ▒███ ██
              ░▒ █   ██▓█      ███  ██▒    █ ███ ▒▒      █▒▒█▓█
            ██▒░█  ███████ █        ██▒  ░████ █      █████▒██       ░█
             ▓█ ░     █░ █ █▒░████  ██▒  ███  ▓      ███▒ ▒██   ░ █▒▓█
            ███  █    ████  ░▒▒░░   ██▒     █        █▒██████░██████
             ███ █      ████████░   ▒▒   ▒    █ ██████░▓████ ███
             ██▓█     ░░░░░█████░         █     ██▒▓▒████
             ▓████         ███████████▓███████████████
             █  ▓  █   ▒     ▓ █████████▓█ ████████████
                    ▓▓       █▒█       ██████    █  ██
                        █      ▓ █   ▒▒
                          █  ▒   █ █░█        █
                     ▒        ██  ██    █
                                ██▓ █████▓███ ███
                                   ▒█ ██  ░████
                                         █▓█

                                              █
  

nano-core

Cyber Code Syndicate (CCS) desarrolla software como una herramienta para el aprendizaje, la colaboración y la práctica tecnológica ética. Nuestros proyectos se guían por principios de autonomía del usuario, transparencia, accesibilidad y libertad de elección, priorizando a las personas por encima de las plataformas. CCS es una iniciativa centrada en la comunidad, enfocada en la educación, el conocimiento compartido y la participación inclusiva; está abierta y es bienvenedora para todas las personas.

CCS no impone una ideología única ni un modelo de licenciamiento. En su lugar fomentamos la toma de decisiones informada, el pensamiento modular y el desarrollo responsable, confiando en que los contribuyentes elijan cómo se construye, comparte y extiende el software. Este proyecto forma parte de esa visión más amplia.

Te invitamos a explorar la comunidad CCS, contribuir en las formas que mejor se adapten a ti y leer el CCS Vision Paper para comprender mejor los principios y valores que guían nuestro trabajo.

nano-core es un core ligero y modular para Discord bots, licenciado bajo la Mozilla Public License v2.0 (MPL v2). Proporciona la infraestructura básica necesaria para construir bots de Discord totalmente personalizados, con un enfoque en la extensibilidad, adaptabilidad y la libertad del usuario. La MPL v2 preserva la libertad del software en el core, pero permite que contribuyentes y comunidades desarrollen, compartan e inyecten nuevas funcionalidades bajo cualquier licencia.

¿Por qué nano-core? | El problema y nuestra solución

La mayoría de los bots de Discord actuales son pesados, cargados con innumerables funciones que nunca utilizarás, o están bloqueados tras paywalls y suscripciones premium. Para obtener la funcionalidad que necesitas, a menudo terminas añadiendo varios bots, saturando tu Server y dificultando la gestión y el control de su configuración. Las funcionalidades suelen ser monolíticas, difíciles de eliminar o adaptar, y raramente existen comunidades alrededor de funcionalidades individuales.

nano-core resuelve esto.

En lugar de descargar un bot sobrecargado innecesariamente, nano-core te anima a desplegar tu propio bot e inyectar exactamente las funcionalidades que deseas, (tal como instalar paquetes en Linux). Mediante un sistema sencillo basado en carpetas y comandos, puedes agregar, quitar o reinstalar funcionalidades (modules) en minutos. Cada module puede tener su propia comunidad, documentación y licencia, haciendo que nano-core sea altamente personalizable, modular y a future proof. Construye el bot que necesitas, no más gasto innecesario de dinero, recursos del Server o esfuerzo en funciones que no deseas.

Licenciamiento y principios comunitarios

El core de nano-core es software libre, protegido por la Mozilla Public License v2.0. Esto garantiza que todo el mundo pueda usar, estudiar, modificar y compartir el código base. Al mismo tiempo, los modules/extensions (plugins, commands, events) pueden usar cualquier licencia, reflejando la dedicación de CCS a la autonomía y la participación inclusiva. Los contribuidores solo deben declarar claramente la licencia de sus modules.

Estructura del repositorio:

• Archivos core (command/event handlers, injection system): MPL v2.0
• Modules/extensions: Any license (must specify in folder or header)

Sección de licenciamiento:

Todos los archivos del core están licenciados bajo la Mozilla Public License, version 2.0 (MPL v2.0). Los modules y extensions pueden usar cualquier licencia. Por favor incluye un archivo LICENSE o un encabezado en cada module/extension. Este modelo asegura un core de software libre y respeta contribuciones diversas, siguiendo los principios de CCS sobre autonomía del usuario, colaboración y aprendizaje.

Primeros pasos

Esta seccion es el arranque rapido; la referencia completa de cada comando, clave de configuracion y servicio esta en el manual.

Requisitos: Node.js >= 20 y una aplicacion de bot creada en el Discord Developer Portal.

1. Clona e instala:

   git clone https://github.com/ccs-devhub/nano-core.git
   cd nano-core && npm install
       

2. Secretos (solo por entorno, nunca en JSON):

   cp .env-template .env
   # DISCORD_TOKEN: portal > Bot > Reset Token
   # CLIENT_ID:     portal > General Information > Application ID
       

3. Configura el bot — abre la ventana de configuracion o edita nano.config.json directamente:

   cp nano.config-template.json nano.config.json
   npm run ui    # Dashboard / Config / Modules / Store / Logs
       

   En Config define el nombre del bot, el dev_guild_id (tu server de pruebas: los slash commands aparecen al instante), intents, base de datos y logging. Colores, paleta y logo del banner y de la ventana viven en nano.style.toml.

4. Invita el bot a tu server: portal > OAuth2 > URL Generator con los scopes bot + applications.commands y los permisos que tu bot necesite.

Verificar que todo funciona

npm run doctor

Revisa cada capa sin conectar el bot: version de Node, config valida, secretos presentes, token autenticando contra la API de Discord, base de datos, nano-store alcanzable, carga de modules e intents (avisa si hay privilegiados por activar en el portal).

Con todo en verde, arranca y prueba en Discord:

npm run dev

/synapse vitals (salud del core y los modules), /synapse scan (radiografia del server), /module list (estado de los modules).

Para desarrollo del core: npm run lint, npm run build, npm run test.

Gestionar modules

npm run module -- search             # catalogo validado (nano-store)
npm run module -- install <name>     # instala version exacta revisada
npm run module -- add ./modules/x    # module local propio
npm run module -- add <npm-pkg> --allow-external   # NO revisado: bajo tu riesgo
npm run module -- enable|disable <name>
npm run module -- outdated           # versiones nuevas validadas
npm run module -- list

Tras activar o desactivar modules, ejecuta /module sync en Discord para refrescar los slash commands. La guia completa para crear modules esta en MODULE-SPEC y las leyes del core en docs/rules/.

El puente MCP (maneja el bot desde una IA)

El module mcp (incluido) corre un servidor de Model Context Protocol dentro del proceso del bot, para que clientes MCP (agentes de IA, editores) operen el bot como tools: snapshots del server, listados de canales y roles, salud, mensajes recientes — y, solo si lo permites explicitamente, envio de mensajes y moderacion.

1. Crea el token de acceso (una sola vez):

   echo "NANO_MCP_TOKEN=$(openssl rand -hex 32)" >> .env
       

2. Verifica que ./modules/mcp este en la lista modules de nano.config.json (la ventana Modules de npm run ui tambien sirve) y arranca el bot:

   npm run dev
       

   El log muestra MCP endpoint listening on http://127.0.0.1:3777/mcp.

3. Conecta un cliente MCP. El repo incluye .mcp.json — los clientes que soportan ese formato detectan el servidor automaticamente; solo exporta el token en la shell antes de arrancar el cliente:

   export NANO_MCP_TOKEN=$(grep '^NANO_MCP_TOKEN=' .env | cut -d= -f2)
       

   El cliente debe mostrar nano-core conectado. Despues solo pregunta: “en que servers esta el bot”, “hazme un snapshot de mi server”, “esta sano el bot”. Cualquier otro cliente MCP funciona con la misma URL mas el header Authorization: Bearer.

El endpoint solo escucha en loopback y no responde nada sin el token. Las tools de escritura (mensajes, DMs, canales, threads, webhooks, invites, roles, eventos programados) y de moderacion (kick/ban/timeout) vienen APAGADAS; se activan por bot con allow_write / allow_moderation en el panel mcp de la TUI. Los gates se aplican en vivo en la siguiente peticion — sin reiniciar; reconecta el cliente si cachea la lista de tools. Las tools sin permiso ni siquiera son visibles para los clientes. Revisa el estado del endpoint con /module health mcp (solo administradores). Referencia completa: MANUAL, “The MCP bridge”.

Documentacion

Toda la documentacion es parte del repositorio:

• MANUAL — la referencia completa: cada comando (doctor, dev, ui, module), cada clave de nano.config.json y nano.style.toml, la TUI, el store, el puente MCP, los Discord commands y los servicios para autores de modules.
• MODULE-SPEC — el contrato completo de un NanoModule, con modules/synapse/ como implementacion de referencia.
• docs/rules/ — las leyes de cada subsistema (convenciones, servicios, dispatcher, store, TUI, el dashboard web, autoria de modules).
• nano-store — el registro curado y su proceso de submission (SUBMISSIONS.md).

Comunidad y contribuciones

nano-core es community-driven. Cualquiera puede contribuir mejoras al core (bajo MPL v2.0) o modules (bajo la licencia que elija). Los modules validados se publican en nano-store via pull request. Comparte tus modules, ayuda a otros a aprender y unete a las discusiones en CCS.

Invitación final

No te conformes con bots genéricos y recursos desperdiciados, configura el Discord bot más personalizable y modular, adaptado a tus necesidades, con la comunidad CCS apoyando su trayecto. Tu defines las características, el licenciamiento y el destino de su bot.