# Cursor MCP (Model Context Protocol)

Cursor MCP is a bridge between Claude's desktop application and the Cursor editor, enabling seamless AI-powered automation and multi-instance management. It's part of the broader Model Context Protocol (MCP) ecosystem, allowing Cursor to interact with various AI models and services through standardized interfaces.

## Overview

### 🤖 AI Integration
- Direct integration with Claude's desktop application
- Ability to leverage other MCP-compatible AI services
- Real-time context sharing between AI and editor
- AI-powered automation and code generation

### 🔌 MCP Protocol Support
- Standardized communication with AI models
- Extensible plugin system for additional MCPs
- Context-aware command execution
- Secure token-based authentication

### 🖥️ Cross-Platform Window Management
- Seamlessly manage Cursor editor windows across operating systems
- Focus, minimize, restore, and arrange windows programmatically
- Track window state changes and positions
- Handle multiple Cursor instances simultaneously

### ⌨️ Input Automation
- AI-driven keyboard input with support for:
  - Code generation and insertion
  - Refactoring operations
  - Context-aware completions
  - Multi-cursor editing
- Intelligent mouse automation including:
  - Smart selection
  - Context-menu operations
  - AI-guided navigation

### 🔄 Process Management
- AI-orchestrated instance management
- Smart workspace organization
- Automatic context preservation
- Intelligent session recovery

## MCP Integration

### Claude Desktop Integration
```typescript
import { ClaudeMCP } from 'cursor-mcp/claude'

// Connect to Claude's desktop app
const claude = await ClaudeMCP.connect()

// Execute AI-powered operations
await claude.generateCode({
    prompt: 'Create a React component',
    context: currentFileContent,
    language: 'typescript'
})

// Get AI suggestions
const suggestions = await claude.getSuggestions({
    code: selectedText,
    type: 'refactor'
})
```

### Using Multiple MCPs
```typescript
import { MCPRegistry } from 'cursor-mcp/registry'

// Register available MCPs
MCPRegistry.register('claude', ClaudeMCP)
MCPRegistry.register('github-copilot', CopilotMCP)

// Use different AI services
const claude = await MCPRegistry.get('claude')
const copilot = await MCPRegistry.get('github-copilot')

// Compare suggestions
const claudeSuggestions = await claude.getSuggestions(context)
const copilotSuggestions = await copilot.getSuggestions(context)
```

### Custom MCP Integration
```typescript
import { BaseMCP, MCPProvider } from 'cursor-mcp/core'

class CustomMCP extends BaseMCP implements MCPProvider {
    async connect() {
        // Custom connection logic
    }

    async generateSuggestions(context: CodeContext) {
        // Custom AI integration
    }
}

// Register custom MCP
MCPRegistry.register('custom-ai', CustomMCP)
```

## Configuration

The tool can be configured through environment variables or a config file at:
- Windows: `%LOCALAPPDATA%\cursor-mcp\config\config.json`
- macOS: `~/Library/Application Support/cursor-mcp/config/config.json`
- Linux: `~/.config/cursor-mcp/config.json`

Example configuration:
```json
{
    "mcp": {
        "claude": {
            "enabled": true,
            "apiKey": "${CLAUDE_API_KEY}",
            "contextWindow": 100000
        },
        "providers": {
            "github-copilot": {
                "enabled": true,
                "auth": "${GITHUB_TOKEN}"
            }
        }
    },
    "autoStart": true,
    "maxInstances": 4,
    "windowArrangement": "grid",
    "logging": {
        "level": "info",
        "file": "cursor-mcp.log"
    }
}
```

## Installation

### Windows
```powershell
# Run as Administrator
Invoke-WebRequest -Uri "https://github.com/your-org/cursor-mcp/releases/latest/download/cursor-mcp-windows.zip" -OutFile "cursor-mcp.zip"
Expand-Archive -Path "cursor-mcp.zip" -DestinationPath "."
.\windows.ps1
```

### macOS
```bash
# Run with sudo
curl -L "https://github.com/your-org/cursor-mcp/releases/latest/download/cursor-mcp-macos.zip" -o "cursor-mcp.zip"
unzip cursor-mcp.zip
sudo ./macos.sh
```

