MCP Todo List Manager

A Model Context Protocol (MCP) server that provides todo list management functionality with YAML-based persistence. This server integrates with Claude Desktop and other MCP clients to offer natural language todo management.

Features

• List todos: View all todo items with their status and timestamps
• Add todos: Create new todo items with automatic timestamp tracking
• Complete todos: Mark items as done with completion timestamps
• Delete todos: Remove todo items by ID
• System timestamp: Independent utility for fetching current time

Quick Start

1. Clone and setup:

   git clone <repository-url>
   cd MCPToDo
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

2. Run the server:

   python main.py
   

3. Test with Claude Desktop (see Integration Guide)

Architecture

• Single-file MCP server: main.py contains the complete implementation
• YAML persistence: Human-readable storage in ~/.todos.yaml
• Atomic writes: Safe file operations prevent data corruption
• UUID identifiers: Unique identifiers for each todo item
• ISO 8601 timestamps: Standard timestamp format for creation and completion

Usage

Running the Server

Start the MCP server:

python main.py

With Logging (to monitor Claude Desktop requests):

# Basic logging to console
LOG_LEVEL=INFO python main.py

# Debug logging with file output
LOG_LEVEL=DEBUG LOG_FILE=/tmp/todo-server.log python main.py

The server will start and expose the following MCP tools:

Claude Desktop Integration

For detailed instructions on integrating with Claude Desktop, see claude-desktop-integration.md.

Quick Setup:

1. Add server configuration to Claude Desktop MCP settings
2. Restart Claude Desktop
3. Use natural language to manage todos through Claude

Example: "Add a todo to buy groceries" → Claude uses the MCP tools automatically

Available Tools

1. list_todos

   • Lists all todo items
   • Returns: Array of todo objects

2. add_todo

   • Creates a new todo item
   • Parameters: description (string)
   • Returns: Created todo object with ID

3. complete_todo

   • Marks a todo as completed
   • Parameters: id (string)
   • Returns: Updated todo object or null if not found

4. delete_todo

   • Removes a todo item
   • Parameters: id (string)
   • Returns: Boolean success status

5. get_timestamp

   • Utility function for current system time
   • Returns: ISO 8601 formatted timestamp

Data Storage

Todos are stored in ~/.todos.yaml with the following structure:

todos:
  - id: "uuid-string"
    description: "Todo description"
    status: "pending"  # or "done"
    created_at: "2025-01-01T12:00:00"
    completed_at: null  # or ISO timestamp when completed

File Permissions

The todo YAML file requires specific permissions for secure operation:

Required Permissions for ~/.todos.yaml:

• Owner: Read + Write (rw-) - Required for loading and saving todos
• Group: No access (---) - Security best practice
• Others: No access (---) - Prevents unauthorized access

Setting Correct Permissions:

# Set restrictive permissions (600 = rw-------)
chmod 600 ~/.todos.yaml

# Verify permissions
ls -la ~/.todos.yaml
# Should show: -rw------- 1 username username

Automatic Permission Setting: The application automatically sets secure permissions (600) when creating new todo files.

Development

Testing

The project includes comprehensive unit tests covering all core functionality:

Run the full test suite:

python -m pytest test_main.py -v

Run tests with coverage information:

pytest test_main.py

Test Coverage

✅ All 21 tests pass successfully

• TestHelperFunctions (6 tests): File operations, data loading/saving, timestamp generation, file permissions
• TestMCPTools (9 tests): CRUD operations for todos, error handling, edge cases
• TestLogging (4 tests): Logging configuration, log levels, file output, MCP request logging
• TestIntegration (2 tests): Complete workflows and data persistence

Test Categories

1. File Operations

   • Loading from non-existent files
   • Empty file handling
   • Valid YAML data processing
   • Atomic file saving

2. Todo Management

   • Adding single and multiple todos
   • Completing existing and non-existent todos
   • Deleting todos with proper cleanup
   • Listing todos in various states

3. Integration Workflows

   • Complete todo lifecycle (create → complete → delete)
   • Data persistence across server restarts
   • Concurrent operations safety

Code Quality

Check code style:

flake8 main.py

Current Status: ✅ All 21 tests pass. Minor style warnings present (line length, whitespace)

Development Setup

1. Install development dependencies from requirements.txt
2. Use virtual environment for isolation
3. Follow PEP 8 style guidelines
4. Run tests before committing changes

Security & Permissions

File System Permissions

Todo Data File (~/.todos.yaml)

