@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.
- package/README.md +138 -0
- 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.
|
|
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.
|
|
15
|
-
"@player-devtools/client-flipper": "0.14.
|
|
16
|
-
"@player-devtools/messenger": "0.14.
|
|
17
|
-
"@player-devtools/types": "0.14.
|
|
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"
|