Omnispindle - The pen of a Mad Man's Todo List (and probably a few other things 🤷)

A comprehensive FastMCP-based todo management system that serves as a central nervous system for multi-project task coordination. Part of the Madness Interactive ecosystem, Omnispindle combines AI-powered task insights, an MCP toolbelt, and task board to transform chaos into productivity.

Example of a todo output from Claude Sonnet 4.0 without anything being additional being added to the prompt:

  {
    "project": "Omnispindle",
    "description": "ANALYSIS: Node-RED routing issues - need to fix link-in/link-out patterns for project operations to match todo operation patterns",
    "priority": "High",
    "metadata": {
      "ticket": "routing-analysis",
      "tags": [
        "node-red",
        "routing",
        "analysis",
        "link-nodes"
      ]
    }
  }
  Result:
  {"success": true, "todo_id": "af007427-9ebb-4304-8d95-5cafc4a855dd", "message": "Todo created successfully"}

🔮 Architecture Overview

Omnispindle consists of multiple integrated components:

MCP Server Core: FastMCP-based server providing standardized tool interfaces for AI agents
Todomill Projectorium: Task dashboard for visual task management and AI insights
MongoDB Backend: Persistent storage for todos, lessons learned, and audit logs
MQTT Integration: Real-time messaging for cross-system coordination
AI Assistant: Integrated AI suggestions and task analysis capabilities

✨ Key Features

🤖 AI Agent Integration

MCP Tool Interface: Standardized tools for AI agents to create, update, and manage todos
Multi-Project Support: Organize tasks across Madness_Interactive, Omnispindle, Swarmonomicon, and your own.
Intelligent Suggestions: AI-powered task analysis and duplicate detection, refactor suggestion
Lessons Learned: Knowledge capture system for development insights
Automated Workflows: Agent-driven task orchestration and status updates

📊 Visual Dashboard (Todomill Projectorium)

Interactive Interface: Rich web-based dashboard with filtering and sorting, controlable via all the commonly expected AI chatbot features (like "show me the todos for the project 'Omnispindle'")
Real-time Updates: Live task synchronization via MQTT messaging
AI-Enhanced Views: Visual indicators for AI suggestions and insights
Project-based Organization: Sidebar navigation and project-specific views

🔗 System Integration

MQTT Messaging: Pub/sub architecture for real-time coordination
Comprehensive Metadata: Priority, status, project assignment, and custom fields
Audit Logging: Complete history tracking for all task operations
MongoDB Storage: Scalable document storage with flexible querying
Cross-Platform APIs: RESTful and MCP interfaces for diverse integrations
Docker Support: Containerized deployment with docker-compose orchestration

The captured tasks integrate seamlessly with the Todomill Projectorium dashboard, where you can review, refine, and execute them when you're ready to tackle them.

🚀 Quick Start

Installation

Clone the repository:

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

Install with uv (recommended):

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate  # On Unix/macOS
uv pip install -r requirements.txt

Configure environment:

cp .env.example .env
# Edit .env with your MongoDB and MQTT settings

Start with Docker (easiest):
```
docker-compose up -d
```

Configuration

Create a .env file with your settings:

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=todo_app
MONGODB_COLLECTION=todos

# MQTT Configuration
MQTT_HOST=localhost
MQTT_PORT=1883

# AI Integration (optional)
AI_API_ENDPOINT=http://localhost:1234/v1
AI_MODEL=qwen2.5-7b-instruct

🛠 Usage

MCP Integration (Claude Desktop)

Docker Configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "omnispindle": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network", "host",
        "-e", "MONGODB_URI=mongodb://localhost:27017",
        "-e", "MONGODB_DB=swarmonomicon",
        "-e", "MQTT_HOST=localhost",
        "danedens31/omnispindle:latest"
      ]
    }
  }
}

Docker Compose Configuration

{
  "mcpServers": {
    "omnispindle": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/your/.env",
        "--network", "omnispindle_default",
        "danedens31/omnispindle:latest"
      ]
    }
  }
}

Local Development Configuration

{
  "mcpServers": {
    "omnispindle": {
      "command": "python",
      "args": ["-m", "src.Omnispindle"],
      "cwd": "/path/to/Omnispindle",
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017",
        "MONGODB_DB": "swarmonomicon",
        "MQTT_HOST": "localhost"
      }
    }
  }
}

Available MCP Tools

The server exposes the following tools for AI agents:

