What is Fastmcp Todo Server

fastmcp-todo-server is a simple MCP server designed to facilitate the addition of items to a MongoDB todo list, specifically for the Swarmonomicon project.

Use cases

Use cases include adding tasks to a todo list, managing task priorities, and integrating with real-time processing systems in collaborative environments.

How to use

To use fastmcp-todo-server, clone the repository, set up a virtual environment, install dependencies, configure your MongoDB settings, and start the server. You can add todos using the FastMCP Python client or directly via MQTT.

Key features

Key features include FastMCP server for receiving todo requests, MongoDB integration for storage, compatibility with Swarmonomicon todo worker, and a Python-based implementation.

Where to use

fastmcp-todo-server can be used in project management and task tracking applications, particularly those utilizing the Swarmonomicon framework.

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:

🔮 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 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!” 🎭✨