📋 Task Master MCP v2.2.1

MCP Server for intelligent task and spec management. State machine, dependency graphs, AI coaching, and spec generation with auto-export.

📝 Base Prompt: pastebin.com/EJcJ3fJF

Features

• Specs — Requirements → Design → Tasks workflow
• Auto-Export — Files created in .gofman3/specs/ automatically
• Auto-Sync — tasks.md updates on task/subtask completion
• Subtasks — Break tasks into steps (1.1, 1.2, 1.3) with completion tracking
• State Machine — Strict task lifecycle with validation
• Dependency Graph — Tasks block until deps complete
• AI Coaching — WIP limits, stale warnings, impact analysis
• Checkpoints — 🚩 validation points in task flow
• Optional Tasks — ⚡ MVP hint when optional tasks exist

Quick Start

npx @gofman3/task-master-mcp

MCP Config

{
  "mcpServers": {
    "task-master": {
      "command": "npx",
      "args": ["@gofman3/task-master-mcp"]
    }
  }
}

Tools

task_spec

Spec management — better than Kiro Specs.

Actions: create, get, list, update, delete, generate_tasks, progress, export

⚠️ CRITICAL: generate_tasks REQUIRES workspacePath!

// Create spec with subtasks
task_spec({
  action: 'create',
  name: 'Auth Module',
  requirements: [
    { id: 'REQ-1', userStory: 'As a user, I want to login', criteria: ['Email validation'] }
  ],
  taskTemplates: [
    { content: 'Design API', priority: 1, subtasks: ['Define endpoints', 'Create schemas'] },
    { content: 'Implement login', dependsOn: ['t1'], priority: 2 },
    { content: 'Write tests', dependsOn: ['t2'], optional: true }
  ]
})

// Generate tasks + auto-export to .gofman3/specs/
task_spec({ 
  action: 'generate_tasks', 
  specId: 'spec-xxx',
  workspacePath: 'F:/Projects/my-app'  // REQUIRED! Files created automatically
})

Export creates in .gofman3/specs/{spec-name}/:

• requirements.md — User stories + acceptance criteria
• design.md — Architecture + components + diagrams
• tasks.md — Progress bar + grouped tasks + subtasks (auto-synced!)
• context.md — #[[file:]] references for auto-load

task_manage

Task CRUD and state transitions.

Actions: add, update, delete, start, complete, complete_subtask, do, block, reopen, abandon

// Complete a subtask (0-based index)
task_manage({ action: 'complete_subtask', taskId: 'xxx', subtaskIndex: 0 })

// When all subtasks done → task auto-completes!

State Machine:

todo → doing, abandoned
doing → todo, blocked, done, abandoned
blocked → todo, doing, abandoned
done → todo (reopen)

task_board

Visual task board.

Views: kanban, list, priority, mermaid

task_bulk

Atomic batch creation with tempId references.

task_recommend

AI-powered next task suggestion.

Auto-Sync

When you complete a task or subtask, tasks.md is automatically updated if workspacePath was provided during generate_tasks.

# Tasks: Auth Module

## Progress: 1/3 (33%)

### ✅ Completed

- [x] 1. Design API
  - [x] 1.1 Define endpoints
  - [x] 1.2 Create schemas

### 📋 To Do

- [ ] 2. Implement login

License

MIT

🎯 How to Use (for humans)

Simple task — just tell AI what to do

You: "Fix bug in auth.ts line 42"
AI: *just does it, no extra steps*

Complex feature — FULL WORKFLOW

Example prompt:

Working directory: C:/Projects/my-backend

1. Study folders src/auth/ and src/services/
2. use think_batch — analyze architecture and edge cases
3. use task_spec — create specification with tasks

Goal: "Implement JWT auth system with refresh tokens"

Requirements:
- Access token expires in 15 minutes
- Refresh token expires in 7 days
- Refresh token rotation on use
- Blacklist for revoked tokens

What happens:

1. AI studies project code
2. think_batch — thinks through edge cases (what if token stolen? race condition on rotation?)
3. task_spec — creates spec in .gofman3/specs/jwt-auth/:

   .gofman3/specs/jwt-auth/
   ├── requirements.md   ← what we're building (user stories)
   ├── design.md         ← how we're building (architecture)
   ├── tasks.md          ← progress tracking (auto-updates!)
   └── context.md        ← file references

Track progress

Show task_board

┌─────────────┬─────────────┬─────────────┐
│    TODO     │   DOING     │   DONE      │
├─────────────┼─────────────┼─────────────┤
│ [P2] Tests  │ [P1] Token  │ [P1] Routes │
│             │   Service   │             │
└─────────────┴─────────────┴─────────────┘

What to work on next?

use task_recommend

AI tells you which task to pick (by priority + dependencies).

Completing subtasks

When working on task with subtasks — they get checked off automatically, tasks.md updates:

- [x] 1. Setup routes
  - [x] 1.1 POST /login
  - [x] 1.2 POST /refresh  
  - [ ] 1.3 POST /logout    ← current