# WaveMaker React Native MCP Server

An MCP (Model Context Protocol) server providing intelligent development assistance for WaveMaker React Native projects. This tool integrates with Cursor IDE to help developers solve bugs, optimize performance, analyze code, and generate tests.

## 🚀 Features

### 🎯 **NEW: Direct Codebase Access**
- **Runtime Source Code**: Direct access to all `wavemaker-rn-runtime` components and systems
- **Codegen Source Code**: Direct access to transpilers, themes, and templates
- **Smart Code Search**: Find implementations, patterns, and examples across both codebases
- **Component Lookup**: Instantly locate any component's source, props, styles, and tests
- **Real Code Examples**: AI provides actual code from the codebase, not hypothetical examples

### 🐛 Bug Diagnosis & Debugging
- **Intelligent Issue Detection**: Pattern-based symptom matching with 5+ common issue types
- **Lifecycle Validation**: Comprehensive cleanup and memory management verification
- **Memory Leak Detection**: Automatic detection of orphaned resources (timeouts, subscriptions, watchers)
- **Data Binding Validation**: Verify reactive data binding and watch expressions

### ⚡ Performance Analysis
- **Render Performance Profiling**: Analyze component complexity and re-render triggers
- **Watcher Profiling**: Detect expensive watch expressions and optimization opportunities
- **Optimization Suggestions**: Prioritized, actionable recommendations for performance improvements

### 🔍 Code Analysis
- **Component Analysis**: Deep inspection of structure, props, lifecycle, and dependencies
- **Project Navigation**: Map project structure (pages, partials, prefabs, variables, services)
- **Dependency Resolution**: Track direct and transitive dependencies
- **Codebase Exploration**: Explore runtime and codegen structure with file listings

### 🧪 Testing
- **Test Skeleton Generation**: Automated test structure for unit, integration, and snapshot tests
- **Test Case Suggestions**: Smart test case recommendations based on component analysis

### 📚 Knowledge Base
- **18+ Curated Patterns**: Best practices and anti-patterns for WaveMaker RN development
- **5 Common Issues**: Documented causes, solutions, and code examples
- **6 Best Practice Categories**: Lifecycle, performance, data-binding, memory management, and more

## 📦 Installation

```bash
cd /Users/raajr_500278/wavemaker-rn-mcp
npm install
npm run build
```

### Verify Installation
```bash
ls -la dist/  # Should show compiled JavaScript files
```

## ⚙️ Configuration

### Required Environment Variable

The MCP server requires **WM_CODEBASE_PATH** to be set in your Cursor settings. This tells the server where to find the WaveMaker runtime and codegen source code.

### For Cursor IDE

Add to your Cursor settings (Cursor > Settings > MCP):

**For Generated Projects (node_modules):**
```json
{
  "mcpServers": {
    "wavemaker-rn": {
      "command": "node",
      "args": ["/Users/you/wavemaker-rn-mcp/dist/index.js"],
      "env": {
        "WM_CODEBASE_PATH": "/path/to/your-project/node_modules/@wavemaker",
        "WORKSPACE_PATH": "/path/to/your/wavemaker/project"
      }
    }
  }
}
```

**For Local Development (source code):**
```json
{
  "mcpServers": {
    "wavemaker-rn": {
      "command": "node",
      "args": ["/Users/you/wavemaker-rn-mcp/dist/index.js"],
      "env": {
        "WM_CODEBASE_PATH": "/Users/you/wavemaker-studio-frontend",
        "WORKSPACE_PATH": "/path/to/your/wavemaker/project"
      }
    }
  }
}
```

**Environment Variables:**
- **`WM_CODEBASE_PATH`** (required): Path to WaveMaker runtime/codegen source
  - **Node modules setup:** Looks for `app-rn-runtime` and `rn-codegen` folders
  - **Local codebase setup:** Looks for `wavemaker-rn-runtime` and `wavemaker-rn-codegen` folders
