graft

Why

Tampermonkey is great until you want your agent to help. graft keeps the userscript model (plain files, @match headers) and adds:

Related MCP server: browser-relay

Install (2 minutes)

git clone https://github.com/shahaklt/graft && cd graft && npm install
node bin/graft.mjs path        # prints the extension folder

1. Open chrome://extensions, enable Developer mode, Load unpacked → the extension/ folder. (One time. You never rebuild or repack after this.)

2. On graft's extension card, switch on Allow User Scripts (lets persistent scripts ignore page CSP; without it graft falls back to eval).

3. Add the MCP server to your agent:

# Claude Code
claude mcp add graft -- node /absolute/path/to/graft/bin/graft.mjs mcp
# or straight from GitHub
claude mcp add graft -- npx -y github:shahaklt/graft mcp

Cursor / Claude Desktop (mcpServers JSON):

{ "mcpServers": { "graft": { "command": "npx", "args": ["-y", "github:shahaklt/graft", "mcp"] } } }

Codex: codex mcp add graft -- npx -y github:shahaklt/graft mcp

4. Try it. Open http://127.0.0.1:7777/playground (served by the hub once running) and ask your agent: "outline the playground page, add a todo, then make the heading green and keep it as a script."

No agent? Run just the hub and hand-write scripts: node bin/graft.mjs dev ./my-scripts.

Writing scripts

~/.graft/scripts/hello.graft.js (or any folder via graft dev <dir>):

// ==Graft==
// @name   Hello
// @match  https://*.example.com/*
// @run-at document-idle
// ==/Graft==
graft.css(`body{outline:3px solid #9fe870}`);
graft.on('a.buy', el => el.textContent = 'buy (graft)');   // current + future elements
graft.toast('hello 🌱');

Save the file → every open matching tab re-runs it. graft.css, graft.on, graft.toast, graft.panel and graft.net.* handlers are auto-cleaned on hot reload; register your own with graft.cleanup(fn).

The graft object (in scope in every script, never on window)

Tampermonkey headers (==UserScript==, @match, @exclude, @run-at) and GM_addStyle / GM_getValue / GM_setValue / GM_xmlhttpRequest / GM_notification / GM_log / unsafeWindow work too. See examples/scripts.

MCP tools

How it fits together

 coding agent ──stdio/MCP──▶ graft mcp ─┐
                                        ├─▶ hub (127.0.0.1:7777) ──ws──▶ extension ──▶ your tabs
 ~/.graft/scripts/*.graft.js ──watch────┘

Multiple agents can share one hub: the first process starts it, later ones attach over /rpc.

Security model

• Hub binds 127.0.0.1 only. The extension socket rejects any browser Origin other than chrome-extension://; /rpc rejects every browser origin.

• Privileged calls (graft.fetch, store, notify) cross from the page to the extension over CustomEvents whose names contain a per-session secret. The graft object is never exposed on window.

• Residual risk: a hostile page that monkey-patches EventTarget before graft loads could try to sniff that secret. Don't run graft-privileged scripts on pages you don't trust.

• Scripts you install run with full access to every site they match. Read them. graft_eval gives your agent the same power on any open tab, so only connect agents you trust.

• Optional debugger permission (requested from the popup) lets one-off eval work on strict-CSP pages; Chrome shows a "debugging" banner while it runs.

Limits

Chrome / Chromium (MV3, ≥120) only for now. No chrome:// pages or the Web Store. Page eval on strict-CSP sites needs the debugger permission or a persistent script.

Develop

npm test                     # protocol smoke test (fake extension)
node scripts/make-icons.mjs  # regenerate extension icons

Branding and UI spec for designers: docs/DESIGN-BRIEF.md. Landing page: docs/index.html.

MIT