Omnispindle

Un sistema de tareas que salió maravillosamente, e intencionalmente, mal.

Omnispindle es la columna vertebral de coordinación del ecosistema Madness Interactive: un servidor Python FastMCP con 33 herramientas que permite a los agentes de IA gestionar tareas, capturar conocimientos, coordinar sesiones y navegar por todo el taller desde una interfaz única y estandarizada. Empaquetado en PyPI. Integrado con Auth0. Se ejecuta en cualquier lugar donde exista una configuración de MCP.

Comenzó como "hagamos las tareas correctamente". Se convirtió en el sistema nervioso central para un laboratorio de desarrollo asistido por IA de múltiples proyectos. Ambas cosas están bien.

Lo que realmente hace

Gestión de tareas — la parte aburrida que permite todo lo demás. Los agentes pueden crear, consultar, actualizar, completar y auditar tareas en cualquier proyecto del ecosistema con metadatos completos, prioridad, seguimiento del agente objetivo y detección de cambios.

Captura de conocimientos — las lecciones aprendidas se almacenan con metadatos de idioma, tema y etiquetas. Se pueden buscar mediante expresiones regulares, texto o incrustaciones vectoriales. La memoria institucional no se evapora cuando termina la conversación.

Seguimiento de sesiones — las sesiones de trabajo de IA en Inventorium se pueden bifurcar, generar, vincular a tareas y rastrear a través de un árbol genealógico completo. Cada hilo de trabajo tiene un padre y un linaje.

Búsqueda semántica — find_relevant utiliza incrustaciones vectoriales para mostrar tareas y lecciones por significado, no solo por palabras clave. get_context_bundle le da a un agente la imagen completa del proyecto en una sola llamada.

Related MCP server: Coding Todo Server

Instalación

pip install omnispindle

Comandos CLI disponibles después de la instalación:

• omnispindle-stdio — Servidor MCP stdio para Claude Desktop

• omnispindle / omnispindle-server — Servidor web HTTP para puntos finales autenticados

Claude Desktop (sin configuración)

Añadir a claude_desktop_config.json:

{
 "mcpServers": {
 "omnispindle": {
 "command": "omnispindle-stdio",
 "env": {
 "OMNISPINDLE_MODE": "api",
 "OMNISPINDLE_TOOL_LOADOUT": "basic",
 "MCP_USER_EMAIL": "you@example.com"
 }
 }
 }
}

La primera llamada a la herramienta abre su navegador para el inicio de sesión de Auth0. El token se guarda localmente. Eso es todo.

Desarrollo

git clone https://github.com/DanEdens/Omnispindle.git
cd Omnispindle
pip install -r requirements.txt
python -m src.Omnispindle.stdio_server

Herramientas

La carga completa es de 33 herramientas en 6 categorías. Controle lo que está disponible — y el presupuesto de tokens de su agente — con OMNISPINDLE_TOOL_LOADOUT.

Gestión de tareas (9 herramientas)

Conocimiento / Lecciones (7 herramientas)

Sesiones de Inventorium (8 herramientas)

Contexto y búsqueda (2 herramientas)

Sistema / Administración (5 herramientas)

Código personalizado (1 herramienta)

Cargas de herramientas

Establezca OMNISPINDLE_TOOL_LOADOUT para controlar lo que se registra:

Modos de operación

Establecido mediante OMNISPINDLE_MODE:

• api — Llamadas HTTP a madnessinteractive.cc/api. No se necesita base de datos local. Ideal para configuraciones nativas en la nube o multiusuario.

• hybrid (predeterminado) — Primero API con respaldo de MongoDB. Confiable cuando la red no lo es.

• local — Solo conexiones directas a MongoDB. Bueno para desarrollo sin conexión.

• auto — Evalúa ambos y elige el más rápido.

Autenticación

Flujo de dispositivo sin configuración: En la primera llamada a la herramienta, se abre una ventana del navegador para el inicio de sesión de Auth0. El token se guarda localmente. Todas las llamadas posteriores se autentican sin ninguna configuración.

Configuración manual del token (opcional):

python -m src.Omnispindle.token_exchange

Variables de entorno:

• MADNESS_AUTH_TOKEN o AUTH0_TOKEN — JWT del flujo de dispositivo Auth0

• MCP_USER_EMAIL — requerido para el aislamiento de datos por usuario

