# 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**:
   ```bash
   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**:
   ```bash
   python main.py
   ```

3. **Test with Claude Desktop** (see [Integration Guide](claude-desktop-integration.md))

## 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:
```bash
python main.py
```

**With Logging** (to monitor Claude Desktop requests):
```bash
# 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](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:

```yaml
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:**
```bash
# 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:
```bash
python -m pytest test_main.py -v
```

Run tests with coverage information:
```bash
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:
```bash
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
```bash
# ✅ 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```dockerfile
# 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

```bash
# 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]