Repository navigation
Add Flipper diagnostic and plugin-activation MCP tools - #29
Merged
Merged
Conversation
Member
Author
|
/canary |
1 similar comment
Member
Author
|
/canary |
Widens ToolDef.handle to accept the raw Transport and return a sync or async CallToolResult, and forwards tool annotations through registerTool. This is prep for tools that need connection-level diagnostics ExtensionClient doesn't expose.
Lifts host/port to instance fields, tracks whether this instance owns the shared flipper-server daemon, and adds getDiagnostics(), restart(), and getPluginInstallStatus() so callers can inspect and manage the transport's connection to the daemon. restart() only acts when this instance owns the daemon and is its sole remaining consumer, otherwise it soft-errors without touching a daemon other instances depend on. FlipperRefcount gains a read-only peek() that never mutates the refcount file.
Adds four MCP tools exposing FlipperServerTransport's connection state to agents: get_flipper_status, get_flipper_consumers, restart_flipper_server, and get_flipper_plugin_install_status. Each narrows the transport via instanceof and soft-errors when it isn't a FlipperServerTransport.
Covers the four MCP flipper tools' handlers (including the non-Flipper and not-owner soft-error paths) and establishes the first test harness for @player-devtools/client-flipper: FlipperServerTransport's getDiagnostics/restart/getPluginInstallStatus, plus a check that FlipperRefcount.peek() never mutates the refcount file.
Adds a Diagnostics subheading covering the four new tools, kept visually distinct from the core Player tools table.
Code review on the Flipper diagnostic tools found four correctness gaps:
- restart() let a failed close()+connect() propagate as an unhandled
rejection instead of the soft-error contract every other tool follows,
and left `owns` set against a daemon in an unknown state. It now wraps
the sequence in try/catch, resets `owns` to false on failure, and
returns `{ ok: false, reason }`.
- restart()'s owns/refcount check was TOCTOU: another instance could
acquire() between the check and the destructive close(). Added a
re-peek immediately before close() that aborts with a soft error if
refs changed; a one-line comment documents the still-narrow residual
window (a full fix would need close()+connect() inside the refcount's
lock, which isn't reentrant-safe with connect()'s own lock use).
- close() sent SIGTERM and returned without confirming the process
actually exited, letting restart()'s immediate connect() race the old
daemon for the port. close() now waits for the pid to stop responding
to signal 0, bounded by a timeout.
- getPluginInstallStatus()'s exec() call was unguarded, so a dropped
daemon mid-call propagated as an unhandled rejection. It now catches
the rejection and returns `{ installed: false, reason }`, distinct
from the "not connected" and "connected, not installed" cases.
flipper.ts, flow.ts, plugins.ts, select.ts and players.ts each redefined their own identical ok()/err() JSON-envelope helpers (or, in players.ts, an errorResult() equivalent plus inline literals for the success case). Extracted a single ok/err pair into tools/index.ts and updated every tool file to import it instead, with no change to the envelope shape.
…tatus soft-error gap Second re-review pass on the Flipper diagnostics transport: close() could double-run teardown (double refcount release / duplicate kill-wait) under concurrent callers, a failed waitForPort() after a successful spawn left an untracked orphan daemon process running, and getPluginInstallStatus()'s .find() call sat outside its try/catch so a malformed exec() response threw instead of returning the soft-error shape.
connect()'s spawn-failure cleanup called child.kill() but didn't confirm the process actually exited before rethrowing, unlike close()'s killAndWait() which is used for the same purpose everywhere else in this file. A caller retrying connect() right after a waitForPort() timeout could spawn a second flipper-server while the first was still mid- teardown, racing for the same port. Also tighten two test assertions flagged in review: pin the exact soft-error reason for getPluginInstallStatus()'s malformed-response case, and drop a vacuous toBeDefined() assertion in the close() reentrancy test.
Exposes FlipperServerTransport.enablePlugin()/disablePlugin() and the connected/active client split as MCP tools, so an agent can check whether the devtools plugin is activated for a specific Flipper client and trigger/release that activation directly, instead of only seeing daemon-wide install status.
sugarmanz
force-pushed
the
feat/mcp-flipper-diagnostics
branch
from
September 23, 2026 02:47
952b23d to
cbf427c
Compare
- get_flipper_status no longer duplicates owns/refs from get_flipper_consumers; renamed to get_flipper_connection_status to read distinctly next to it. - Document that clientId is a Flipper transport-level identifier, not a Player devtools playerId, and that it has no "current selection" fallback (unlike playerId) — both in the clientId schema description and the README's Diagnostics section.
There's no direct way to correlate a Flipper clientId to the playerId(s) it hosts yet. Documented the workaround (poll list_players after activating) directly in the tool description so an agent sees it before calling the tool, rather than only in the README.
They only ever derived from the options passed to the constructor, so lazily assigning them at the top of connect() served no purpose beyond delaying when getDiagnostics() reflected custom host/port — which was itself surprising, not intentional. Resolving them eagerly and marking them readonly makes that fixed relationship explicit and removes the possibility of drift between calls.
sugarmanz
marked this pull request as ready for review
September 23, 2026 03:10
spentacular
approved these changes
Sep 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds seven MCP tools for the shared
flipper-serverdaemon and the devtools Flipper plugin's per-client lifecycle, plus theToolDefannotation/async-handler plumbing they need, and hardens the daemon lifecycle across several review rounds:get_flipper_connection_status/get_flipper_consumersreport connection health and daemon-wide consumer/ownership info without overlapping fields.restart_flipper_serverrestarts the daemon when safe, failing soft with a clear reason otherwise; always resolves rather than throwing, including when the daemon fails to come back up, and resets ownership state on failure.get_flipper_plugin_install_statusreports whether the plugin is installed on the daemon, distinguishing "not connected," "checked, not installed," and "check itself failed."get_flipper_plugin_activation_status,enable_flipper_plugin,disable_flipper_pluginexpose per-client plugin activation — Flipper only opens a live connection for a plugin after aninithandshake, which previously required a human driving the Flipper desktop UI. These let an agent check which connected clients are active and trigger/release the handshake directly.close()now waits for the daemon process to actually exit before resolving, and is safe to call concurrently.ok/errMCP result-envelope helpers into one shared module.clientId(the Flipper transport-level identifier used by the new tools) is documented as distinct from the devtoolsplayerIdused elsewhere in the MCP tool surface, since the two are easy to conflate.Known limitations
restart_flipper_server's pre-close ownership re-check narrows but does not fully eliminate a TOCTOU race: another consumer could still attach in the gap between the re-check and the destructive close. Closing this fully would require holding the refcount lock across the entire close+connect sequence, which isn't safe givenconnect()'s own internal use of that same lock. Documented in code as an accepted residual risk.There is currently no way to correlate a Flipper
clientIdto theplayerId(s) it hosts — under investigation as a possible follow-up.Test plan
bazel test //devtools/mcp/... //devtools/client/flipper/...passes.Release Notes
Added seven new MCP tools for the shared
flipper-serverdaemon and the devtools Flipper plugin:get_flipper_connection_statusandget_flipper_consumersreport connection health (host, port) and consumer info (ownership, refcount, active/connected clients).restart_flipper_serverrestarts the daemon when safe to do so, failing soft with a clear reason otherwise.get_flipper_plugin_install_statuschecks whether the Player UI Devtools Flipper plugin is installed on the daemon.get_flipper_plugin_activation_status,enable_flipper_plugin, anddisable_flipper_pluginreport and control per-client plugin activation, so an agent can activate the plugin for a connected client without a human driving the Flipper desktop UI.All tools fail soft rather than throwing, consistent with the rest of the MCP tool surface. No breaking changes.