feat: fix heap snapshot crashes, add restart_iwdp tool

- Increase WebSocket read limit from 64 MB to 512 MB to handle large
  heap snapshots wrapped in Target routing JSON escaping
- HeapSnapshot now saves directly to temp file instead of buffering
  in memory, with a 5-minute timeout
- New restart_iwdp tool to recover after iwdp crashes (kills old
  process, starts fresh, clears stale WebSocket connection)
- Add restart_iwdp to README tools table
- Bump version to 0.3.0

Author: nnemirovsky

.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "iwdp-mcp",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "iOS Safari debugging via ios-webkit-debug-proxy — MCP server with full WebKit Inspector Protocol support",
   "owner": {
     "name": "nnemirovsky"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "iwdp-mcp",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "iOS Safari debugging via ios-webkit-debug-proxy — MCP server with full WebKit Inspector Protocol support",
   "mcpServers": {
     "iwdp-mcp": {

README.md

@@ -281,6 +281,7 @@ Set a breakpoint in main.js and step through it
 | Tool | Description |
 |------|-------------|
 | `iwdp_status` | Check/auto-start ios-webkit-debug-proxy |
+| `restart_iwdp` | Restart iwdp after a crash (e.g., heap snapshot) |
 | `list_devices` | List connected iOS devices (HTTP GET :9221) |
 | `list_pages` | List Safari tabs (HTTP GET :9222+) |
 | `select_page` | Connect to a specific tab |

cmd/iwdp-mcp/main.go

@@ -41,7 +41,7 @@ func getClient(ctx context.Context) (*webkit.Client, error) {
 func main() {
 	server := mcp.NewServer(&mcp.Implementation{
 		Name:    "iwdp-mcp",
-		Version: "0.2.4",
+		Version: "0.3.0",
 	}, nil)
 
 	registerTools(server)
@@ -483,6 +483,22 @@ func registerTools(server *mcp.Server) {
 		return nil, map[string]any{"running": true, "started": true, "message": "ios-webkit-debug-proxy was not running — started it automatically"}, nil
 	})
 
+	mcp.AddTool(server, &mcp.Tool{
+		Name: "restart_iwdp", Description: "Restart ios-webkit-debug-proxy. Use this to recover after a crash (e.g., after a large heap snapshot kills the connection).",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, _ EmptyInput) (*mcp.CallToolResult, any, error) {
+		// Also disconnect any active WebSocket client since the old connection is dead
+		sess.mu.Lock()
+		if sess.client != nil {
+			_ = sess.client.Close()
+			sess.client = nil
+		}
+		sess.mu.Unlock()
+		if err := proxy.Restart(ctx); err != nil {
+			return nil, map[string]any{"restarted": false, "message": fmt.Sprintf("failed to restart iwdp: %v", err)}, nil
+		}
+		return nil, map[string]any{"restarted": true, "message": "ios-webkit-debug-proxy restarted. Use list_devices and select_page to reconnect."}, nil
+	})
+
 	// --- Device/Page management ---
 	mcp.AddTool(server, &mcp.Tool{
 		Name: "list_devices", Description: "List connected iOS devices (from iwdp listing port 9221). Each device's URL shows which port to use for list_pages.",
@@ -1532,17 +1548,21 @@ func registerTools(server *mcp.Server) {
 	})
 
 	mcp.AddTool(server, &mcp.Tool{
-		Name: "heap_snapshot", Description: "Take a heap snapshot",
+		Name: "heap_snapshot", Description: "Take a heap snapshot and save to file. Warning: can be very large (50-200+ MB) on heavy pages and may take minutes.",
 	}, func(ctx context.Context, req *mcp.CallToolRequest, _ HeapSnapshotInput) (*mcp.CallToolResult, any, error) {
 		c, err := getClient(ctx)
 		if err != nil {
-			return nil, RawOutput{}, err
+			return nil, TextOutput{}, err
 		}
-		result, err := tools.HeapSnapshot(ctx, c)
+		filePath, err := tools.HeapSnapshot(ctx, c)
 		if err != nil {
-			return nil, RawOutput{}, err
+			return nil, TextOutput{}, err
 		}
-		return nil, RawOutput{Result: result}, nil
+		return &mcp.CallToolResult{
+			Content: []mcp.Content{&mcp.TextContent{
+				Text: fmt.Sprintf("Heap snapshot saved to %s — use the Read tool to view it.", filePath),
+			}},
+		}, TextOutput{Text: filePath}, nil
 	})
 
 	mcp.AddTool(server, &mcp.Tool{

internal/proxy/proxy.go

@@ -59,13 +59,23 @@ func Start(ctx context.Context) error {
 }
 
 // EnsureRunning checks if iwdp is running and starts it if not.
+// If iwdp crashed (e.g., after a large heap snapshot), this will restart it.
 func EnsureRunning(ctx context.Context) error {
 	if IsRunning() {
 		return nil
 	}
 	return Start(ctx)
 }
 
+// Restart kills any existing iwdp process and starts a fresh one.
+// Use this when iwdp is in a bad state (e.g., after a WebSocket crash).
+func Restart(ctx context.Context) error {
+	// Best-effort kill — ignore errors if not running
+	_ = exec.Command("pkill", "-f", "ios_webkit_debug_proxy").Run()
+	time.Sleep(500 * time.Millisecond)
+	return Start(ctx)
+}
+
 // ListDevices fetches connected devices from the listing port (9221).
 // Each device entry contains a URL like "localhost:9222" indicating
 // which port to query for that device's pages.

internal/tools/memory.go

@@ -3,10 +3,18 @@ package tools
 import (
 	"context"
 	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
 
 	"github.com/nnemirovsky/iwdp-mcp/internal/webkit"
 )
 
+// HeapSnapshotTimeout is the maximum time to wait for a heap snapshot.
+// Large pages can take a long time to serialize their heap.
+var HeapSnapshotTimeout = 5 * time.Minute
+
 // MemoryStartTracking starts memory tracking.
 func MemoryStartTracking(ctx context.Context, client *webkit.Client) error {
 	_, err := client.Send(ctx, "Memory.startTracking", nil)
@@ -19,13 +27,52 @@ func MemoryStopTracking(ctx context.Context, client *webkit.Client) error {
 	return err
 }
 
-// HeapSnapshot takes a heap snapshot and returns the raw result.
-func HeapSnapshot(ctx context.Context, client *webkit.Client) (json.RawMessage, error) {
+// HeapSnapshot takes a heap snapshot and saves it to a temp file.
+// Heap snapshots can be 50-200+ MB on heavy pages, so we stream directly
+// to disk instead of holding the entire snapshot in memory.
+func HeapSnapshot(ctx context.Context, client *webkit.Client) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, HeapSnapshotTimeout)
+	defer cancel()
+
 	result, err := client.Send(ctx, "Heap.snapshot", nil)
 	if err != nil {
-		return nil, err
+		return "", fmt.Errorf("heap snapshot failed (page may be too large): %w", err)
+	}
+
+	tmpDir := filepath.Join(os.TempDir(), "iwdp-mcp")
+	if err := os.MkdirAll(tmpDir, 0o755); err != nil {
+		return "", fmt.Errorf("creating temp dir: %w", err)
+	}
+	f, err := os.CreateTemp(tmpDir, "heap-snapshot-*.json")
+	if err != nil {
+		return "", fmt.Errorf("creating temp file: %w", err)
+	}
+	defer func() { _ = f.Close() }()
+
+	// Extract snapshotData string if present, otherwise write raw result
+	var snap struct {
+		SnapshotData json.RawMessage `json:"snapshotData"`
 	}
-	return result, nil
+	if json.Unmarshal(result, &snap) == nil && len(snap.SnapshotData) > 0 {
+		// snapshotData is a JSON string — unquote it to get the raw snapshot
+		var data string
+		if json.Unmarshal(snap.SnapshotData, &data) == nil {
+			if _, err := f.WriteString(data); err != nil {
+				return "", fmt.Errorf("writing snapshot: %w", err)
+			}
+		} else {
+			// Not a string, write as-is
+			if _, err := f.Write(snap.SnapshotData); err != nil {
+				return "", fmt.Errorf("writing snapshot: %w", err)
+			}
+		}
+	} else {
+		if _, err := f.Write(result); err != nil {
+			return "", fmt.Errorf("writing snapshot: %w", err)
+		}
+	}
+
+	return f.Name(), nil
 }
 
 // HeapStartTracking starts heap tracking.

internal/tools/tools_domains_test.go

@@ -3,6 +3,7 @@ package tools_test
 import (
 	"context"
 	"encoding/json"
+	"os"
 	"testing"
 	"time"
 
@@ -481,24 +482,23 @@ func TestHeapSnapshot(t *testing.T) {
 	mock, client := setup(t)
 	mock.HandleFunc("Heap.snapshot", map[string]interface{}{
 		"snapshotData": "snapshot-content",
-		"title":        "Heap Snapshot",
 	})
 
 	ctx := context.Background()
-	result, err := tools.HeapSnapshot(ctx, client)
+	filePath, err := tools.HeapSnapshot(ctx, client)
 	if err != nil {
 		t.Fatalf("HeapSnapshot returned error: %v", err)
 	}
-	if result == nil {
-		t.Fatal("expected non-nil result")
+	if filePath == "" {
+		t.Fatal("expected non-empty file path")
 	}
-	// Verify the raw JSON contains expected data.
-	var parsed map[string]interface{}
-	if err := json.Unmarshal(result, &parsed); err != nil {
-		t.Fatalf("failed to parse result JSON: %v", err)
+	defer func() { _ = os.Remove(filePath) }()
+	data, err := os.ReadFile(filePath)
+	if err != nil {
+		t.Fatalf("failed to read snapshot file: %v", err)
 	}
-	if parsed["title"] != "Heap Snapshot" {
-		t.Errorf("expected title %q, got %v", "Heap Snapshot", parsed["title"])
+	if string(data) != "snapshot-content" {
+		t.Errorf("expected %q, got %q", "snapshot-content", string(data))
 	}
 }
 

internal/webkit/client.go

@@ -81,8 +81,10 @@ func NewClientWithDialer(ctx context.Context, wsURL string, dialer *websocket.Di
 	return c, nil
 }
 
-// maxReadSize is the maximum WebSocket message size the client will accept (64 MB).
-const maxReadSize = 64 * 1024 * 1024
+// maxReadSize is the maximum WebSocket message size the client will accept (512 MB).
+// Heap snapshots on heavy pages can be 50-200+ MB, and Target-based routing adds
+// ~30% overhead from JSON string escaping, so we need a generous limit.
+const maxReadSize = 512 * 1024 * 1024
 
 func (c *Client) connect(ctx context.Context) error {
 	conn, _, err := c.Dialer.DialContext(ctx, c.url, nil)