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 it

  • list_puppets – the characters it may cast, with their poses and expressions – the shipped ones, and any puppet file sent with a document

  • validate – every finding at once, shaped rather than dumped as raw SARIF

  • compile – the Panel Core: where the compiler put everything, and why

  • render – the SVG, byte-identical to what scenet build --embed-images writes

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: BaseModel

Every panel in a document, compiled, and the pages they are laid out on.

panels#

In reading order

Type:

list[CompiledPanel]

pages#

In order; empty when the document has no pages:

Type:

list[CompiledPage]

class scenet.mcp.CompiledPage[source]#

Bases: BaseModel

One page: where each panel’s frame is.

number#

The page’s number, from 1

Type:

int

core#

The Page Core: the page’s size, the type height its panels share, and one frame per panel in reading order, as scenet build --core writes it

Type:

dict[str, Any]

class scenet.mcp.CompiledPanel[source]#

Bases: BaseModel

One compiled panel.

name#

panel for a single panel, else its name or number

Type:

str

notes#

Decisions the compiler made that the source did not literally ask for

Type:

list[str]

core#

The Panel Core: every resolved coordinate, as scenet build --core writes it

Type:

dict[str, Any]

class scenet.mcp.Finding[source]#

Bases: BaseModel

One thing wrong with a document: which rule, where, and what to do about it.

rule#

Stable rule id, such as scenet/unknown-actor

Type:

str

level#

error stops the document compiling; a note reports a house limit, such as a balloon over the words a publisher asks for, and the document still compiles

Type:

Literal['error', 'note']

message#

What is wrong, naming the offending construct

Type:

str

fix#

What to do about it

Type:

str

help_uri#

Where the rule is explained, with a document that gives it and its fix

Type:

str

where#

Path to the offending value, such as script.0.say.by

Type:

str

line#

1-based line the finding starts on

Type:

int

column#

1-based column the finding starts at

Type:

int

end_line#

1-based line the finding ends on

Type:

int

end_column#

1-based column the finding ends before

Type:

int

class scenet.mcp.Puppet[source]#

Bases: BaseModel

A character a cast member’s reference can name.

name#

What reference writes: a shipped puppet’s name, or a puppet file’s path

Type:

str

heads_tall#

Height in head-heights; taller reads as older

Type:

float

poses#

Every value pose may take for this puppet

Type:

list[str]

expressions#

Every value expression may take

Type:

list[str]

class scenet.mcp.PuppetCatalogue[source]#

Bases: BaseModel

The puppet library.

puppets#

Every puppet the library holds, by name

Type:

list[Puppet]

class scenet.mcp.ValidationReport[source]#

Bases: BaseModel

Everything wrong with a document, all at once.

valid#

True when no finding is an error; notes may remain

Type:

bool

findings#

In source order; fix every error, and weigh each note

Type:

list[Finding]

scenet.mcp.build_server()[source]#

Build the server with every tool registered, without starting it.

Separate from serve so that a test, or a host embedding Scenet in a server of its own, can connect to it in process.

Return type:

MCPServer[Any]

Returns:

The server, ready to run on any transport.

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 validate reports.

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:

CompileReport

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 – language for every construct, comic-script for the script format, gallery for worked examples that are known to compile.

Return type:

str

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 reference names one of these; its pose and expression must be names that puppet declares. Anything else fails validation. A puppet of your own is a *.puppet.yaml file a cast member names by its path, reference: puppets/pip.puppet.yaml: send it in files, as validate, compile and render take it, and it is listed after the shipped ones, by that path.

Return type:

PuppetCatalogue

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-images writes, one embedded image/svg+xml resource 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 findings validate reports.

A document with pages: gets one more resource per page, scenet://pages/<n>.svg, after the panels: each panel at its frame, exactly as scenet build writes 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.svg and .semantics.json, exactly as scenet build --conditioning writes them.

Return type:

list[TextContent | EmbeddedResource]

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.mcp.serve(transport, **options)[source]#

Run the server until the client disconnects.

Parameters:
  • transport (Literal['stdio', 'streamable-http']) – stdio for a local client that launches the server itself, or streamable-http to listen for remote ones.

  • **options (Any) – Passed to the transport: host and port for Streamable HTTP.

Return type:

None

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 of SPEC_PARTS.

Return type:

str

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.md on the documentation site.

Return type:

str

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