feat(mcp): read element context from the OS clipboard

[aidenybai]

Summary

• The browser plugin no longer makes localhost network requests. The MCP server reads the existing application/x-react-grab MIME type directly off the OS clipboard.
• Replaces the POST /context + /health channel with per-OS clipboard readers: osascript -l JavaScript (macOS), wl-paste/xclip (Linux), PowerShell -Sta + WinForms (Windows), and a WSL bridge that tries the Windows host via powershell.exe then falls back to WSLg via the Linux reader.
• Adds a /skills/react-grab skill that tells agents to call the get_element_context MCP tool whenever the user references a grabbed element.
• Drops the @react-grab/mcp/client export and the browser IIFE bundle. Drops the react-grab and fkill workspace deps from @react-grab/mcp. CLI is now always stdio.
• @react-grab/cli no longer adds the now-pointless --stdio flag to generated MCP configs (existing configs keep working since the flag is silently ignored).

Why permissionless

• No localhost requests from the browser side, so no CORS, no mixed-content warnings, no Chrome local-network-access prompts.
• The clipboard already carries the payload in three formats (text/plain, text/html, application/x-react-grab JSON) — we just read the one that's already there.

Failure-mode handling

Environment	Reader	Hint surfaced when broken
macOS	osascript -l JavaScript JXA	"macOS requires osascript (preinstalled). Check $PATH."
Linux X11	xclip -selection clipboard -t application/x-react-grab -o	"Install a custom-MIME clipboard reader: apt install xclip (X11) or apt install wl-clipboard (Wayland)."
Linux Wayland	wl-paste -t application/x-react-grab -n, falls back to xclip	same install hint
Windows	powershell.exe -Sta + System.Windows.Forms.Clipboard::GetData	"Cannot launch powershell.exe. Ensure Windows PowerShell is on PATH."
WSL	host PowerShell first, then WSLg, then a WSL interop hint	"Could not reach the Windows clipboard from WSL. Enable WSL interop (set enabled = true under [interop] in /etc/wsl.conf)..."
SSH	bails immediately	"Clipboard channel is unavailable in SSH sessions. Run react-grab-mcp on the same machine as your browser."

runExecFile attaches stdout/stderr to its rejection so timeouts, non-zero exits, and Add-Type failures all log the actual diagnostic via [react-grab-mcp] <bin> stderr: ....

Test plan

• pnpm --filter @react-grab/mcp test — 49/49 passing
• pnpm test:cli — 116/116 passing (the --stdio removal is reflected in install-mcp.test.ts)
• pnpm lint — clean
• pnpm typecheck — clean
• pnpm format — applied
• pnpm --filter @react-grab/mcp build — clean (no more client.* artifacts)
• Live macOS end-to-end: wrote a real payload to NSPasteboard via JXA, ran the full MCP stdio handshake (initialize + tools/list + tools/call get_element_context), got the formatted prompt + element snippet back
• Negative paths verified live: empty clipboard, expired payload (timestamp older than CONTEXT_TTL_MS), simulated SSH session via SSH_CLIENT env

Notes / breaking changes

• @react-grab/mcp/client export is removed. Any external consumer importing the empty plugin needs to drop the import (the plugin was a no-op after the rewrite).
• The HTTP /context and /health endpoints and the PORT env var are gone. react-grab-mcp is stdio-only now.
• No changeset is included; pin the bump to major (or whichever your release cadence prefers) when releasing.

---

Note

Medium Risk
Moderate risk because it replaces agent-integration flow (MCP config install) with new skill install/remove commands and adds cross-platform clipboard readers/streaming behavior that can vary by OS/shell environment.

Overview
Switches agent integration from MCP server configuration to installing a react-grab agent skill (grab install-skill, updated grab add flow) and adds grab remove support for uninstalling skills with project/global scope handling and monorepo-aware root detection.

Adds a new grab log command that reads application/x-react-grab from the OS clipboard (macOS/Linux/Windows/WSL/SSH-aware), streams grabs as NDJSON (optionally exits after first match when piped), and mirrors output to .react-grab/logs with an auto-created .gitignore.

