Reproduce a reaction with CLI, Python, REST and MCP

Use the same Diels–Alder reaction through every interface. The downloadable clients check their results and create a new output directory, so a repeated run cannot silently overwrite an earlier exercise. These examples prepare figures and vibe-qc inputs; they do not submit calculations.

Command line and Python SDK

Download reaction_cli.sh, activate the vibe-sketch environment, and run:

bash reaction_cli.sh diels-alder-cli
vibe-sketch serve diels-alder-cli/ready.vsk --open

The script exercises convert, validate, info, schema, writers, clean, render, embed, input, name and --version. It prints a name only if the optional naming engine verifies one. The opened document shows the same species the command-line report describes. With a source installation, vibe-sketch desktop diels-alder-cli/ready.vsk launches the native window instead.

For the SDK, run named_reactions.py:

python named_reactions.py named-reaction-files

It uses import_into, derive, clean, embed, the document models, save, export, write_input and write_inputs. It checks chemical formulas, spin, 3D caching/replacement, exchange-format round-trips and writer refusals. Inspect the code around the operation you want to adapt; all examples use the document’s actual species ids. WriterRefusal.reasons explains unsupported requests. Use the SDK’s write_output for outputs that may replace an existing file, so QVF-result protection is applied.

A shared document over REST

Start vibe-sketch serve in one terminal. Download reaction_rest.py, then pass the address printed by the server:

python reaction_rest.py http://127.0.0.1:8766 diels-alder-rest

The standard-library client creates the reaction, edits labels and a name, cleans and embeds it, checks its formula report, requests JSON and ZIP inputs, and exports the sketch. It also demonstrates stateless conversion/reporting, validation, schema discovery, isolated SMILES embedding, document listing, canvas updates, append/replace and closing a scratch document. With QVF available, it checks overwrite eligibility and round-trips base64 archive data. Open the printed link to inspect the live document. requests.json lists the actual requests and HTTP statuses from your run.

Handle a revision conflict

The example deliberately edits the document, then tries the old revision:

state = client.call("GET", route)
old_revision = state["revision"]
state = client.call(
    "PATCH",
    f"{route}/species/{sid}",
    {"revision": old_revision, "label": "1", "name": "1,3-butadiene"},
)
client.call("POST", route + "/clean", {"revision": old_revision}, expected=409)

For whole-document PUT, send If-Match; a stale value returns 412. Fetch the current document, review what changed and apply a deliberate new edit. Do not loop by blindly replacing revisions. The client does this explicitly. The running browser also sees accepted server edits through its shared session.

A document created through REST has no server-side file path. Its /save therefore returns 409; export and write the downloaded bytes on the client. To exercise save-back, start the server with a copy of a VSK file, edit that open document and use /save. REST never takes arbitrary desktop save paths. /api/qvf/overwrite-check inspects archive bytes, not a path; it is only one part of safely replacing a file whose contents could change before writing.

An MCP client using the actual protocol

Register the command as in Working with agents. To follow a visible session, configure vibe-sketch mcp --server URL; omit --server for discovery of an existing local server, or use --new-server to start one separately. The server’s address is written on stderr, preserving the MCP protocol on stdout.

Download reaction_mcp.py:

python reaction_mcp.py http://127.0.0.1:8766 diels-alder-mcp

This is a real stdio client, not an invented agent transcript. It initializes the protocol, discovers 17 tools, exercises 14 without external side effects, and saves transcript.json. The queue/viewer tools below require their corresponding integrations and a deliberate request.

The browser displays the MCP client’s edits. The saved VSK records those edits with actor agent and client mcp in provenance.

Tools	Exercise
status, list_writers	Discover the app, documents and supported writer capabilities.
new_document, open_document, show_document, report	Create the reaction, inspect identity, save and reopen it.
add_structures, set_species, clean_up, embed_3d	Append/replace, label, name, clean and prepare the shared drawing.
write_inputs, export, save_document	Write three vibe-qc scripts, SVG and a VSK.
show_runs	Read the document’s runs, or handle the queue install hint.
submit_jobs, cancel_run	Use the queue lifecycle exercise.
show_in_vibe_view	Send a prepared species through the viewer handoff.

An agent can use this prompt with the same tools:

Open my Diels–Alder sketch, check the species and roles, prepare missing 3D geometries, and write vibe-qc B3LYP/def2-SVP single-point inputs into a new directory. Export an SVG and save a VSK copy. Report warnings and refused requests. Do not submit calculations.

Run vibe-sketch submit, runs and cancel only for the queue workflow; view launches the viewer. These commands are covered in their own illustrated tutorials rather than hidden inside the preparation scripts. See the coverage map for every REST route and tool.