- **`WORKSPACE_PATH`** (required): Path to your WaveMaker project directory
  - This is where the MCP tools will search for your project code
  - Example: `/path/to/your-project/target/generated-expo-app`

The server validates paths on startup and provides clear error messages if misconfigured.

### Project-Specific Rules

To ensure the AI follows the debugging protocol in your project:

1. **Cursor Rules**: Create `.cursor/rules/wm.mdc` in your project root
   - Copy from the MCP repo's `.cursorrules` file
   - Cursor will automatically load these rules for your project

2. **Agent Configuration** (Optional): Create `.cursor/agent.md` in your project
   - Use the template from `.cursor/agent-template.md`
   - Customize with your specific paths
   - Provides additional context for agent-like workflows

## 🐛 Debugging Workflow

This MCP server enforces a **systematic debugging protocol** to ensure reliable, evidence-based bug fixes.

### Overview

The debugging workflow consists of **4 mandatory phases**:

```
Phase 0: GATHER RUNTIME DATA (REQUIRED FIRST)
  ↓
Phase 1: READ SOURCE CODE
  ↓
Phase 2: ANALYZE
  ↓
Phase 2.5: VERIFICATION CHECKPOINT
  ↓
Phase 3: PROPOSE FIX
```

### Phase 0: Gather Runtime Data (REQUIRED FIRST)

**The AI will ALWAYS ask for runtime information before analyzing code:**

1. **Request Current Information**
   - Error messages or console output
   - Reproduction steps
   - Platform (iOS/Android/Web)
   - Expected vs. actual behavior

2. **Add Diagnostic Logging**
   ```javascript
   console.log('=== Debug Info ===');
   console.log('State:', this.state);
   console.log('Props:', this.props);
   ```

3. **Wait for User Response**
   - AI will not proceed without data
   - You must provide logs or confirm behavior

4. **Document Runtime Data**
   - AI will summarize all collected information
   - This becomes the foundation for analysis

### Phase 1: Read Source Code

After collecting runtime data, the AI will:
- Use `wm_rn_smart_search` to locate relevant files
- Use `wm_rn_read_file` to read component source
- Read third-party library source if needed
- Understand the actual implementation

### Phase 2: Analyze

The AI will:
- Calculate and verify with actual runtime values
- Trace logic step-by-step
- Identify root cause with code evidence

### Phase 2.5: Verification Checkpoint

**Before proposing ANY fix, the AI must answer:**

1. What is the EXACT root cause? (with evidence)
2. Where is the problematic code located?
   - Runtime/Codegen (WM_CODEBASE_PATH) - READ ONLY
   - Generated Project (WORKSPACE_PATH) - MODIFIABLE
   - Third-party (node_modules) - READ ONLY
3. Can I modify the source? (If NO → Need workaround)
4. Is this a regression from an upgrade?
5. What is my fix strategy?

### Phase 3: Propose Fix

Only after verification, the AI will:
- Propose ONE targeted fix in your project (WORKSPACE_PATH)
- Explain WHY it works (with evidence)
- Add verification logging
- Ask you to test and confirm

### Two Codebases

The debugging workflow operates with clear boundaries:

```
┌─────────────────────────────────────┐
│ WaveMaker Runtime/Codegen           │
│ (WM_CODEBASE_PATH)                  │
│                                     │
│ Purpose: ANALYSIS ONLY              │
│ Rule: NEVER modify                  │
└─────────────────────────────────────┘
          ↓ (read to understand)
┌─────────────────────────────────────┐
│ Your Generated Project              │
│ (WORKSPACE_PATH)                    │
│                                     │
│ Purpose: APPLY FIXES HERE           │
│ Rule: All changes in this project   │
└─────────────────────────────────────┘
```

### Example: Progress Circle Clipping Issue

