Cursor Plan Executor

A Model Context Protocol (MCP) server for Cursor that helps manage and execute task plans with SQLite3 database management tools.

Features

• Plan Management: Complete CRUD operations for task plan steps
• SQLite3 Database: Persistent storage for plan management
• Status Tracking: Track completion status of plan steps
• Execution Data: Store progress notes and results for each step
• Workflow Tools: Streamlined tools for plan execution workflow

Database Schema

The server includes a SQLite3 database with the following table:

CREATE TABLE plan (
  step INTEGER PRIMARY KEY AUTOINCREMENT,
  instructions VARCHAR(10000) NOT NULL,
  status TINYINT DEFAULT 0 CHECK (status IN (0, 1)),
  execution_data TEXT
);

Installation

Global Installation (Recommended for Cursor integration)

npm install -g .

Local Development

npm install
npm run build

Usage

As a Global Command

After installing globally, you can run:

cursor-plan-executor

With npx

npx cursor-plan-executor

Direct Execution

node dist/index.js

Cursor Integration

Configuration

Add the following to your Cursor settings:

{
  "mcp": {
    "servers": {
      "cursor-plan-executor": {
        "command": "cursor-plan-executor",
        "args": [],
        "env": {}
      }
    }
  }
}

Or use the alternative format:

{
  "mcpServers": {
    "cursor-plan-executor": {
      "command": "cursor-plan-executor",
      "args": [],
      "env": {}
    }
  }
}

Available Tools

initialize_plan

Initialize a new task with your plan. Call this tool whenever you start a new task and already have the plan for it. Define all separate steps in the plan. Do not initialize a plan twice, as once initialized it will delete all previous plan data. Create the plan for the whole task.

Parameters:

• plan_steps (required): Array of plan steps (instructions) for the task

Example Usage:

{
  "name": "initialize_plan",
  "arguments": {
    "plan_steps": [
      "Create a new React component",
      "Add state management",
      "Implement the UI",
      "Add tests",
      "Deploy the component"
    ]
  }
}

show_all_steps

Show all plan steps in a readable format with status indicators.

Parameters: None

Example Usage:

{
  "name": "show_all_steps",
  "arguments": {}
}

Response:

All Plan Steps:

1. ⏳ PENDING - Create a new React component

2. ✅ DONE - Add state management
   Execution Data: Redux store configured successfully

3. ⏳ PENDING - Implement the UI

get_next_step

Get the next pending step that you should follow.

Parameters: None

Example Usage:

{
  "name": "get_next_step",
  "arguments": {}
}

Response:

Next step to follow: 1 - Create a new React component

get_current_validation_criteria

Get the validation criteria for the currently unfinished task. This will list the validation criteria for the next pending step.

Parameters: None

Example Usage:

{
  "name": "get_current_validation_criteria",
  "arguments": {}
}

Response:

Current unfinished task:
Step 1 - Create a new React component
Validation Criteria: Component should have proper TypeScript types and error handling

Response (when no validation criteria):

Current unfinished task:
Step 1 - Create a new React component
No validation criteria specified for this step.

mark_current_step_done

Mark the current (next pending) step as done.

Parameters: None

Example Usage:

{
  "name": "mark_current_step_done",
  "arguments": {}
}

Response:

Step 1 marked as done: Create a new React component

mark_step_as_not_done

Mark a specific step as not done (pending). Call this tool when you need to revert a completed step back to pending status.

Parameters:

• step (required): Step number to mark as not done

Example Usage:

{
  "name": "mark_step_as_not_done",
  "arguments": {
    "step": 2
  }
}

update_step_data

Update the instructions for a specific step by step ID.

Parameters:

• step (required): Step number to update
• instructions (required): New instructions for the step

Example Usage:

{
  "name": "update_step_data",
  "arguments": {
    "step": 1,
    "instructions": "Create a new React component with TypeScript"
  }
}

update_step_execution_data

Update the execution data for a plan step (useful for tracking progress and notes).

Parameters:

• step (required): Step number to update
• execution_data (required): Execution data to store (progress notes, results, etc.)

Example Usage:

{
  "name": "update_step_execution_data",
  "arguments": {
    "step": 1,
    "execution_data": "Component created successfully with proper TypeScript types"
  }
}

get_plan_step

Get a specific plan step by step number with full details.

Parameters:

• step (required): Step number to retrieve

Example Usage:

{
  "name": "get_plan_step",
  "arguments": {
    "step": 1
  }
}

delete_plan_step

Delete a plan step by step number.

Parameters:

• step (required): Step number to delete

Example Usage:

{
  "name": "delete_plan_step",
  "arguments": {
    "step": 1
  }
}

clear_all_plan_steps

Clear all plan steps from the database (use with caution).

Parameters: None

Example Usage:

{
  "name": "clear_all_plan_steps",
  "arguments": {}
}

Typical Workflow

1. Initialize Plan: Use initialize_plan to set up your complete task plan
2. Review Steps: Use show_all_steps to see the current status
3. Get Next Step: Use get_next_step to see what to do next
4. Complete Step: Use mark_current_step_done when finished with a step
5. Add Notes: Use update_step_execution_data to add progress notes (optional)
6. Repeat: Continue steps 3-5 until all steps are complete

Development

Prerequisites

• Node.js 18 or higher
• npm