npm package: @meta-boltz/nova
Description: Nova - Intelligent Planning and Execution MCP for Cursor
Author: Nova MCP Team
Latest version: 1.0.8

# Nova MCP - Intelligent Planning and Execution

Nova is a Model Context Protocol (MCP) server that provides intelligent planning and execution capabilities for Cursor IDE. It helps developers create, plan, and execute projects through a structured workflow.

## 🚀 Features

- **Intelligent Task Creation**: Generate requirements analysis for new projects
- **Planning Phase**: Create detailed execution plans
- **Task Management**: Break down plans into executable tasks
- **Execution Tracking**: Monitor progress and status of tasks
- **Cursor Integration**: Seamless integration with Cursor IDE

## 📁 Project Structure

```
nova-mcp/
├── src/
│   ├── handlers/          # Tool handlers and business logic
│   │   └── ToolHandler.ts
│   ├── generators/        # Content generation utilities
│   │   └── ContentGenerator.ts
│   ├── utils/            # Core utilities
│   │   ├── taskManager.ts
│   │   ├── fileManager.ts
│   │   ├── aiProcessor.ts
│   │   └── buttonHandler.ts
│   ├── types.ts          # TypeScript type definitions
│   └── index.ts          # Main server entry point
├── config/               # Configuration files
│   └── cursor-config-example.json
├── docs/                 # Documentation
│   ├── *.md             # Various guides and documentation
├── tests/                # Test files
│   ├── legacy/          # Legacy test files
│   └── test-mcp.js      # Current test file
├── dist/                 # Compiled JavaScript output
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file
```

## 🛠️ Installation

### Option 1: Local Installation (Recommended for Windows)

For Windows machines, local installation is the most reliable method:

```bash
# Clone the repository
git clone https://github.com/Meta-Boltz/nova.git
cd nova

# Install dependencies
npm install

# Build the project
npm run build
```

Then add to your Cursor configuration:

```json
{
  "mcpServers": {
    "nova": {
      "command": "node",
      "args": ["C:/path/to/nova/dist/index.js"],
      "env": {
        "NOVA_TASKS_DIR": ".cursor/tasks",
        "NOVA_AUTO_OPEN": "true",
        "NOVA_NOTIFICATIONS": "true"
      }
    }
  }
}
```

**Windows Quick Setup**: Run `install-windows.bat` for automated installation.

### Option 2: Using npx (Linux/macOS)

Add the following to your Cursor configuration:

```json
{
  "mcpServers": {
    "nova": {
      "command": "npx",
      "args": ["-y", "@meta-boltz/nova"],
      "env": {
        "NOVA_TASKS_DIR": ".cursor/tasks",
        "NOVA_AUTO_OPEN": "true",
        "NOVA_NOTIFICATIONS": "true"
      }
    }
  }
}
```

### Option 3: Local Development

1. **Clone the repository**:
   ```bash
   git clone <repository-url>
   cd nova-mcp
   ```

2. **Install dependencies**:
   ```bash
   npm install
   ```

3. **Build the project**:
   ```bash
   npm run build
   ```

4. **Configure Cursor** to use the local build:
   ```json
   {
     "mcpServers": {
       "nova": {
         "command": "node",
         "args": ["/path/to/nova-mcp/dist/index.js"],
         "env": {
           "NOVA_TASKS_DIR": ".cursor/tasks",
           "NOVA_AUTO_OPEN": "true",
           "NOVA_NOTIFICATIONS": "true"
         }
       }
     }
   }
   ```

## 🔧 Development

### Available Scripts

- `npm run build` - Compile TypeScript to JavaScript
- `npm run dev` - Watch mode for development
- `npm start` - Run the compiled server
- `npm test` - Run tests

### Development Workflow

1. **Make changes** in the `src/` directory
2. **Build the project** with `npm run build`
3. **Test your changes** with `npm test`
4. **Start the server** with `npm start`

## 📋 Usage

### Nova Commands

Nova supports the following commands:

- `/nova create [project-type] [app-type]` - Create a new project
- `/nova continue planning` - Continue to planning phase
- `/nova continue tasks` - Continue to tasks phase
- `/nova continue execution` - Continue to execution phase
- `/nova status` - Check project status

### Examples

```bash
# Create a React todo app
/nova create react todo

# Create a Vue.js authentication system
/nova create vue auth

# Create a Node.js API
/nova create node api
```

## 🏗️ Architecture

### Core Components

1. **NovaMCPServer** (`src/index.ts`)
   - Main server class that handles MCP communication
   - Manages tool registration and request handling

2. **ToolHandler** (`src/handlers/ToolHandler.ts`)
   - Handles all tool operations and business logic
   - Manages command translation and response generation

3. **ContentGenerator** (`src/generators/ContentGenerator.ts`)
   - Generates markdown content for requirements, plans, and tasks
   - Provides structured templates for project documentation

4. **TaskManager** (`src/utils/taskManager.ts`)
   - Manages task lifecycle and state
   - Handles task creation, updates, and status tracking

5. **FileManager** (`src/utils/fileManager.ts`)
   - Handles file operations and directory management
   - Manages project file structure creation

6. **AIProcessor** (`src/utils/aiProcessor.ts`)
   - Processes AI-related operations
   - Handles intelligent content generation

## 🔌 MCP Tools

Nova provides the following MCP tools:

- `nova_translate_message` - Translate user messages to Nova commands
- `nova_create_task` - Create new tasks and generate requirements
- `nova_continue_planning` - Continue to planning phase
- `nova_continue_tasks` - Continue to tasks phase
- `nova_continue_execution` - Continue to execution phase
- `nova_execute_task` - Execute specific tasks
- `nova_get_status` - Get task status
- `nova_list_tasks` - List all active tasks
- `nova_wait_for_user` - Wait for user confirmation
- `nova_update_task_status` - Update task status

## 📚 Documentation

Additional documentation is available in the `docs/` directory:

- **Guides**: Step-by-step guides for different features
- **Summaries**: Overview documents for various approaches
- **Solutions**: Complete solution documentation

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

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

## 🆘 Support

If you encounter any issues or have questions:

1. Check the documentation in the `docs/` directory
2. Review the troubleshooting guide
3. Open an issue on GitHub

---

**Nova MCP** - Making project planning and execution intelligent and efficient.