• MADNESS_API_URL — anular la base de la API (predeterminado: https://madnessinteractive.cc/api)

Todos los datos están limitados por usuario a nivel de base de datos. Tus tareas siguen siendo tuyas.

Configuración

# Operation mode
OMNISPINDLE_MODE=hybrid # api | hybrid | local | auto
OMNISPINDLE_TOOL_LOADOUT=basic # see loadouts table above
OMNISPINDLE_FALLBACK_ENABLED=true
OMNISPINDLE_VALIDATE_PROJECT_NAMES=false # optional: enable slower DB-backed project validation

# Authentication
MADNESS_AUTH_TOKEN=<jwt>
MCP_USER_EMAIL=you@example.com

# Local/hybrid database
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=swarmonomicon

# Real-time events
MQTT_HOST=localhost
MQTT_PORT=1883

Ecosistema

Omnispindle es la capa de interfaz de IA. El resto del taller:

Inventorium — Panel web de React y espacio de trabajo espacial 3D SwarmDesk. Los humanos usan esto. Lee tareas y sesiones a través de la API REST directamente, no MCP, que es estrictamente para agentes de IA. Si estás haciendo clic en botones, estás en Inventorium. Si eres un agente, estás llamando a herramientas MCP.

cartogomancy — Herramienta de análisis de código base JS/TS (npm install -g @madnessengineering/cartogomancy). Apúntalo a cualquier proyecto de JavaScript o TypeScript; obtén un rico mapa JSON de estructura, complejidad, git blame y referencias cruzadas. Alimenta ese mapa a SwarmDesk y tu código base se convierte en una ciudad 3D por la que puedes caminar.

SwarmDesk — La capa de visualización espacial 3D dentro de Inventorium. Tareas, sesiones y mapas de código de cartogomancy renderizados como arquitectura explorable. Tu proyecto como un lugar, no como una lista.

MadnessVR — Versión de realidad virtual de Quest 2 de SwarmDesk. Ponte el casco, camina por tu código base como geometría real. Esto está en la hoja de ruta, no en las notas de la versión. Pero el plan existe y es detallado.

Cogwyrm — Compañero de chat de IA integrado en el ecosistema. Utiliza herramientas Omnispindle MCP durante las conversaciones para leer y escribir contexto compartido.

Swarmonomicon — La capa de base de datos central. MongoDB, base de datos swarmonomicon. Todo lo persistente vive aquí.

La regla de arquitectura

UI (Inventorium, forms, dashboards) → REST API → Database
AI agents (Claude, Cogwyrm, any MCP client) → MCP tools → Backend → Database

Nunca dirijas la interfaz de usuario a través de MCP. Nunca llames a la API REST directamente desde un agente de IA. La separación es intencional y estructural.

Desarrollo

# Tests
pytest tests/

# Stdio server (Claude Desktop)
python -m src.Omnispindle.stdio_server

# Web server
python -m src.Omnispindle

# Check tool count
python -c "from src.Omnispindle.tool_loadouts import _BASE_LOADOUTS; print(len(_BASE_LOADOUTS['full']), 'tools in full loadout')"

Publicación en PyPI

# Build and check
python -m build
python -m twine check dist/*

# Publish
python -m twine upload dist/*

Privacidad y seguridad

Este repositorio contiene configuraciones de Auth0 e infraestructura como código para nuestro ecosistema. Es de código abierto para aprender y bifurcar, no para implementar tal cual.

Si realmente estás ejecutando esto para tu propia configuración:

1. Bifúrcialo

2. Reemplaza todos los proveedores de autenticación y credenciales

3. Apúntalo a tu propio dominio y base de datos

4. Revisa los permisos de las herramientas (somos permisivos por defecto)

Este es un sistema de trabajo para nuestro laboratorio. Para el tuyo, hazlo tuyo.

Filosofía

La mayoría de la gente construye una aplicación de tareas con 5 funciones. Nosotros construimos una con 33 herramientas MCP, tres modos de operación, árboles genealógicos de sesiones, incrustaciones vectoriales, OAuth sin configuración y una hoja de ruta que incluye caminar por tu código en realidad virtual.

Esta es la cantidad correcta de complejidad. Cada pieza es estructural.

Trabajando ahora:

• Gestión de tareas para agentes de IA: robusta, auditada, por usuario

• Captura de conocimiento persistente entre proyectos

• Seguimiento de sesiones con linaje completo

• Búsqueda semántica mediante incrustaciones vectoriales

• Auth0 sin configuración que no requiere una guía de configuración

Próximamente:

• MadnessVR: SwarmDesk en Quest 2

• Enseñar ingeniería de prompts a través de mecánicas de inventario estilo Terraria

• cartogomancy → SwarmDesk → VR como un pipeline continuo

Escribimos código cuidadoso. No tenemos miedo de superar los límites cuando es práctico.

*"¿Sobre-diseñado? Tal vez. ¿Poco ambicioso? Nunca."

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers