A lightweight MCP server that provides durable task primitives: create, update, pause/resume, and query long-running workflows. State is persisted in a local SQLite backend and can be resumed across agent restarts, enabling multi-day agentic projects with checkpoints.

Quick Start • Features • Examples • Contributing

What is this?

TaskFlow MCP Server is a lightweight task management server designed to facilitate the creation, updating, pausing, resuming, and querying of long-running workflows. It is particularly useful for agent developers using MCP-compatible clients like Claude Desktop and Cursor. Here’s a quick example of how you can use it:

$ taskflow create "Initial Task"
Task created with ID: 1

Problem

Agents lack built-in support for workflows that span multiple sessions or survive interruptions. Teams currently stitch together custom retry logic, state files, or external queues, which is fragile and hard to share.

Features

Feature	Description
Task Management	Create, update, pause, resume, and query tasks.
State Persistence	Persist task state in a local SQLite database.
CLI Interface	Manage tasks using a command-line interface.
Multi-Session Support	Resume tasks across agent restarts.
Query by ID and Status	Query tasks by their unique ID or status.
Compatibility	Works with MCP-compatible clients like Claude Desktop and Cursor.

Quick Start

1. Clone the Repository:

   $ git clone https://github.com/yourusername/taskflow-mcp-server.git

2. Install Dependencies:

   $ cd taskflow-mcp-server
   $ pip install -r requirements.txt

3. Run the Server:

   $ python main.py

4. Create Your First Task:

   $ taskflow create "Initial Task"
   Task created with ID: 1

Examples

Creating and Managing Tasks

Create a Task:

$ taskflow create "Initial Setup"
Task created with ID: 1

Update a Task:

$ taskflow update 1 "Initial Configuration"
Task 1 updated to Initial Configuration

Pausing and Resuming Tasks

Pause a Task:

$ taskflow pause 1
Task 1 paused

Resume a Task:

$ taskflow resume 1
Task 1 resumed

Querying Tasks

Query a Task by ID:

$ taskflow query 1
ID: 1, Name: Initial Configuration, Status: active

Query Tasks by Status:

$ taskflow query --status paused
ID: 1, Name: Initial Configuration, Status: paused

File Structure

TaskFlow MCP Server/
├── .self-healing-pipeline/         # Self-healing pipeline configurations
├── taskflow/                      # Core source code
│   ├── __init__.py                # Package initializer
│   ├── cli.py                     # Command-line interface
│   ├── database.py                # SQLite database operations
│   ├── main.py                    # Entry point for the server
│   ├── server.py                  # Task management server logic
│   └── tasks.py                   # Task management functions
├── tests/                         # Test suite
│   ├── __init__.py                # Package initializer
│   ├── test_cli.py                # CLI tests
│   ├── test_database.py           # Database tests
│   ├── test_server.py             # Server tests
│   └── test_tasks.py              # Task management tests
├── .gitignore                     # Git ignore rules
├── .heartbeat-callback            # Heartbeat callback configuration
├── README.md                      # Project documentation
├── conftest.py                    # Pytest configuration
├── pytest.ini                     # Pytest configuration file
├── requirements.txt               # Python dependencies
└── spec.md                        # Project specification

Tech Stack

Technology	Purpose
Python 3.11+	Main programming language
Click	Command-line interface (CLI) framework
Pytest	Testing framework
SQLite	Local database for state persistence

Contributing

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Run tests to ensure everything works.
4. Submit a pull request.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio