Frsync Mud

A file transfer and immort editor system for Final Realms: Legacy.

FRsync lets builders move files between their own computer and the MUD over the normal creator login — no FTP required. It works because FR's creator shell exposes exec (run LPC) and the write_file / read_bytes efuns; FRsync logs in as you and pushes/pulls files straight over that connection. The MUD's own permission system (valid_write) decides what you may touch — exactly as it does in-game — so this works for any builder, for their /w/<name>/ home and any /d/<zone>/ they're granted.

It comes in two parts:

1. frsync.py — a zero-dependency command-line tool (interactive shell + scriptable push/pull/status/mirror/watch).
2. frsync_mcp.py — an MCP server that exposes the MUD to Claude Code (or any MCP client) as tools, so an AI agent can read a room, fix a bug, write it back, reload, and test.

---

Requirements

• Python 3.8+ (the CLI uses only the standard library).
• A creator/builder account on Final Realms: Legacy.
• For the MCP server only: pip install mcp keyring (keyring provides cross-platform secure credential storage).

The default server is fr.hyssing.net:4010; override with --host / --port (CLI) or FRHOST / FRPORT (MCP).

---

Get started

git clone <repo-url> frsync
cd frsync

Nothing to build — frsync.py runs as-is. Everything below is driven through the Makefile; run make help to see every target.

---

Part 1 — The command-line tool

Interactive shell

make start

You'll be prompted for your creator name and password, then dropped into an interactive shell that behaves just like telnet — every normal MUD and creator command goes straight to the server (look, ed myroom.c, update myroom.c, ls /w/you, …). On top of that you get local /commands for moving files:

Saved logins. After you log in, FRsync offers to remember the login (yes / no / don't ask again). The password goes into your OS keychain (macOS Keychain, or the cross-platform keyring if installed) — never a plaintext file; only the creator name is recorded. Next time, it shows your saved logins and you pick one with the arrow keys and Enter — no retyping. Press d on a login in that menu to forget it (with a y/N confirm). You can also manage them from the CLI with frsync logins (--forget <name>, --forget-all, --ask to re-enable the prompt). If a saved password is ever rejected (you changed it on the MUD), FRsync offers to forget it and re-enter — no manual cleanup needed.

Command	Does
/upload <f> [..]	send local file(s) → the remote folder (or just drag files onto the window)
/download <f> [..]	fetch remote file(s) → this computer
/push	mirror the whole local folder tree → remote (recursive)
/pull	mirror the whole remote folder tree → local (recursive)
/diff [file|glob]	unified diff local vs the MUD — what differs (catches live ed edits). No args diffs the whole folder (only changed files shown); *.c globs too
/rm <f> [..]	delete remote file(s)/empty dir(s) — asks first, default no (alias /del)
/mv <src> <dst>	rename / move a remote file (alias /rename)
/update [-o] <f>	recompile file(s) in-game; prints compile errors as file:line: msg
/goto <file>	teleport into a room by its file
/clone <file>	clone an object to test it
/lint [dir]	check the area's exits/inherits/clone+load targets/includes resolve on the MUD — catches broken exits before players do
/errors [n|all]	tail your MUD error log (runtime + compile errors)
/autoupdate on|off	toggle auto-reload after each push (on by default)
/where	show your current local + remote folders
/lcd <dir>	change the local folder (downloads land here)
/rcd <dir>	change the remote folder (transfers use this)
/lpwd, /lls	print / list the local folder
/idle [on|off|N]	stay connected when idle (on by default): silent TCP ping every N s (60) plus a MUD idle-reset every ~20 min so you're not auto-logged-off
/help, /quit	full command list / leave

Type / and the matching commands appear after your cursor, narrowing as you type; press Tab to complete (a unique match fills in, several extend to the common prefix). This works for file-name arguments too, descending into subfolders as you go: local files for /upload, /diff, /lint narrow live as you type (listing your folder is cheap); remote files for /download, /rm, /goto, /update, … complete on Tab (they're listed over the MUD on demand, so the per-keystroke hint doesn't pester the server).

/upload and /download take multiple files and glob patterns — space-separated names, or wildcards like *.c, cloud*.c, *.*. Uploads glob against your local folder; downloads glob against the remote folder. For example /upload *.c or /download room*.c a.c b.c.

The builder loop. Whenever you upload a .c (via /upload, /push, or drag-and-drop), FRsync automatically updates it on the MUD and shows the result — a clean reload count, or the compile error mapped to file:line:

  ↑ 1 file(s), 1.2K -> /w/you/drifting_forest/rooms
  ⟳ update 1 file(s)…
    ✗ hut.c:14: Undefined variable 'exts' before  ; }

