PLexus makes, starts, stops and deletes Pharo images that answer MCP, and forwards tool calls to a running one.
- An image is a directory of PLexus's Pharo Launcher profile:
$PLEXUS_HOME/profiles/images/<name>/<name>.image, withPLEXUS_HOMEdefaulting to~/.plexus. It exists when that file does. Nothing declares it first and nothing remembers it after. - A running image is a process: a VM whose command line names that image
file, compared on the real path. Every call asks the host's process list
once, the way
psdoes, so an answer is as old as the call that gave it. Nothing tells PLexus that a VM stopped, so nothing records that one started. - A scope is a name prefix. With scope
Proj, imagedevis the directoryProj-dev, and onlyProj-directories are listed, without the prefix. A scope holds no dash, so the first dash of a directory name ends its scope:shopnever listsshop_api-dev, which isshop_api's. PLexus stores no scope: the caller passes one, and without one every image is listed.
An image keeps what PLexus knows about it in <image>/plexus/, which goes
with it:
| File | Written | Read |
|---|---|---|
created.properties |
by create: template, category, how MCP got in, PLexus version | by list |
on-start |
by create with --every-start: the script to file in |
by every start, before MCP starts |
endpoint.properties |
by the running VM: the port it bound and its pid | by list and forwarding, while that pid runs the image |
start.st, start-status.properties, launch.lock |
during a start | by that start |
building |
by a create with a script, naming its process, until the image is ready | by list, start and delete |
A create with a script builds the image under a name of its own and renames it
in with building, which start refuses. While that create runs, delete
refuses the image too; once its process is gone, delete is how the unfinished
image goes. What a PLexus that was killed left elsewhere, a base it was
building or a directory it was copying or removing, is named after its
process, and the next create removes it.
plexus image templates
plexus image create <name> --template <t> [--category <c>] [--script <file> [--every-start]]
plexus image start <name> [--display interactive] [--timeout <seconds>]
plexus image stop <name>
plexus image delete <name>
plexus image list [<name>]
plexus mcpEvery command takes --home <dir> (PLEXUS_HOME) and --scope <prefix>
(PLEXUS_SCOPE), and --help. Results are JSON on stdout; a refusal is
{"ok":false,"code":...,"error":...} with exit status 1.
- templates lists the launcher's templates with their category. A name in
more than one category is marked
ambiguous, and a create from it must say which. - create refuses a name that is taken, and never starts the image.
- start launches the image headless unless asked otherwise, and answers once its MCP server does, with its pid and endpoint. It refuses an image a VM already runs, and fails as soon as the VM reports a failure or exits, naming the launcher's logs. It never creates: a missing image is refused.
- stop kills every VM running the image. A kill does not save, so an agent that wants the image saved saves it through the image first. An image that is not running is already stopped.
- delete removes the image's directory, and refuses while a VM runs it or a create or a start is still at work on it.
- list shows each image, whether it runs, its pids, its endpoint, its template, Pharo version and how MCP got into it. It pings nothing and writes nothing.
Without a script, an image is a copy of a base: its template with the MCP
release PLexus pins loaded and saved. The first create from a template builds
the base, which takes minutes; later creates copy it, cloning blocks where the
filesystem can. A base is a directory of $PLEXUS_HOME/bases named after its
template, category and pin. It is built under a temporary name and renamed
when complete, so its existence is its record, and the bases of other pins are
removed when one is built.
With --script, the image is built from the template and the script is filed
in once instead, which is how an image gets MCP from a checkout or an older
Pharo gets a version that loads on it. With --every-start as well, every
start files the script in again before the server starts, so an image follows
the checkout it loads from.
A stdio MCP server for an agent host, in the scope given when it starts:
{ "mcpServers": { "plexus": { "command": "plexus", "args": ["mcp", "--scope", "MyProject"] } } }It offers image_templates, image_create, image_start, image_stop,
image_delete and image_list, followed by the tools of every image in scope
that runs with an endpoint. Each of those takes an image argument naming the
image to call; it may be left out while one image runs. After a start, a stop
or a delete, the server tells the host its tool list changed.
Its own tools answer in plain text, for a model: what happened first, then what it found. A refusal, a call whose arguments break the tool's schema among them, is an error result that says what happened and what to do. A forwarded call waits as long as the call's own time limit allows, and at least a minute; whatever the image answers passes through as it is, and a call that gets no answer says what became of the image.
import { Images, callTool, listTools } from "@evref-bl/plexus";
const images = new Images({ scope: "MyProject" });
await images.create("dev", { template: "Pharo 14.0 - 64bit" });
await images.start("dev");
const tools = await listTools(await images.endpoint("dev"));
await images.stop("dev");Everything reachable from the package root is API and moves under semver.
Refusals are PlexusErrors whose code says which.
imageToolAnswers renders the answers of plexus mcp's image tools, checks
their arguments and says what a failed forwarded call did, for a server that
offers the same tools.
Requires Node.js 22.12 or newer, and Pharo Launcher for anything that runs an image.
npm install
npm run check # typecheck, build, unit tests
npm run verify:env # where the launcher was found
npm run smoke:start-route-stop -- --template "Pharo 14.0 - 64bit"The smoke runs a real image through create, start, a tool listing, stop and
delete, in a scratch scope of its own (plexus_smoke_<run>), so it never names
an image anyone works in. It is not part of npm run check.