Agent-facing surface#
The MCP server and the spec pack it serves. See the MCP server reference for the tools as a client sees them, and driving Scenet from a model for connecting one.
scenet.mcp needs the optional extra, pip install 'scenet[mcp]'; scenet.spec_pack does not.
scenet.mcp#
An MCP server, so a model can check and render the panels it writes.
The spec pack tells a model what the language is; this lets it find out what it got
wrong. A model writes a document, calls validate, reads findings that each name a
rule, a line and a fix, corrects its own output and calls render – with no human
copying error text between a terminal and a chat window. It is the only part of the
agent-facing surface that closes that loop.
Install it with the extra, and start it with the scenet mcp command:
pip install 'scenet[mcp]'
scenet mcp # stdio, for a local client
scenet mcp --transport streamable-http # for a remote one
The official SDK, and only as an extra
Built on the official mcp
package, which already speaks protocol revision 2026-07-28 – the stateless core, the
extensions framework, cacheable list results – and adds nothing FastMCP would have to
supply. It is an extra rather than a dependency because it brings an HTTP stack the
compiler has no use for: the browser playground installs the base wheel into Pyodide,
and someone who only wants scenet build should not have to put Starlette through
their own licence review.
Transports are stdio and Streamable HTTP. Not SSE: the protocol has deprecated it, and Streamable HTTP replaced it.
Five tools, shaped after compilers that are already served this way
typst-mcp serves its
documentation one chapter at a time, checks a snippet, and renders one;
d2-mcp has a cheat sheet, compile to validate and
render to draw. The same shapes, rather than new ones:
get_spec– the spec pack, one part at a time, so a model need not read all of itlist_puppets– the characters it may cast, with their poses and expressions – the shipped ones, and any puppet file sent with a documentvalidate– every finding at once, shaped rather than dumped as raw SARIFcompile– the Panel Core: where the compiler put everything, and whyrender– the SVG, byte-identical to whatscenet build --embed-imageswrites
Each takes the 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. Every tool is read-only and closed-world, and says so in its annotations: nothing here writes a file or reaches the network.
A document that names a file – a picture behind the cast, a lettering face, a puppet of
its own – is sent with it: files maps the path the document writes to the file’s
bytes, in base64. They stand in for the document’s folder and are read in memory; the
server never reads a folder of its own, and never writes one.
Keeping stdout clean
On stdio, stdout is the protocol stream, and one stray line corrupts it. That is why
nothing here goes through cli.run_build, which prints wrote and note: lines –
the easiest way there is to ship a broken stdio server. Notes travel in the tool
result instead. The SDK also 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 to make sure neither ever matters.
- class scenet.mcp.CompileReport[source]#
Bases:
BaseModelEvery panel in a document, compiled, and the pages they are laid out on.
- panels#
In reading order
- Type:
- pages#
In order; empty when the document has no
pages:- Type:
- class scenet.mcp.Finding[source]#
Bases:
BaseModelOne thing wrong with a document: which rule, where, and what to do about it.
- class scenet.mcp.ValidationReport[source]#
Bases:
BaseModelEverything wrong with a document, all at once.
- scenet.mcp.build_server()[source]#
Build the server with every tool registered, without starting it.
Separate from
serveso that a test, or a host embedding Scenet in a server of its own, can connect to it in process.
- scenet.mcp.compile_panel(source, syntax='yaml', files=None)[source]#
Compile a document and return where the compiler put everything.
The result is the Panel Core for each panel: every figure’s position and scale, every balloon’s box and tail. Its notes say what the compiler did that the source did not literally ask for – a camera that retreated so the cast would fit, a tail that bent around a face. A document that does not compile is an error carrying the same findings
validatereports.A document with
pages:also gets each page’s Page Core: where every panel’s frame is. A panel on a page is compiled at its frame’s size.- Return type:
- Returns:
Every panel, in reading order, with its notes and its Panel Core, then the pages.
- Raises:
ToolError – The document does not compile. The message lists every finding.
- scenet.mcp.get_spec(section=None)[source]#
Read the Scenet language specification, one part at a time.
With no section: what Scenet is, the two ways to write a panel, the check-and-fix loop, the mistakes generators make most, and what every other part holds. Read it first. With a section: that part in full –
languagefor every construct,comic-scriptfor the script format,galleryfor worked examples that are known to compile.- Return type:
- Returns:
Markdown, exactly as it appears in the spec pack.
- scenet.mcp.list_puppets(files=None)[source]#
List the characters a panel can cast, with every pose and expression each declares.
A cast member’s
referencenames one of these; itsposeandexpressionmust be names that puppet declares. Anything else fails validation. A puppet of your own is a*.puppet.yamlfile a cast member names by its path,reference: puppets/pip.puppet.yaml: send it infiles, as validate, compile and render take it, and it is listed after the shipped ones, by that path.- Return type:
- Returns:
Every shipped puppet, by name, then every puppet file sent, by path – each with its poses and expressions sorted.
- scenet.mcp.render_panel(source, syntax='yaml', live_text=False, aria=True, files=None, *, mono=False, conditioning=False)[source]#
Compile a document and return each panel as SVG.
The SVG is exactly what
scenet build --embed-imageswrites, one embeddedimage/svg+xmlresource per panel, after a short text summary with the compiler’s notes. A picture the document is drawn over is written into it, since whoever reads the SVG has no folder to find a linked one in. A document that does not compile is an error carrying the same findingsvalidatereports.A document with
pages:gets one more resource per page,scenet://pages/<n>.svg, after the panels: each panel at its frame, exactly asscenet buildwrites the page.With
conditioning, each panel’s exports for image models follow, five per panel:scenet://panels/<name>.pose.json,.boxes.json,.depth.svg,.mask.svgand.semantics.json, exactly asscenet build --conditioningwrites them.- Return type:
- Returns:
A summary, then one SVG resource per panel in reading order, then one per page, then, when asked, each panel’s exports for image models.
- Raises:
ToolError – The document does not compile. The message lists every finding.
scenet.spec_pack#
The spec pack: the whole language in one file, for a model to read.
Nothing tells a model how to write Scenet, and nothing will from training – a niche
language is not in anybody’s weights, and pretending otherwise wastes effort. What
works for every new library is the same thing: one self-contained document a model can
be handed. This is that document, generated by scripts/build_spec.py from the
language reference, the shot-type table, the comic-script guide, the puppet library,
the diagnostic rule catalogue, the published JSON Schema and the whole gallery.
It ships inside the package because the MCP server’s get_spec tool serves it, and an
installed wheel cannot read docs/. A test regenerates it and compares, so the copy
here cannot go stale.
The pack is split into named parts, each opened by a marker comment, so a client that can ask for one part at a time – a tool call, an agent skill – need not pay for the other seven:
<!-- scenet-spec:part=language -->
- scenet.spec_pack.MARKER = '<!-- scenet-spec:part={name} -->'#
The comment that opens each part. One per part, on a line of its own.
- scenet.spec_pack.SPEC_PARTS: dict[str, str] = {'characters': 'The shipped puppets, with every pose and expression each declares', 'comic-script': 'The comic-script format: PAGE and PANEL headings as Dark Horse writes them, @shot:, cues, captions, off-panel speech, pages, and French scripts', 'diagnostics': 'Every rule `scenet check` reports, and what to do about each', 'gallery': 'Every gallery example in full, each known to compile', 'language': 'The language reference: every block and key of a panel or scene document', 'preamble': 'Start here: what Scenet is, the two ways to write a panel, the check-and-fix loop, and the mistakes generators make most', 'schema': 'The JSON Schema for a single-panel YAML document', 'shot-types': 'Normative: what each camera shot frames, in head-heights'}#
Every part of the pack, in order, with what it is for. The descriptions are what a model sees when choosing which part to read, so they say what is in each one.
- scenet.spec_pack.part(name)[source]#
One part of the pack, without its marker.
- Parameters:
name (
str) – A key ofSPEC_PARTS.- Return type:
- Returns:
The part’s Markdown, from the line after its marker up to the next marker.
- Raises:
KeyError – There is no part by that name. The message lists the ones there are.
Example
>>> from scenet.spec_pack import part >>> part("comic-script").lstrip().startswith("# Write a panel as a comic script") True
- scenet.spec_pack.spec_pack_text()[source]#
The whole pack, exactly as published at
/scenet-spec.mdon the documentation site.- Return type:
- Returns:
The Markdown text, read once and cached.
Example
>>> from scenet.spec_pack import spec_pack_text >>> "<!-- scenet-spec:part=language -->" in spec_pack_text() True