cursorx-mcp/README.md

🚀 Cursor MCP Bridge (生产就绪v1.2.3) - 完整端到端测试验证，16条消息成功提取。集成DOM操作、智能等待机制、内容稳定性检测等生产级功能。

# cursor-mcp-bridge

🚀 **Fully Tested & Production Ready** - Enhanced Bridge between Claude Code and Cursor AI for intelligent project consultation through MCP (Model Context Protocol). Complete DOM operations, intelligent waiting mechanisms, and verified end-to-end communication!

## 🚀 Quick Start

### Installation

You don't need to install anything! Just use `npx`:

```bash
npx cursor-mcp-bridge
```

### Configuration

Add to your Claude Code MCP configuration file:

**Windows:**
```json
{
  "mcpServers": {
    "cursor-project-advisor": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "cursor-mcp-bridge"]
    }
  }
}
```

**Mac/Linux:**
```json
{
  "mcpServers": {
    "cursor-project-advisor": {
      "command": "npx",
      "args": ["-y", "cursor-mcp-bridge"]
    }
  }
}
```

### 🎛️ Environment Configuration

Customize Cursor analysis behavior:

```json
{
  "mcpServers": {
    "cursor-project-advisor": {
      "command": "npx",
      "args": ["-y", "cursor-mcp-bridge"],
      "env": {
        "CURSOR_MESSAGE_PREFIX": "[Project Analysis Mode] Use Cursor's built-in search and analysis tools first: 1) Search related code files and configs 2) Analyze project architecture and dependencies 3) Provide analysis based on complete understanding. No code modifications, no long code blocks:",
        "CURSOR_MESSAGE_TIMEOUT": "360000"
      }
    }
  }
}
```

**Environment Variables:**

- **`CURSOR_MESSAGE_PREFIX`**: Customizes the analysis instruction prefix sent to Cursor for project-first analysis approach.
- **`CURSOR_MESSAGE_TIMEOUT`**: Request timeout in milliseconds. Default: 360000 (6 minutes). Adjust based on project complexity and network conditions.

### Usage in Claude Code

Once configured, you can use the MCP tool in Claude Code:

```
mcp__cursor-project-advisor__consult("Please analyze the project architecture")
```

## 📋 Requirements

- Node.js >= 18.0.0
- Cursor (latest version)
- Claude Code with MCP support

## 🛠️ CLI Commands

```bash
# Start the server (default)
npx cursor-mcp-bridge

# Show help
npx cursor-mcp-bridge help

# Show version
npx cursor-mcp-bridge version
```

## 🔧 How It Works (Enhanced Version)

1. **HTTP Discovery Service**: Server starts on port 28765 for script injection and status monitoring
2. **Dynamic WebSocket Allocation**: Automatically finds available ports from multiple ranges (28766-28776, 38766-38776, 48766-48776)
3. **One-Click Script Injection**: Visit `http://localhost:28765/inject` or use the auto-injection command
4. **Intelligent Communication**: Enhanced client script with DOM operations, button state monitoring, and content stability detection
5. **Deep Project Analysis**: Cursor provides comprehensive project understanding with enhanced message processing

### 🆕 Enhanced Features

- **Smart Button Detection**: Automatically detects and clicks New Tab buttons
- **Message Completion Intelligence**: Advanced waiting mechanisms based on button states and content stability
- **HTML Entity Decoding**: Proper handling of encoded content from Cursor responses  
- **Diagnostic Tools**: Built-in debugging and status checking capabilities
- **Multi-Instance Support**: Intelligent port management allows multiple server instances

## 📝 Features

### 🎯 Core Features
- **Context Auto-expansion**: Cursor automatically retrieves and supplements relevant code based on key information
- **Deep Project Understanding**: Leverages retrieval models to understand entire codebase structure
- **Intelligent Association Analysis**: Finds related code patterns and potential impacts
- **Architecture Consistency**: Provides suggestions that align with existing code style
- **Configurable Timeouts**: Flexible timeout configuration via environment variables for different project needs

### 🚀 Enhanced Features (v1.2.0)
- **Complete DOM Operations**: Full-featured element detection, text input, and button clicking
- **Intelligent Waiting Systems**: Advanced message completion detection using multiple strategies
- **Content Stability Monitoring**: Ensures responses are fully loaded before extraction
- **New Tab Management**: Automatic new tab creation with smart button detection
- **HTML Entity Processing**: Complete decoding of HTML entities in responses
- **Dynamic Port Discovery**: Automatic port allocation from multiple ranges
- **One-Click Injection**: HTTP-based script injection for easier setup
- **Real-time Diagnostics**: Built-in debugging and status monitoring tools

## 🐛 Troubleshooting

### Enhanced Version (v1.2.0)

#### Script Injection Issues
- Visit `http://localhost:28765` to check server status
- Use the one-click injection: `fetch('http://localhost:28765/inject').then(r=>r.text()).then(script=>{new Function(script)();})`
- Check browser console for any Trusted Types errors

#### WebSocket Connection Failed
- Enhanced version uses dynamic ports (28766-28776, 38766-38776, 48766-48776)
- Server automatically finds available ports and clears conflicts
- Check `http://localhost:28765/status` for current port information
- Check firewall settings for port ranges
- Restart both Cursor and Claude Code

#### Message Processing Issues
- Enhanced version includes content stability detection
- If responses seem incomplete, check the diagnostic tools: `window.diagnose()`
- Use `window.testMessage("test")` in Cursor console to verify functionality
- Check for proper copy button detection in message completion

### Standard Troubleshooting

#### MCP Tool Not Available
- Verify the MCP configuration is correct
- Check Node.js version (must be >= 18.0.0)
- Review Claude Code logs for errors

#### Performance Issues
- Adjust `CURSOR_MESSAGE_TIMEOUT` environment variable for complex projects
- Enhanced version includes intelligent timeout mechanisms
- Monitor connection status via `http://localhost:28765/status`

## 📄 License

MIT

## 🔗 Links

- [GitHub Repository](https://github.com/Vanyangyang/cursor-bridge)
- [Report Issues](https://github.com/Vanyangyang/cursor-bridge/issues)