🔍 Root Problem
Task-master CLI was showing different results than the tasks.json file content:
- JSON file: Contained 7 QR system tasks with proper progress
- CLI output: “No tasks found” and “Found 0 tags”
- MCP tools: Also showing 0 tasks
🛠️ Issues Discovered & Fixed
Issue #1: MCP Configuration Error
Problem:
"taskmaster-ai": { "command": "bun", "args": ["run", "task-master-ai"], // ❌ Wrong: treats it as package script "env": { "OPENAI_API_KEY": "..." } }
Solution:
"taskmaster-ai": { "command": "bun", "args": ["x", "task-master-ai"], // ✅ Correct: runs global command "env": { "OPENAI_API_KEY": "..." } }
Why: bun run
looks for package scripts, bun x
executes global CLI tools like npx
.
Issue #2: Incorrect JSON Structure
Problem – Nested tags structure:
{ "version": "1.0.0", "tags": { // ❌ Wrong: nested structure "master": { "name": "master", // ❌ Redundant field "tasks": [...] } } }
Solution – Top-level tags:
{ "version": "1.0.0", "master": { // ✅ Correct: top-level tag "tasks": [...], "metadata": { // ✅ Correct: metadata structure "created": "...", "updated": "...", "description": "..." } } }
Why: Task-master expects tags as top-level objects, not nested under a “tags” container.
Issue #3: Reserved Tag Name Behavior
Problem:
"master"
is a reserved tag name in task-master- Cannot be created using
add-tag master
command - Has special handling and initialization behavior
Solution:
- Understand that “master” is pre-defined and reserved
- Manual creation requires exact structure matching
- Use other tag names (
development
,feature-branch
, etc.) for additional contexts
Issue #4: API Key Mismatch
Problem:
// MCP has OpenAI key "env": { "OPENAI_API_KEY": "sk-..." } // But config uses different providers "models": { "main": { "provider": "anthropic", "modelId": "claude-..." }, "research": { "provider": "perplexity", "modelId": "sonar-pro" } }
Solution:
Either update MCP keys to match providers OR change config to use OpenAI models.
🔧 Step-by-Step Fix Process
1. Fix MCP Configuration
# Edit ~/.cursor/mcp.json or project/.cursor/mcp.json # Change: "args": ["run", "task-master-ai"] # To: "args": ["x", "task-master-ai"]
2. Fix JSON Structure
# Before - nested structure: { "tags": { "master": { "name": "master", "tasks": [...] } } } # After - top-level structure: { "master": { "tasks": [...], "metadata": { "created": "...", "description": "..." } } }
3. Test & Verify
# Should now work: task-master tags # Shows available tags task-master list # Shows tasks with progress task-master next # Shows next recommended task # MCP tools should also work: # get_tasks, add_task, set_task_status, etc.
⚠️ Key Lessons Learned
- MCP Args Format Matters:
["run", "script"]
= package script["x", "command"]
= global CLI tool
- Task-master JSON Structure:
- Tags are top-level objects, not nested
"master"
is reserved with special behavior- Metadata goes in
metadata
object, not mixed with tag definition
- API Key Consistency:
- MCP environment keys must match configured model providers
- Or vice versa – update config to use available API keys
- Debugging Process:
- Always check both CLI and MCP tool outputs
- Verify JSON syntax with
jq
- Compare working vs. non-working structures
- Test tags recognition separately from task listing
📋 Quick Diagnostic Commands
# Test MCP connection task-master --version # Check JSON syntax jq . .taskmaster/tasks/tasks.json # Verify tag structure task-master tags # Test task listing task-master list # Check model configuration task-master models
This troubleshooting guide should help anyone facing similar task-master issues! The key insight was understanding that task-master expects a flat tag structure rather than the nested format that seems more intuitive.
Example of Working tasks.json
{ "version": "1.0.0", "projectName": "QR Code Platform", "projectDescription": "QR-Code Receipt Validation & Redemption Platform", "createdAt": "2025-01-27T12:00:00.000Z", "master": { "tasks": [ { "id": 1, "title": "Database Schema Setup", "description": "Create comprehensive database schema with tables for customers, receipts, QR tokens, and audit logging", "status": "done", "priority": "high", "dependencies": [], "details": "✅ COMPLETED: Created comprehensive database schema with all 8 QR system tables + 4 auth tables. Includes proper relationships, constraints, and indexes for optimal performance.", "testStrategy": "Verify all tables created with proper relationships and constraints in PostgreSQL database", "subtasks": [] }, { "id": 2, "title": "Webhook Trigger Endpoint", "description": "Build webhook endpoint to receive receipt validation triggers and initiate QR generation workflow", "status": "done", "priority": "high", "dependencies": [1], "details": "✅ COMPLETED: Implemented webhook endpoint at /api/generate-qr with proper HMAC-SHA256 authentication, payload validation, and error handling.", "testStrategy": "Test webhook with sample payload using HMAC authentication", "subtasks": [] }, { "id": 3, "title": "Token Creation & QR Encoding", "description": "Implement secure token generation and QR code creation with watermarks and branding", "status": "done", "priority": "high", "dependencies": [1, 2], "details": "✅ COMPLETED: Built complete token generation system with secure random tokens, QR encoding with custom styling, watermarks, and error handling.", "testStrategy": "Generate test QR codes and verify they contain correct token data and branding", "subtasks": [] }, { "id": 4, "title": "QR Delivery System", "description": "Implement system to deliver generated QR codes via email, SMS, or API response", "status": "pending", "priority": "high", "dependencies": [3], "details": "Build flexible delivery system supporting multiple channels (email, SMS, webhook callback) with proper templating, retry logic, and delivery confirmation tracking.", "testStrategy": "Test delivery via all supported channels with success/failure tracking", "subtasks": [] }, { "id": 5, "title": "Redemption & Void APIs", "description": "Create APIs for QR code redemption validation and voiding unredeemed codes", "status": "pending", "priority": "high", "dependencies": [4], "details": "Implement redemption validation endpoint with fraud detection, void functionality for unredeemed codes, and comprehensive audit logging for all redemption attempts.", "testStrategy": "Test successful redemption, duplicate redemption prevention, and void operations", "subtasks": [] }, { "id": 6, "title": "Anti-Fraud Controls", "description": "Implement comprehensive fraud detection and prevention measures", "status": "pending", "priority": "medium", "dependencies": [5], "details": "Build fraud detection system with rate limiting, IP tracking, device fingerprinting, suspicious pattern detection, and automated blocking mechanisms.", "testStrategy": "Test fraud detection with various attack scenarios and verify blocking mechanisms", "subtasks": [] }, { "id": 7, "title": "Admin & Ops Dashboard", "description": "Create real-time dashboard for monitoring QR system performance and managing operations", "status": "pending", "priority": "medium", "dependencies": [6], "details": "Build comprehensive dashboard with real-time metrics, QR generation/redemption tracking, fraud alerts, system health monitoring, and administrative controls.", "testStrategy": "Verify all dashboard features work correctly with real-time data updates and proper authentication", "subtasks": [] } ], "metadata": { "created": "2025-01-27T12:00:00.000Z", "updated": "2025-01-27T12:00:00.000Z", "description": "Main development tasks for QR-Code Receipt Validation Platform" } }, "development": { "tasks": [], "metadata": { "created": "2025-07-01T05:48:05.886Z", "updated": "2025-07-01T05:48:05.889Z", "description": "Development tasks for QR platform" } } }