Metro Bundler Management with expo-mcp Support

Overview

Manage Metro bundler lifecycle with EXPO_UNSTABLE_MCP_SERVER=1 environment variable to enable expo-mcp local capabilities.

Core principle: Start Metro with MCP flag. Monitor health. Enable autonomous testing.

Announce at start: "I'm using the claude-mobile-metro-manager skill to start Metro with expo-mcp support."

When to Use

• Starting Metro for development (Phase 4)
• Before iOS builds or expo-mcp testing (Gate 4A)
• Debugging Metro errors (port conflicts, cache issues)
• Enabling expo-mcp local tools (automation_take_screenshot, automation_tap_by_testid, etc.)

Critical Requirement: MCP Flag

ALWAYS start Metro with expo-mcp flag:

EXPO_UNSTABLE_MCP_SERVER=1 npx expo start

Why: Enables expo-mcp local capabilities:

• automation_take_screenshot
• automation_tap, automation_tap_by_testid
• automation_find_view_by_testid
• open_devtools
• expo_router_sitemap

Without flag: Only server tools available (search_documentation, add_library, generate_*_md, learn)

Quick Reference

Task	Command	Tool
Start with MCP	./scripts/start-metro.sh	Serena execute_shell_command
Start + clear cache	./scripts/start-metro.sh --clear-cache	Serena
Check health	Read logs/metro.log	morphllm read_file
Stop Metro	./scripts/stop-metro.sh	Serena
Verify MCP enabled	Check for "expo-mcp server" in logs	morphllm

Core Workflow

1. Start Metro with MCP Support

mcp__serena__execute_shell_command({
  command: "./scripts/start-metro.sh",
  cwd: "/Users/nick/Desktop/claude-mobile-expo"
});

// Script includes: EXPO_UNSTABLE_MCP_SERVER=1 npm start

// Verify success
mcp__morphllm__read_file({
  path: "/Users/nick/Desktop/claude-mobile-expo/logs/metro.log",
  head: 100
});
// Must show: "Metro.*waiting" AND "expo-mcp server" or "MCP server"

2. Verify expo-mcp Local Tools Available

After Metro starts with flag, verify local capabilities:

"Take a screenshot to test expo-mcp"

If successful: expo-mcp local tools are working ✅

If error: Check Metro logs for MCP server status

3. Clear Cache When Needed

mcp__serena__execute_shell_command({
  command: "./scripts/start-metro.sh --clear-cache"
});

When to clear:

• "Unable to resolve module" errors
• After dependency changes
• After Metro crash

4. Fix Common Errors

Port 8081 in use:

mcp__serena__execute_shell_command({
  command: "pkill -f metro && ./scripts/start-metro.sh"
});

Module resolution failed:

mcp__serena__execute_shell_command({
  command: "./scripts/start-metro.sh --clear-cache"
});

Common Mistakes

Mistake	Reality
"Start without MCP flag"	WRONG. Local tools won't work. Must use EXPO_UNSTABLE_MCP_SERVER=1.
"npm start is fine"	WRONG. Use script with logging and MCP flag.
"Don't check logs"	WRONG. Verify MCP server started.
"Cache clear is slow"	WRONG. 10s vs hours debugging.

❌ WRONG

cd claude-code-mobile && npx expo start  # Missing MCP flag!

✅ CORRECT

cd claude-code-mobile && EXPO_UNSTABLE_MCP_SERVER=1 npx expo start
# OR use automation script:
./scripts/start-metro.sh  # Has flag built-in

Red Flags

• "MCP flag is optional" → WRONG. Required for autonomous testing.
• "Server tools are enough" → WRONG. Local tools needed for testing.
• "Direct npm start is fine" → WRONG. Use script with flag and logging.

Integration

• Enables: expo-mcp local capabilities for autonomous testing
• Use BEFORE: @claude-mobile-ios-testing (requires Metro with MCP)
• Use WITH: All Phase 4 development (frontend implementation)

Reference

Metro should show in logs:

✅ Metro waiting on port 8081
✅ expo-mcp server listening (or MCP server enabled)