@samitouri / QOS-React-2
Code Commits Issues Pulls Sessions CI/CD
main
main
md 153 lines 5.21 KB
Rendered Raw
1 # react-devtools-cdt-mcp
2
3 Integrates React tools with
4 [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp).
5
6 Importing `react-devtools-cdt-mcp/register` **before React** installs the
7 DevTools hook and registers a React tool group via chrome-devtools-mcp's
8 `devtoolstooldiscovery` / `__dtmcp` third-party-tool protocol. The React tools
9 then become discoverable and callable inside a chrome-devtools-mcp session — no
10 separate server.
11
12 ## Usage
13
14 Import the register entry **before** React so the hook is installed before
15 React initializes:
16
17 ```js
18 import 'react-devtools-cdt-mcp/register';
19 import React from 'react';
20 ```
21
22 The package root is side-effect-free and exports the lower-level API for custom
23 targets:
24
25 ```js
26 import {register, buildToolGroup} from 'react-devtools-cdt-mcp';
27 ```
28
29 When the page runs under chrome-devtools-mcp, the React tools are listed by
30 `list_3p_developer_tools` and callable either via
31 `execute_3p_developer_tool({toolName, params})` or directly via `evaluate_script`
32 (`window.__dtmcp.executeTool(toolName, params)`).
33
34 ## Conventions
35
36 - **UIDs** — components are identified by a stable uid like `r5`. UIDs
37 are consistent across every tool and across re-renders. These UIDs don't survive page reloads.
38 - **Output** — every tool returns the shape described below as a plain
39 JavaScript value. On failure a tool returns `{error: string}` instead.
40 - **Durations** — profiler durations are in milliseconds, or `null` when the
41 build does not collect profiling timing.
42
43 ## Tools
44
45 ### `react_get_component_tree`
46
47 Snapshot of the component tree.
48
49 - **Input:** `depth?` (number, max depth, default 20), `rootUid?` (string,
50 start from this component).
51 - **Output:** `{nodes}` where `nodes` is an array of
52 `{uid, type, name, key, firstChild, nextSibling}`. `firstChild` and
53 `nextSibling` reference other nodes by uid (or are `null`).
54
55 ### `react_get_component_by_uid`
56
57 Detailed info for a single component.
58
59 - **Input:** `uid` (string, required), `includeHooks?` (boolean, default
60 `false`).
61 - **Output:** `{uid, type, name, key?, props?, hooks?}`. `props` excludes
62 children and is normalized to a serialization-safe shape; when `includeHooks`
63 is true, `hooks` (function, forwardRef, and memo components) is an array of
64 `{id, name, value, subHooks}`.
65
66 ### `react_get_component_by_dom_element`
67
68 Detailed info for the React DOM component corresponding to a DOM element.
69
70 - **Input:** `element` (object, required). This is an opaque page-side DOM
71 element reference. Chrome DevTools MCP clients pass this as
72 `{uid: string}`, using an element uid from the page snapshot.
73 - **Output:** `{uid, type, name, key?, props?, hooks?}`.
74
75 ### `react_find_components`
76
77 Find components by case-insensitive name substring.
78
79 - **Input:** `name` (string, required), `rootUid?` (string, limit to subtree),
80 `page?` (number, default 1), `pageSize?` (number, default 10).
81 - **Output:** `{page, pageSize, totalCount, totalPages, results}` where
82 `results` is an array of tree nodes (same shape as `react_get_component_tree`).
83
84 ### `react_get_component_source`
85
86 Definition source location of a component.
87
88 - **Input:** `uid` (string, required).
89 - **Output:** `{source: {name, fileName, line, column}}`, or `{source: null}`
90 when the location cannot be determined (e.g. host components, production
91 builds).
92
93 ### `react_get_owner_stack_trace`
94
95 Raw owner stack trace — the chain of JSX creation locations up to the root.
96
97 - **Input:** `uid` (string, required).
98 - **Output:** `{stack: string}` (DEV-only; empty in production).
99
100 ### `react_get_parent_stack`
101
102 Rendered parent list — where a component is mounted in the rendered component
103 tree.
104
105 - **Input:** `uid` (string, required).
106 - **Output:** an array of `{uid, name, type}`, ordered from immediate parent to
107 root (empty for the root). This can include host DOM components and the root.
108
109 ### `react_get_owner_stack`
110
111 Structured owner list — which components created/rendered this element through
112 JSX.
113
114 - **Input:** `uid` (string, required).
115 - **Output:** an array of `{uid, name, type}`, ordered from immediate owner to
116 root owner (empty for a root component). DEV-only. Owners are not structural
117 parents; use `react_get_parent_stack` for mounted tree ancestry.
118
119 ### `react_start_profiling`
120
121 Start a profiling session that records per-commit render timing.
122
123 - **Input:** `traceName?` (string, trace name; auto-generated if omitted).
124 - **Output:** `{status: "started", traceName}`.
125
126 ### `react_stop_profiling`
127
128 Stop the active profiling session.
129
130 - **Input:** none.
131 - **Output:** `{status: "stopped", traceName, commits}` (`commits` is the number of
132 commits recorded).
133
134 ### `react_get_trace_overview`
135
136 Per-commit overview of a recorded trace.
137
138 - **Input:** `traceName` (string, required).
139 - **Output:** array of
140 `{commit, committedAt, renderDuration, layoutDuration, passiveDuration, componentsChanged}`,
141 one row per commit.
142
143 ### `react_get_commit_report`
144
145 Detailed report for a single commit.
146
147 - **Input:** `traceName` (string, required), `commitIndex` (number, required;
148 zero-based).
149 - **Output:**
150 `{committedAt, priority, renderDuration, layoutDuration, passiveDuration, components}`
151 where `components` is an array of
152 `{uid, name, type, actualDuration, selfDuration}` sorted by `actualDuration`
153 descending.