gornskew/cyborg-whisperer

-->
> [!IMPORTANT]
> **Looking for lisply-mcp?** The plain-language "corporate" fork
> lives at genworks/lisply-mcp.
>
> This repository (cyborg-whisperer) is the gaming-language upstream
> and is maintained separately. A clone whose origin still points at
> gornskew/lisply-mcp lands here; to follow the fork instead:
>
>
Cyborg Whisperer: a Protocol Officer for Lisp-Speaking Crews
Aboard a Basilisk-class
vessel, no cyborg wanders. Every visit — however it beams aboard — is
bound for a particular crew member, and every visit begins the same
way: with the **Protocol Officer**. He receives each arriving cyborg,
interviews it, schools it in the ship's ways, and dispatches it to
the crew member it came to see.
Cyborg Whisperer is the kit for that post — the species, if you like,
of which every Protocol Officer is a member. Post one beside any crew
member who answers the _Lisply_ dialect, aboard ship or ashore, and
arriving cyborgs find themselves received, educated, and set to
useful work.
Plainly: this is the middleware that speaks
MCP — the Muster-and-Conduct
Protocol, in which an Officer musters each arriving cyborg and
conducts it to its crew member — to the large language
models that are
the cyborgs, and a lightweight dialect called _Lisply_ to the
Lisp residents that are the crew.
**Note: the Officer raises no residence.** He is a caller at a hatch
that is already open — a pure HTTP client (HTTP being the
Hatch-To-hatch Transfer Protocol, a plain hail from one hatch to
another) to a resident already answering. Raising rooms is the vat's
business, through the Basilisk yard — see "Running it" in the
Basilisk README — or open a
Lisply hatch of your own on the dock and point the Officer at it.
Once a resident answers, Claude Desktop calls on him as the example
registries below show.
What Is it Meant to Do?
The Officer connects the craft a cyborg arrives in — any
MCP-capable client, such as
Claude Desktop — to a Lisp
resident who keeps a REPL, a Read-Eval-Print Loop. The connection is
meant for AI-assisted symbolic programming, sometimes called
_Neuro-Symbolic Programming_. We coined "Lisply" for the small
dialect most any Lisp-like resident can learn so as to stand with a
Protocol Officer of his own.
The idea is that the cyborg can compose and have worked arbitrary
Lisp incantations, up to and including writing, compiling, loading
and testing whole scrolls and projects.
Sandbox Trust Model
Lisply-backed MCP servers are intended to be exposed to the LLM as
**trusted sandboxes**. The wrapper is not designed to restrict Lisp
operators, filesystem access, or subprocess execution inside the
backend environment. Instead, the backend itself is expected to run in
an isolated container or other sandbox chosen by the operator.
This is intentional:
- lisp_eval is meant to support free-form, full use by LLMs.
- /projects may be a host-mounted working tree, but the rest of the
backend filesystem may remain container-ephemeral.
- Trust decisions should therefore be made at the container/backend
boundary, not by crippling Lisp evaluation in the MCP wrapper.
The wrapper now advertises this trust model in tool metadata with a
default TRUST_AS_SANDBOX=true. Operators can override the explanatory
text with SANDBOX_NOTE if needed.
Extra Quick Start
Follow "Running it" in the Basilisk
README — git clone the yard,
then ./basilisk up.
This raises a whole ship, with a Protocol Officer already at his post
beside the Captain.
Quick Start
The following gets you going quickly with a minimal default
registry and the default public Common Lisp resident (the First
Officer, a Gendl room raised from the vat). See the main Contents
below for more background and every flag.
1. Install
1. Install Node.js (18+ recommended). If on Windows, this can be
installed directly in Windows or in WSL.
2. Have a resident with an open hatch to call on. The easiest way is
a ship raised from the Basilisk
yard (requires a vat:
Docker); or open a
Lisply hatch of your own on the dock.
3. Copy these cyborg-whisperer scrolls to somewhere the craft (Claude
Desktop, say) can reach.
2. Tell the craft where the Officer stands