### Linux
```bash
# Run with sudo
curl -L "https://github.com/your-org/cursor-mcp/releases/latest/download/cursor-mcp-linux.zip" -o "cursor-mcp.zip"
unzip cursor-mcp.zip
sudo ./linux.sh
```

## Usage

### Basic Usage
```typescript
import { CursorInstanceManager } from 'cursor-mcp'

// Get the instance manager
const manager = CursorInstanceManager.getInstance()

// Start a new Cursor instance
await manager.startNewInstance()

// Get all running instances
const instances = await manager.getRunningInstances()

// Focus a specific instance
await manager.focusInstance(instances[0])

// Close all instances
await manager.closeAllInstances()
```

### Window Management
```typescript
import { WindowManager } from 'cursor-mcp'

const windowManager = WindowManager.getInstance()

// Find all Cursor windows
const windows = await windowManager.findCursorWindows()

// Focus a window
await windowManager.focusWindow(windows[0])

// Arrange windows side by side
await windowManager.arrangeWindows(windows, 'sideBySide')

// Minimize all windows
for (const window of windows) {
    await windowManager.minimizeWindow(window)
}
```

### Input Automation
```typescript
import { InputAutomationService } from 'cursor-mcp'

const inputService = InputAutomationService.getInstance()

// Type text
await inputService.typeText('Hello, World!')

// Send keyboard shortcuts
if (process.platform === 'darwin') {
    await inputService.sendKeys(['command', 'c'])
} else {
    await inputService.sendKeys(['control', 'c'])
}

// Mouse operations
await inputService.moveMouse(100, 100)
await inputService.mouseClick('left')
await inputService.mouseDrag(100, 100, 200, 200)
```

## How It Works

### Bridge Architecture
This tool acts as a middleware layer between Cursor and MCP servers:
1. **Cursor Integration**:
   - Monitors Cursor's file system events
   - Captures editor state and context
   - Injects responses back into the editor
   - Manages window and process automation

2. **MCP Protocol Translation**:
   - Translates Cursor's internal events into MCP protocol messages
   - Converts MCP responses into Cursor-compatible actions
   - Maintains session state and context
   - Handles authentication and security

3. **Server Communication**:
   - Connects to Claude's desktop app MCP server
   - Routes requests to appropriate AI providers
   - Manages concurrent connections to multiple MCPs
   - Handles fallbacks and error recovery

```mermaid
graph LR
    A[Cursor Editor] <--> B[Cursor MCP Bridge]
    B <--> C[Claude Desktop MCP]
    B <--> D[GitHub Copilot MCP]
    B <--> E[Custom AI MCPs]
```

### Example Workflow

1. **Code Completion Request**:
   ```typescript
   // 1. Cursor Event (File Change)
   // When user types in Cursor:
   function calculateTotal(items) {
     // Calculate the total price of items|  <-- cursor position
   
   // 2. Bridge Translation
   const event = {
     type: 'completion_request',
     context: {
       file: 'shopping-cart.ts',
       line: 2,
       prefix: '// Calculate the total price of items',
       language: 'typescript',
       cursor_position: 43
     }
   }
   
   // 3. MCP Protocol Message
   await mcpServer.call('generate_completion', {
     prompt: event.context,
     max_tokens: 150,
     temperature: 0.7
   })
   
   // 4. Response Translation
   // Bridge converts MCP response:
   const response = `return items.reduce((total, item) => {
     return total + (item.price * item.quantity);
   }, 0);`
   
   // 5. Cursor Integration
   // Bridge injects the code at cursor position
   ```

2. **Code Refactoring**:
   ```typescript
   // 1. Cursor Event (Command)
   // User selects code and triggers refactor command
   const oldCode = `
     if (user.age >= 18) {
       if (user.hasLicense) {
         if (car.isAvailable) {
           rentCar(user, car);
         }
       }
     }
   `
   
   // 2. Bridge Translation
   const event = {
     type: 'refactor_request',
     context: {
       selection: oldCode,
       command: 'simplify_nesting'
     }
   }
   
   // 3. MCP Protocol Message
   await mcpServer.call('refactor_code', {
     code: event.context.selection,
     style: 'simplified',
     maintain_logic: true
   })
   
   // 4. Response Translation
   const response = `
     const canRentCar = user.age >= 18 
       && user.hasLicense 
       && car.isAvailable;
     
     if (canRentCar) {
       rentCar(user, car);
     }
   `
   
   // 5. Cursor Integration
   // Bridge replaces selected code
   ```