So edit → save → drop → see the compile result, without touching the MUD window. Then /goto rooms/hut to stand in the room, /clone obj/torch to test an object, and /errors to read runtime errors. Turn the auto-reload off with /autoupdate off (then reload by hand with /update, -o to update an inherit chain when you changed a base or .h).

Validate the whole area with /lint: it reads your local .c source, resolves every referenced path — room exits (add_exit), inherit, clone_object/add_clone, load_object/find_object, and #include — through the area's #define path macros, and checks each target actually exists on the MUD. It reports broken references as file:line kind → /path, so a mistyped exit or a room you renamed-but-forgot-to-repoint is caught before a player walks into it.

It also learns your area's helper functions: if a room wires exits through a custom wrapper like add_dream_exit(dir, dest, type) that forwards to add_exit, /lint detects it and checks calls to the wrapper too — so an area whose exits all go through a helper is still fully covered, not silently skipped.

References it can't resolve statically — a path built from a runtime variable, or a macro defined outside the area (e.g. a standard mudlib path like WEAPON) — are counted and skipped, never silently dropped; run /lint -v to list them so you can confirm none hides a real reference. If a file uses an exit/load style /lint doesn't recognise, it says so rather than giving a false all-clear.

A multi-file transfer runs through the files one at a time, advancing a single overall progress bar (total bytes across the whole batch, and which file is moving) — so you watch it climb as you go:

  [████████████░░░░░░░░░░]  55%  (2/3) workroom2.c     5.0K/9.0K

If a file would overwrite an existing destination, it asks right then:

  workroom.c already exists — overwrite? [y]es [n]o [a]ll-yes [s]kip-all [q]uit

• y / n — this file
• a — yes to all remaining
• s — no to all remaining (skip every existing file)
• q — quit the transfer now

(The scriptable push/pull already compare and confirm separately.)

Downloaded files land in ./downloads by default (created automatically, relative to where you launched), so they don't clutter your working folder. Change it any time with /lcd <dir>, or start elsewhere with make start DIR=./myarea.

Scriptable commands

For automation and one-shot transfers, call the subcommands directly. Each takes a local path and a server path; either can be a single file or a directory (directories sync recursively). Every push/pull is verified (size + checksum) on both ends.

Command	Direction	What it does
status	compare	Show what differs between local and MUD. Changes nothing.
push	local → MUD	Upload, verified. Asks before writing.
pull	MUD → local	Download, verified.
watch	local → MUD (live)	Auto-upload files as you save/drop them, then auto-reload each .c in-game (compile errors shown). --no-update to just push.
mirror	MUD → local (bulk)	Download whole subtrees for a local working copy. Resumable.

# compare a local area against the MUD, change nothing
python3 frsync.py status ./drifting_forest /w/<creator>/drifting_forest

# upload an area (or a single file); --dry-run to preview, --delete to prune
python3 frsync.py push ./drifting_forest /w/<creator>/drifting_forest

# download an area
python3 frsync.py pull /w/<creator>/drifting_forest ./backup

# bulk-download whole server subtrees into ./MUD (resumable — re-run to continue)
python3 frsync.py mirror ./MUD /std /d /w/<creator>

# "synced folder": auto-push a local dir as files change, reloading each in-game
python3 frsync.py watch ./myarea /w/<creator>/myarea

Typical workflow:

python3 frsync.py pull   /w/<creator>/myarea ./myarea   # get the current version
# …edit files locally in your editor…
python3 frsync.py status ./myarea /w/<creator>/myarea   # check what changed
python3 frsync.py push   ./myarea /w/<creator>/myarea   # ship it (verified)

…or just leave watch running: every save uploads and reloads the object in-game, printing any compile error as file:line: message — the full edit→save→reload loop with no MUD-window typing.

Flags:

Flag	Meaning
--char NAME	Creator name (skip the prompt).
--ext .c,.h	Only these file types (directory syncs).
--dry-run	Show what would happen; change nothing.
-y / --yes	Don't ask for confirmation (for scripts).
--delete	push only: remove server files missing locally (off by default).
--include-backup	mirror only: include old BACKUP//ATTIC/ archives (skipped by default).
--rewalk	mirror only: re-list the tree instead of using the cached manifest.

Run python3 frsync.py --help for the complete list.

The same operations are wrapped as Make targets:

