io.github.Buoy-gg/mcp

---

⚡ Quick Start

Have a coding agent? Paste this into Claude Code, Cursor or Codex. It reads your lockfile and package.json, installs the core plus only the tools that match your app, mounts the menu below your providers, wires your stores, and tells you what to check on the device. It follows buoy.gg/install.md — read it first if you like.

Install Buoy, the in-app devtools for React Native and Expo, in this project.

Read the full instructions first:
  curl -fsSL https://buoy.gg/install.md
Read the raw text, not a summary. If curl is unavailable, use any HTTP tool you have. Ask me to paste the document only if nothing can fetch it.

Do the install yourself: inspect the repo, run the commands, edit the files. Do not hand me steps you can run.

Work out the routine decisions from the repo: package manager, which app to target, where the menu mounts, which Buoy tools match the dependencies already installed. If Buoy is already partly installed, repair and extend it; never add a second mount, provider, or package set.

When instructions conflict, follow this order: what I say here, then the document's rules about which packages exist and what needs my permission, then this project's own constraints, then the rest of the document, then your judgment.

Ask me before: adding a native dependency, opening a browser or creating an account, changing what a production build does beyond what the document specifies, or anything hard to undo. Do not commit.

You are not done when the packages install. Run this project's existing typecheck; add no tooling. Then report what you installed and why, what you skipped and why, every file you changed, what you verified, and the exact steps I take on the device to confirm the menu appears and captures a request.

By hand:

Install from your app’s directory, then sign in:

npm install @buoy-gg/core @buoy-gg/network
npx --package=@buoy-gg/core buoy login

In an Expo Router project, keep your existing navigator and providers. For example:

import { Stack } from "expo-router";
import { Buoy, FloatingDevTools } from "@buoy-gg/core";

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

export default function RootLayout() {
  return (
    <>
      <Stack />
      <FloatingDevTools />
    </>
  );
}

The login command writes the Expo key to .env.local. Keep the navigator and menu inside your existing providers. Without Expo Router, keep your app’s root content in place of Stack. For React Native CLI, load the key through your app’s environment configuration and pass it to Buoy.init; .env.local is not loaded automatically.

Restart the development server after installation. Open Buoy, complete any account prompt, and select Network. Trigger a new HTTP request in your app and check its URL and status. If no request appears, check whether the app used cached data or an unsupported transport.

See the Quick Start for the full setup and Installation for requirements. Other tools may need store registration, provider context, or native dependencies.

---

🛟 One live session. Four ways in.

Inspect configured tools in the floating menu on your device. You can also connect them to:

• Buoy Desktop, for desktop panels and remote actions. React Native apps need @buoy-gg/external-sync; follow the connection guide and sign in to Desktop separately.
• MCP, for an AI editor to inspect and act on the app. Configure both process and device accounts; data and action tools require Pro.
• Ask Buoy, for an in-app assistant. It requires Pro, a model endpoint you configure, and the tool integrations its tasks depend on.

Supported features vary by platform, build, and installed tools. Flutter has a separate debug-build setup.

---

🧰 Tools

