feat: add MCP server for Claude Code integration (#1598)

## Please verify the following:

- [x] `yarn build-and-test:local` passes
- [x] I have added tests for any new features, if relevant
- [x] `README.md` (or relevant documentation) has been updated with your
changes

## Describe your PR

Adds a built-in [MCP](https://modelcontextprotocol.io/) server to
Reactotron, allowing AI coding assistants like [Claude
Code](https://claude.ai/claude-code) to read debug events and send
commands to connected React Native / React apps.

### What it does

**New package: `reactotron-mcp`** (`lib/reactotron-mcp/`)

A self-contained MCP server that receives the `reactotron-core-server`
instance and exposes its data as MCP resources and tools over HTTP.

**Resources** (read-only debug data):
- Timeline — last 500 events (logs, state changes, network, benchmarks,
custom commands)
- App state — latest cached Redux/MST snapshot
- Network log — captured HTTP request/response pairs
- Connected apps — with platform, version, and clientId
- Benchmarks — performance benchmark results
- State subscriptions — values at subscribed state paths
- AsyncStorage — mutations (setItem, removeItem, etc.)

**Tools** (interact with running app):
- `dispatch_action` — dispatch Redux actions with confirmation polling
- `request_state` — request fresh state snapshot (1.5s timeout)
- `swap_state` — hot-swap entire state tree
- `send_custom_command` — trigger registered custom commands
- `list_custom_commands` — discover available custom commands
- `show_overlay` — image overlay with local file→base64 conversion and
dimension extraction
- `subscribe_state` / `unsubscribe_state` — watch state paths for
changes
- `clear_timeline` — clear MCP event buffer

### Architecture

```
React Native app
    | WebSocket (port 9090, unchanged)
    v
Reactotron Desktop
    ├── relay server (reactotron-core-server, unchanged)
    └── MCP server (reactotron-mcp, HTTP on configurable port)
          ↑
Claude Code
```

- **No changes to the React Native app or relay protocol**
- MCP server reads directly from the server instance's connections and
event emitter
- Built with tsup (Node.js server, not a React Native lib)
- Bundles `@modelcontextprotocol/sdk` (its CJS exports are broken)
- Stateless per-request HTTP transport (required by MCP SDK)

### Desktop app changes

- "MCP" toggle button in the footer bar with green status indicator
- MCP port configurable via electron-store (default: 4567, localhost
only)
- `reactotron-mcp` is NOT whitelisted in electron-webpack — loaded via
Node.js at runtime

### Multi-app support

When multiple apps are connected, resources include `_meta` hints
guiding Claude to ask the user which app they're working on. Single-app
connections are auto-selected.

### Setup

```bash
claude mcp add --transport http reactotron http://localhost:4567/mcp
```

### Tests

20 integration tests covering resources, tools, multi-app handling, and
edge cases.

### Documentation

Added `docs/mcp.md` with getting started guide, feature overview, and
architecture docs.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Joshua Yoes <37849890+joshuayoes@users.noreply.github.com>

Author: 3 people

.yarn/patches/expo-localization-npm-15.0.3-6e534a2836.patch

@@ -0,0 +1,13 @@
+diff --git a/ios/LocalizationModule.swift b/ios/LocalizationModule.swift
+index 17c9cb78a927db705f331827f4f48e894317c42f..26bbc58d567a8a69df1fdf25413d04e2fc433480 100644
+--- a/ios/LocalizationModule.swift
++++ b/ios/LocalizationModule.swift
+@@ -123,6 +123,8 @@ public class LocalizationModule: Module {
+       return "roc"
+     case .iso8601:
+       return "iso8601"
++    @unknown default:
++      return calendar.identifier.debugDescription
+     }
+   }
+ 

apps/example-app/app/devtools/ReactotronConfig.ts

@@ -117,6 +117,58 @@ reactotron.onCustomCommand({
   },
 })
 
+reactotron.onCustomCommand<[{ name: "message"; type: ArgType.String }]>({
+  command: "showAlert",
+  title: "Show Alert",
+  description: "Displays an alert dialog on the device with a custom message",
+  args: [{ name: "message", type: ArgType.String }],
+  handler: (args) => {
+    const { message } = args ?? {}
+    const { Alert } = require("react-native")
+    Alert.alert("Reactotron", message || "Hello from Reactotron!")
+    Reactotron.log(`Alert shown: ${message || "Hello from Reactotron!"}`)
+  },
+})
+
+reactotron.onCustomCommand<[{ name: "key"; type: ArgType.String }, { name: "value"; type: ArgType.String }]>({
+  command: "setAsyncStorage",
+  title: "Set AsyncStorage Value",
+  description: "Sets a key/value pair in AsyncStorage",
+  args: [
+    { name: "key", type: ArgType.String },
+    { name: "value", type: ArgType.String },
+  ],
+  handler: async (args) => {
+    const { key, value } = args ?? {}
+    if (key && value) {
+      await AsyncStorage.setItem(key, value)
+      Reactotron.log(`AsyncStorage set: ${key} = ${value}`)
+    } else {
+      Reactotron.log("Missing key or value")
+    }
+  },
+})
+
+reactotron.onCustomCommand<[{ name: "key"; type: ArgType.String }]>({
+  command: "getAsyncStorage",
+  title: "Get AsyncStorage Value",
+  description: "Reads a value from AsyncStorage and logs it to the timeline",
+  args: [{ name: "key", type: ArgType.String }],
+  handler: async (args) => {
+    const { key } = args ?? {}
+    if (key) {
+      const value = await AsyncStorage.getItem(key)
+      Reactotron.display({
+        name: "AsyncStorage",
+        preview: `${key} = ${value}`,
+        value: { key, value },
+      })
+    } else {
+      Reactotron.log("Missing key")
+    }
+  },
+})
+
 /**
  * We're going to add `console.tron` to the Reactotron object.
  * Now, anywhere in our app in development, we can use Reactotron like so:

apps/example-app/app/screens/LoggingScreen.tsx

@@ -105,6 +105,44 @@ export const LoggingScreen: React.FC<LoggingScreenProps> = function LoggingScree
             }}
           />
         </View>
+        <View style={$topContainer}>
+          <Text style={$text} text="Stress Test" />
+        </View>
+        <View style={{ marginTop: spacing.lg }}>
+          <Button
+            text="Spam 100 logs"
+            textStyle={$darkText}
+            style={$button}
+            onPress={() => {
+              for (let i = 0; i < 100; i++) {
+                console.log(`Spam log #${i}`, {
+                  index: i,
+                  timestamp: Date.now(),
+                  data: "x".repeat(500),
+                  nested: { a: { b: { c: { d: `deep-value-${i}` } } } },
+                })
+              }
+            }}
+          />
+          <Button
+            text="Log huge object"
+            textStyle={$darkText}
+            style={$button}
+            onPress={() => {
+              const bigState: Record<string, any> = {}
+              for (let i = 0; i < 200; i++) {
+                bigState[`key_${i}`] = {
+                  id: i,
+                  name: `Item ${i}`,
+                  description: `This is a description for item ${i} with some padding ${"x".repeat(200)}`,
+                  tags: Array.from({ length: 10 }, (_, j) => `tag-${i}-${j}`),
+                  metadata: { created: new Date().toISOString(), updated: new Date().toISOString() },
+                }
+              }
+              console.log("Huge state dump:", bigState)
+            }}
+          />
+        </View>
         <View style={$topContainer}>
           <Text style={$text} tx="loggingsScreen.subtitle" />
         </View>

apps/example-app/package.json

@@ -46,7 +46,7 @@
     "expo-font": "~12.0.10",
     "expo-linear-gradient": "~13.0.2",
     "expo-linking": "~6.3.1",
-    "expo-localization": "~15.0.3",
+    "expo-localization": "patch:expo-localization@npm%3A15.0.3#~/.yarn/patches/expo-localization-npm-15.0.3-6e534a2836.patch",
     "expo-splash-screen": "~0.27.7",
     "expo-status-bar": "~1.12.1",
     "i18n-js": "3.9.2",

apps/reactotron-app/package.json

@@ -68,6 +68,7 @@
     "reactotron-core-contract": "workspace:*",
     "reactotron-core-server": "workspace:*",
     "reactotron-core-ui": "workspace:*",
+    "reactotron-mcp": "workspace:*",
     "source-map-support": "^0.5.21",
     "styled-components": "^6.1.0",
     "v8-compile-cache": "^2.4.0"

apps/reactotron-app/src/renderer/components/Footer/Footer.story.tsx

@@ -63,6 +63,9 @@ storiesOf("components/Footer", module)
       isOpen={false}
       setIsOpen={() => {}}
       onChangeConnection={() => {}}
+      mcpStatus="stopped"
+      mcpPort={null}
+      onToggleMcp={() => {}}
     />
   ))
   .add("Collpased w/ connections", () => (
@@ -73,6 +76,9 @@ storiesOf("components/Footer", module)
       isOpen={false}
       setIsOpen={() => {}}
       onChangeConnection={() => {}}
+      mcpStatus="stopped"
+      mcpPort={null}
+      onToggleMcp={() => {}}
     />
   ))
   .add("Expanded", () => (
@@ -83,6 +89,9 @@ storiesOf("components/Footer", module)
       isOpen
       setIsOpen={() => {}}
       onChangeConnection={() => {}}
+      mcpStatus="stopped"
+      mcpPort={null}
+      onToggleMcp={() => {}}
     />
   ))
   .add("Expanded w/ connections", () => (
@@ -93,6 +102,9 @@ storiesOf("components/Footer", module)
       isOpen
       setIsOpen={() => {}}
       onChangeConnection={() => {}}
+      mcpStatus="started"
+      mcpPort={4567}
+      onToggleMcp={() => {}}
     />
   ))
   .add("Expanded w/ lots connections", () => (
@@ -103,5 +115,8 @@ storiesOf("components/Footer", module)
       isOpen
       setIsOpen={() => {}}
       onChangeConnection={() => {}}
+      mcpStatus="started"
+      mcpPort={4567}
+      onToggleMcp={() => {}}
     />
   ))

apps/reactotron-app/src/renderer/components/Footer/Stateless.tsx

@@ -9,6 +9,7 @@ import {
   getConnectionName,
 } from "../../util/connectionHelpers"
 import { Connection, ServerStatus } from "../../contexts/Standalone/useStandalone"
+import { McpStatus } from "../../contexts/Standalone"
 import ConnectionSelector from "../ConnectionSelector"
 
 const Container = styled.div`
@@ -49,6 +50,34 @@ const ExpandContainer = styled.div`
   cursor: pointer;
 `
 
+interface McpButtonProps {
+  $active: boolean
+}
+
+const McpButton = styled.div.attrs(() => ({}))<McpButtonProps>`
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 2px 8px;
+  border-radius: 3px;
+  cursor: pointer;
+  font-size: 11px;
+  user-select: none;
+  background-color: ${(props) => props.$active ? "rgba(80, 200, 120, 0.15)" : "transparent"};
+  border: 1px solid ${(props) => props.$active ? "rgba(80, 200, 120, 0.4)" : props.theme.chromeLine};
+  color: ${(props) => props.$active ? "#50c878" : props.theme.foregroundDark};
+  &:hover {
+    background-color: ${(props) => props.$active ? "rgba(80, 200, 120, 0.25)" : "rgba(255,255,255,0.05)"};
+  }
+`
+
+const McpDot = styled.div<McpButtonProps>`
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background-color: ${(props) => props.$active ? "#50c878" : props.theme.foregroundDark};
+`
+
 function renderExpanded(
   serverStatus: ServerStatus,
   connections: Connection[],
@@ -105,6 +134,9 @@ interface Props {
   isOpen: boolean
   setIsOpen: (isOpen: boolean) => void
   onChangeConnection: (clientId: string | null) => void
+  mcpStatus: McpStatus
+  mcpPort: number | null
+  onToggleMcp: () => void
 }
 
 function Header({
@@ -114,13 +146,24 @@ function Header({
   isOpen,
   setIsOpen,
   onChangeConnection,
+  mcpStatus,
+  mcpPort,
+  onToggleMcp,
 }: Props) {
   const renderMethod = isOpen ? renderExpanded : renderCollapsed
 
   return (
     <Container>
       <ContentContainer onClick={() => !isOpen && setIsOpen(true)} $isOpen={isOpen}>
         {renderMethod(serverStatus, connections, selectedConnection, onChangeConnection)}
+        <McpButton
+          $active={mcpStatus === "started"}
+          onClick={(e) => { e.stopPropagation(); onToggleMcp() }}
+          title={mcpStatus === "started" ? `MCP running on port ${mcpPort}` : "Start MCP server"}
+        >
+          <McpDot $active={mcpStatus === "started"} />
+          {mcpStatus === "started" ? `MCP :${mcpPort}` : "MCP"}
+        </McpButton>
         <ExpandContainer onClick={() => setIsOpen(!isOpen)}>
           <ExpandIcon size={18} />
         </ExpandContainer>

apps/reactotron-app/src/renderer/components/Footer/index.tsx

@@ -5,7 +5,7 @@ import StandaloneContext from "../../contexts/Standalone"
 import Footer from "./Stateless"
 
 export default function ConnectedFooter() {
-  const { serverStatus, connections, selectedConnection, selectConnection } =
+  const { serverStatus, connections, selectedConnection, selectConnection, mcpStatus, mcpPort, toggleMcp } =
     useContext(StandaloneContext)
   const [isOpen, setIsOpen] = useState(false)
 
@@ -17,6 +17,9 @@ export default function ConnectedFooter() {
       onChangeConnection={selectConnection}
       isOpen={isOpen}
       setIsOpen={setIsOpen}
+      mcpStatus={mcpStatus}
+      mcpPort={mcpPort}
+      onToggleMcp={toggleMcp}
     />
   )
 }

apps/reactotron-app/src/renderer/config.ts

@@ -3,6 +3,7 @@ import Store from "electron-store"
 type StoreType = {
   serverPort: number
   commandHistory: number
+  mcpPort: number
 }
 
 const config = new Store<StoreType>({
@@ -15,6 +16,10 @@ const config = new Store<StoreType>({
       type: "number",
       default: 500,
     },
+    mcpPort: {
+      type: "number",
+      default: 4567,
+    },
   },
 })
 
@@ -25,5 +30,8 @@ if (!config.has("serverPort")) {
 if (!config.has("commandHistory")) {
   config.set("commandHistory", 500)
 }
+if (!config.has("mcpPort")) {
+  config.set("mcpPort", 4567)
+}
 
 export default config

apps/reactotron-app/src/renderer/contexts/Standalone/index.tsx

@@ -1,24 +1,33 @@
-import React, { useRef, useEffect, useCallback } from "react"
+import React, { useRef, useEffect, useCallback, useState } from "react"
 import Server, { createServer } from "reactotron-core-server"
+import { createMcpServer, type ReactotronMcpServer } from "reactotron-mcp"
 
 import ReactotronBrain from "../../ReactotronBrain"
 import config from "../../config"
 
 import useStandalone, { Connection, ServerStatus } from "./useStandalone"
 
+export type McpStatus = "stopped" | "started" | "error"
+
 // TODO: Move up to better places like core somewhere!
 interface Context {
   serverStatus: ServerStatus
   connections: Connection[]
   selectedConnection: Connection
   selectConnection: (clientId: string) => void
+  mcpStatus: McpStatus
+  mcpPort: number | null
+  toggleMcp: () => void
 }
 
 const StandaloneContext = React.createContext<Context>({
   serverStatus: "stopped",
   connections: [],
   selectedConnection: null,
   selectConnection: null,
+  mcpStatus: "stopped",
+  mcpPort: null,
+  toggleMcp: () => {},
 })
 
 const Provider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
@@ -66,6 +75,44 @@ const Provider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
     portUnavailable,
   ])
 
+  const mcpServerRef = useRef<ReactotronMcpServer>(null)
+  const [mcpStatus, setMcpStatus] = useState<McpStatus>("stopped")
+  const [mcpPort, setMcpPort] = useState<number | null>(null)
+
+  // Clean up MCP server on unmount
+  useEffect(() => {
+    return () => {
+      if (mcpServerRef.current) {
+        mcpServerRef.current.stop()
+        mcpServerRef.current = null
+      }
+    }
+  }, [])
+
+  const toggleMcp = useCallback(() => {
+    if (!reactotronServer.current) return
+
+    if (mcpStatus === "started") {
+      if (mcpServerRef.current) {
+        mcpServerRef.current.stop()
+        mcpServerRef.current = null
+      }
+      setMcpStatus("stopped")
+      setMcpPort(null)
+    } else {
+      const port = config.get("mcpPort") as number
+      const mcp = createMcpServer(reactotronServer.current)
+      mcp.start(port).then(() => {
+        mcpServerRef.current = mcp
+        setMcpStatus("started")
+        setMcpPort(port)
+      }).catch(() => {
+        setMcpStatus("error")
+        setMcpPort(null)
+      })
+    }
+  }, [mcpStatus])
+
   const sendCommand = useCallback(
     (type: string, payload: any, clientId?: string) => {
       // TODO: Do better then just throwing these away...
@@ -83,6 +130,9 @@ const Provider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
         connections,
         selectedConnection,
         selectConnection,
+        mcpStatus,
+        mcpPort,
+        toggleMcp,
       }}
     >
       <ReactotronBrain