Omnispindle

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

1. Clone the repository:

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

2. 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
   

3. Configure environment:

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

4. 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

1. Access the dashboard at http://localhost:1880/ui
2. Import flows from Todomill_projectorium/ExportedNodeRedTabs/
3. 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

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

Adding New MCP Tools

1. Define the tool function in src/Omnispindle/tools.py
2. Register the tool in src/Omnispindle/__init__.py
3. Add tests in tests/
4. 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

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: pytest tests/
5. 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 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: directory

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