Skip to main content
Glama

Selvage for agents

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.

Get it working

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 selvaged to 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:

  1. Start selvaged and note the address it prints.

  2. Ask the agent to call session_host with the folder to share. It answers with two links, each carrying the key fragment: page: is the link a person opens in a browser, and invite: is the link a client joins with.

  3. Give a person the page: link (:SelvageJoin <link> in the Neovim client, or the VS Code one, or a browser). Give a peer the invite: link, or paste either into session_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.

  4. 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.

  5. 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.

Related MCP server: Human-Agent Chatroom MCP

Tools

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 as a live collaborator

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.

Being told without asking

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.

Where the other people are

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.

What it cannot do

  • 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. applyFromRoom reads 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_file or write_file touched 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_host answers 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.

Tests

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.

Current-source server compatibility

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:e2e

Public copy contracts

contracts.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_SHA

The 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_SHA

No 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.

Licence

MIT OR Apache-2.0: LICENSE-MIT and LICENSE-APACHE.

Available Tools

10 tools
edit_fileA

Replace "old_string" with "new_string" in one granted path's shared text. Refuses, changing nothing, when "old_string" does not appear, when it appears more than once unless "replace_all" is true, and when "new_string" writes two lines the document already holds again: an ambiguous edit is never guessed at, and a piece of the document written a second time through a line-level tool is what "write_file" is for. Only the changed range is published to the room, and a viewer's edit is refused. A host's own folder follows the room, but this cannot create a file the folder does not already hold.

Inputs: path (required), new_string (required), old_string (required), replace_all.

list_participantsA

List the seats in the room: each display name, its role, whether it is this connection, whether a cursor is published, and where the peer is — the document its cursor names and the line and column the engine resolved from the awareness it publishes, so an agent can see where a person is typing and answer them there. This server publishes a cursor only when a session was opened with "publish_cursor", so its own seat has one only then; a peer that publishes nothing says "no cursor seen" rather than being shown at an invented position. The roster is as current as the last event from the room, so a seat that has just arrived or left may still be reported as it was.

Inputs: no named parameters.

list_pathsA

List the paths the room's grant names, sorted, optionally filtered by a prefix and capped at 100 unless a higher limit is asked for (at most 1000). The listing is what the host walked when the room opened and is not live: a file the folder gained since is not in it, and one the folder lost still is, until a new session. A truncated answer says so and names the limit. Takes the optional prefix and limit.

Inputs: limit, prefix.

read_fileA

Read one granted path's shared text as the room holds it. Only a path the room's grant names can be read; a path that is not text, or is over the size a session carries, is refused rather than answered. The text is the room's — the host folder's copy where the host is keeping that true — and this tool never reads the disk itself. A guest waits for the room to send the document and is refused if it does not arrive in time.

Inputs: path (required).

session_hostA

Share a folder with a room and host it, and answer with the two links that open it. The folder is walked once, here: the paths the walk finds are the room's listing, and only a file the folder holds at that moment can be listed, so a file that appears in the folder later is not listed until a new session, because nothing republishes the listing — and a host cannot create a file its folder does not already hold. A person opens the page link in a browser; a client — another session_join included — joins with the client invite, and either form works. Both links carry the same room, token and key fragment, and the fragment is the credential: hand a link, whole, only to whoever should join. A host leaving closes the room for everyone. Takes the folder, the server address, a display name, and the two opt-ins: whether to publish a cursor, and whether to tell the client about room activity as it happens.

Inputs: folder (required), server_url, display_name, notify_changes, +1 more.

session_joinA

Join a room from an invite URL in either form session_host answered with — the page link a person would open, or the client invite — which has to carry the key in its fragment. Answers with the room id, this seat's role, the participants and how many paths the host granted. The listing is what the host shared when the room opened, so a path shared afterwards is not in it until a new session. A guest edits the room's shared text and writes nothing to its own disk. Takes the invite, a display name, and the two opt-ins: whether to publish a cursor, and whether to tell the client about room activity as it happens.

Inputs: invite (required), display_name, notify_changes, publish_cursor.

session_leaveA

Leave the room this server is in, closing the connection and freeing the session so it can host or join again. A host leaving closes the room for everyone: the other seats are disconnected and the room ends, and the only way back is to host again or to join another invite. With no session it is a caller error, because there is nothing to leave.

Inputs: no named parameters.

session_statusA

Report the live session: role, room, mode, participants, whether the connection is carrying traffic, the granted paths this replica holds, the room's open documents, and any problem the session could not fix (a room change a host could not put on disk, a granted path the folder would not read). With no session open it still answers, saying there is none, rather than failing: asking where this server stands is not a mistake.

Inputs: no named parameters.

wait_for_changeA

Block until the room changes a watched path, then answer with a bounded partial report rather than whole files: for each path that changed, the changed region as a small diff hunk with line numbers and a few lines of context, and the path's new length; a path that appeared or disappeared is said in words instead of a hunk. Watching is the whole grant and the open documents unless "paths" names a subset. It returns at the first change or at "timeout_ms" (default 30000, at most 300000), never spinning, and a deadline that passes says so plainly rather than looking like a change. It reports what changed since the previous wait, not since the call: a change that lands while the agent is thinking is reported by the next wait, so nothing is lost between two waits. The report is capped in size and says how many changes it left out.

Inputs: paths, timeout_ms.

write_fileA

Replace a granted path's whole shared text with "content". This is how a host changes a file its folder already holds: the folder follows the room, but a file the folder does not hold cannot be created, and a path the room did not grant cannot be written at all. A viewer is refused, and text over the size a session carries is refused. Prefer edit_file where a small change is meant.

Inputs: path (required), content (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct action or resource: session lifecycle tools are separate from file operations, listing, participant inspection, and change waiting. The only mild overlap is session_status vs list_participants, but the descriptions clearly distinguish an overall session report from a detailed seat roster.

    Naming Consistency4/5

    Most names follow predictable snake_case patterns: session_* for lifecycle, list_* for collections, and verb_noun for file operations. wait_for_change is a minor deviation, but the set remains highly readable and consistent overall.

    Tool Count5/5

    Ten tools are well-scoped for a collaborative room/session server, covering session lifecycle, shared file reading/writing/editing, path listing, participant listing, and change watching without obvious redundancy.

    Completeness4/5

    The surface covers core room and file collaboration workflows, including read, write, edit, list, join, host, leave, and wait for changes. Minor gaps exist around creating, deleting, or renaming shared files and modifying grants after hosting, but these appear partly by design since the host folder supplies the file set.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers