Omnispindle

by madnessengineering

10 stars

411 downloads

Not rated

GitHub Website

About

A todo management system designed for coordinating tasks across multiple projects, utilizing MongoDB and MQTT.

Details

Author: madnessengineering
GitHub stars: 10
Downloads: 411
Categories: Productivity, Project Management, Other, Automation
Tags: #mongodb

- 38 MCP tools across seven categories for comprehensive task and knowledge management.
- Tool loadouts control which tools are registered, optimizing token usage.
- Zero-config Auth0 device flow for automatic authentication on first use.
- Semantic search via vector embeddings for relevant todos and lessons.
- Session genealogy allows tracing work through parent-child relationships.
- Quest system for managing multi-step epic goals with progress tracking.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Omnispindle

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

From the repository

Install via pip install omnispindle, then run the CLI command omnispindle-stdio for Claude Desktop or omnispindle for an HTTP web server. Add the server configuration to claude_desktop_config.json with environment variables for mode and tool loadout. The first tool call opens a browser for Auth0 login; tokens are saved locally. Development setup involves cloning the repository, installing dependencies, and running python -m src.Omnispindle.stdio_server.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "omnispindle": {
            "omnispindle-madnessengineering": {
                "command": "python",
                "args": [
                    "-m",
                    "src.Omnispindle.stdio_server"
                ]
            }
        }
    }
}

McpServers

{
    "omnispindle-madnessengineering": {
        "command": "python",
        "args": [
            "-m",
            "src.Omnispindle.stdio_server"
        ]
    }
}

A todo system that went wonderfully, intentionally wrong.

Omnispindle is the coordination spine of the Madness Interactive ecosystem — a Python FastMCP server with 38 tools that lets AI agents manage tasks, capture knowledge, coordinate sessions, track epic goals (quests), and navigate the whole workshop from a single, standardized interface. PyPI packaged. Auth0 integrated. Runs anywhere a MCP config lives.

It started as "let's do todos properly." It became the central nervous system for a multi-project AI-assisted development lab. Both of these things are fine.

Todo management— the boring part that enables everything else. Agents can create, query, update, complete, and audit tasks across any project in the ecosystem with full metadata, priority, target agent tracking, and change detection.

Knowledge capture— lessons learned get stored with language, topic, and tag metadata. Searchable by regex, text, or vector embedding. The institutional memory doesn't evaporate when the conversation ends.

Session tracking— AI work sessions in Inventorium can be forked, spawned, linked to todos, and traced through a full genealogy tree. Every thread of work has a parent and a lineage.

Semantic search—find_relevantuses vector embeddings to surface todos and lessons by meaning, not just keywords.get_context_bundlegives an agent the full project picture in one call.

- omnispindle-stdio— MCP stdio server for Claude Desktop
- omnispindle/omnispindle-server— HTTP web server for authenticated endpoints

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

First tool call opens your browser for Auth0 login. Token saves locally. That's it.

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

Full loadout is 38 tools across 7 categories. Control what's available — and your agent's token budget — withOMNISPINDLE_TOOL_LOADOUT.

SetOMNISPINDLE_TOOL_LOADOUTto control what's registered:

- api— HTTP calls tomadnessinteractive.cc/api. No local database needed. Best for cloud-native or multi-user setups.
- hybrid(default)— API-first with MongoDB fallback. Reliable when the network isn't.
- local— Direct MongoDB connections only. Good for offline development.
- auto— Benchmarks both and picks the faster one.

Zero-config device flow: On first tool call, a browser window opens for Auth0 login. Token is saved locally. All subsequent calls are authenticated without any configuration.

python -m src.Omnispindle.token_exchange

- MADNESS_AUTH_TOKENorAUTH0_TOKEN— JWT from Auth0 device flow
- MCP_USER_EMAIL— required for per-user data isolation
- MADNESS_API_URL— override API base (default:https://madnessinteractive.cc/api)

All data is scoped per user at the database level. Your todos stay yours.

# 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

Omnispindle is the AI interface layer. The rest of the workshop:

Inventorium— React web dashboard and SwarmDesk 3D spatial workspace. Humans use this. It reads todos and sessions via the REST API directly — not MCP, which is strictly for AI agents. If you're clicking buttons, you're in Inventorium. If you're an agent, you're calling MCP tools.

cartogomancy— JS/TS codebase analysis tool (npm install -g @madnessengineering/cartogomancy). Point it at any JavaScript or TypeScript project; get back a rich JSON map of structure, complexity, git blame, and cross-references. Feed that map to SwarmDesk and your codebase becomes a 3D city you can walk through.

SwarmDesk— The 3D spatial visualization layer inside Inventorium. Todos, sessions, and cartogomancy code maps rendered as explorable architecture. Your project as a place, not a list.

MadnessVR— Quest 2 VR version of SwarmDesk. Put on the headset, walk through your codebase as actual geometry. This one is on the roadmap, not the release notes. But the plan exists and it's detailed.

MadQTT— Live terminal TUI for the workshop's MQTT + MongoDB event stream (pip install madqtt). Agent sessions, tool calls, and failures from every machine, readable in real time instead of a firehose.

Madness Desktop— GitHub Desktop fork wired into the workshop: composable git-hook loadouts, MQTT commit events shared across machines, and live workshop todos inside the git client.

Swarmonomicon— The core database layer. MongoDB,swarmonomicondatabase. Everything persistent lives here.

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

Never route UI through MCP. Never call the REST API directly from an AI agent. The separation is intentional and load-bearing.

# 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')"

# Build and check python -m build python -m twine check dist/ # Publish python -m twine upload dist/

This repo contains Auth0 configs and infrastructure-as-code for our ecosystem. It's open source for learning and forking — not for deploying as-is.

If you're actually running this for your own setup:
- Fork it
- Replace all auth providers and credentials
- Point it at your own domain and database
- Review tool permissions (we're permissive by default)

This is a working system for our lab. For yours, make it yours.

- Todo management for AI agents — robust, audited, per-user
- Persistent knowledge capture across projects
- Session tracking with full lineage
- Semantic search via vector embeddings
- Zero-config Auth0 that doesn't require a setup guide

- MadnessVR: SwarmDesk on Quest 2
- Teaching prompt engineering through Terraria-style inventory mechanics
- cartogomancy → SwarmDesk → VR as one continuous pipeline

We write careful code. We're not afraid to push the boundaries when it's practical.

"Over-engineered? Maybe. Under-ambitious? Never."

Keep teams & agents coordinated automatically

Connect to the Taskade platform via MCP. Access tasks, projects, workflows, and AI agents in real-time through a unified workspace and API.

The Outcome Backcasting MCP is a strategic planning tool that helps you work backwards from a desired future outcome to identify the specific steps, resources, and dependencies needed to achieve your goals. Unlike traditional forward planning, backcasting starts with your end goal and creates a reverse roadmap to get there.

Interact with the ClickUp API to manage tasks, lists, and spaces, automating project planning and workflows.

Apify-hosted MCP server for ClickUp with 20 tools. Tasks, spaces, folders, lists, views, docs, and custom fields. No local setup needed.

Interact with Jira to manage issues, projects, and workflows using the Jira Cloud Platform REST API.

An MCP server for interacting with the Jira API to manage projects, issues, and workflows.

About AI-powered Jira CLI and MCP server for humans and agents manage issues, sprints, boards with interactive wizards, multi-provider AI

A Python monorepo for AI-powered project management and productivity servers, utilizing the Claude API.

Manage complex AI agent workflows with a Kanban-based task management system.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Install

More like this

Sequential Thinking

Time

Filesystem

EverArt

Google Drive

GitLab