make mirror-code CHAR=yourname                 # mirror the standard mudlib roots
make status DIR=./myarea REMOTE=/w/you/myarea
make watch  DIR=./myarea REMOTE=/w/you/myarea

Install on your PATH (optional)

make install            # installs `frsync` to /usr/local/bin (set PREFIX= to change)
frsync --help
make uninstall

frsync.py is a single standard-library file with no dependencies — you can also just copy or paste it anywhere and run it.

---

Part 2 — The MCP server for Claude Code

This exposes the MUD to an AI agent as tools: mud_ls, mud_read, mud_write, mud_update, mud_errors, mud_download, mud_upload, mud_delete, mud_rename, mud_command, mud_exec, mud_whoami. So an agent can read a room, fix a bug, write it back, mud_update to reload it and catch compile errors, then mud_errors to read runtime errors — the full build/test loop.

Deleting is gated on a human. mud_delete (and mud_rename when it would overwrite an existing file) call MCP elicitation to ask you to confirm before anything is removed — the agent cannot delete server files on its own, and if your client can't show that prompt the delete is refused. The human interactive shell has the same guardrail: /rm asks first and defaults to no.

1. Install the dependencies

make mcp-deps           # pip install mcp
pip install keyring     # for secure credential storage

2. Register the server with Claude Code

make mcp-register

This registers the server without any credentials in the config:

claude mcp add frsync-mud -- python3 /path/to/frsync_mcp.py

3. Store your credentials securely (one time)

make mcp-login

You'll be prompted for your creator name and password (hidden — no echo). They're saved to your operating system's secure secret store, never to any config file. Then restart the frsync-mud MCP server for it to take effect.

That's it — the agent now has the mud_* tools available.

---

Credentials & security

Credentials are stored in your OS secret store via the cross-platform keyring package:

OS	Where it's stored
macOS	login Keychain
Windows	Credential Locker
Linux	Secret Service (libsecret / GNOME Keyring / KWallet)

Manage them with:

make mcp-login      # enter / update credentials
make mcp-status     # show whether credentials are configured (no secrets shown)
make mcp-reset      # forget the stored credentials

(or call python3 frsync_mcp.py --login | --status | --reset directly.)

Resolution order at connect time: FRCHAR + FRPASS environment variables (an escape hatch for CI) → the OS secret store → otherwise the tools fail with a message telling you to run --login. No password is ever written to a config file in plaintext, and the interactive CLI tools read the password with no echo, so it never passes through the agent or model context.

The command-line tool (frsync.py) prompts for credentials on each run (or reads $FRPASS / --char if you set them); only the long-running MCP server uses the secret store.

---

Troubleshooting

• Only one session per creator at a time. A creator can only be connected once. If you're already logged in elsewhere (e.g. the MCP server holds the session, or you're in the game normally), FRsync detects it and uses FR's built-in takeover: the interactive shell asks " is already logged in elsewhere. Throw out that session and take over here? [Y/n]", and the MCP server reclaims the session automatically. Note this means the two can play tug-of-war — use one at a time.
• Restart the MCP server after make mcp-login / mcp-reset. A running server keeps the old credentials until it's respawned.
• "No frsync credentials configured." Run make mcp-login, then restart the server.
• Editing frsync.py doesn't change MCP behavior? The MCP server loads the engine once at startup — restart it after editing.
• Syntax-check the tools any time with make check.

---

How it works (in brief)

FRsync speaks the creator shell's exec channel rather than a file-transfer protocol. Reads use read_bytes (chunked, since it's capped per call); writes use write_file and are verified after the fact with a length + CRC check. Everything you can do is bounded by your in-game permissions — FRsync grants no access you don't already have as a builder.

A few things worth knowing:

• Nothing on the server is deleted unless you ask: push --delete, the shell's /rm (which asks first, default no), or mud_delete (which asks you to confirm before the agent can remove anything).
• Every push/pull is verified by comparing size + checksum on both ends.
• mirror is resumable — stop any time and re-run; it skips what's already downloaded (the file list is cached in a .frmanifest_*.tsv).
• Read-protected dirs (player accounts, /secure, server scripts) are skipped cleanly and listed in .frsync_skipped.txt.
• It auto-reconnects if the MUD drops the link, and streams file contents in safe chunks (the driver drops very long input lines).
• The interactive shell stays connected when idle (/idle): a silent telnet NOP every 60s holds the TCP link open, and a newline every ~20 min resets the MUD's own idle-logoff (which only counts real commands). If the link dies anyway, it exits cleanly instead of crashing.

---

Built by Malric and Silbago for Final Realms: Legacy. For questions, contact the Final Realms admin.