Cursor Taskmaster MCP Server

A comprehensive MCP (Model Context Protocol) server designed to enhance agentic workflows through project-scoped task management, memory retrieval, and intelligent workflow execution.

🎯 Overview

Cursor Taskmaster transforms your development workflow by providing:

• Project-Scoped Storage: All data stored in .taskmaster/ directory within your project
• Hierarchical Task Management: Organize tasks in prompt → task → subtask structure
• Memory Retrieval System: Semantic search and context management for your project
• Agent Workflow Engine: Parse prompts, generate tasks, execute with user approval
• User Approval Workflow: Review and modify tasks before execution

🏗️ Architecture

The system uses a hierarchical approach:

Project Root/
├── .taskmaster/
│   ├── tasks.json      # Hierarchical task storage
│   ├── prompts.json    # Prompt definitions and metadata
│   ├── lists.json      # Task list management
│   ├── workflow.json   # Workflow state and execution log
│   ├── memories.db     # SQLite database for memory storage
│   └── vectors.index/  # Vector embeddings for semantic search

🚀 Features

Task Management

• Create, read, update, delete tasks with hierarchical structure
• Task status tracking (pending, in_progress, completed, failed, awaiting_approval)
• Priority levels (low, medium, high, critical)
• Time estimation and tracking
• Rich metadata support

Memory System

• Project-scoped memory storage with semantic search
• Automatic vectorization using Sentence Transformers
• Context retrieval with similarity thresholds
• Metadata tagging and filtering

Workflow Engine

• Parse natural language prompts into structured tasks
• Sequential task execution with error handling
• User approval checkpoints
• Workflow state persistence and resumption
• Comprehensive execution logging

📋 Available Tools

Task Management Tools

createTask

Create a new task in the project's task management system.

{
  "title": "Task title",
  "description": "Detailed description",
  "priority": "medium",
  "parentId": "optional-parent-task-id",
  "dueDate": "2024-01-01T00:00:00Z",
  "estimatedTime": 60,
  "metadata": { "key": "value" }
}

getTask

Retrieve a specific task by ID.

getAllTasks

Retrieve all tasks in the project.

updateTask

Update an existing task's properties.

deleteTask

Delete a task and all its subtasks.

getTaskHierarchy

Get hierarchical view of tasks with optional root task filter.

Memory Tools

storeMemory

Store information with automatic vectorization for semantic search.

{
  "key": "unique-identifier",
  "content": "Content to store",
  "metadata": { "tags": ["tag1", "tag2"] }
}

retrieveMemory

Retrieve relevant memories using semantic search.

{
  "query": "search query",
  "limit": 5,
  "threshold": 0.7
}

Workflow Tools

parsePrompt

Parse a user query into a structured task workflow.

{
  "query": "Create a REST API with authentication",
  "title": "API Development",
  "description": "Build secure REST API"
}

executeWorkflow

Execute a workflow from a parsed prompt.

approveTask

Approve a task for execution.

rejectTask

Reject a task with optional modifications.

resumeWorkflow

Resume workflow execution from a checkpoint.

getWorkflowState

Get the current workflow execution state.

List Management Tools

getAllPrompts

Get all prompts in the project.

getAllLists

Get all task lists in the project.

🔄 Workflow Process

1. Parse Prompt: Convert natural language query into structured tasks
2. User Review: Tasks marked as awaiting_approval for user review
3. Approval/Modification: User can approve, reject, or modify tasks
4. Sequential Execution: Execute approved tasks in hierarchical order
5. Progress Tracking: Monitor execution with detailed logging
6. Error Handling: Pause on errors with recovery options
7. Memory Storage: Store execution context and results

📦 Installation

npm install @notbnull/mcp-cursor-taskmaster

Or for development:

git clone <repository-url>
cd mcp-cursor-taskmaster
npm install
npm run build

⚙️ Configuration

The server automatically creates a .taskmaster/ directory in your project root. No additional configuration required.

MCP Client Configuration

Add to your MCP client configuration:

{
  "servers": {
    "cursor-taskmaster": {
      "command": "npx",
      "args": ["@notbnull/mcp-cursor-taskmaster"]
    }
  }
}

🛠️ Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Lint code
npm run lint

📁 Project Structure

src/
├── index.ts           # Main MCP server implementation
├── task-store.ts      # Task management and storage
├── workflow-engine.ts # Workflow execution engine
├── memory-store.ts    # Memory storage with SQLite
└── vector-store.ts    # Vector embeddings and search

🤖 Usage Examples

Basic Task Creation

// Create a main task
const task = await tools.createTask({
  title: "Build Authentication System",
  description: "Implement JWT-based authentication",
  priority: "high",
  estimatedTime: 240,
});

// Create subtasks
await tools.createTask({
  title: "Create User Model",
  description: "Define user schema and database model",
  parentId: task.id,
  priority: "medium",
  estimatedTime: 60,
});

Workflow Automation

// Parse user query into tasks
const result = await tools.parsePrompt({
  query: "Set up a React app with TypeScript and testing",
  title: "React App Setup",
});

// Review and approve tasks
await tools.approveTask(taskId, "Looks good!");

// Execute the workflow
await tools.executeWorkflow(result.promptId);

Memory Management

// Store project knowledge
await tools.storeMemory({
  key: "api_endpoints",
  content:
    "User authentication endpoints: POST /auth/login, POST /auth/register",
  metadata: { type: "api_documentation", module: "auth" },
});

// Retrieve relevant context
const memories = await tools.retrieveMemory({
  query: "authentication endpoints",
  limit: 3,
});

🔐 Security

• All data stored locally in project directory
• No external API calls for core functionality
• Vector embeddings computed locally using Sentence Transformers

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the Model Context Protocol
• Uses Sentence Transformers for embeddings
• Powered by SQLite for reliable data storage

📞 Support

• GitHub Issues: Report bugs or request features
• Documentation: Check this README and inline code documentation
• Examples: See the examples/ directory for usage patterns