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

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

Verify Installation

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

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

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

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

// 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

// 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

// 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

# 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: 🆕 How to use direct source code access
• Usage Guide: Comprehensive usage examples and scenarios
• Configuration Guide: Centralized path and environment configuration
• Path Handling Guide: Understanding absolute vs relative paths in MCP tools
• Cursor Configuration: Step-by-step setup for Cursor IDE
• Changelog: Version history and release notes
• .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
• TypeScript
• WaveMaker RN documentation and best practices