# Ross

> Point-and-draw visual-intent layer for coding agents — select real components in your running Next.js app, grounded to their true source file:line, and hand a ready-to-paste instruction to your AI agent (e.g. Claude Code).

- **Type:** MCP server
- **Install:** `agentstack add mcp-renzoviale-ross`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Renzoviale](https://agentstack.voostack.com/s/renzoviale)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Renzoviale](https://github.com/Renzoviale)
- **Source:** https://github.com/Renzoviale/ross

## Install

```sh
agentstack add mcp-renzoviale-ross
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Ross

A point-and-draw layer over your own running web app. Open the overlay, **select /
draw / measure / capture** real components — each grounded to its true source
`file:line` — compose one intent, and **Send** copies a ready-to-paste instruction
for your coding agent. You paste it into Claude Code, review, and run it. Selection
identifies; the agent edits. See [`SPEC.md`](./SPEC.md) for the original design.

> **Status:** working dogfood. Grounding, the in-app overlay (compose gestures →
> clipboard), and `design.md` memory work end-to-end on Next 16 + React 19 +
> Turbopack. Delivery is **clipboard-paste** (see below); the MCP server is now
> optional (design-memory tools only).

## How it works

```
overlay in your dev app                          you, in Claude Code
  ⌥R → select / draw / measure / capture   ─►   ⌘V the pasted instruction
  gestures compose into one intent              review / edit / ↵
  Send → clipboard                              agent edits the grounded file

  build-time loader injects data-src      ·     daemon (:5179) serves overlay.js
  (grounding: file:line + component)            design.md ← agent reconciles taste
```

1. A build-time **loader** injects `data-src="file:line:col"` + `data-component`
   onto host elements (Next 16 + React 19 + Turbopack; covers Server Components).
   It's self-contained — Babel is bundled in, so your app needs no extra deps.
2. The **overlay** reads those attributes as you point/draw, and builds a single
   composite **intent** (subjects + an optional measured vector + optional marks).
3. **Send** composes the intent into one plain-language instruction (with the real
   `file:line`s) and copies it to your **clipboard**.
4. You **paste it into Claude Code**, review/edit, and press Enter. The agent edits
   the grounded file. You are the gate — nothing is auto-applied.
5. For design-relevant changes, the agent can reconcile the decision into an
   evolving **`design.md`** (via the optional MCP tools `ross_get_design_context` +
   `ross_update_design`) so accumulated taste informs future edits.

The **daemon** (`:5179`) mainly serves `overlay.js`. The **MCP server** is optional:
it exposes the `design.md` tools (and legacy intent-queue tools that the
clipboard flow no longer uses).

## The overlay (⌥R)

One window, top-right. Modes (each keyboard-bound), and gestures **compose** onto a
single intent until you Send:

- **⌖ Select** (`S`) — hover and click component(s); clicks accumulate. Selected
  elements get a persistent outline.
- **✎ Draw** (`D`) — sketch **pen / arrow / box** (`P`/`A`/`B`) *about* the
  selection. Each mark resolves to the grounded elements it covers, so the intent
  carries `annotation.targets` + placement (container + insertion order + alignment).
  An arrow predicts a **move**; a box over empty space predicts **create**.
- **⤡ Measure** (`M`) — drag a vector to capture a precise pixel delta (`deltas`),
  predicts **move**.
- **⬚ Capture** (`C`) — marquee a region to **multi-select every component inside it**
  in one drag (not an image).

The window shows the running summary, the **predicted intent** (`↑↓` to change it),
and **Send** (`↵`). `Esc` clears the composition; `⟲` clears just the drawn marks.
Send copies the instruction to your clipboard (`navigator.clipboard`); if the
browser blocks it, a selectable fallback box appears.

## Run the demo

```bash
# from the repo root: starts the daemon (:5179) AND the demo app (:3000). Ctrl-C stops both.
npm start
```

Then open the app, press **⌥R**, gesture, **Send**, and `⌘V` into your Claude Code
session. Prefer two terminals? `node ross/src/cli.js` in one, `cd spike-grounding &&
npm run dev` in another.

## Use it in your own Next.js app

Published to npm as [`getross`](https://www.npmjs.com/package/getross) (the CLI it
installs is `ross`). **Requires Next.js 16+ / React 19 / Turbopack (App Router,
`.tsx`) and Node.js 18+.**

```bash
npx getross init /path/to/your-next-app   # wire loader + overlay + design.md + .mcp.json
npx getross dev  /path/to/your-next-app   # daemon (serves overlay.js) + your `npm run dev`
```

Or install globally and use the `ross` command directly:

```bash
npm i -g getross
ross init /path/to/your-next-app
ross dev  /path/to/your-next-app
```

`init` builds the self-contained loader (no Babel needed in your app), adds it to
`next.config` turbopack rules, injects the dev-only overlay `` into your root
layout, seeds `design.md`, and registers the (optional) Ross MCP server in the app's
`.mcp.json`. It's idempotent and prints manual steps for anything it can't patch
confidently. Clear `.next` if Turbopack reports a stale module after wiring.

Then in the browser: **⌥R** → gesture → **Send** → `⌘V` into Claude Code → review →
Enter. (No need to restart Claude Code for the paste flow — the clipboard is the
hand-off. Restart it only if you want the `design.md` MCP tools.)

## Layout

```
ross/                     the tool (published to npm as `getross`)
  loader/                 build-time data-src injector (Turbopack loader)
  overlay/overlay.js      vanilla in-app overlay (framework-agnostic)
  src/daemon.js           localhost server that serves overlay.js (and legacy endpoints)
  src/mcp-server.js       stdio MCP server (design.md tools; legacy intent tools)
  src/store.js            intent/design store
  test/                   loader / overlay / draw / capture / mcp / design tests
spike-grounding/          demo Next.js app wired to use Ross
```

## Tests

```bash
npm test                  # from the repo root: builds loader + overlay, runs the full suite
```

Covers the loader, `ross init`, the overlay logic against a real DOM (happy-dom:
select/measure compose, draw grounding + placement, capture multi-select), the MCP
server, and `design.md` reconciliation.

## Known constraints

- **Next.js + Turbopack + App Router, `.tsx`.** The grounding loader is a Turbopack
  rule for `*.tsx`, and the overlay is injected into `app/layout.tsx`. Other stacks
  (Webpack, Pages Router, `.jsx`, non-Next) need a different loader/injection.
- **Port `5179` is hardcoded** in the injected overlay `` — it must be free
  and the daemon must be running, or the overlay never loads.
- **Clear `.next`** after changing loader config/deps — Turbopack caches the module
  graph and will otherwise report stale "cannot find module" errors.
- The in-browser UI is verified with happy-dom (the headless Chromium QA tool can't
  run in the build sandbox); drive it manually in a real browser.

## Contributing

Issues and PRs welcome — see [`CONTRIBUTING.md`](./CONTRIBUTING.md). Changes are
tracked in [`CHANGELOG.md`](./CHANGELOG.md).

## License

[MIT](./LICENSE) © Renzo Viale

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Renzoviale](https://github.com/Renzoviale)
- **Source:** [Renzoviale/ross](https://github.com/Renzoviale/ross)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-renzoviale-ross
- Seller: https://agentstack.voostack.com/s/renzoviale
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.