add_todo_tool - Create new tasks with metadata
query_todos_tool - Search and filter tasks
update_todo_tool - Modify existing tasks
mark_todo_complete_tool - Complete tasks
list_project_todos_tool - Get tasks by project
add_lesson_tool - Capture lessons learned
search_lessons_tool - Query knowledge base
mqtt_publish_tool - Send real-time messages
mqtt_get_tool - Retrieve MQTT messages

Starting the MCP Server

# Development mode
python -m src.Omnispindle

# Production mode
uvicorn src.Omnispindle.server:app --host 0.0.0.0 --port 8000

Using MCP Tools (for AI Agents)

The server exposes standardized MCP tools that AI agents can call:

# Example: AI agent creating a todo
await add_todo_tool(
    description="Implement user authentication",
    project="Omnispindle",
    priority="High",
    target_agent="developer",
    metadata={"ticket": "AUTH-123", "tags": ["security", "backend"]}
)

# Example: AI agent querying todos
results = await query_todos_tool(
    query_or_filter="project:Omnispindle",
    fields_or_projection="all",
    limit=50
)

API Usage

from fastmcp import FastMCPClient

# Connect to Omnispindle
client = FastMCPClient("http://localhost:8000")

# Create a new todo
response = await client.call_tool("add_todo_tool", {
    "description": "Fix critical bug in authentication",
    "project": "Madness_interactive",
    "priority": "High"
})

# Get project todos
todos = await client.call_tool("list_project_todos_tool", {
    "project": "Omnispindle",
    "limit": 10
})

Node-RED Dashboard

Access the dashboard at http://localhost:1880/ui
Import flows from Todomill_projectorium/ExportedNodeRedTabs/
Configure MQTT connection to point to your Omnispindle instance

📁 Project Structure

Omnispindle/
├── src/Omnispindle/           # Main MCP server implementation
│   ├── __init__.py           # Tool registration and initialization
│   ├── server.py             # FastMCP server core
│   ├── tools.py              # Todo and lesson management tools
│   ├── ai_assistant.py       # AI integration and suggestions
│   ├── scheduler.py          # Smart scheduling features
│   ├── mqtt.py               # MQTT messaging integration
│   └── todo_log_service.py   # Audit logging service
├── Todomill_projectorium/     # Node-RED dashboard subrepo
│   ├── ExportedNodeRedTabs/  # Node-RED flow definitions
│   ├── JavascriptFromFunctionNode/  # Dashboard logic
│   ├── HtmlFromTemplateNode/ # UI templates
│   └── UIComponents/         # Reusable UI components
├── tests/                    # Test suite
├── config/                   # Configuration files
├── docs/                     # Documentation
├── docker-compose.yml        # Container orchestration
└── pyproject.toml           # Project metadata

🔧 Development

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=src tests/

# Run specific tests
pytest tests/test_todo_log.py -v

Working with the Node-RED Dashboard

Edit JavaScript/HTML files in Todomill_projectorium/
Copy changes to Node-RED editor
Export updated flows to JSON files
Commit both the extracted files and JSON exports

Adding New MCP Tools

Define the tool function in src/Omnispindle/tools.py
Register the tool in src/Omnispindle/__init__.py
Add tests in tests/
Update documentation

🌐 Integration Examples

Swarmonomicon Integration

# Omnispindle works with Swarmonomicon for distributed task processing
from swarmonomicon import TaskAgent

agent = TaskAgent("omnispindle-worker")
agent.register_mcp_server("http://localhost:8000")

# Agent can now create and manage todos via MCP
await agent.execute_task("create_todo", {
    "description": "Process data pipeline",
    "project": "Swarmonomicon"
})

GitHub Issues Sync

# Sync todos with GitHub issues
todo_id = await add_todo_tool(
    description="Fix authentication bug",
    project="Madness_interactive",
    metadata={"github_issue": 1234}
)

MQTT Event Streaming

# Subscribe to todo events
mosquitto_sub -t "omnispindle/todos/+/+"

# Publish todo creation request
mosquitto_pub -t "omnispindle/todos/create" -m '{
    "description": "Deploy to production",
    "project": "Omnispindle",
    "priority": "High"
}'

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: pytest tests/
Submit a pull request

Development Guidelines

Follow PEP 8 for Python code style
Write tests for new features
Update documentation for API changes
Use semantic commit messages

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

Madness Interactive - Parent project ecosystem
Swarmonomicon - Distributed task processing system
FastMCP - Model Context Protocol server framework

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/ directory

"In the chaotic symphony of development tasks, Omnispindle conducts with AI-powered precision!" 🎭✨

Omnispindle