3. **Multi-File Context**:
   ```typescript
   // 1. Cursor Event (File Dependencies)
   // When user requests help with a component
   
   // 2. Bridge Translation
   const event = {
     type: 'context_request',
     files: {
       'UserProfile.tsx': '...',
       'types.ts': '...',
       'api.ts': '...'
     },
     focus_file: 'UserProfile.tsx'
   }
   
   // 3. MCP Protocol Message
   await mcpServer.call('analyze_context', {
     files: event.files,
     primary_file: event.focus_file,
     analysis_type: 'component_dependencies'
   })
   
   // 4. Response Processing
   // Bridge maintains context across requests
   ```

### Integration Methods

1. **File System Monitoring**:
   ```typescript
   import { FileSystemWatcher } from 'cursor-mcp/watcher'
   
   const watcher = new FileSystemWatcher({
     paths: ['/path/to/cursor/workspace'],
     events: ['change', 'create', 'delete']
   })
   
   watcher.on('change', async (event) => {
     const mcpMessage = await bridge.translateEvent(event)
     await mcpServer.send(mcpMessage)
   })
   ```

2. **Window Integration**:
   ```typescript
   import { CursorWindow } from 'cursor-mcp/window'
   
   const window = new CursorWindow()
   
   // Inject AI responses
   await window.injectCode({
     position: cursorPosition,
     code: mcpResponse.code,
     animate: true  // Smooth typing animation
   })
   
   // Handle user interactions
   window.onCommand('refactor', async (selection) => {
     const mcpMessage = await bridge.createRefactorRequest(selection)
     const response = await mcpServer.send(mcpMessage)
     await window.applyRefactoring(response)
   })
   ```

3. **Context Management**:
   ```typescript
   import { ContextManager } from 'cursor-mcp/context'
   
   const context = new ContextManager()
   
   // Track file dependencies
   await context.addFile('component.tsx')
   await context.trackDependencies()
   
   // Maintain conversation history
   context.addMessage({
     role: 'user',
     content: 'Refactor this component'
   })
   
   // Send to MCP server
   const response = await mcpServer.send({
     type: 'refactor',
     context: context.getFullContext()
   })
   ```

## Security

- Secure token-based authentication for AI services
- Encrypted communication channels
- Sandboxed execution environment
- Fine-grained permission controls

## Requirements

### Windows
- Windows 10 or later
- Node.js 18 or later
- Administrator privileges for installation

### macOS
- macOS 10.15 (Catalina) or later
- Node.js 18 or later
- Xcode Command Line Tools
- Accessibility permissions for Terminal

### Linux
- X11 display server
- Node.js 18 or later
- xdotool
- libxtst-dev
- libpng++-dev
- build-essential

## Development

### Setup
```bash
# Clone the repository
git clone https://github.com/your-org/cursor-mcp.git
cd cursor-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test
```

### Running Tests
```bash
# Run all tests
npm test

# Run specific test suite
npm test -- window-management

# Run with coverage
npm run test:coverage
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📚 [Documentation](https://your-org.github.io/cursor-mcp)
- 🐛 [Issue Tracker](https://github.com/your-org/cursor-mcp/issues)
- 💬 [Discussions](https://github.com/your-org/cursor-mcp/discussions)
- 🔒 [Security](SECURITY.md)

## Acknowledgments

- [Cursor Editor](https://cursor.sh) - The AI-first code editor
- [Claude AI](https://anthropic.com/claude) - Advanced AI assistant
- [@nut-tree/nut-js](https://github.com/nut-tree/nut-js) - Cross-platform automation
- [active-win](https://github.com/sindresorhus/active-win) - Window detection