AI agents and humans share the same editable illustration document model. The browser API modifies the active canvas and participates in undo/redo and local autosave; the command-line interface modifies designated local project files. The two do not synchronize automatically.
After downloading or cloning the source, connect the local MCP stdio server to Codex or any MCP client supporting stdio. Node.js 20+ is required; no npm packages need to be installed. Replace the placeholder paths below with absolute paths (quote paths containing spaces).
codex mcp add biocanvas -- node /path/to/biocanvas/scripts/mcp-server.mjs --workspace /path/to/figures
Open a new chat to load tools: biocanvas_search_assets, biocanvas_list_projects, biocanvas_create_project, biocanvas_get_scene, biocanvas_apply_operations, and biocanvas_export_scene. Always obtain the current revision first, then submit a batch of mutations; exports return document content and attribution. The MCP server only operates on .biocanvas project files inside the configured workspace folder. The repository README contains complete configuration examples.
await window.bioCanvasAI.ready;
const api = window.bioCanvasAI;
api.search_assets({query: "Arabidopsis", module: "transcription"});
const {revision} = api.get_scene();
await api.apply_operations({
baseRevision: revision,
operations: [
{op: "add_node", node: {id: "plant-1", type: "asset",
assetId: "bioicons-ArabidopsisSeedlings", label: "Arabidopsis Seedlings",
x: 90, y: 180, w: 120, h: 120}}
]
});
const svg = await api.export_scene({format: "svg"});
Under “Integrations → AI Operations Interface”, import a JSON request file to execute operations and download the response. Always fetch the current revision before modifying; manual edits will invalidate older revisions. The interface never executes arbitrary JavaScript contained in requests.
{"method":"get_scene"}
node scripts/agent-cli.mjs --scene figure.biocanvas < request.json
{"method":"search_assets","params":{"query":"worm","module":"movement"}}
{"method":"apply_operations","params":{
"baseRevision":"copied from get_scene response",
"operations":[{"op":"set_title","title":"BIO 251 Experimental Diagram"}]
}}
{"method":"export_scene","params":{"format":"svg"}}
Responses always take the shape of {"ok":true,"result":…} or {"ok":false,"error":{"code":…,"message":…}}. CLI errors return a non-zero exit code. Nonexistent project files are created on the first successful mutation. Exported file content is returned in result.content. CLI exports support bundled assets only; sanitize and export custom SVGs through the browser editor.
| Method | Behavior |
|---|---|
| capabilities | Returns version, methods, operations, formats, and course modules |
| search_assets | query, module, license, limit (1–200) |
| get_scene | Complete scene document, revision, and layout warnings |
| apply_operations | Atomic batch mutation; rolls back completely on any validation failure |
| export_scene | biocanvas, svg, drawio; accompanied by attribution and layout warnings |
Supported operations: add_node {node}, update_node {id,changes}, remove_node {id}, connect {edge}, update_edge {id,changes}, remove_edge {id}, set_title {title}, layout {ids,columns,x,y,gapX,gapY}. Node types: asset, text, box. Edges reference node IDs; removing a node automatically cascades to connected edges.
A maximum of 200 operations may be applied per batch. Layout warnings provide approximate boundary and text overflow heuristics; inspect the exported SVG or canvas for precise verification. Exported SVG can also serve as a visual preview. The MCP server runs locally without external models or real-time cross-device sync.
Curated course modules cover basic pipetting, bacterial forward genetics, Arabidopsis transcriptional regulation, organic anion transport, the Hill reaction, and C. elegans motility & GFP observation. Modules reflect illustrative teaching utility and do not claim that generic icons represent exact course strains or equipment models.
Known gaps include species-specific illustrations for Eublaberus posticus, Malpighian tubule anatomy, spinach thylakoids/PSII, luminometer instruments, and gene-specific unc motility/GFP patterns. Generic leaves, membrane carriers, and microscopes are labeled explicitly as illustrative diagrams rather than unverified species replacements.
Source artwork: Bioicons and Wikimedia Commons. Per-asset author, license, and pinned commit source URLs are preserved in catalog.json; exports include complete attribution metadata. Vector SVGs are sanitized into static primitives with rewritten internal IDs for security and style isolation. Course lab manuals and student experimental data are not included.