@player-devtools/mcp 0.14.0 → 0.14.1--canary.19.1010

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.
Files changed (2) hide show
  1. package/README.md +138 -0
  2. package/package.json +5 -5
package/README.md ADDED
@@ -0,0 +1,138 @@
1
+ # @player-devtools/mcp
2
+
3
+ An [MCP](https://modelcontextprotocol.io) server that exposes the Player UI
4
+ Devtools to AI agents. It lets a model — e.g. Claude — inspect and drive a live
5
+ Player instance: list running Players, read their flow / data / logs / config,
6
+ inspect plugin state, select a Player, and invoke plugin actions.
7
+
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
10
+ to the same Player Devtools plugins over the [messenger](../messenger) protocol.
11
+ The MCP server connects to those plugins through a running
12
+ [`flipper-server`](https://github.com/facebook/flipper) and re-exposes them as
13
+ MCP tools over stdio.
14
+
15
+ ```
16
+ agent (Claude) ──stdio/MCP──▶ MCPServer ──▶ ExtensionClient ──▶ FlipperServerTransport
17
+ │
18
+ flipper-server (localhost:52342)
19
+ │
20
+ Player Devtools plugins
21
+ ```
22
+
23
+ ## Installation
24
+
25
+ The package ships a CLI, `player-devtools-mcp`, which is what an MCP client runs.
26
+
27
+ ### Register with Claude Code
28
+
29
+ Add it as an MCP server with `claude mcp add` — no env vars or tokens are
30
+ required:
31
+
32
+ ```bash
33
+ claude mcp add player-devtools -- npx -y @player-devtools/mcp@latest
34
+ ```
35
+
36
+ That runs the server over stdio via `npx` (no global install needed). To pin a
37
+ version, replace `@latest`. To point at a non-default Flipper server, pass the
38
+ host/port through the CLI after `--` (see [Transport](#transport)).
39
+
40
+ > **NOTE**
41
+ > You do **not** need to install or start Flipper first — the server starts and
42
+ > manages a shared `flipper-server` for you (see
43
+ > [Shared `flipper-server` daemon](#shared-flipper-server-daemon)).
44
+
45
+ ### Other MCP clients
46
+
47
+ Any MCP client that launches a stdio command works — point it at
48
+ `npx -y @player-devtools/mcp@latest` (or the `player-devtools-mcp` bin if you've
49
+ installed the package). To install the package directly:
50
+
51
+ ```bash
52
+ npm install @player-devtools/mcp
53
+ ```
54
+
55
+ See [Running](#running) for the bin and the in-repo `just` recipes.
56
+
57
+ ## Tools
58
+
59
+ The server registers the following tools (defined as `ToolDef`s in
60
+ [`src/tools`](./src/tools) and registered in one loop in `MCPServer`). Every
61
+ player-scoped tool takes an optional `playerId` and falls back to the currently
62
+ selected Player when it's omitted.
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). |
75
+
76
+ A typical agent flow: `list_players` → `select_player` → `describe_plugin` →
77
+ `get_*` / `invoke_action`.
78
+
79
+ > **NOTE**
80
+ > Tool handlers return *soft errors* (e.g. `{ "error": "player not found" }`) as
81
+ > normal results rather than throwing, so a failed call still returns a
82
+ > structured payload the agent can read.
83
+
84
+ ## Transport
85
+
86
+ The server is decoupled from how it reaches the Player via the `Transport`
87
+ interface. The shipped implementation is `FlipperServerTransport`.
88
+
89
+ ```ts
90
+ import { MCPServer, FlipperServerTransport } from "@player-devtools/mcp";
91
+
92
+ const server = new MCPServer(new FlipperServerTransport({ host, port }));
93
+ await server.start();
94
+ ```
95
+
96
+ `FlipperServerTransport` options:
97
+
98
+ | Option | Default | Description |
99
+ | --- | --- | --- |
100
+ | `host` | `"localhost"` | Flipper server host. |
101
+ | `port` | `52342` | Flipper server WebSocket port. |
102
+
103
+ ### Shared `flipper-server` daemon
104
+
105
+ Multiple MCP processes (one per editor/agent registration) attach to a **single**
106
+ `flipper-server` on the fixed port. Because no in-process state can coordinate
107
+ separate processes, the transport tracks the daemon with a cross-process
108
+ **refcount** — a small file under the OS temp dir guarded by an atomic lock
109
+ directory:
110
+
111
+ - The first process to attach starts the daemon (detached + `unref`'d so it
112
+ outlives that process) and records its PID with `refs: 1`.
113
+ - Each subsequent attach increments `refs`.
114
+ - Each `close()` decrements `refs`; the **last** one out shuts the daemon down.
115
+
116
+ This means you can run several agents against the same devices without each
117
+ spawning (or prematurely killing) its own Flipper server.
118
+
119
+ ## Running
120
+
121
+ Via the CLI (wraps `FlipperServerTransport` + `MCPServer` and wires `SIGINT` /
122
+ `SIGTERM` to a graceful shutdown):
123
+
124
+ ```bash
125
+ player-devtools-mcp
126
+ ```
127
+
128
+ From the repo, two `just` recipes are provided:
129
+
130
+ ```bash
131
+ just mcp # bazel run //devtools/mcp:mcp_server
132
+ just mcp-inspect # open the MCP inspector against the server
133
+ ```
134
+
135
+ Register it with an MCP client (e.g. Claude) by pointing the client at the
136
+ `player-devtools-mcp` command over stdio.
137
+
138
+ [browser extension]: https://github.com/player-ui/browser-devtools
package/package.json CHANGED
@@ -5,16 +5,16 @@
5
5
  "bin"
6
6
  ],
7
7
  "name": "@player-devtools/mcp",
8
- "version": "0.14.0",
8
+ "version": "0.14.1--canary.19.1010",
9
9
  "main": "dist/cjs/index.cjs",
10
10
  "bin": {
11
11
  "player-devtools-mcp": "bin/run"
12
12
  },
13
13
  "dependencies": {
14
- "@player-devtools/client": "0.14.0",
15
- "@player-devtools/client-flipper": "0.14.0",
16
- "@player-devtools/messenger": "0.14.0",
17
- "@player-devtools/types": "0.14.0",
14
+ "@player-devtools/client": "0.14.1--canary.19.1010",
15
+ "@player-devtools/client-flipper": "0.14.1--canary.19.1010",
16
+ "@player-devtools/messenger": "0.14.1--canary.19.1010",
17
+ "@player-devtools/types": "0.14.1--canary.19.1010",
18
18
  "@modelcontextprotocol/sdk": "^1.0.0",
19
19
  "zod": "^3.0.0",
20
20
  "tslib": "^2.6.2"