react-devtools-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Skylar Barrera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# react-devtools-bridge
+
+Give AI agents eyes into your React app.
+
+## Setup
+
+### 1. Add MCP server to Claude Code
+
+`.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "react-devtools": {
+      "command": "npx",
+      "args": ["react-devtools-bridge"]
+    }
+  }
+}
+```
+
+### 2. Connect your React app
+
+**Web** - Add to your HTML (before your app bundle):
+```html
+<script src="http://localhost:8097"></script>
+```
+
+**React Native** - DevTools is built-in. No extra setup needed.
+
+### 3. (Optional) Install the skill
+
+Teach Claude when to use these tools:
+
+```bash
+npx add-skill skylarbarrera/react-devtools-mcp
+```
+
+Or manually:
+```bash
+cp node_modules/react-devtools-bridge/SKILL.md ~/.claude/skills/react-devtools/SKILL.md
+```
+
+## Usage
+
+With your React app running, ask Claude things like:
+- "What's the current state of the Counter component?"
+- "Why doesn't clicking this button update the UI?"
+- "Which components are re-rendering too often?"
+
+## Docs
+
+- [All tools](TOOLS.md)
+- [Skill guide](SKILL.md) - When and how to use each tool
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: react-devtools
+description: Debug React apps by inspecting runtime state, props, hooks, and renders
+---
+
+# React DevTools
+
+Inspect running React apps. See actual props, state, hooks - not just source code.
+
+## When to Use
+
+**Use these tools when:**
+- User says "why doesn't this update" or "state is wrong"
+- Behavior doesn't match what code suggests
+- Need to verify actual runtime values
+- Debugging performance / excessive renders
+- Exploring unfamiliar React codebase
+
+**Don't use when:**
+- Bug is obvious from source (missing dep, typo)
+- Just need to read/edit files
+- No React app is running
+
+## Setup Check
+
+Before using, ensure:
+1. MCP server is configured in `.mcp.json`
+2. React app is running with DevTools connected
+
+## Core Workflow
+
+### 1. Connect
+```
+connect()
+```
+
+### 2. Find the component
+```
+search_components({ query: "ComponentName" })
+```
+or
+```
+get_component_tree()
+```
+
+### 3. Inspect it
+```
+inspect_element({ id: <element_id> })
+```
+
+Returns: `{ props, state, hooks, context }`
+
+## Common Debugging Patterns
+
+### "Why doesn't clicking X update Y?"
+```
+1. search_components({ query: "ButtonComponent" })
+2. inspect_element({ id }) → check state/props
+3. Compare actual values vs expected
+```
+
+### "This component re-renders too much"
+```
+1. start_profiling()
+2. [user interacts with app]
+3. stop_profiling() → see render counts and timing
+```
+
+### "What's the actual value of this state?"
+```
+1. search_components({ query: "ComponentName" })
+2. inspect_element({ id })
+3. Look at hooks[].value for useState values
+```
+
+### "Who renders this component?"
+```
+get_owners_list({ id }) → shows parent chain
+```
+
+## Key Tools
+
+| Tool | Use For |
+|------|---------|
+| `inspect_element` | See props, state, hooks, context |
+| `search_components` | Find component by name |
+| `get_component_tree` | See full hierarchy |
+| `get_owners_list` | Trace render chain |
+| `start/stop_profiling` | Measure render performance |
+| `highlight_element` | Visually identify component in app |
+
+## Tips
+
+- Element IDs change on hot reload - re-search after code changes
+- Use `highlight_element` to confirm you're looking at the right component
+- Hooks are indexed - `hooks[0]` is first useState/useEffect in component

package/TOOLS.md

@@ -0,0 +1,96 @@
+# Tools
+
+## Connection
+
+| Tool | Description |
+|------|-------------|
+| `connect` | Connect to DevTools backend |
+| `disconnect` | Disconnect |
+| `get_connection_status` | Check connection state |
+| `health_check` | Server health status |
+
+## Component Tree
+
+| Tool | Description |
+|------|-------------|
+| `get_component_tree` | Get full component hierarchy |
+| `get_element_by_id` | Get element info |
+| `search_components` | Find components by name |
+| `get_owners_list` | Get render chain (who rendered this) |
+| `get_element_source` | Get source file location |
+
+## Inspection
+
+| Tool | Description |
+|------|-------------|
+| `inspect_element` | Get props, state, hooks, context |
+| `get_native_style` | Get style info (React Native) |
+
+## Mutation
+
+| Tool | Description |
+|------|-------------|
+| `override_props` | Change a prop value |
+| `override_state` | Change state (class components) |
+| `override_hooks` | Change hook value (function components) |
+| `override_context` | Change context value |
+| `delete_path` | Delete a prop/state/hook/context path |
+| `rename_path` | Rename a key |
+| `set_native_style` | Set style (React Native) |
+
+## Profiling
+
+| Tool | Description |
+|------|-------------|
+| `start_profiling` | Start recording renders |
+| `stop_profiling` | Stop and get profiling data |
+| `get_profiling_data` | Get data without stopping |
+| `get_profiling_status` | Check if profiling is active |
+
+## Errors & Warnings
+
+| Tool | Description |
+|------|-------------|
+| `get_errors_and_warnings` | Get all React errors/warnings |
+| `clear_errors_and_warnings` | Clear errors/warnings |
+| `toggle_error` | Force error boundary state |
+| `toggle_suspense` | Force suspense state |
+
+## UI Helpers
+
+| Tool | Description |
+|------|-------------|
+| `highlight_element` | Highlight element in app |
+| `clear_highlight` | Remove highlight |
+| `scroll_to_element` | Scroll to show element |
+| `log_to_console` | Log element as `$r` in console |
+| `store_as_global` | Store value as global variable |
+| `view_source` | Open source in IDE |
+
+## Filters
+
+| Tool | Description |
+|------|-------------|
+| `get_component_filters` | Get current filters |
+| `set_component_filters` | Hide certain components |
+| `set_trace_updates_enabled` | Toggle render highlighting |
+
+## Native Inspection (React Native)
+
+| Tool | Description |
+|------|-------------|
+| `start_inspecting_native` | Start tap-to-select mode |
+| `stop_inspecting_native` | Stop inspection mode |
+| `get_inspecting_native_status` | Check if inspecting |
+| `capture_screenshot` | Screenshot an element |
+
+## Advanced
+
+| Tool | Description |
+|------|-------------|
+| `get_renderers` | List all React renderers |
+| `get_renderer` | Get specific renderer |
+| `get_elements_by_renderer` | Elements for a renderer |
+| `get_capabilities` | Protocol capabilities |
+| `view_attribute_source` | Source for specific attribute |
+| `save_to_clipboard` | Copy to clipboard |