A charming and extensible MCP server for managing time-stamped todoodle items with MongoDB integration and user isolation. Built with TypeScript and the Model Context Protocol, designed for seamless integration with LibreChat and SMS user management.
The server supports two storage backends through a unified interface:
JSON Storage (Development)
MongoDB Storage (Production)
UserAwareTodoodlesManager Class
Enhanced Data Model
interface TodoodleItem {
id: string; // Sequential numeric ID (per user)
text: string; // Todoodle content
createdAt: string; // ISO timestamp
completed: boolean; // Completion status
completedAt?: string; // Completion timestamp
timeToComplete?: number; // Time taken in milliseconds
category?: string; // Optional category for organization
priority: 'low' | 'medium' | 'high' | 'urgent'; // Priority level
dueDate?: string; // Optional due date in ISO format
}
interface TodoodleData {
items: TodoodleItem[];
metadata: {
lastId: number; // Per-user ID counter
version: string; // Schema version
updatedAt: string; // Last update timestamp
totalItems: number; // Total item count
completedItems: number; // Completed item count
};
}
User Context Integration
Web UI Framework Integration
mcp-web-ui frameworkCreate a .env file in the server root directory:
# ===== STORAGE CONFIGURATION =====
# Storage type: 'json' or 'mongodb'
MCP_STORAGE_TYPE=mongodb
# ===== JSON FILE STORAGE (when MCP_STORAGE_TYPE=json) =====
TODOS_FILE_PATH=./todoodle.json
# ===== MONGODB STORAGE (when MCP_STORAGE_TYPE=mongodb) =====
MONGODB_CONNECTION_STRING=mongodb://localhost:27017/LibreChat
MONGODB_DATABASE=LibreChat
MONGODB_COLLECTION=user_todoodles
MCP_MONGODB_TIMEOUT=10000
MCP_MONGODB_RETRIES=3
# ===== USER ISOLATION =====
MCP_USER_BASED=true # Enable user-based storage
MCP_USER_ID=${USER_ID} # User ID (passed by LibreChat)
# ===== ENCRYPTION (Optional) =====
CREDS_KEY=your-64-character-hex-encryption-key
# ===== WEB UI CONFIGURATION =====
MCP_WEB_UI_BASE_URL=http://localhost # Base URL for web UI access (use Tailscale URL for remote access)
# ===== DEVELOPMENT/DEBUGGING =====
MCP_DEBUG=true # Enable debug logging
MCP_BACKUP_ENABLED=true # Enable automatic backups (JSON only)
MCP_BACKUP_MAX_FILES=5 # Maximum backup files to keep
Development (JSON Storage):
MCP_STORAGE_TYPE=json
TODOS_FILE_PATH=./todoodle.json
MCP_USER_BASED=false
MCP_DEBUG=true
Production (MongoDB with LibreChat):
MCP_STORAGE_TYPE=mongodb
MONGODB_CONNECTION_STRING=mongodb://localhost:27017/LibreChat
MONGODB_DATABASE=LibreChat
MONGODB_COLLECTION=user_todoodles
MCP_USER_BASED=true
MCP_USER_ID=${USER_ID}
Add to your librechat.yaml:
mcpServers:
todoodles:
type: stdio
command: node
args:
- "../Sizzek/mcp-servers/todoodles/dist/user-aware-index.js"
timeout: 30000
initTimeout: 10000
env:
# Storage configuration
MCP_STORAGE_TYPE: "mongodb"
MCP_USER_BASED: "true"
# MongoDB configuration
MONGODB_CONNECTION_STRING: "mongodb://localhost:27017/LibreChat"
MONGODB_DATABASE: "LibreChat"
MONGODB_COLLECTION: "user_todoodles"
# User context (passed by LibreChat)
MCP_USER_ID: "${USER_ID}"
# Optional encryption
CREDS_KEY: "${CREDS_KEY}"
# Web UI configuration
MCP_WEB_UI_BASE_URL: "http://localhost"
# Debug settings
MCP_DEBUG: "false"
stderr: inherit
For SMS users, todoodles automatically isolate data per phone number:
# SMS users get user IDs like "+1234567890"
# Each phone number gets completely separate todoodles
# Perfect for multi-tenant SMS bot scenarios
volumes:
- ../Sizzek/mcp-servers:/app/mcp-servers
- ../Sizzek/memory_files:/app/data # For JSON storage fallback
add_todoodle (Enhanced)
{
"name": "add_todoodle",
"arguments": {
"text": "Task description",
"category": "work", // Optional: organize todoodles
"priority": "high", // Optional: low|medium|high|urgent (defaults to medium)
"dueDate": "2024-12-25" // Optional: ISO date format
}
}
complete_todoodle
{
"name": "complete_todoodle",
"arguments": {
"id": "1"
}
}
get_todoodles (Enhanced with filtering)
{
"name": "get_todoodles",
"arguments": {
"completed": false // Optional: true=completed, false=incomplete, omit=all
}
}
delete_todoodle
{
"name": "delete_todoodle",
"arguments": {
"id": "1"
}
}
search_todoodles
{
"name": "search_todoodles",
"arguments": {
"query": "search text"
}
}
get_todoodles_by_category
{
"name": "get_todoodles_by_category",
"arguments": {
"category": "work"
}
}
get_todoodles_by_priority
{
"name": "get_todoodles_by_priority",
"arguments": {
"priority": "urgent" // low|medium|high|urgent
}
}
{
"name": "get_due_todoodles",
"arguments": {
"overdue_only": false // true=only overdue, false=due today + overdue
}
}
get_categories
{
"name": "get_categories",
"arguments": {}
}
get_todoodles_stats
{
"name": "get_todoodles_stats",
"arguments": {}
}
{
"name": "get_web_ui",
"arguments": {}
}
The server automatically detects user context from:
request.meta.user_idrequest.meta.phone_numberMCP_USER_ID'default' for standalone usageMongoDB Collections:
// Collection: user_todoodles
{
"userId": "+1234567890", // Phone number or user ID
"data": { // TodoodleData object
"items": [...],
"metadata": {
"lastId": 5,
"version": "2.1.0",
"updatedAt": "2024-12-15T...",
"totalItems": 5,
"completedItems": 2
}
},
"updatedAt": "2024-12-15T...",
"createdAt": "2024-12-15T..."
}
JSON Storage Structure:
todoodle_data/
├── users/
│ ├── default/
│ │ └── data.json
│ ├── +1234567890/
│ │ └── data.json
│ └── user123/
│ └── data.json
└── backups/
Clone and install dependencies
cd mcp-servers/todoodles
npm install
Create environment configuration
cp env.example .env
# Edit .env for your environment
Build the server
npm run build
Run locally
npm start
JSON Storage (Development):
# Edit .env
MCP_STORAGE_TYPE=json
MCP_USER_BASED=false
MCP_DEBUG=true
# Build and test
npm run build
npm start
MongoDB Testing:
# Start MongoDB locally
docker run -d -p 27017:27017 mongo:7.0
# Edit .env
MCP_STORAGE_TYPE=mongodb
MONGODB_CONNECTION_STRING=mongodb://localhost:27017/test_todoodles
MCP_USER_BASED=true
MCP_USER_ID=test-user
# Test with MongoDB
npm run build
npm start
Database Preparation
// MongoDB indexes for performance
db.user_todoodles.createIndex({ "userId": 1 })
db.user_todoodles.createIndex({ "updatedAt": -1 })
db.user_todoodles.createIndex({ "userId": 1, "updatedAt": -1 })
LibreChat Integration
librechat.yamlMCP_USER_BASED=true for user isolation${USER_ID} for automatic user contextSMS User Support
userId and updatedAtThe todoodles server includes a built-in web UI framework powered by mcp-web-ui that allows users to interact with their todoodles through a modern web interface instead of just chat commands.
Request Web UI Access: Ask your AI agent: "Can I get a web interface for my todoodles?"
Agent Response:
The agent will call the get_web_ui tool and return a secure URL like:
http://localhost:3247/ui/f47ac10b-58cc-4372-a567-0e02b2c3d479
Enhanced Web Interface:
Automatic Security:
For accessing todoodles from mobile devices over Tailscale or VPN:
# Set your Tailscale machine URL
MCP_WEB_UI_BASE_URL=http://your-machine.tailscale-network.ts.net
# Or your VPN/network address
MCP_WEB_UI_BASE_URL=http://192.168.1.100
The framework automatically:
The web UI integration follows a clean separation pattern:
get_web_ui) added to existing server# Export existing JSON data
node -e "
const fs = require('fs');
const data = JSON.parse(fs.readFileSync('./todoodle.json', 'utf8'));
console.log(JSON.stringify({
userId: 'default',
data: {
items: data,
metadata: {
lastId: Math.max(...data.map(i => parseInt(i.id))) || 0,
version: '2.1.0',
updatedAt: new Date().toISOString(),
totalItems: data.length,
completedItems: data.filter(i => i.completed).length
}
}
}, null, 2));
"
Old tools → New tools:
add → add_todoodlecomplete → complete_todoodleget_all → get_todoodlesget_incomplete → get_todoodles (with completed: false)delete → delete_todoodlesearch → search_todoodlesget_by_category → get_todoodles_by_categoryget_by_priority → get_todoodles_by_priorityget_due_today → get_due_todoodlesget_overdue → get_due_todoodles (with overdue_only: true)SMS User Integration:
# User +1234567890 adds a todo
add_todoodle("Buy groceries", "personal", "medium", "2024-12-16")
# User +0987654321 adds a todo (completely isolated)
add_todoodle("Finish report", "work", "urgent", "2024-12-15")
# Each user only sees their own todoodles
get_todoodles() # Returns different results per user
Development Testing:
# Test as different users
MCP_USER_ID=alice npm start
MCP_USER_ID=bob npm start
MCP_USER_ID=charlie npm start
Web UI Usage:
# User requests web interface through chat
"Can I get a web interface for my todoodles?"
# Agent calls get_web_ui tool and returns secure URL
# User clicks URL and gets personal todoodles interface
# Each user sees only their own data, even through web UI
MongoDB Connection Errors
# Check MongoDB is running
docker ps | grep mongo
# Test connection
mongosh mongodb://localhost:27017/LibreChat
Environment Variable Issues
# Verify .env loading
MCP_DEBUG=true npm start
# Check console for environment variable dump
User Isolation Not Working
# Ensure MCP_USER_BASED=true
# Check LibreChat passes USER_ID correctly
# Verify user extraction in logs
Permission Errors
# JSON storage directory permissions
chmod -R 755 ./todoodle_data/
Enable comprehensive logging:
MCP_DEBUG=true
Logs include:
ISC - See LICENSE file for details
For issues, feature requests, or contributions:
FAQs
A time-stamped todo list MCP server with categories, priorities, and due dates
We found that todoodles demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.