Skip to content

DrSkippy/task.md-utilities

BranchesTags

Repository files navigation

Task.md Utilities (HENDRICKSON KANBAN)

A REST API, MCP server, and interactive CLI for managing tasks organized in lanes, where each task is a markdown file. The CLI includes a full-screen Textual TUI (kanban board with keyboard navigation) as well as non-interactive subcommands for scripting.

About Tasks.md

This project builds on and extends the Tasks.md project. For comprehensive information about the Tasks.md system, including task visualization, board views, file format specifications, and VSCode integration, visit the Tasks.md repository.

This package adds a REST API, a network-capable interactive CLI, and an MCP server for programmatic task management.

Overview

Tasks are stored as markdown files organized in lane directories:

  • Task title = filename (without .md)
  • Tags: [tag:tagname] — one per line at the top of the file
  • Due dates: [due:YYYY-MM-DD]
  • Tasks can be split into subtasks using the [[split]] marker

Architecture

┌─────────────┐     HTTP      ┌──────────────────┐
│  tasks CLI  │ ─────────────▶│  Flask REST API   │  :2999 (internal)
│  (bin/tasks)│               │  (task_api/)      │  :3101 (host)
└─────────────┘               └────────┬─────────┘
                                        │
                              ┌─────────▼─────────┐
┌─────────────┐    MCP        │     task_lib/      │
│ AI assistant│ ─────────────▶│  MCP Server        │  :3003
│ (Claude etc)│               │  (mcp_task_service)│
└─────────────┘               └────────┬─────────┘
                                        │
                              ┌─────────▼─────────┐
                              │  Markdown files    │
                              │  /data/tasks/      │
                              └───────────────────┘

Project Structure

task.md-utilities/
├── bin/
│   ├── tasks               # CLI — TUI (no args) or subcommands (scripting)
│   └── tag-utility.py      # One-time tag format migration utility
├── docs/
│   └── screenshot.svg      # TUI kanban board screenshot
├── task_lib/
│   ├── api_client.py       # Shared HTTP helpers (used by CLI and TUI)
│   ├── config.py           # Configuration (YAML)
│   ├── task.py             # Task model and file I/O
│   └── task_manager.py     # Lane and task operations
├── task_tui/               # Textual TUI package
│   ├── app.py              # KanbanApp — main board, keybindings, workers
│   ├── api.py              # Sync API wrappers for use in workers
│   ├── screens.py          # Detail, form, confirm, filter, move screens
│   └── widgets.py          # LaneColumn, TaskItem, FunctionKeyBar
├── task_api/               # Flask REST API service
│   ├── app.py
│   ├── config.py
│   ├── models.py           # Pydantic request/response schemas
│   ├── routes/
│   ├── gunicorn.conf.py
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── README.md
├── mcp_task_service/       # FastMCP server for AI assistants
│   ├── server.py
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── README.md
├── tests/                  # pytest suite
├── config.yaml             # Task data location (baked into Docker images)
└── docker-compose.yml      # Deploys both services together

Deployment

Both services are deployed as Docker containers. Build from the repo root (build context must include both task_lib/ and the service directory).

Build images

docker build -t localhost:5000/task-api:latest -f task_api/Dockerfile .
docker build -t localhost:5000/task-manager-mcp:latest -f mcp_task_service/Dockerfile .

docker push localhost:5000/task-api:latest
docker push localhost:5000/task-manager-mcp:latest

Deploy

docker-compose up -d

The root docker-compose.yml starts both services on a shared network:

Service Internal port Host port
REST API 2999 3101
MCP server 3003 3003

Both containers mount the task data directory:

volumes:
  - /mnt/raid1/lib/tasks.md/tasks:/data/tasks

Configuration

config.yaml (committed to the repo) sets the task data location inside the container. It is copied into the image at build time — no volume mount needed:

base_dir: /data/tasks

To change the data path, edit config.yaml and rebuild the images.

Running services individually

Each service has its own docker-compose.yml for standalone use:

cd task_api && docker-compose up -d       # REST API only
cd mcp_task_service && docker-compose up -d  # MCP only

CLI (bin/tasks)

The tasks binary has two modes:

  • No arguments — launches the full-screen interactive TUI (kanban board)
  • With a subcommand — runs non-interactively for scripting

Installation

poetry install
chmod +x bin/tasks

API URL configuration

Resolution order (first match wins):

  1. --api-url URL flag
  2. TASKS_API_URL environment variable
  3. ~/.config/tasks/config.yaml → api_url key
  4. Default: http://localhost:3101

Create ~/.config/tasks/config.yaml to set a permanent remote URL:

api_url: http://your-server:3101

Interactive TUI

tasks

