A Model Context Protocol server that lets an agent take part in a Selvage session: host a folder, or join an invite link, and read, edit and write the files the room shares.
It is a client of the session protocol, like the editor clients: it drives the same sync engine and speaks the same wire, so an agent and a person edit the same documents and see each other's changes.
Status: v1 in progress. Hosting, joining by invite, and editing in both directions work today.
You need:
- Node 22.18 or newer on
PATH. The sync engine runs at every end of a session, so an agent that edits a room runs the same code an editor does. - A
selvagedto connect to. Start one and note the address it prints.
It is a stdio server — one JSON-RPC message per line — and its diagnostics go to stderr. There are two ways to start it, and they start the same program. An agent should have it configured in its client, not drive it by hand.
From a checkout. npm ci installs the dependencies and builds the runnable artifact, because
prepare runs npm run build: a bundle of the sources and the vendored engine, written to
dist/. Point a client at it — this is the mcp.json entry (mcpServers is the key every
client reads):
{
"mcpServers": {
"selvage": {
"command": "node",
"args": ["/path/to/mcp/dist/main.js"],
"cwd": "/path/to/mcp",
"env": {
"SELVAGE_SERVER_URL": "ws://127.0.0.1:8080",
"SELVAGE_DISPLAY_NAME": "agent",
"SELVAGE_NOTIFY_CHANGES": "true"
}
}
}
}pi's own command line writes the same entry, which is the one-liner to hand an agent that runs
under pi:
pi mcp add selvage \
--env SELVAGE_SERVER_URL=ws://127.0.0.1:8080 \
--env SELVAGE_DISPLAY_NAME=agent \
--cwd /path/to/mcp \
-- node /path/to/mcp/dist/main.js-l writes .pi/mcp.json in the project rather than the global ~/.pi/agent/mcp.json. Either
way the server is a tool the client starts and the agent just calls.
dist/main.js carries a shebang and the executable bit, so it is also the command bin names:
selvage-mcp and node <path>/dist/main.js are the same process. npm run build alone rebuilds
it. src/main.ts is the same server run straight from the sources — Node 22.18 strips the types
as it loads it — so node <path>/src/main.ts works too, with no build at all.
From git, with no checkout. npx fetches the repository, installs it, which runs the same
build, and starts the command the package declares:
{
"mcpServers": {
"selvage": {
"command": "npx",
"args": ["-y", "github:selvage-protocol/mcp"],
"env": {
"SELVAGE_SERVER_URL": "ws://127.0.0.1:8080",
"SELVAGE_DISPLAY_NAME": "agent"
}
}
}
}There is no cwd to set: the server reads its own package.json from where it was installed, and
everything else it needs arrives through the environment or through a tool call.
The package is not on npm, and npx selvage-mcp does not exist. It stays private: true:
publishing needs an account and a token for the scope, and that is not a decision this repository
takes on its own. The git form above is the same package a publish would carry.
SELVAGE_SERVER_URL is the Selvage server's address, and it matters because it is the only way
the address arrives without being asked for: a client starts this server as a subprocess and has
nothing to answer a question with, so session_host falls back to this variable when its
server_url argument is left out, and refuses, naming both, when neither is there. A bare
ws://host:port is enough — the engine adds the /session path — and what you hand it is the
address selvaged prints. SELVAGE_DISPLAY_NAME is the name the other seats see; without it
this server seats itself as agent.
SELVAGE_PUBLISH_CURSOR is the fallback for a publish_cursor argument on either session tool,
and it is off unless it is set to one of 1, true, yes or on. With it on, the server
publishes a cursor for the path each read_file, edit_file and write_file touches — a
position in the room's document, renewed on the room's awareness clock and cleared when the
session ends — so a person sharing the file can see which file the agent has open and roughly
where in it. It is off by default because a caret in someone's editor says the agent is there,
and an agent that never asked for that should not have one invented for it. It is a position and
nothing more: it says the last tool call landed there, not that the agent is looking.
A first session:
- Start
selvagedand note the address it prints. - Ask the agent to call
session_hostwith the folder to share. It answers with two links, each carrying the key fragment:page:is the link a person opens in a browser, andinvite:is the link a client joins with. - Give a person the
page:link (:SelvageJoin <link>in the Neovim client, or the VS Code one, or a browser). Give a peer theinvite:link, or paste either intosession_join— both forms name the same room, token and fragment. The fragment is the room's key, so hand out a link only to whoever should join, and hand it over whole. - Both read and edit the same files. A guest's edit arrives in the room and on the host's disk; a
host's write arrives in every guest's
read_file. - To work live rather than poll, have the agent call
wait_for_change: it blocks until the other seat edits something and answers with the changed region, not the file. See "An agent as a live collaborator" below.
session_host |
Share a folder and host the room. The folder is walked once, here. Answers with the room id, the path count, and two links that carry the same key fragment: a page: link a person opens in a browser and an invite: link a client joins with. |
session_join |
Join a room from either link session_host answered with — the page link or the client invite, the fragment included — or from either form pasted. Answers with the room id, this seat's role, the participants and the path count. |
session_status |
Where this server stands: room, role, mode, granted paths, open documents, participants, and any problem the session could not fix. Answers with no session too. |
session_leave |
Leave the room and free the process to host or join again. A host leaving closes the room for everyone. |
list_paths |
The room's shared paths, sorted, filtered by prefix and bounded by limit; a cut answer says it was cut and names the limit. |
read_file |
The room's text for one shared path. |
edit_file |
Replace old_string with new_string in a shared file, refusing an absent or an ambiguous match unless replace_all is set. |
write_file |
Replace a shared file's whole text. |
list_participants |
One line per seat: name, role, whether it is this connection, the cursor a seat publishes — which this server does only when asked to — and where that peer is: the document its cursor names and the line and column the engine resolved. A peer that publishes nothing says so. |
wait_for_change |
Block until the room changes a watched path, then answer with a bounded partial report — the changed region as a small diff hunk, not whole files. Returns at the first change or at its deadline, and reports what changed since the previous wait. |
An agent that works with a person has a different loop from one that answers a question: it has
to be told when the room moves, and it must not be handed the whole document every time. That
loop is session_host or session_join, then wait_for_change, then edit_file on what the
wait reported, then wait_for_change again.
wait_for_change blocks until a watched path actually changes, or until its deadline. It is
always bounded: it never polls and never spins, a deadline that passes says no change within N ms rather than looking like a change, and timeout_ms is capped at five minutes. Watching is
the whole grant and the open documents unless paths names a subset.
What it returns is a partial update, never a file. For each path that changed it gives the
changed region as a small diff hunk — - lines for the old text, + for the new, a few lines of
context, line numbers — and the path's new length in characters. A path that appeared or
disappeared is said in words instead of a hunk. The report is capped in size and says how many
changes it left out; those stay pending and the next wait carries them. It reports what changed
since the previous wait, not since the call, so a change that lands while the agent is thinking
between two waits is reported by the next one rather than swallowed.
edit_file is the writing half: the agent applies the smallest change to the region the wait
showed it, and the room and the other seats see it. The agent's own edit is not reported back to
it; only what the room did after is.
With notify_changes: true on session_host or session_join — or SELVAGE_NOTIFY_CHANGES set
in the server's environment, the way SELVAGE_SERVER_URL works — the server also tells its client
about room activity as it happens, as MCP notifications/message messages: document changes with
the same bounded hunk, and peers joining and leaving. It is off by default. The messages are rate
limited (at most one per path per half second, and at most twenty in a second across the room),
never carry the invite, and are a second channel rather than a replacement for wait_for_change:
a notification is best-effort, and the wait still owes the change it announced.
A client that wants none of them can set a higher level with logging/setLevel; the messages are
all info, so a warning floor silences them. That method exists only because the logging
capability is declared, and the capability is declared only when this server has a channel to
send through.
list_participants reads the awareness peers publish — which is anchored to relative positions —
and reports each peer's document and selection as a line and column, so an agent can see where a
person is typing and answer them there:
grace (guest, publishes a cursor) in src/main.rs selecting line 12, column 3 to line 12, column 9
ada (host, this connection, no cursor seen)
A peer that publishes nothing is reported as such, and one whose anchors this replica cannot place is reported with its document and no position, rather than at a position this server invented.
- A host cannot create a file its folder does not already hold. The write side of the path clamp is a read: a write happens only for a path the folder already resolves to a plain file of it, so a path the room has and the folder does not is a recorded refusal, not a new file.
- Queued host write-back is not generation-bound.
applyFromRoomreads the current engine and root inside a serialized callback; ending a session clears the write queue map without canceling callbacks already queued. A callback could therefore observe a subsequent session's engine and folder. This is an unreproduced lifecycle limitation, not a demonstrated failure or a claimed fix. The absent-document guard does not establish session-generation isolation. - Nothing republishes the listing after the initial walk. The paths a host's walk finds are the room's listing for the life of the session; a file added to the folder later is not listed until a new session, and no folder watcher runs on this side.
- A guest writes nothing to disk. The room's text lives in the agent's replica; a guest's edits go to the room and nowhere else. Hosting is the only direction that touches a disk.
- A published cursor is a position, not attention. Off by default, and when on it sits where
the last
read_file,edit_fileorwrite_filetouched the path — the end of the range an edit changed, the start of the file for a read — and stays there between calls. It is renewed on the room's awareness clock and cleared when the session ends, and it says nothing about what the agent is reading. - A change names a path, never its author. The engine reports that a document changed but not which peer changed it, so a wait or a notification says a path moved and never names the peer who moved it.
- The invite fragment is a credential. Both links
session_hostanswers with carry the same room key in their fragment, so either one is as sensitive as the room itself: anything that holds a link can join and read what the host shares. A failed join reports the URL as[invite]rather than echoing the key.
Which link goes to whom, in one place: the page: link is what a person opens — a browser
fetches the client at the server's page root — and the invite: link is what a client dials,
and what session_join takes. A person given the invite: form, or a client given the page:
form, may still get in — the two are one invitation — but the page link is the one that opens as
a page.
After npm ci, npm run typecheck and npm test run the server-free checks in CI. The suite
includes interop against a real third-party client, the official @modelcontextprotocol/sdk,
driving the shipped process.
test/packed.test.ts is the packaging proof rather than the exercise: it runs npm pack here,
installs the tarball into a scratch project outside this checkout, and drives the installed command
— not the sources — through initialize and tools/list. It fails, rather than skipping, when the
artifact is not in the tarball.
npm run test:e2e is the proof rather than the exercise: two MCP servers over their real stdio,
editing one room on a real selvaged, converging in both directions. It fails rather than
skipping when there is no server binary, naming the command that builds one, and finds the binary
through SELVAGE_SELVAGED or as a sibling reference_server's build. The runner has no such
checkout, so CI and scripts/ci-local.sh e2e both take the published binary from its image
instead — scripts/fetch-selvaged.sh, a second of network — and name it in SELVAGE_SELVAGED.
nix develop . --max-jobs 2 -c ./scripts/ci-local.sh all runs this checkout's local gate: lint,
checks, released-server e2e, links.
The separate public current-server.yml workflow runs weekly and on manual dispatch. It
checks out public reference_server main, logs its resolved SHA and the MCP candidate SHA,
builds a fresh selvaged with Rust 1.99.1 and cargo build --locked, then runs the existing
npm run test:e2e suite with Node 26.13.0. It has a 40-minute job timeout, shorter build/test
step timeouts, and retains build/test logs for seven days on failure. It does not replace the
digest-checked released-server E2E in ci.yml; a current-source build or test failure is red,
not treated as evidence of compatibility.
To run against an explicit local source build instead:
cargo build --locked --manifest-path /path/to/reference_server/Cargo.toml -p selvaged
npm ci
SELVAGE_SELVAGED=/path/to/reference_server/target/debug/selvaged npm run test:e2econtracts.yml runs the public specification's scripts/check-workspace.py against this
candidate's committed HEAD and current public VS Code main. It compares engine
and bridge copies and CRDT dependency versions. It logs every resolved input SHA,
uses read-only permissions, and does not persist checkout credentials. The executable
checker is pinned to a reviewed public specification commit; canonical VS Code source
resolves once from main so upstream changes remain visible. Sync from the exact canonical
commit reported by the job; do not freeze that ref or hand-edit vendored sources to make
the check pass.
Locally, arrange Git repositories named mcp, vscode_client, and specification under an
explicit workspace (a symlink to this worktree is fine), then supply the revisions:
bash scripts/ci-local.sh contracts /path/to/workspace SPECIFICATION_SHA \
--revision mcp=HEAD --revision vscode_client=VSCODE_SHAThe wrapper extracts the checker from the supplied specification commit with git show and
passes --revision specification=RESOLVED_SHA. It does not execute an uncommitted checker.
The equivalent public command, using the checker checked out at SPECIFICATION_SHA, is:
python3 /path/to/specification/scripts/check-workspace.py \
--workspace /path/to/workspace --consumer mcp \
--revision mcp=HEAD --revision vscode_client=VSCODE_SHA \
--revision specification=SPECIFICATION_SHANo Neovim checkout or private coordination files are needed. Missing repositories or refs fail
rather than falling back to working-tree files. HEAD compares committed content, so commit
candidate changes before relying on the comparison. Contracts are separate from all, since
the workspace and every compared revision must be explicit.
MIT OR Apache-2.0: LICENSE-MIT and LICENSE-APACHE.