Omnispindle

Omnispindle acts as the coordination layer for the Madness Interactive ecosystem, exposing standardized MCP tools for todo management, lesson capture, and cross-project knowledge work. It supports multiple operation modes (api, hybrid, local, auto) and provides a zero-config authentication flow via Auth0, with the browser handling login and token storage for subsequent requests. You can run the MCP stdio server to enable Claude Desktop and AI agents to interact with Omnispindle through a local, authenticated interface. The server also supports a web/API-first mode and a hybrid mode with a MongoDB backend for persistence. Tools are grouped into loadouts (from basic to full 30-tool configurations) to fit your token budget and security needs. When you launch the stdio server, Claude Desktop or other clients can access the toolset and perform operations like creating todos, capturing lessons, and querying knowledge bases, all within an auditable, project-aware context.

Once running, tools are accessed via the configured loadout. For Claude Desktop integration, you typically run the stdio server locally and point Claude Desktop at it; authentication happens in the browser, and tokens are stored for future sessions. The API/CLI surface allows programmatic control for AI agents, including creating and updating todos, retrieving context across projects, and performing cross-tool orchestration. The system also supports MQTT for real-time cross-system coordination and a web dashboard through Inventorium for humans to monitor activity and context.

Prerequisites:

• Python 3.8+ installed on your system
• Git to clone the repository
• Access to the internet to install Python dependencies

1. Clone the repository:

git clone https://github.com/DanEdens/Omnispindle.git
cd Omnispindle

2. Create and/or activate a Python virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # on Windows use: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Run the MCP stdio server (UI for Claude Desktop and AI agents):

python -m src.Omnispindle.stdio_server

5. Optional: Run the web server (authenticated endpoints) locally for testing:

omnispindle  # if installed as a CLI entry point

6. If you prefer the CLI/auto config approach, you can adjust the environment variables, for example:

export OMNISPINDLE_TOOL_LOADOUT=basic
export OMNISPINDLE_MODE=api

Tips and notes:

• OMNISPINDLE_MODE controls how the server talks to data: api (cloud API only), hybrid (default; API-first with MongoDB as a safety net), local (direct MongoDB access), or auto (let the system pick the fastest path).
• OMNISPINDLE_TOOL_LOADOUT selects which tools are exposed. Use minimal for core functionality and full for the complete suite of 30 tools.
• The web dashboard Inventorium, MQTT real-time coordination, and zero-config Auth0 login are key features to explore once running.
• For Claude Desktop integration, you can point Claude to the stdio server with a config snippet that specifies the command and environment, including TOOL_LOADOUT.
• Security note: The repository includes real auth and infrastructure references; replace credentials and endpoints with your own when deploying to production.
• If you run into issues with authentication, ensure the browser can open the Auth0 login and that tokens are stored locally for subsequent sessions.