Introduces grab check-installed/is-installed, telemetry gating via CI/opt-out env vars, and replaces the old MCP installer code with a skill installer implementation (including persisted “last selected agents” state) plus extensive new unit tests and updated docs.

^{Reviewed by Cursor Bugbot for commit 78f1537. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Replaces the MCP server with a clipboard‑driven agent skill and a streaming CLI. react-grab log reads application/x-react-grab from the OS clipboard, emits NDJSON, mirrors to .react-grab/logs, and @react-grab/mcp is now a deprecation stub.

• New Features

  • log: streams continuously; in piped mode exits after first match; writes .react-grab/logs (auto .gitignore); outputs lines as {"prompt"?,"content"}.
  • install-skill/remove/add: standardizes on .agents/skills/ for compatible agents; adds Windsurf and Pi as universal; Amp uses .agents/skills/ (project) and ~/.config/agents/skills/ (global); refuses unsupported clients (e.g. Cline); remembers last-selected agents and filters them against currently supported clients; walks up from subdirs to the workspace/project root; remove defaults to project scope.
  • check-installed (alias is-installed): exits 0/1; --json includes projectRoot and requestedCwd; walks up to the nearest project root; treats the source repo and monorepo workspaces as installed when applicable.
  • Telemetry: gated by DISABLE_TELEMETRY, DO_NOT_TRACK, and common CI envs.
  • Skill template: single-sourced markdown bundled in @react-grab/cli and symlinked at skills/react-grab/SKILL.md.

• Bug Fixes

  • Clipboard readers: macOS decodes Chromium/WebKit web‑custom‑data; Windows handles System.IO.Stream and avoids UTF‑8 BOM; Linux Wayland only falls back to xclip on ENOENT; WSL bridges host PowerShell and WSLg and combines hints; SSH fast‑exit; emit helper stderr; fast‑exit when helper binary is missing.
  • Log loop: avoids stale grabs after an initial parse failure; exits cleanly in piped mode; flushes stderr before exit.
  • Installer/remover: preserves the shared canonical skill when other universal agents still use it; won’t persist auto‑routed selections; init -y installs (and re‑runs) the skill; add exits 1 on failed install and on cancel.
  • Formatting: dedupes the prompt and strips its untrimmed prefix while keeping the canonical elements body; threads extraPrompt to commentText for getContent payloads.

^{Written for commit 7d36e4e. Summary will update on new commits. Review in cubic}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-grab-storybook	Ready	Preview, Comment	May 1, 2026 1:28am
react-grab-website	Ready	Preview, Comment	May 1, 2026 1:28am

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/cli@311

npm i https://pkg.pr.new/aidenybai/react-grab/grab@311

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/mcp@311

npm i https://pkg.pr.new/aidenybai/react-grab@311

commit: 78f1537

[cubic-dev-ai]

5 issues found across 33 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/mcp/src/utils/read-clipboard-windows.ts">

<violation number="1" location="packages/mcp/src/utils/read-clipboard-windows.ts:11">
P1: Reading the clipboard by `application/x-react-grab` will miss Chromium's custom clipboard format on Windows, so browser-copied element context is likely always unavailable there.</violation>

<violation number="2" location="packages/mcp/src/utils/read-clipboard-windows.ts:18">
P1: The fallback `$data.ToString()` in the `else` branch will silently produce `"System.IO.MemoryStream"` instead of the actual payload content. For custom clipboard formats, `[System.Windows.Forms.Clipboard]::GetData()` typically returns a `System.IO.MemoryStream`, not a `byte[]` or a string. Add a `System.IO.Stream` branch that reads the stream content as UTF-8:

```powershell
} elseif ($data -is [System.IO.Stream]) {
    $reader = [System.IO.StreamReader]::new($data, [System.Text.Encoding]::UTF8)
    [Console]::Out.Write($reader.ReadToEnd())
    $reader.Close()
```</violation>
</file>

<file name="packages/mcp/src/utils/read-clipboard-wsl.ts">

<violation number="1" location="packages/mcp/src/utils/read-clipboard-wsl.ts:15">
P2: Preserve the Linux fallback hint instead of always overwriting it with the WSL interop message.</violation>
</file>

<file name="packages/mcp/src/utils/read-clipboard-linux.ts">

<violation number="1" location="packages/mcp/src/utils/read-clipboard-linux.ts:45">
P2: A non-ENOENT `wl-paste` failure returns early instead of falling back to `xclip`, so clipboard reads can fail on Wayland/XWayland setups where the X11 reader would still work.</violation>
</file>

<file name="packages/mcp/src/server.ts">

<violation number="1" location="packages/mcp/src/server.ts:22">
P2: `payload.content` can already include the user prompt, so this formats prompted grabs with the prompt duplicated in both `Prompt:` and `Elements:`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/mcp/src/server.ts">

<violation number="1" location="packages/mcp/src/server.ts:30">
P2: Using `entry.content` to rebuild the elements body loses the canonical formatting in `payload.content`. Multi-element copies will drop their `[1]`/`[2]` labels, and any `transformCopyContent` output is discarded.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/mcp/src/server.ts">

<violation number="1" location="packages/mcp/src/server.ts:27">
P2: The trimmed prompt fallback can truncate real element content that happens to start with the prompt text.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

12 issues found across 66 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/commands/watch.ts">

<violation number="1" location="packages/cli/src/commands/watch.ts:74">
P1: Let the process exit naturally after writing the payload; `process.exit(0)` here can truncate stdout.</violation>
</file>

<file name="skills/react-grab/SKILL.md">

<violation number="1" location="skills/react-grab/SKILL.md:19">
P2: Don't route pasted React Grab output through `watch`; it waits for a newer clipboard timestamp and will hang on already-pasted context.</violation>
</file>

<file name="packages/cli/src/utils/install-skill.ts">

<violation number="1" location="packages/cli/src/utils/install-skill.ts:137">
P2: Unsupported agents are exposed as valid install/remove targets, so commands can accept VS Code or Zed and then no-op as if the selection were valid.</violation>
</file>

<file name="packages/mcp/src/cli.ts">

<violation number="1" location="packages/mcp/src/cli.ts:15">
P3: Avoid `process.exit(1)` here; it can cut off the deprecation notice before stderr flushes.</violation>
</file>

<file name="packages/cli/src/utils/wait-for-next-grab.ts">

<violation number="1" location="packages/cli/src/utils/wait-for-next-grab.ts:53">
P2: The polling loop does not enforce the requested timeout while `read()` is in flight, so short `watch --timeout` values can still block for the clipboard reader's full 3s timeout.</violation>
</file>

<file name="packages/cli/src/commands/init.ts">

<violation number="1" location="packages/cli/src/commands/init.ts:350">
P1: Project-scoped skill installs use the original cwd, so selecting a subproject can write the skill into the wrong repo directory.</violation>
</file>

<file name="packages/cli/test/watch-cli.test.ts">

<violation number="1" location="packages/cli/test/watch-cli.test.ts:6">
P1: Use an ESM-safe path source here; `__dirname` is undefined in this package.</violation>
</file>

<file name="packages/cli/README.md">

<violation number="1" location="packages/cli/README.md:43">
P3: `grab add` is not an alias of `install-skill`; it is a separate wrapper command with different behavior. Reword this to avoid implying the commands are interchangeable.</violation>
</file>

<file name="packages/cli/src/utils/last-selected-agents.ts">

<violation number="1" location="packages/cli/src/utils/last-selected-agents.ts:12">
P2: Ignore relative `XDG_STATE_HOME` values before building the state path.</violation>
</file>

<file name="package.json">

<violation number="1" location="package.json:9">
P1: Keep `@react-grab/mcp` in the root build filter so its `dist` binary is generated before publishing.</violation>
</file>

<file name="packages/cli/src/commands/install-skill.ts">

<violation number="1" location="packages/cli/src/commands/install-skill.ts:85">
P2: Check `installSkills()` results before printing the restart/success message. This command currently reports success even when every requested install was skipped or failed.</violation>
</file>

<file name="packages/cli/src/utils/format-payload.ts">

<violation number="1" location="packages/cli/src/utils/format-payload.ts:27">
P2: Prompt-mode payloads created through `getContent` lose their `Prompt:` section because this formatter only reads prompts from `entries.commentText`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}