@player-devtools/mcp 0.14.3--canary.24.1132 → 0.15.1--canary.29.1254

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,7 +6,7 @@ Player instance: list running Players, read their flow / data / logs / config,
6
6
  inspect plugin state, select a Player, and invoke plugin actions.
7
7
 
8
8
  It is the agent-facing sibling of the [browser extension] and the
9
- [Flipper plugin](../flipper-plugin): all three are Devtools *clients* that speak
9
+ [Flipper plugin](../flipper-plugin): all three are Devtools _clients_ that speak
10
10
  to the same Player Devtools plugins over the [messenger](../messenger) protocol.
11
11
  The MCP server connects to those plugins through a running
12
12
  [`flipper-server`](https://github.com/facebook/flipper) and re-exposes them as
@@ -61,23 +61,38 @@ The server registers the following tools (defined as `ToolDef`s in
61
61
  player-scoped tool takes an optional `playerId` and falls back to the currently
62
62
  selected Player when it's omitted.
63
63
 
64
- | Tool | Args | Returns |
65
- | --- | --- | --- |
66
- | `list_players` | — | All known Player instances and which one is selected. |
67
- | `get_player_status` | `playerId?` | Active status + registered plugin IDs. |
68
- | `get_flow` | `playerId?` | The current flow (from the basic plugin). |
69
- | `get_data` | `playerId?` | The current flow data model. |
70
- | `get_logs` | `playerId?` | Accumulated runtime logs. |
71
- | `get_plugin_data` | `playerId?`, `pluginId`, `dataKey` | A specific data key from any plugin. |
72
- | `describe_plugin` | `playerId?`, `pluginId` | The plugin's capability descriptor — the data keys and actions it exposes. **Call this first** to discover what a plugin supports. |
73
- | `select_player` | `playerId` | Selects a Player as the default target for later calls. |
74
- | `invoke_action` | `playerId?`, `pluginId`, `action`, `payload?` | Invokes a named action (validated against the plugin's declared capabilities). |
64
+ | Tool | Args | Returns |
65
+ | ------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
66
+ | `list_players` | — | All known Player instances and which one is selected. |
67
+ | `get_player_status` | `playerId?` | Active status + registered plugin IDs. |
68
+ | `get_flow` | `playerId?` | The current flow (from the basic plugin). |
69
+ | `get_data` | `playerId?` | The current flow data model. |
70
+ | `get_logs` | `playerId?` | Accumulated runtime logs. |
71
+ | `get_plugin_data` | `playerId?`, `pluginId`, `dataKey` | A specific data key from any plugin. |
72
+ | `describe_plugin` | `playerId?`, `pluginId` | The plugin's capability descriptor — the data keys and actions it exposes. **Call this first** to discover what a plugin supports. |
73
+ | `select_player` | `playerId` | Selects a Player as the default target for later calls. |
74
+ | `invoke_action` | `playerId?`, `pluginId`, `action`, `payload?` | Invokes a named action (validated against the plugin's declared capabilities). |
75
75
 
76
76
  A typical agent flow: `list_players` → `select_player` → `describe_plugin` →
77
77
  `get_*` / `invoke_action`.
78
78
 
79
+ ### Diagnostics
80
+
81
+ These tools inspect and manage the MCP server's connection to the shared
82
+ [`flipper-server` daemon](#shared-flipper-server-daemon) itself, rather than
83
+ any Player instance behind it — useful when an agent needs to tell "no Players
84
+ are connected" apart from "the Flipper transport itself is unhealthy." They
85
+ soft-error when the server isn't running on a `FlipperServerTransport`.
86
+
87
+ | Tool | Args | Returns |
88
+ | ----------------------------------- | ---- | ------------------------------------------------------------------------------------------------------ |
89
+ | `get_flipper_status` | — | Connection health: `connected`, `host`, `port`, `owns`, `refs`. |
90
+ | `get_flipper_consumers` | — | `owns`, `refs` (daemon-wide, not just this process), and `activeClientIds`. |
91
+ | `restart_flipper_server` | — | Restarts the daemon — only when this process owns it and is its sole consumer, otherwise a soft error. |
92
+ | `get_flipper_plugin_install_status` | — | Whether the Player UI Devtools Flipper plugin is installed on the daemon. |
93
+
79
94
  > **NOTE**
80
- > Tool handlers return *soft errors* (e.g. `{ "error": "player not found" }`) as
95
+ > Tool handlers return _soft errors_ (e.g. `{ "error": "player not found" }`) as
81
96
  > normal results rather than throwing, so a failed call still returns a
82
97
  > structured payload the agent can read.
83
98
 
@@ -95,55 +110,10 @@ await server.start();
95
110
 
96
111
  `FlipperServerTransport` options:
97
112
 
98
- | Option | Default | Description |
99
- | --- | --- | --- |
100
- | `host` | `"localhost"` | Flipper server host. |
101
- | `port` | `52342` | Flipper server WebSocket port. |
102
- | `open` | `false` | Open a browser/PWA UI once the server is up. Off by default — an agent has no use for a browser tab. |
103
- | `url` | `http://localhost:{port}` | URL to open when `open` is true. `flipper-server` itself always binds to `localhost`, regardless of this value — it only controls what gets opened in the browser, so a custom host must already resolve to this machine (e.g. via `/etc/hosts`). |
104
- | `autoEnablePlugin` | `false` | Automatically call `enablePlugin()` for every client that connects (see [Plugin activation](#plugin-activation) below). |
105
-
106
- The CLI (`player-devtools-mcp` / `bin/run`) reads `open`/`url` from
107
- `PLAYER_DEVTOOLS_FLIPPER_OPEN` / `PLAYER_DEVTOOLS_FLIPPER_URL`, and always
108
- installs the plugin and enables it for connected/connecting clients on
109
- startup (see below) — no manual Flipper UI interaction is required.
110
-
111
- ### Plugin installation
112
-
113
- `flipper-server` has no built-in way to auto-fetch a plugin — but it does
114
- expose the same install RPCs its own desktop UI's "Install Plugin" button
115
- uses, over the same `exec(...)` mechanism this transport already relies on.
116
- `FlipperServerTransport.ensurePluginInstalled()` calls
117
- `plugins-get-installed-plugins` to check whether
118
- `flipper-plugin-player-ui-devtools` is already installed, and if not, installs
119
- it from npm via `plugins-install-from-npm` — no filesystem access, no
120
- dependency on this repo's Bazel/justfile tooling, just Flipper's documented
121
- plugin-management API:
122
-
123
- ```ts
124
- const transport = new FlipperServerTransport();
125
- await transport.connect();
126
- await transport.ensurePluginInstalled();
127
- ```
128
-
129
- ### Plugin activation
130
-
131
- Flipper only opens a live connection for a plugin (and starts relaying its
132
- messages) after sending it an `init` handshake — normally something only the
133
- Flipper *desktop app* does, either automatically for a small class of
134
- "background" plugins, or when a human selects that plugin's tab. Neither
135
- applies to `flipper-plugin-player-ui-devtools` or to a headless MCP session,
136
- so `FlipperServerTransport` exposes the handshake directly:
137
-
138
- ```ts
139
- await transport.enablePlugin(); // activate for every connected client
140
- await transport.enablePlugin(id); // or just one
141
- await transport.disablePlugin(id); // release it again, without disconnecting
142
- ```
143
-
144
- Pass `autoEnablePlugin: true` to the constructor to have this happen
145
- automatically for every client as it connects, instead of calling
146
- `enablePlugin()` yourself.
113
+ | Option | Default | Description |
114
+ | ------ | ------------- | ------------------------------ |
115
+ | `host` | `"localhost"` | Flipper server host. |
116
+ | `port` | `52342` | Flipper server WebSocket port. |
147
117
 
148
118
  ### Shared `flipper-server` daemon
149
119
 
@@ -185,10 +155,10 @@ Register it with an MCP client (e.g. Claude) by pointing the client at the
185
155
  The server reports anonymous usage analytics so we can tell how widely it's used
186
156
  and whether it's working in the field. It is **on by default** and sends:
187
157
 
188
- | | |
189
- | --- | --- |
190
- | Identity | A random UUID generated on first run and stored at `~/.player-ui-devtools/install.json`. It is not derived from anything about you or your machine — delete the file and a new one is generated. |
191
- | Events | Session start (`$mcp_initialize`), tool calls (`$mcp_tool_call`), tool listing (`$mcp_tools_list`), and errors (`$exception`). |
158
+ | | |
159
+ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
160
+ | Identity | A random UUID generated on first run and stored at `~/.player-ui-devtools/install.json`. It is not derived from anything about you or your machine — delete the file and a new one is generated. |
161
+ | Events | Session start (`$mcp_initialize`), tool calls (`$mcp_tool_call`), tool listing (`$mcp_tools_list`), and errors (`$exception`). |
192
162
  | Properties | Tool **name**, call duration, whether the call errored, the MCP client name/version (e.g. which editor), the devtools version, OS platform, Node major version, and whether the Flipper transport connected. |
193
163
 
194
164
  **Tool arguments and tool responses are never transmitted.** Those can contain
package/bin/run CHANGED
@@ -5,40 +5,13 @@ const {
5
5
  FlipperServerTransport,
6
6
  } = require("@player-devtools/client-flipper");
7
7
 
8
- // PLAYER_DEVTOOLS_FLIPPER_OPEN=true opens a browser/PWA UI once flipper-server
9
- // is up (off by default — an agent has no use for a browser tab).
10
- // PLAYER_DEVTOOLS_FLIPPER_URL overrides the URL that gets opened (defaults to
11
- // http://localhost:{port}); the host still needs to resolve to this machine.
12
- const transport = new FlipperServerTransport({
13
- open: process.env.PLAYER_DEVTOOLS_FLIPPER_OPEN === "true",
14
- url: process.env.PLAYER_DEVTOOLS_FLIPPER_URL,
15
- // flipper-server never activates a non-background plugin like ours on its
16
- // own unless a full Flipper desktop app is attached with our tab selected —
17
- // we don't want to depend on that, so every connecting device gets the
18
- // plugin activated for it automatically.
19
- autoEnablePlugin: true,
20
- });
8
+ const transport = new FlipperServerTransport();
21
9
  const server = new MCPServer(transport);
22
10
 
23
- server
24
- .start()
25
- .then(async () => {
26
- try {
27
- await transport.ensurePluginInstalled();
28
- // Catch up any client that connected before this resolved — going
29
- // forward, autoEnablePlugin covers newly-connecting clients.
30
- await transport.enablePlugin();
31
- } catch (err) {
32
- console.warn(
33
- "[bin/run] Failed to install/activate the devtools plugin:",
34
- err,
35
- );
36
- }
37
- })
38
- .catch((err) => {
39
- console.error("Failed to start MCP server:", err);
40
- process.exit(1);
41
- });
11
+ server.start().catch((err) => {
12
+ console.error("Failed to start MCP server:", err);
13
+ process.exit(1);
14
+ });
42
15
 
43
16
  process.on("SIGINT", () => {
44
17
  server.stop().then(() => process.exit(0));
@@ -61,14 +61,6 @@ function resolveBasicPlugin(client, playerId) {
61
61
  if (!basicPlugin) return { error: "no plugin registered for this player" };
62
62
  return { id, player, basicPlugin };
63
63
  }
64
- function ok(value) {
65
- return { content: [{ type: "text", text: JSON.stringify(value) }] };
66
- }
67
- function err(message) {
68
- return {
69
- content: [{ type: "text", text: JSON.stringify({ error: message }) }]
70
- };
71
- }
72
64
  function handleGetFlow(client, input) {
73
65
  const { playerId } = PlayerInput.parse(input);
74
66
  const resolved = resolveBasicPlugin(client, playerId);
@@ -137,41 +129,16 @@ var playerIdShape2 = {
137
129
  var GetPlayerStatusInput = import_zod2.z.object(playerIdShape2);
138
130
  function handleListPlayers(client) {
139
131
  const { players, current } = client.getState();
140
- return {
141
- content: [
142
- {
143
- type: "text",
144
- text: JSON.stringify({
145
- players: Object.keys(players),
146
- current: current.player
147
- })
148
- }
149
- ]
150
- };
132
+ return ok({ players: Object.keys(players), current: current.player });
151
133
  }
152
134
  function handleGetPlayerStatus(client, input) {
153
135
  const { playerId } = GetPlayerStatusInput.parse(input);
154
136
  const { players, current } = client.getState();
155
137
  const id = playerId ?? current.player;
156
- if (!id) return errorResult("no player selected");
138
+ if (!id) return err("no player selected");
157
139
  const player = players[id];
158
- if (!player) return errorResult(`player not found: ${id}`);
159
- return {
160
- content: [
161
- {
162
- type: "text",
163
- text: JSON.stringify({
164
- active: player.active,
165
- plugins: Object.keys(player.plugins)
166
- })
167
- }
168
- ]
169
- };
170
- }
171
- function errorResult(message) {
172
- return {
173
- content: [{ type: "text", text: JSON.stringify({ error: message }) }]
174
- };
140
+ if (!player) return err(`player not found: ${id}`);
141
+ return ok({ active: player.active, plugins: Object.keys(player.plugins) });
175
142
  }
176
143
  var listPlayersDef = {
177
144
  name: "list_players",
@@ -193,26 +160,18 @@ var describePluginShape = {
193
160
  pluginId: import_zod3.z.string().describe("Plugin ID.")
194
161
  };
195
162
  var DescribePluginInput = import_zod3.z.object(describePluginShape);
196
- function err2(message) {
197
- return {
198
- content: [{ type: "text", text: JSON.stringify({ error: message }) }]
199
- };
200
- }
201
- function ok2(value) {
202
- return { content: [{ type: "text", text: JSON.stringify(value) }] };
203
- }
204
163
  function handleDescribePlugin(client, input) {
205
164
  const { playerId, pluginId } = DescribePluginInput.parse(input);
206
165
  const { players, current } = client.getState();
207
166
  const id = playerId ?? current.player;
208
- if (!id) return err2("no player selected");
167
+ if (!id) return err("no player selected");
209
168
  const player = players[id];
210
- if (!player) return err2(`player not found: ${id}`);
169
+ if (!player) return err(`player not found: ${id}`);
211
170
  const plugin = player.plugins[pluginId];
212
- if (!plugin) return err2(`plugin not found: ${pluginId}`);
171
+ if (!plugin) return err(`plugin not found: ${pluginId}`);
213
172
  if (!plugin.capabilities)
214
- return err2(`plugin "${pluginId}" has no capabilities declared`);
215
- return ok2(plugin.capabilities);
173
+ return err(`plugin "${pluginId}" has no capabilities declared`);
174
+ return ok(plugin.capabilities);
216
175
  }
217
176
  var describePluginDef = {
218
177
  name: "describe_plugin",
@@ -234,35 +193,27 @@ var invokeActionShape = {
234
193
  };
235
194
  var SelectPlayerInput = import_zod4.z.object(selectPlayerShape);
236
195
  var InvokeActionInput = import_zod4.z.object(invokeActionShape);
237
- function err3(message) {
238
- return {
239
- content: [{ type: "text", text: JSON.stringify({ error: message }) }]
240
- };
241
- }
242
- function ok3(value) {
243
- return { content: [{ type: "text", text: JSON.stringify(value) }] };
244
- }
245
196
  function handleSelectPlayer(client, input) {
246
197
  const { playerId } = SelectPlayerInput.parse(input);
247
198
  const { players } = client.getState();
248
- if (!players[playerId]) return err3(`player not found: ${playerId}`);
199
+ if (!players[playerId]) return err(`player not found: ${playerId}`);
249
200
  client.selectPlayer(playerId);
250
- return ok3({ selected: playerId });
201
+ return ok({ selected: playerId });
251
202
  }
252
203
  function handleInvokeAction(client, input) {
253
204
  const { playerId, pluginId, action, payload } = InvokeActionInput.parse(input);
254
205
  const { players, current } = client.getState();
255
206
  const id = playerId ?? current.player;
256
- if (!id) return err3("no player selected");
207
+ if (!id) return err("no player selected");
257
208
  const player = players[id];
258
- if (!player) return err3(`player not found: ${id}`);
209
+ if (!player) return err(`player not found: ${id}`);
259
210
  const plugin = player.plugins[pluginId];
260
- if (!plugin) return err3(`plugin not found: ${pluginId}`);
211
+ if (!plugin) return err(`plugin not found: ${pluginId}`);
261
212
  if (plugin.capabilities?.actions && !(action in plugin.capabilities.actions)) {
262
- return err3(`action "${action}" not declared in plugin capabilities`);
213
+ return err(`action "${action}" not declared in plugin capabilities`);
263
214
  }
264
215
  client.handleInteraction({ type: action, payload, target: id });
265
- return ok3({ invoked: action });
216
+ return ok({ invoked: action });
266
217
  }
267
218
  var selectPlayerDef = {
268
219
  name: "select_player",
@@ -277,7 +228,78 @@ var invokeActionDef = {
277
228
  handle: handleInvokeAction
278
229
  };
279
230
 
231
+ // ../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/devtools/mcp/src/tools/flipper.ts
232
+ var import_client_flipper = require("@player-devtools/client-flipper");
233
+ function asFlipperTransport(transport) {
234
+ return transport instanceof import_client_flipper.FlipperServerTransport ? transport : null;
235
+ }
236
+ function handleGetFlipperStatus(_client, _args, transport) {
237
+ const flipper = asFlipperTransport(transport);
238
+ if (!flipper) return err("not using a Flipper transport");
239
+ const { connected, host, port, owns, refs } = flipper.getDiagnostics();
240
+ return ok({ connected, host, port, owns, refs });
241
+ }
242
+ function handleGetFlipperConsumers(_client, _args, transport) {
243
+ const flipper = asFlipperTransport(transport);
244
+ if (!flipper) return err("not using a Flipper transport");
245
+ const { owns, refs, activeClientIds } = flipper.getDiagnostics();
246
+ return ok({ owns, refs, activeClientIds });
247
+ }
248
+ async function handleRestartFlipperServer(_client, _args, transport) {
249
+ const flipper = asFlipperTransport(transport);
250
+ if (!flipper) return err("not using a Flipper transport");
251
+ const result = await flipper.restart();
252
+ if (!result.ok) return err(result.reason);
253
+ return ok({ restarted: true, host: result.host, port: result.port });
254
+ }
255
+ async function handleGetFlipperPluginInstallStatus(_client, _args, transport) {
256
+ const flipper = asFlipperTransport(transport);
257
+ if (!flipper) return err("not using a Flipper transport");
258
+ if (!flipper.getDiagnostics().connected) {
259
+ return err("flipper transport not connected");
260
+ }
261
+ const status = await flipper.getPluginInstallStatus();
262
+ if (!status.installed && status.reason) return err(status.reason);
263
+ return ok(status);
264
+ }
265
+ var getFlipperStatusDef = {
266
+ name: "get_flipper_status",
267
+ description: "Get the MCP server's connection status to the shared flipper-server daemon (host, port, ownership, refcount).",
268
+ inputSchema: {},
269
+ annotations: { readOnlyHint: true, destructiveHint: false },
270
+ handle: handleGetFlipperStatus
271
+ };
272
+ var getFlipperConsumersDef = {
273
+ name: "get_flipper_consumers",
274
+ description: "Get the active devtools clients attached through this Flipper connection, plus the daemon-wide refcount (reflects all consumers of the shared daemon, not just this process).",
275
+ inputSchema: {},
276
+ annotations: { readOnlyHint: true, destructiveHint: false },
277
+ handle: handleGetFlipperConsumers
278
+ };
279
+ var restartFlipperServerDef = {
280
+ name: "restart_flipper_server",
281
+ description: "Restart the shared flipper-server daemon. Only succeeds when this MCP server owns the daemon and is its sole consumer; otherwise returns a soft error rather than disrupting other consumers.",
282
+ inputSchema: {},
283
+ annotations: { readOnlyHint: false, destructiveHint: true },
284
+ handle: handleRestartFlipperServer
285
+ };
286
+ var getFlipperPluginInstallStatusDef = {
287
+ name: "get_flipper_plugin_install_status",
288
+ description: "Check whether the Player UI Devtools Flipper plugin is installed on the connected daemon.",
289
+ inputSchema: {},
290
+ annotations: { readOnlyHint: true, destructiveHint: false },
291
+ handle: handleGetFlipperPluginInstallStatus
292
+ };
293
+
280
294
  // ../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/devtools/mcp/src/tools/index.ts
295
+ function ok(value) {
296
+ return { content: [{ type: "text", text: JSON.stringify(value) }] };
297
+ }
298
+ function err(message) {
299
+ return {
300
+ content: [{ type: "text", text: JSON.stringify({ error: message }) }]
301
+ };
302
+ }
281
303
  var TOOL_DEFS = [
282
304
  listPlayersDef,
283
305
  getPlayerStatusDef,
@@ -287,7 +309,11 @@ var TOOL_DEFS = [
287
309
  getPluginDataDef,
288
310
  describePluginDef,
289
311
  selectPlayerDef,
290
- invokeActionDef
312
+ invokeActionDef,
313
+ getFlipperStatusDef,
314
+ getFlipperConsumersDef,
315
+ restartFlipperServerDef,
316
+ getFlipperPluginInstallStatusDef
291
317
  ];
292
318
 
293
319
  // ../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/devtools/mcp/src/telemetry/index.ts
@@ -396,7 +422,7 @@ function allowlistEventProperties(event) {
396
422
  }
397
423
 
398
424
  // ../../../../../../../../../../execroot/_main/bazel-out/k8-fastbuild/bin/devtools/mcp/src/telemetry/index.ts
399
- var MCP_VERSION = true ? "0.14.3--canary.24.1132" : "unstamped";
425
+ var MCP_VERSION = true ? "0.15.1--canary.29.1254" : "unstamped";
400
426
  function createAnalytics(server, deps) {
401
427
  try {
402
428
  const config = resolveTelemetryConfig();
@@ -456,8 +482,12 @@ var MCPServer = class {
456
482
  const register = this.server.registerTool.bind(this.server);
457
483
  register(
458
484
  def.name,
459
- { description: def.description, inputSchema: def.inputSchema },
460
- (args) => def.handle(this.client, args)
485
+ {
486
+ description: def.description,
487
+ inputSchema: def.inputSchema,
488
+ annotations: def.annotations
489
+ },
490
+ (args) => def.handle(this.client, args, this.transport)
461
491
  );
462
492
  }
463
493
  }
@@ -467,10 +497,10 @@ var MCPServer = class {
467
497
  try {
468
498
  await this.transport.connect();
469
499
  this.transportConnected = true;
470
- } catch (err4) {
500
+ } catch (err2) {
471
501
  console.warn(
472
502
  "[MCPServer] Transport connect failed (will operate in disconnected mode):",
473
- err4 instanceof Error ? err4.message : err4
503
+ err2 instanceof Error ? err2.message : err2
474
504
  );
475
505
  }
476
506
  }