🔍 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 mastercommand - 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
metadataobject, 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"
}
}
}