FastMCP Todo Server

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.

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!" 🎭✨

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A server that receives todo requests via FastMCP and stores them in MongoDB for processing by the Swarmonomicon todo worker.

Related MCP Servers

Todo List MCP Server
RegiByte
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that provides tools for managing todo items, including creation, updating, completion, deletion, searching, and summarizing tasks.
Last updated -
10
23
TypeScript
MIT License
Coding Todo Server
dennismartis
-
security
F
license
-
quality
An MCP server that provides tools and resources for managing a coding project's todo list, allowing users to view, add, update, and delete todo items with details like priority, status, and tags.
Last updated -
1
Python
FastMCP Todo Server
MadnessEngineering
-
security
F
license
-
quality
A todo management server that receives requests via FastMCP and stores them in MongoDB for processing by the Swarmonomicon todo worker.
Last updated -
7
Python
MCP Todo.txt Integration
guifelix
A
security
F
license
A
quality
A server implementation that enables LLMs to programmatically manage tasks in Todo.txt files using the Model Context Protocol (MCP), supporting operations like adding, completing, deleting, listing, searching, and filtering tasks.
Last updated -
11
12
7
TypeScript

View all related MCP servers