Skip to content

Add Flipper diagnostic and plugin-activation MCP tools - #29

Merged
sugarmanz merged 13 commits into
mainfrom
feat/mcp-flipper-diagnostics
Sep 25, 2026
Merged

sugarmanz merged 13 commits into
mainfrom
feat/mcp-flipper-diagnostics

Conversation

@sugarmanz

@sugarmanz sugarmanz commented Sep 18, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds seven MCP tools for the shared flipper-server daemon and the devtools Flipper plugin's per-client lifecycle, plus the ToolDef annotation/async-handler plumbing they need, and hardens the daemon lifecycle across several review rounds:

  • get_flipper_connection_status / get_flipper_consumers report connection health and daemon-wide consumer/ownership info without overlapping fields.
  • restart_flipper_server restarts 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_status reports 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_plugin expose per-client plugin activation — Flipper only opens a live connection for a plugin after an init handshake, 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.
  • A failed daemon startup (spawn succeeds, port never comes up) no longer orphans the child process.
  • Consolidated previously-duplicated ok/err MCP result-envelope helpers into one shared module.

clientId (the Flipper transport-level identifier used by the new tools) is documented as distinct from the devtools playerId used 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 given connect()'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 clientId to the playerId(s) it hosts — under investigation as a possible follow-up.

Test plan

  • Unit tests for diagnostics, restart (ownership/refcount guard paths, TOCTOU re-check, failure recovery), plugin install/activation status (rejection and malformed-response paths), enable/disable plugin, and close() (wait-for-exit, idempotency under concurrent calls, orphan-kill-and-wait on failed spawn).
  • bazel test //devtools/mcp/... //devtools/client/flipper/... passes.

Release Notes

Added seven new MCP tools for the shared flipper-server daemon and the devtools Flipper plugin:

  • get_flipper_connection_status and get_flipper_consumers report connection health (host, port) and consumer info (ownership, refcount, active/connected clients).
  • restart_flipper_server restarts the daemon when safe to do so, failing soft with a clear reason otherwise.
  • get_flipper_plugin_install_status checks whether the Player UI Devtools Flipper plugin is installed on the daemon.
  • get_flipper_plugin_activation_status, enable_flipper_plugin, and disable_flipper_plugin report 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.

@sugarmanz

Copy link
Copy Markdown
Member Author

/canary

1 similar comment
@sugarmanz

Copy link
Copy Markdown
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
sugarmanz force-pushed the feat/mcp-flipper-diagnostics branch from 952b23d to cbf427c Compare September 23, 2026 02:47
- 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.
@sugarmanz sugarmanz changed the title Harden Flipper daemon lifecycle: restart, close, and diagnostics races Add Flipper diagnostic and plugin-activation MCP tools Sep 23, 2026
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
sugarmanz marked this pull request as ready for review September 23, 2026 03:10
@sugarmanz
sugarmanz requested a review from a team as a code owner September 23, 2026 03:10
@sugarmanz sugarmanz added the minor Increment the minor version when merged label Sep 25, 2026
@sugarmanz
sugarmanz merged commit 1f5f6ae into main Sep 25, 2026
8 checks passed
@sugarmanz
sugarmanz deleted the feat/mcp-flipper-diagnostics branch September 25, 2026 01:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

minor Increment the minor version when merged release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants