void-bridge — Void ↔ Hermes control surface

A per-machine bridge that exposes your Void Editor workspace (and its git remotes) to Hermes / any MCP client as a clean, path-confined tool surface. It lets the agent search, read, write, reset, and git-push/pull your host files and remote repos without shelling into your machine ad hoc.

Layout

• bridge.py — dependency-free stdlib HTTP server (Bearer-token auth). Every path is confined to VOID_BRIDGE_ROOT.
• mcp_server.py — FastMCP wrapper reusing the same functional API, so the MCP tools and the HTTP endpoints behave identically.
• run.sh — venv bootstrap + launcher.
• void_bridge.service — systemd user unit.

Run (HTTP)

cd ~/Projects/void-bridge
VOID_BRIDGE_TOKEN=$(openssl rand -hex 24) VOID_BRIDGE_ROOT=$HOME/Projects ./run.sh

Health check: curl -H "Authorization: Bearer $TOKEN" localhost:8787/health

Run (MCP for Void / MCP clients)

. .venv/bin/activate
pip install mcp
python3 mcp_server.py        # stdio transport

Point your MCP client (Void extension host, etc.) at this script. Tools: read_file, search, tree, write_file, reset, git_status, git_commit, git_push, git_pull, remotes.

HTTP API

All calls: Authorization: Bearer <VOID_BRIDGE_TOKEN>, JSON in/out.

Method	Path	Body / Query	Effect
GET	/health	—	{ok, root}
GET	/tree	?path=&depth=	workspace tree
GET	/read	?path=	file content (≤5MB)
GET	/remotes	—	repos + remotes + ahead count
POST	/search	{pattern, path, glob, limit}	regex search (ripgrep)
POST	/write	{path, content}	write/create file
POST	/reset	{path, mode}	backup→.voidbak / git→HEAD
POST	/git/status	{repo}	git status -b --porcelain
POST	/git/commit	{repo, message, all}	commit
POST	/git/push	{repo}	push to origin
POST	/git/pull	{repo}	ff-only pull from origin

Security notes

• All paths are resolved and confined to VOID_BRIDGE_ROOT; symlink/escape attempts are rejected.
• Bind to 127.0.0.1 only. Do not expose the port to the network without a reverse proxy + TLS.
• reset with mode:"git" runs git checkout -- . (local restore). To pull remote state over local, call /git/pull.
• The token is the only auth — keep it out of git (.env is gitignored).