**Phase 0: Gather Data**
```
AI: "Can you share:
- Screenshot of the issue?
- Console errors/warnings?
- Platform (iOS/Android)?
- Did this work in a previous version?"

You: "iOS, no errors, worked in Expo 52, broke in 54"

AI: "Let's add logging:
console.log('Container:', this.state.radius);
Please reload and share output."

You: "Container: 120"

AI: "RUNTIME DATA:
- Issue: 1px clipping
- Platform: iOS
- Version: Expo 54 (regression)
- Container: 120x120px"
```

**Phase 1-2: Read & Analyze**
```
wm_rn_smart_search "WmProgressCircle"
wm_rn_read_file progress-circle.component.tsx
wm_rn_read_file node_modules/react-native-circular-progress

Calculate: radius=52, stroke=8, edge=60, container=120
→ 0px buffer! SVG clipping at boundary.
```

**Phase 2.5: Checkpoint**
```
Q: Root cause?
A: SVG needs padding prop, runtime doesn't pass it

Q: Can I modify?
A: NO - runtime is in node_modules

Q: Fix strategy?
A: Workaround in generated page component
```

**Phase 3: Fix**
```
File: src/pages/MyPage/MyPage.component.js

<View style={{overflow: 'visible', margin: -2}}>
  <WmProgressCircle ... />
</View>

Why: Creates 2px buffer without changing circle size
Verification: console.log('Wrapper margin:', -2)
```

### Benefits

✅ **No Random Fixes**: AI calculates once, fixes once  
✅ **Evidence-Based**: Every fix backed by code analysis  
✅ **Respects Boundaries**: Never modifies runtime/node_modules  
✅ **Regression-Aware**: Handles upgrade issues correctly  
✅ **Verification Built-In**: Confirms fix before and after  

### Configuration Files

The debugging workflow is defined in:
- **`.cursorrules`**: Base protocol definition (this repo)
- **`.cursor/rules/wm.mdc`**: Project-specific rules (copy to your project)
- **`.cursor/agent.md`**: Optional agent configuration (customize paths)

See [`.cursorrules`](./.cursorrules) for the complete protocol definition.

## Available Tools

### 🎯 Codebase Exploration (NEW)
- `wm_rn_search_codebase` - Search across runtime/codegen source code
- `wm_rn_find_component_source` - Locate component implementations
- `wm_rn_get_implementation` - Get actual feature implementations
- `wm_rn_list_all_components` - List all available components
- `wm_rn_get_widget_transpiler` - Get widget transpiler source
- `wm_rn_explore_runtime_structure` - Explore runtime codebase
- `wm_rn_explore_codegen_structure` - Explore codegen codebase

### Bug Diagnosis & Debugging
- `wm_rn_diagnose_issue` - Diagnose issues from symptoms
- `wm_rn_check_component_lifecycle` - Validate lifecycle implementation
- `wm_rn_validate_data_binding` - Check data binding setup
- `wm_rn_check_memory_leaks` - Detect potential memory leaks

### Performance Analysis
- `wm_rn_analyze_render_performance` - Profile component renders
- `wm_rn_profile_watchers` - Analyze watch expressions
- `wm_rn_suggest_optimizations` - Get optimization suggestions

### Code Analysis
- `wm_rn_analyze_component` - Comprehensive component analysis
- `wm_rn_find_pattern` - Find code patterns
- `wm_rn_get_project_structure` - Map project structure
- `wm_rn_find_dependencies` - Resolve dependencies

### Testing
- `wm_rn_generate_test_skeleton` - Generate test structure
- `wm_rn_suggest_test_cases` - Get test case suggestions

### Utilities
- `wm_rn_grep_code` - Advanced code search
- `wm_rn_exec_command` - Execute shell commands
- `wm_rn_read_file` - Read file contents
- `wm_rn_write_file` - Write file contents

## Usage Examples

### Diagnose a Bug

```
User: "My component isn't re-rendering when data changes"
Assistant uses: wm_rn_diagnose_issue
```

### Analyze Performance

```
User: "Why is my Dashboard page slow?"
Assistant uses: wm_rn_analyze_render_performance + wm_rn_profile_watchers
```

### Check for Memory Leaks

