# 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:

```sql
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)

```bash
npm install -g .
```

### Local Development

```bash
npm install
npm run build
```

## Usage

### As a Global Command

After installing globally, you can run:

```bash
cursor-plan-executor
```

### With npx

```bash
npx cursor-plan-executor
```

### Direct Execution

```bash
node dist/index.js
```

## Cursor Integration

### Configuration

Add the following to your Cursor settings:

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

Or use the alternative format:

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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