MCP server#
scenet mcp serves the compiler over the Model Context Protocol,
targeting revision 2026-07-28. It is
the one way of driving Scenet from a model that closes the loop: the model writes a document,
validates it, reads findings that name the rule, the line and the fix, corrects its own output,
and renders it — with no person copying error text from a terminal into a chat window.
Starting it, transports and exit status are in the command-line reference; connecting a client is in driving Scenet from a model. This page is the tools.
Tools#
Five, deliberately. Each extra tool is more for a model to read before it can choose one.
Tool |
Takes |
Returns |
|---|---|---|
|
|
The spec pack, one part at a time, as Markdown |
|
|
Every shipped character, then every puppet file sent, with each pose and expression it declares |
|
|
|
|
|
Each panel’s notes and Panel Core, then each page’s Page Core |
|
|
A summary, then one SVG per panel, then one per page, then each panel’s exports for image models when asked |
Every tool is annotated read-only, idempotent and closed-world: none writes a file, reaches the network, or answers differently on a second call. A client can run them without asking.
Arguments#
sourceThe whole document, as text. Not a path: a remote client shares no file system with the server, and one calling convention for both transports is one less thing to get wrong.
filesThe files the document names — a picture behind the cast, a lettering face, a puppet of its own — by the path it writes, each as base64:
{"art/p01.png": "iVBORw0KGgo…"}. They stand in for the document’s folder, which the server never reads, and are read in memory, so nothing is written to the server’s disk. A path is held to a document’s own rules — relative,/between folders — and a value that is not base64 is a tool error naming it. Left out, a document that names a file getsimage-file,font-fileorpuppet-file, as text with no folder does anywhere. A cast of figures a picture draws also needs the picture’s artwork contract, beside it and named after it —{"art/p01.png": "…", "art/p01.art.yaml": "…"}; without it the finding isartwork-contract, at the line naming the picture. Given tolist_puppets, each*.puppet.yamlamong them is listed after the shipped puppets, by its path — whatreferencewrites — and one that is not a puppet is a tool error saying why.syntaxyaml(default) for a*.panel.yamlor*.scene.yamldocument — a top-levelpanels:key is what makes it a scene, so there is no third value — orscriptfor a comic script.sectionOne of
preamble,language,shot-types,comic-script,characters,diagnostics,schema,gallery. Omitted,get_specreturns the preamble — what Scenet is, the check-and-fix loop, the mistakes generators make most — and a list of the other parts.deepAlso run the solver, as
scenet check --deepdoes, to catchlayoutandballoon-placementfailures the cheap pass cannot see.live_textEmit selectable
<text>instead of glyph outlines, asscenet build --live-textdoes. About a third the size, which matters inside a model’s context, but it depends on the viewer having a matching font.ariatrue(default): each panel is an image a screen reader can read, named with what it shows and then everything said in it, in reading order, asscenet buildwrites it — which also gives a model reading the SVG back the panel’s words.falseleaves that out, as--no-ariadoes.monotruedraws every value as its grey and ignores a palette’s colour, asscenet build --monodoes: byte for byte what the same document draws withpalette: mono.false(default) draws each colour the palette gave.
Findings#
validate returns every finding, in source order:
Field |
|
|---|---|
|
Stable rule id, such as |
|
|
|
What is wrong, naming the offending construct |
|
What to do about it |
|
Where the rule is explained: its entry, with a document that gives it and the same document fixed |
|
Path to the offending value, such as |
|
1-based |
A document whose only findings are notes is valid: it compiles as it is. Weigh each note,
and fix it if the panel should read better.
compile and render refuse a document that does not compile with a tool error, whose
text lists the same findings with the same fixes, errors only. A solver failure is located as well as a
syntax one: only a failure pays for the deep check that locates it, so a document that compiles
is compiled once.
The findings travel in two forms: as structured content for clients that read it, and as text for the many hosts that show a model only a result’s text.
Rendering#
render returns a short text summary — how many panels, and the compiler’s notes — then one
embedded resource per panel, scenet://panels/NAME.svg, of type image/svg+xml. A document
with pages: gets one more per page after them, scenet://pages/N.svg. The SVG is
byte-identical to what scenet build --embed-images writes for the same document: a picture
it is drawn over is written into it as a data: URI, since whoever reads the SVG has no folder to
find a linked one in. A document with no picture is byte-identical to plain scenet build.
With conditioning: true, each panel’s exports for image
models follow the pages, five per panel and exactly as
scenet build --conditioning writes them: scenet://panels/NAME.pose.json, .boxes.json and
.semantics.json as application/json, .depth.svg and .mask.svg as image/svg+xml. A
parameter rather than a sixth tool, which keeps the server at five.
It is never sent as an image content block. Hosts forward image blocks to the model, and model APIs that accept images do not accept SVG, so an image block would fail the whole turn instead of showing a picture. There is no PNG either: rasterising would put a renderer in the runtime dependencies for one tool.
Instructions#
On connecting, the server sends instructions that many hosts hand straight to the model. They
say what to do rather than what the server is: read get_spec first, cast only what
list_puppets lists, validate until clean, and pass text rather than paths — with the bytes
of any picture, font or puppet file the document names in files, and of the artwork contract
beside a picture whose figures the cast names. A puppet file of the document’s own needs no tool
either: list_puppets given the same files describes it. Figures have no tool of their own,
which keeps the server at five: their names are the contract’s, and get_spec’s characters part
says where they come from.
Keeping stdout clean#
On the stdio transport, stdout is the protocol stream, and one stray line corrupts it. Nothing
in the server goes through the code scenet build uses to print wrote and note: lines; the
compiler’s notes travel inside tool results instead. The SDK additionally points file descriptor
1 at stderr while it serves, which catches a stray print from a dependency. The test suite
drives a real stdio session against the installed command, so neither can regress quietly.
From Python#
The tools are plain functions, importable without starting a server:
from scenet.mcp import list_puppets, validate
report = validate("""
cast:
alice: {reference: alice}
script:
- say: {by: bpb, text: Hello}
""")
assert not report.valid
finding = report.findings[0]
assert finding.rule == "scenet/unknown-actor"
assert finding.where == "script.0.say.by"
assert (finding.line, finding.column) == (5, 15)
assert [puppet.name for puppet in list_puppets().puppets] == ["alice", "bob"]
build_server() returns the configured server without running it, for a host that wants to
connect in process or mount it inside a server of its own.
Publishing#
server.json at the repository root
describes the server for the official MCP registry,
which holds metadata only and points at the package on PyPI. Ownership of the
io.github.creatoan/scenet namespace is proved by the mcp-name marker in the README, which
becomes the PyPI project description. Listing a release is done by a workflow; see
releasing.