• Required: 600 (rw-------) - Owner read/write only
• Purpose: Protects personal todo data from other users
• Auto-set: Application creates file with secure permissions

Application Directory

• Python files: 644 (rw-r--r--) - Standard read permissions
• Virtual environment: 755 (rwxr-xr-x) - Standard directory permissions
• Temporary files: 600 (rw-------) - Used during atomic writes

Home Directory Considerations

• Parent directory: Must have execute permission for user (x bit)
• Example: If using ~/Documents/todos.yaml, ensure ~/Documents/ is accessible
• Verification: ls -ld ~/ should show execute permission

Security Best Practices

1. File Location Security

# ✅ Good: User home directory
~/.todos.yaml
~/Documents/my-todos.yaml

# ❌ Avoid: Shared or system directories
/tmp/todos.yaml          # Accessible by all users
/var/shared/todos.yaml   # May have broad permissions

2. Directory Permissions

# Verify home directory access
ls -ld ~/
# Should show: drwx------ or drwxr-xr-x (user must have 'x')

# Check custom directory permissions
mkdir -p ~/my-todos/
chmod 700 ~/my-todos/    # Restrictive directory access

3. Process Permissions

• User Context: MCP server runs as current user
• No Root Required: Application doesn't need elevated privileges
• Isolation: Each user's todos are isolated by file system permissions

4. Network Security

• Local Only: MCP server binds to local process communication
• No Network Ports: Doesn't open TCP/UDP ports
• Process Communication: Uses stdin/stdout for MCP protocol

Common Permission Issues

Issue: "Permission Denied" when accessing todo file

# Diagnosis
ls -la ~/.todos.yaml

# Solutions
chmod 600 ~/.todos.yaml              # Fix file permissions
chown $USER:$USER ~/.todos.yaml      # Fix ownership if needed

Issue: Cannot create todo file in directory

# Diagnosis
ls -ld ~/target/directory/

# Solutions
chmod 755 ~/target/directory/        # Ensure directory is writable
mkdir -p ~/target/directory/         # Create directory if missing

Issue: Application cannot access home directory

# Diagnosis
ls -ld ~/

# Solution
chmod u+x ~/                         # Ensure execute permission on home

Multi-User Considerations

Separate User Data

• Each user gets their own todo file: ~/.todos.yaml
• No shared state between users
• File system provides natural isolation

System Administrator Setup

# For multiple users on shared system
for user in alice bob charlie; do
    sudo -u $user touch /home/$user/.todos.yaml
    sudo chmod 600 /home/$user/.todos.yaml
    sudo chown $user:$user /home/$user/.todos.yaml
done

Container/Docker Permissions

# Ensure proper user context
RUN adduser --disabled-password --gecos '' todouser
USER todouser
WORKDIR /home/todouser
# Application will create .todos.yaml with correct permissions

Security Limitations

⚠️ Current Security Gaps (See TODO.md for improvements):

• No input validation on todo descriptions
• No file size limits (potential DoS)
• No encryption at rest
• Uses yaml.load() instead of yaml.safe_load() (code execution risk)

Recommended Setup Checklist

• [ ] Verify home directory has execute permission (ls -ld ~/)
• [ ] Use default location ~/.todos.yaml or secure custom path
• [ ] Avoid shared directories like /tmp/ or /var/shared/
• [ ] Run application as regular user (not root)
• [ ] Check file permissions after first run (ls -la ~/.todos.yaml)
• [ ] Consider separate todo files for different contexts (work/personal)

Configuration

Environment Variables

• TODO_FILE: Custom location for todo storage (default: ~/.todos.yaml)
• LOG_LEVEL: Logging verbosity - DEBUG, INFO, WARNING, ERROR (default: DEBUG)
• LOG_FILE: Log output file path (default: ~/.todo-mcp-server.log)

Other Settings

• Timestamp Format: ISO 8601 with second precision (not configurable)

Usage Examples

# Use custom todo file location
TODO_FILE="~/Documents/my-todos.yaml" python main.py

# Different log level and file
LOG_LEVEL=INFO LOG_FILE=/tmp/mcp-server.log python main.py

# Combined configuration
TODO_FILE="~/work-todos.yaml" LOG_LEVEL=DEBUG LOG_FILE=/tmp/debug.log python main.py

Dependencies

• mcp: MCP server framework (≥0.2.0)
• ruamel.yaml: YAML processing with formatting preservation (≥0.18.6)
• pytest: Testing framework (≥8.3.0)
• flake8: Code style checker (≥7.1.0)

License

[Add license information]

Contributing

[Add contribution guidelines]