npm package: @gofman3/task-master-mcp
Description: MCP Server for task management with specs, state machine, dependency graphs, and AI coaching
Author: GofMan3
Latest version: 2.2.1

# 📋 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](https://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

```bash
npx @gofman3/task-master-mcp
```

## MCP Config

```json
{
  "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`!

```typescript
// 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`

```typescript
// 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`.

```markdown
# 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:
```markdown
- [x] 1. Setup routes
  - [x] 1.1 POST /login
  - [x] 1.2 POST /refresh  
  - [ ] 1.3 POST /logout    ← current
```