Launches a full-screen kanban board. Lanes are displayed as side-by-side columns; tasks are listed under each lane.

Kanban Board

Keyboard navigation

Key Action
← / → Move between lanes
↑ / ↓ Move between tasks within a lane
Enter Open task detail view
Esc Go back / close dialog
F1 Show keyboard shortcut help
F2 New task (in the focused lane)
F3 Edit selected task
F4 Delete selected task (confirm prompt)
F5 Filter tasks (by lane, tag, or title substring)
F6 Move selected task to another lane
F7 Open / close task detail view
F8 Refresh board from the API
F9 Quit

Active filters are shown in a status bar at the top; press F5 again to change or clear them.

Subcommands

tasks [--api-url URL] COMMAND

Commands:
  show    List tasks (--lane, --tag, --string filters)
  get     Show a single task in full
  add     Create a new task
  update  Update task fields
  delete       Move a task to Trash
  empty-trash  Permanently delete all tasks in Trash
  move         Change a task's lane
  split        Split tasks containing [[split]] marker
  lanes        Manage lanes
    list       List lanes with task counts
    add        Create a new lane
  stats        Show statistics summary

Examples

# List all tasks
tasks show

# Filter by lane, tag, or title substring (all case-insensitive)
tasks show --lane "In Progress"
tasks show --tag urgent
tasks show --string "login"

# Show full task detail
tasks get "Implement login"

# Create a task (prompts for missing fields)
tasks add --title "Fix bug" --content "Reproduce and fix" --lane Backlog --tags "bug,urgent"

# Update fields (only provided fields change)
tasks update "Fix bug" --tags "bug,urgent,p1" --due-date 2026-06-01

# Move between lanes
tasks move "Fix bug" "In Progress"

# Delete (moves to Trash, prompts for confirmation)
tasks delete "Fix bug"

# Permanently delete all tasks in Trash (prompts for confirmation)
tasks empty-trash

# Lane management
tasks lanes list
tasks lanes add "Sprint 3"

# Split a task (divides on [[split]] marker)
tasks split

# Statistics
tasks stats

MCP Server

The MCP server exposes kanban operations to AI assistants (Claude, Cursor, etc.) via the Model Context Protocol.

Connecting a client

Add to your Claude Desktop / Claude Code config (~/.claude/claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "task-manager": {
      "type": "http",
      "url": "http://localhost:3003/mcp"
    }
  }
}

Available tools

Tool Description
add_task Create a task (title, content, lane, tags, due_date)
get_task Retrieve a task by title
update_task Update task fields
delete_task Move a task to Trash
move_task_to_lane Move a task to a different lane
list_tasks List tasks (lane and tag filters, case-insensitive)
list_lanes List lanes with task counts
add_lane Create a new lane
split_tasks Split tasks with [[split]] marker
empty_trash Permanently delete Trash contents
get_statistics Lane, tag, and due-date statistics

Title and tag matching is case-insensitive across all tools.

See mcp_task_service/README.md for full details.

REST API

The REST API is documented in task_api/README.md.

Quick reference:

# Health check
curl http://localhost:3101/health

# List tasks
curl "http://localhost:3101/tasks"
curl "http://localhost:3101/tasks?lane=Backlog&tag=urgent"
curl "http://localhost:3101/tasks?search=login"

# Create a task
curl -X POST http://localhost:3101/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"My Task","content":"Details","lane":"Backlog","tags":["urgent"]}'

# Move a task
curl -X POST "http://localhost:3101/tasks/My%20Task/move" \
  -H 'Content-Type: application/json' \
  -d '{"lane":"In Progress"}'

# Statistics
curl http://localhost:3101/operations/statistics

Task File Format

[tag:frontend]
[tag:urgent]
[due:2026-06-01]

Task body text goes here.

Data Directory Structure

/data/tasks/
├── Backlog/
│   └── Implement login.md
├── In Progress/
│   └── Fix auth bug.md
├── Done/
│   └── Setup CI.md
└── Trash/
    └── old-task.md

Development

Run tests

poetry run pytest --cov=task_lib --cov=task_api --cov=task_tui --cov-report=term-missing tests/

Run REST API locally

TASK_CONFIG_PATH=config.yaml poetry run gunicorn --config task_api/gunicorn.conf.py "task_api.app:create_app()"

Run MCP server locally

TASK_CONFIG_PATH=config.yaml poetry run python mcp_task_service/server.py

Utilities

Tag Format Migration

bin/tag-utility.py converts old-format tags (tags: tag1, tag2) to the current format ([tag:tagname]). Edit the hardcoded directory path in the script before running. Supports dry-run mode.

About

MCP Server and command line application enhancing tasks.td stories/notes management.

Topics

markdown mcp task-management

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages