Cursor Integration

Cursor is an AI-powered code editor built for pair programming with AI. VDK CLI provides native integration with Cursor's MDC (Markdown with Directives) rule format to enhance its project understanding.

Overview

Cursor integration creates:

MDC Rule Files: .cursor/rules/ directory with structured Markdown files
Project Configuration: Cursor-specific settings and preferences
AI Context Enhancement: Rich project context for Cursor's AI assistant
Real-time Updates: Dynamic rule updates as your project evolves

Setup

Automatic Setup

# Initialize VDK with Cursor integration
vdk init --ide-integration

# Or setup Cursor specifically
vdk integrations --setup cursor

Manual Setup

# Check if Cursor is detected
vdk integrations --scan

# Setup Cursor integration
vdk integrations --setup cursor

# Verify setup
vdk integrations --list

Generated Files

`.cursor/rules/` Directory Structure

.cursor/
├── rules/
│   ├── project-context.mdc       # Main project overview
│   ├── framework-patterns.mdc    # Framework-specific patterns
│   ├── coding-conventions.mdc    # Code style and conventions
│   ├── architecture-guide.mdc    # Architectural patterns
│   └── technology-stack.mdc      # Technology-specific rules
└── settings.json                 # Cursor-specific settings

MDC Format Features

Core Directives

Cursor recognizes special XML-like directives in MDC files:

<cursor:context> - Provides high-level project context
<cursor:patterns> - Defines coding patterns with examples
<cursor:rules> - Specific coding rules and guidelines
<cursor:technologies> - Technology stack information
<cursor:structure> - Project structure and organization

Example MDC File Structure

---
title: "Project Context"
description: "Next.js project overview"
version: "2.0.1"
schema: "cursor-mdc-v1"
tags: ["nextjs", "typescript", "react"]
priority: 10
---

# Project Context

This section contains cursor directives that provide context to the AI assistant.

## Technology Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.0+
- Styling: Tailwind CSS
- Database: PostgreSQL with Prisma ORM

## Coding Conventions
- Use TypeScript for all files
- Components use PascalCase naming
- Files use kebab-case naming
- Prefer server components unless client features needed

Configuration

Cursor Settings (`.cursor/settings.json`)

{
  "cursor": {
    "rules": {
      "enabled": true,
      "autoUpdate": true,
      "validateOnSave": true
    },
    "mdc": {
      "version": "1.0",
      "directivesEnabled": true,
      "syntaxHighlighting": true
    },
    "ai": {
      "contextAware": true,
      "projectMemory": true,
      "codeCompletion": {
        "useProjectRules": true,
        "respectConventions": true
      }
    }
  },
  "vdk": {
    "integration": "cursor",
    "version": "2.0.1",
    "lastUpdated": "2024-01-15T10:30:00Z",
    "rulesPath": ".cursor/rules/",
    "autoSync": true
  }
}

Enhanced AI Responses

With VDK rules, Cursor's AI chat becomes more project-aware:

Before VDK:

User: "Create a user profile component"
Cursor: "I'll create a basic React component..."

After VDK:

User: "Create a user profile component"
Cursor: "I'll create a user profile component following your Next.js App Router patterns:
- Using TypeScript with your interface conventions
- Server component by default
- Styled with Tailwind CSS utilities
- Located in components/user/UserProfile.tsx
- Following your naming conventions"

Advanced Features

Real-time Rule Updates

Cursor can update rules in real-time as you work:

# Enable watch mode for continuous updates
vdk init --watch

# Manual rule refresh
vdk integrations --refresh cursor

Rule Validation

Validate MDC files for correct format:

# Validate all Cursor rules
vdk validate --ide cursor

# Validate specific rule file
vdk validate --file .cursor/rules/project-context.mdc

# Fix common MDC issues
vdk rules fix --ide cursor

Team Synchronization

Share Cursor rules with your team:

# Deploy rules to VDK Hub
vdk deploy --team frontend-team

# Team members can sync with:
vdk update
vdk integrations --sync cursor

Troubleshooting

Common Issues

Cursor not detecting rules:

# Check if Cursor is running
ps aux | grep -i cursor

# Verify rule files exist
ls -la .cursor/rules/

# Restart Cursor and check logs
tail -f ~/.cursor/logs/main.log

MDC syntax errors:

# Validate MDC syntax
vdk validate --ide cursor --verbose

# Check for common issues
vdk rules lint --ide cursor

# Fix formatting
vdk rules format --ide cursor

Rules not updating:

# Force rule regeneration
vdk init --overwrite --ide cursor

# Clear Cursor cache
rm -rf ~/.cursor/cache/

# Restart Cursor
pkill cursor && cursor .

Best Practices

1. Organize Rules by Scope

Structure your rules logically:

.cursor/rules/
├── global/
│   ├── project-context.mdc      # Overall project info
│   └── coding-conventions.mdc   # General conventions
├── frontend/
│   ├── components.mdc           # Component patterns
│   └── styling.mdc              # CSS/styling rules
└── backend/
    ├── api-routes.mdc           # API patterns
    └── database.mdc             # Database conventions

2. Use Specific Scopes

Target rules to specific file patterns in your frontmatter:

scope: ["app/**/*.tsx", "components/**/*.tsx"]

3. Maintain Rule Quality

Use clear, descriptive titles
Include practical examples
Keep rules focused and specific
Update rules as project evolves

4. Leverage Cursor Directives

Make full use of Cursor-specific features for enhanced AI understanding.

Integration with Other Tools

Git Integration

Include Cursor rules in version control:

# Add to git
git add .cursor/

# .gitignore (optional - exclude cache)
.cursor/cache/
.cursor/logs/

Next Steps

Windsurf Integration - Learn about Windsurf's XML-enhanced format
GitHub Copilot Integration - VS Code workspace integration
Multi-IDE Setup - Using multiple IDEs together

Cursor Integration

On this page