Tool	Package	What it does
Network	@buoy-gg/network	Inspect HTTP requests captured through your React Native app’s global fetch and XMLHttpRequest hooks. Open a request to see its URL, status, headers, timing, and captured body.
Storage	@buoy-gg/storage	Browse and edit supported AsyncStorage, registered MMKV instances, and registered SecureStore keys inside your app.
Time Machine	@buoy-gg/time-machine	Save and restore supported client state; external side effects are not reversed.
Ask Buoy (beta)	@buoy-gg/ask-buoy	Use an in-app assistant with your model endpoint and configured tools.
Env	@buoy-gg/env	Inspect runtime environment values and validate required variables.
Query	@buoy-gg/react-query	Inspect the TanStack Query cache used by your app. Refetch or invalidate a query and simulate states while checking the screen that consumes it.
Routes	@buoy-gg/route-events	Inspect recorded navigation events and supported routes.
Debug Borders	@buoy-gg/debug-borders	Show layout borders and component labels over your React Native app. Tap a label to inspect the component’s available properties.
Highlight Updates	@buoy-gg/highlight-updates	Highlight observed React component updates in development builds and inspect the available render details.
Bench	@buoy-gg/perf-monitor	Measure available frame-rate, CPU, and memory metrics on a device. Record comparable runs to investigate performance changes.
JS Top	@buoy-gg/js-top	Task Manager for the JS thread — a live ranked table of which timers, Promise chains & callbacks eat your JS FPS
Images	@buoy-gg/images	Inspect image loads observed by Buoy’s supported image hooks, including timing, dimensions, and estimated decoded memory.
Assets	@buoy-gg/assets	Inspect assets visible to the runtime registry and, in development, the Metro dependency graph. Compare sizes and find possible duplicates.
Events	@buoy-gg/events	Review events from configured Buoy tools in one timeline. Filter by source, inspect an event, and export a selection for debugging.
Console	@buoy-gg/console	Read captured JavaScript console logs in your React Native app. Filter messages by level, search their contents, and inspect logged objects.
Sentry	@buoy-gg/sentry	Inspect captured Sentry envelopes and diagnostic estimates.
Redux	@buoy-gg/redux	Inspect your connected Redux store, review captured actions and state changes, and dispatch actions from your device.
Zustand	@buoy-gg/zustand	Inspect the Zustand stores you register with Buoy. Review changes, edit state, and restore retained snapshots.
Jotai	@buoy-gg/jotai	Inspect registered Jotai atoms and their captured changes, with live values and per-atom history.
Impersonate	@buoy-gg/impersonate	Connect your app’s user-switching flow to Buoy so testers can switch test accounts, roles, or flags without rebuilding.
TV Remote	@buoy-gg/tv-remote	Send supported TV input and replay recorded navigation sequences.
Focus Inspector	@buoy-gg/focus-inspector	Inspect observed TV focus changes and possible focus problems.
Camera	(no package — desktop app)	Give the iOS Simulator a real camera — point it at your Mac screen, webcam, an image or a video, and scan QR codes or driver's licences without a device
Overlay	@buoy-gg/image-overlay	Place a reference image over your app to compare spacing, alignment, and sizing on the device.

Install tools as you need them. Follow each linked guide for its peer dependencies and app integration.

See them in action

---

🤖 Your agent gets hands

Install @buoy-gg/external-sync in your React Native app and complete the MCP account and connection setup. Then run:

npx -y @buoy-gg/mcp@latest init

Review the generated editor configuration. Setup preserves other server entries but updates the Buoy entry and its generated skill. Reconnect your MCP client, open your app, and start with list_devices.

Available actions include reading captured requests and state, changing supported stores, and running configured benchmarks. These actions can change your running app. UI inspection depends on React Native hooks; simulator screenshots and camera features require macOS and Xcode.

---

🖥️ Buoy Desktop

Download Buoy Desktop for your platform and sign in. It displays connected tools, supports device switching, and exposes supported remote actions.

React Native connections require @buoy-gg/external-sync. Automatic address discovery depends on your Metro setup and network; follow the Desktop guide for physical devices, tunnels, and release builds.

---

Why Buoy?

Use Buoy when you want to inspect app behavior from the device and share that session with desktop tools or an assistant. Choose packages for your app’s libraries and verify their capture paths with a known test action.

---

Production and connections

Start with a development build. Before enabling Buoy in a shipped app, restrict access using your app’s authorization checks and review the component reference. Production access requires Pro, and development-only capabilities remain unavailable.

Hiding the menu is not a substitute for backend authorization. Headless mode hides the on-device UI; it still requires account admission and sync configuration. Release sync is disabled by default and must be explicitly enabled.

Device sessions can travel over your LAN to the configured broker. Buoy also makes account and license requests; development telemetry is described in Telemetry. Ask Buoy sends model requests to the endpoint you configure.

---

Account and plan requirements

Use a Free or Pro Buoy account. History limits and paid features vary by tool; see pricing. Production access requires Pro where supported. Development-only hooks and actions remain unavailable in release builds.

---

Feedback

Found a bug or want a tool that doesn't exist yet? Open an issue — feature requests drive the roadmap.

License

Proprietary software. © Buoy LLC. All rights reserved. See the Terms of Service.

---