TODO MCP Server

A Model Context Protocol (MCP) server for managing todo lists and items with webhook notifications, built with Bun and TypeScript.

Features

Todo List Management

• Create new todo lists with names and descriptions

• Read individual lists or get all lists

• Update list names and descriptions

• Delete lists (cascades to all items)

Todo Item Management

• CRUD Operations: Create, read, update, delete todo items

• Assignee Support: Assign todos to specific people

• Priority Levels: None, low, medium, high

• Status Tracking: pending, in_progress, completed, cancelled

• Tags: Flexible tagging system for categorization

• Due Dates: Set deadlines for tasks

• Snooze Functionality: Temporarily hide items until a specific time

Advanced Features

• Recurrence: Daily, weekly, monthly, or specific weekdays

• Search: Find todos by title, description, or keywords

• Filtering: Filter by assignee, tags, status, priority, due dates

• Sorting: Sort by time, priority, creation date, or update date

• Pagination: Limit and offset for large datasets

• Notifications: Webhook notifications for approaching deadlines

Related MCP server: Todo List MCP Server

Installation

Prerequisites

• Bun runtime

• SQLite3 (included with most systems)

Setup

# Clone the repository
git clone <repository-url>
cd mcp-todo

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

Environment Variables

# webhook URL for task notifications (optional)
NOTIFICATION_WEBHOOK=http://localhost:3000/api/webhooks/your-webhook-url

# Database configuration
DATABASE_PATH=./todo.db

# Server configuration
MCP_SERVER_NAME=mcp-todo
MCP_SERVER_VERSION=1.0.0

Usage

Development

# Start in development mode with auto-reload
bun run dev

# Run type checking
bun run typecheck

# Run tests
bun test

Production

# Start the server
bun run start

# Or build and run with Docker
docker-compose up -d

MCP Tools

The server provides the following MCP tools:

Todo List Operations

• createTodoList - Create a new todo list

• getTodoList - Get a todo list by ID

• getAllTodoLists - Get all todo lists

• updateTodoList - Update a todo list

• deleteTodoList - Delete a todo list

Todo Item Operations

• createTodoItem - Create a new todo item

• getTodoItem - Get a todo item by ID

• searchTodoItems - Search and filter todo items

• updateTodoItem - Update a todo item

• markTodoDone - Mark a todo item as completed

• deleteTodoItem - Delete a todo item

Usage Examples

Creating a Todo List

{
  "name": "Work Tasks",
  "description": "Tasks related to work projects"
}

Creating a Todo Item

{
  "list_id": "list-uuid",
  "title": "Complete project documentation",
  "description": "Write comprehensive docs for the new feature",
  "assignee": "john.doe@example.com",
  "priority": "high",
  "tags": ["documentation", "urgent"],
  "due_date": "2024-12-31T23:59:59Z",
  "recurrence": {
    "type": "weekly",
    "weekdays": [1, 3, 5]
  }
}

Searching Todo Items

{
  "query": "documentation",
  "status": ["pending", "in_progress"],
  "priority": ["high", "medium"],
  "assignee": "john.doe@example.com",
  "due_before": "2024-12-31T23:59:59Z",
  "sort_field": "due_date",
  "sort_order": "asc",
  "limit": 10
}

Database Schema

The server uses SQLite with the following tables:

• todo_lists: Stores todo list information

• todo_items: Stores individual todo items

• tags: Stores unique tag names

• todo_tags: Many-to-many relationship between todos and tags

• recurrences: Stores recurrence patterns for todos

Docker Deployment

Using Docker Compose

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Using Docker directly

# Build the image
docker build -t mcp-todo .

# Run the container
docker run -d \
  --name mcp-todo \
  -v todo-data:/data \
  -e NOTIFICATION_WEBHOOK=your-webhook-url \
  mcp-todo

Notifications

When a NOTIFICATION_WEBHOOK is configured, the server will:

1. Check for tasks with due dates within the next hour every 5 minutes

2. Send webhook notifications for upcoming deadlines

3. Automatically snooze notifications for 1 hour to avoid spam

4. Include task details like title, assignee, priority, and tags

Webhook Payload Format

{
  "content": "Task deadline approaching!",
  "data": {
    "id": "string";
    "list_id": "string";
    "title": "string";
    "description": "string";
    "assignee": "string";
    "priority": "none"; // none, low, medium, high
    "status": "completed"; // pending, in_progress, completed, cancelled
    "tags": [];
    "due_date": Date;
    "snoozed_until": Date;
    "recurrence": {
      "type": "daily"; // daily, weekly, monthly, weekdays 
      "weekdays": []; // 0-6 for Sunday-Saturday
      "day_of_month": 1; // 1-31
      "next_due": Date;
    };
    "completed_at"?: Date;
    "created_at": Date;
    "updated_at": Date;
    "metadata": {};
  }
}

API Reference

Recurrence Types

• daily: Repeats every day

• weekly: Repeats on specific weekdays (0=Sunday, 6=Saturday)

• monthly: Repeats on a specific day of the month

• weekdays: Repeats on weekdays only (Monday-Friday)

Priority Levels

• none: No priority set

• low: Low priority

• medium: Medium priority

• high: High priority

Status Options

• pending: Task not started

• in_progress: Task is being worked on

• completed: Task is finished

• cancelled: Task was cancelled

Development

Project Structure

src/
├── db/           # Database connection and schema
├── models/       # Repository classes for data access
├── server/       # MCP server implementation
├── types/        # TypeScript type definitions
└── utils/        # Utility functions

Testing

# Run all tests
bun test

# Run with coverage
bun test --coverage

# Run specific test file
bun test tests/todo-list.repository.test.ts

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass

6. Submit a pull request

License

This project is licensed under the MIT License.

Troubleshooting

Common Issues

1. Database locked error: Ensure only one instance of the server is running

2. Permission denied: Check file permissions for the database path

3. Webhook not working: Verify the webhook URL is correct and accessible

Debug Mode

Set NODE_ENV=development to enable additional logging.

Support

For issues and questions, please:

1. Check the troubleshooting section above

2. Search existing issues on GitHub

3. Create a new issue with detailed information