```
User: "Check my LoginPage for memory leaks"
Assistant uses: wm_rn_check_memory_leaks
```

## 🎯 Quick Start Examples

### Diagnose a Bug
```typescript
// User: "My component isn't re-rendering when data changes"
// AI uses: wm_rn_diagnose_issue
{
  "symptom": "component not re-rendering",
  "componentPath": "src/pages/HomePage/HomePage.tsx"
}
// Returns: causes, solutions, code examples, documentation links
```

### Check for Memory Leaks
```typescript
// User: "Check my HomePage for memory leaks"
// AI uses: wm_rn_check_memory_leaks
{
  "targetPath": "src/pages/HomePage",
  "checkTypes": ["all"]
}
// Returns: orphaned timeouts, unsubscribed listeners, recommendations
```

### Analyze Performance
```typescript
// User: "Why is my Dashboard slow?"
// AI uses: wm_rn_analyze_render_performance
{
  "componentPath": "src/pages/Dashboard/Dashboard.tsx"
}
// Returns: complexity analysis, performance issues, optimization suggestions
```

## 📊 Statistics

- **35 Tools** across 7 categories
- **10 Handler Implementations**
- **Direct Access** to 1000+ source files
- **18+ Knowledge Base Entries**
- **10,000+ Lines of Code**
- **< 5 Second Build Time**

## 🏗️ Architecture

```
wavemaker-rn-mcp/
├── src/
│   ├── server.ts              # Core MCP server
│   ├── index.ts               # Entry point
│   ├── types.ts               # Shared TypeScript types
│   ├── tools/                 # Tool definitions (28 tools)
│   │   ├── analysis.tools.ts
│   │   ├── debugging.tools.ts
│   │   ├── performance.tools.ts
│   │   ├── navigation.tools.ts
│   │   ├── build.tools.ts
│   │   ├── testing.tools.ts
│   │   └── utility.tools.ts
│   ├── handlers/              # Tool implementations (9 handlers)
│   │   ├── ComponentAnalyzer.ts
│   │   ├── IssueDiagnoser.ts
│   │   ├── LifecycleChecker.ts
│   │   ├── MemoryLeakDetector.ts
│   │   ├── RenderAnalyzer.ts
│   │   ├── WatcherProfiler.ts
│   │   ├── ProjectNavigator.ts
│   │   ├── DataBindingValidator.ts
│   │   └── TestGenerator.ts
│   ├── utils/                 # Shared utilities
│   │   ├── file-utils.ts
│   │   ├── grep-utils.ts
│   │   ├── command-executor.ts
│   │   └── logger.ts
│   └── knowledge/             # Knowledge base
│       ├── patterns.json
│       ├── issues.json
│       └── best-practices.json
├── scripts/
│   └── extract-knowledge.ts   # Doc extraction script
└── dist/                      # Compiled output
```

## 🛠️ Development

```bash
# Build
npm run build

# Watch mode
npm run watch

# Run locally
npm start

# Extract knowledge from docs (optional)
npm run extract-knowledge
```

## 📖 Documentation

- **[Codebase Integration](./CODEBASE_INTEGRATION.md)**: 🆕 How to use direct source code access
- **[Usage Guide](./USAGE_GUIDE.md)**: Comprehensive usage examples and scenarios
- **[Configuration Guide](./CONFIG.md)**: Centralized path and environment configuration
- **[Path Handling Guide](./PATH_HANDLING.md)**: Understanding absolute vs relative paths in MCP tools
- **[Cursor Configuration](./CURSOR_CONFIG.md)**: Step-by-step setup for Cursor IDE
- **[Changelog](./CHANGELOG.md)**: Version history and release notes
- **[.cursorrules](./.cursorrules)**: In-editor best practices and patterns

## 🤝 Contributing

This is an internal tool for WaveMaker RN development. For issues or improvements, please contact the WaveMaker team.

## 📄 License

MIT

## 🎉 Acknowledgments

Built with:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
- TypeScript
- WaveMaker RN documentation and best practices