mcp-todo-list-server

StrongMonkey/mcp-todo-list-server

3.2

If you are the rightful owner of mcp-todo-list-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server that provides CRUD operations for TODO items with a PostgreSQL backend, supporting user-specific lists and various features.

Tools

  1. create-todo

    Create a new TODO item with specified details.

  2. list-todos

    List TODO items with optional filters for completion, priority, and search terms.

  3. get-todo

    Retrieve details of a specific TODO item by ID.

  4. update-todo

    Update an existing TODO item with new details.

  5. complete-todo

    Mark a TODO item as completed.

  6. delete-todo

    Delete a TODO item by ID.

  7. get-todo-stats

    Retrieve statistics about TODO items.

  8. get-todo-resources

    Get resource links for TODO items.

TODO List MCP Server

A Model Context Protocol (MCP) server that provides CRUD operations for TODO items with PostgreSQL backend. The server extracts user information from forwarded headers and stores TODO items per user.

Features

  • ✅ Create, Read, Update, Delete TODO items
  • 🔍 Search and filter TODOs by status, priority, and text
  • 📊 Get TODO statistics and completion rates
  • 🏷️ Priority levels (low, medium, high)
  • 📅 Due date support
  • 👤 User-specific TODO lists (extracted from headers)
  • 🔗 Resource links for TODO items
  • 📝 Prompt templates for TODO creation

Prerequisites

  • Node.js 18+
  • PostgreSQL database
  • npm or yarn

Installation

  1. Clone the repository:
git clone <repository-url>
cd go-mcp-todo-list
  1. Install dependencies:
npm install
  1. Set up environment variables:
cp env.example .env

Edit .env with your database configuration:

DATABASE_URL=postgresql://username:password@localhost:5432/todo_db
PORT=3000
DB_POOL_MIN=2
DB_POOL_MAX=10
  1. Create the PostgreSQL database:
CREATE DATABASE todo_db;

Usage

Development

npm run dev

Production

npm run build
npm start

The server will start on port 3000 (or the port specified in your .env file).

API Endpoints

MCP Endpoint

  • POST /mcp - Main MCP protocol endpoint
  • DELETE /mcp - Clean up session

Health Check

  • GET /health - Server health status

MCP Tools

1. Create TODO

{
  "method": "tools/call",
  "params": {
    "name": "create-todo",
    "arguments": {
      "title": "Buy groceries",
      "description": "Milk, bread, eggs",
      "priority": "medium",
      "due_date": "2024-01-15T18:00:00Z"
    }
  }
}

2. List TODOs

{
  "method": "tools/call",
  "params": {
    "name": "list-todos",
    "arguments": {
      "completed": false,
      "priority": "high",
      "search": "groceries",
      "limit": 10,
      "offset": 0
    }
  }
}

3. Get TODO

{
  "method": "tools/call",
  "params": {
    "name": "get-todo",
    "arguments": {
      "id": "todo-id-here"
    }
  }
}

4. Update TODO

{
  "method": "tools/call",
  "params": {
    "name": "update-todo",
    "arguments": {
      "id": "todo-id-here",
      "title": "Updated title",
      "completed": true,
      "priority": "high"
    }
  }
}

5. Complete TODO

{
  "method": "tools/call",
  "params": {
    "name": "complete-todo",
    "arguments": {
      "id": "todo-id-here"
    }
  }
}

6. Delete TODO

{
  "method": "tools/call",
  "params": {
    "name": "delete-todo",
    "arguments": {
      "id": "todo-id-here"
    }
  }
}

7. Get Statistics

{
  "method": "tools/call",
  "params": {
    "name": "get-todo-stats",
    "arguments": {}
  }
}

8. Get Resources

{
  "method": "tools/call",
  "params": {
    "name": "get-todo-resources",
    "arguments": {
      "completed": false,
      "limit": 5
    }
  }
}

MCP Prompts

Create TODO Template

{
  "method": "prompts/get",
  "params": {
    "name": "create-todo-template",
    "arguments": {
      "title": "New task",
      "description": "Task description",
      "priority": "medium",
      "due_date": "2024-01-15"
    }
  }
}

MCP Resources

Read TODO Resource

{
  "method": "resources/read",
  "params": {
    "uri": "todo://todo-id-here"
  }
}

Read Statistics Resource

{
  "method": "resources/read",
  "params": {
    "uri": "todo://stats"
  }
}

User Authentication

The server extracts user information from the following headers:

  • X-Forwarded-User - User ID
  • X-Forwarded-Email - User email
  • X-Forwarded-Name - User name

If these headers are not provided, the server will use default anonymous values.

Database Schema

The server automatically creates the following table:

CREATE TABLE todo_items (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title VARCHAR(255) NOT NULL,
  description TEXT,
  completed BOOLEAN DEFAULT FALSE,
  priority VARCHAR(10) CHECK (priority IN ('low', 'medium', 'high')) DEFAULT 'medium',
  due_date TIMESTAMP,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  user_id VARCHAR(255) NOT NULL,
  user_email VARCHAR(255) NOT NULL,
  user_name VARCHAR(255) NOT NULL
);

Session Management

The server supports session-based connections:

  • Include mcp-session-id header for session persistence
  • Sessions are automatically cleaned up on DELETE requests
  • Database connections are pooled per session

Error Handling

The server returns standard JSON-RPC 2.0 error responses:

  • -32601 - Method not found
  • -32603 - Internal error
  • -32000 - Session not initialized

Development

Building

npm run build

Testing

npm test

TypeScript

The project is written in TypeScript with strict type checking enabled.

License

MIT License