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
• 🆕 File Recreation & Recovery: Automatically detects and recreates missing files to ensure workflow continuity

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

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

{
  "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:

{
  "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:

   git clone <repository-url>
   cd nova-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Configure Cursor to use the local build:

   {
     "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"
         }
       }
     }
   }

🚨 Important: /nova Command Setup

If you're getting the error "The /nova command isn't activating the Nova MCP", this is a configuration issue, not a code problem. Here's how to fix it:

Quick Fix (Recommended)

1. Run the setup script:

   # Linux/macOS
   chmod +x setup-nova-mcp.sh
   ./setup-nova-mcp.sh
   
   # Windows
   setup-nova-mcp.bat

2. Restart Cursor to load the new MCP configuration

3. Test the command: Type /nova in Cursor

Manual Setup

If the setup script doesn't work, manually create the configuration:

1. Project-specific (recommended): Create .cursor/settings.json in your project root
2. Global: Add to your Cursor global settings

Copy this configuration:

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

Why This Happens

• /nova is not a built-in Cursor command - it needs configuration
• Nova MCP server is working perfectly - the issue is Cursor's configuration
• MCP tools are available - you can use mcp_nova_nova_* functions as a workaround

Troubleshooting

• Restart Cursor after configuration changes
• Check MCP status in Cursor's status bar
• Verify configuration file location and syntax
• Use explicit MCP calls if /nova still doesn't work

For detailed troubleshooting, see Nova Command Activation Fix.

🔧 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

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