MCP tool reference

List projects read-only

exotool_list_projects

List the Exotool projects owned by the logged-in user, each with its preview-install URL (where the compiled PWA can be opened).

No parameters.

Get preview address read-only

exotool_get_preview_url

Get the preview URL for a project — a SHAREABLE link to the live preview of its compiled PWA. Anyone given the URL can open the running app on a phone or browser (it is the per-user preview install; on production a dynamically started per-user Docker instance). It always serves the last compiled build, so re-run exotool_save to refresh it. Returns an absolute URL.

Create project modifies

exotool_create_project

Create a new Exotool project, seeded with a default diagram (a "Home" page plus one extra page). Returns the full diagram JSON so you can edit it and save it back. To start from a complete sample app instead, use exotool_copy_project. The result also gives the address that opens the new project in the editor: pass it on to the user.

Copy project modifies

exotool_copy_project

Copy an existing project into a NEW project. source may be one of your own projects OR a system sample (e.g. 'element_gallery') — the new project project is created as your own, seeded with the full contents (diagram + assets) of the source. The preferred way to start a new app; exotool_get_example lists the samples and what each shows. Fails if project already exists. The result gives the preview address and the address that opens the new project in the editor: pass both on to the user.

Load diagram read-only

exotool_get_diagram

Load a project's complete diagram. Returns an outline plus the full diagram JSON. To modify the app, edit this JSON and pass the ENTIRE edited tree to exotool_save. Diagram shape: root classname 'viewdiagram' -> elements.pool1 (viewpool) -> pages/popups/sequence_connectors. A page holds a navbar (with links/back_links), content blocks and arg_placeholders. Navigation = a 'link' wired by a 'sequence_connector' whose 'from' is the link's element-key and 'to' is the target page/popup key. If you have not read the diagram reference in this session, call exotool_docs("diagrams") before interpreting the result. The result gives the diagram's revision, to pass back with a save, a patch or an undo. With scope only a part is returned, which keeps a large diagram out of the conversation: an element key (that element and everything inside it, with the connectors that touch it), sheet:<n> (the elements of that sheet, 0 being the main one), or a list of these. Each part comes with its path, for exotool_patch_diagram. A scoped load is for reading and for patching; exotool_save always takes the whole diagram.

Get example diagram read-only

exotool_get_example

Worked examples: the diagrams of Exotool's system samples, which compile and run. Without name: the list of samples, each with its preview address, its number of screens and the element types it uses, so that you can pick the one that shows what you need. With name: that sample's complete diagram, in the shape exotool_get_diagram returns. Use it to see how an element type you have not authored before is written (its fields, its _params, where it sits, how it is wired) and copy that shape. A sample is read-only: to build on one, make your own copy with exotool_copy_project. Changes nothing.

Save and compile diagram modifies

exotool_save

Save AND compile a project's diagram (one step in Exotool). Pass the ENTIRE diagram tree as diagram (the full 'viewdiagram' object, exactly the shape returned by exotool_get_diagram, with your edits applied). Returns OK, the refreshed preview URL and the address that opens the project in the editor (pass both on to the user), or the per-element compiler errors if compilation fails. Saving replaces the user's live project and its preview. Pass the revision that exotool_get_diagram (or the create or copy that made the project) gave: it is required, and a save without it or with a stale one is refused. The design being replaced is backed up first, and the result gives the new revision and what changed. exotool_undo_diagram takes a save back. For a small change prefer exotool_patch_diagram, which sends only the change. Confirm with the user before saving to a project you did not create in this conversation. A diagram that fails to compile is saved all the same; correct it with a patch or another save, or undo. Preserve every field you loaded (keys, identifiers, geometry, _params, the root metadata) unless you mean to change it. Load exotool_docs("diagrams") before your first save and exotool_docs("language") before writing any activity code.

Undo last save modifies

exotool_undo_diagram

Put a project's design back to what it was before its last save: the diagram, the project's settings and its uploaded files, from the automatic backup that save made. Each undo goes one save further back; the newest four automatic backups of a project are kept, so at most four. The design as it stood before the undo is itself backed up first and can be had back from the editor's Backups list. Pass the revision that exotool_get_diagram gave; a stale one is refused and nothing is changed. The restored design is compiled, and the result gives its new revision and what changed. Use it when a save produced something the user did not want; say so to the user before calling it on a project you did not just save.

Check diagram read-only

exotool_validate_diagram

Check a diagram without saving anything: it is compiled for its errors, and nothing in the project changes - not the saved diagram, not the compiled app, not the preview. Pass diagram (the ENTIRE tree, as for exotool_save) to check what you are about to save, with project naming the project it is for; or pass project alone to check what is saved now. With scope (an element key, "sheet:<n>", or a list) only the errors in those parts are reported. It checks what the compiler checks: the activity code of every activity (syntax, built-ins, cloud-object fields), templates, and references the compiler follows. It does NOT check the containment rules or the layout, which the compiler does not enforce: a diagram that passes can still render nothing where an element sits in the wrong parent, so keep to exotool_docs("elements"). Each error comes with the element's key, its JSON Pointer path, the message and the source concerned. Counts against the hourly compile limit, as a save does. Use it before a large save; for a small change, exotool_patch_diagram reports the same errors when it saves.

Check activity code read-only

exotool_validate_activity

Check one piece of Exotool activity code without saving it. With project, the code is checked in that project's diagram, so its cloud objects, variables and subroutines are known; with element as well (the key of an activity of that diagram) it is checked in place of that activity's code. Without a project it is checked on its own, as in a new app. Returns the compiler's errors for this code only, and says how many errors the rest of the diagram has (a diagram that does not compile as it stands can hide errors here). Changes nothing; counts against the hourly compile limit. Call exotool_docs("language") before writing activity code, and use this tool on an activity you are unsure of before you place it in a diagram.

Get build errors read-only

exotool_get_build_errors

Compile a project's diagram as it is saved, saving and changing nothing, and return the compiler's errors: for each, the element's key, identifier and title, its JSON Pointer path, the message and the source code concerned. Correct them with exotool_patch_diagram at the path given. The errors of a save or a patch you have just made are already in its result; use this tool when you come to a project that may not compile as it stands. Counts against the hourly compile limit, as a save does.

Patch diagram modifies

exotool_patch_diagram

Change part of a project's diagram with JSON Patch operations (RFC 6902: add, remove, replace, move, copy, test), then save and compile, in one step. Use it for a small change in place of sending the whole diagram to exotool_save. ops is the list of operations; each path is a JSON Pointer. Without scope a path starts at the root of the diagram ("/elements/pool1/elements/<key>/title"). With scope, one element key, a path is relative to that element ("/title" is its title). A path that begins with "/pool" is relative to the app's pool whatever the scope, so any screen or connector is "/pool/elements/<key>/...". The operations are applied all or nothing: if one fails, the result names it and nothing is saved. Pass the revision exotool_get_diagram gave; a stale one is refused. The result gives the new revision and what changed. A patch that compiles with errors is saved all the same, as a save is.

List presets read-only

exotool_list_presets

List the presets available to a project. A preset is a named bundle of parameter values for an element class; an element's presets field selects one by id. Presets are organized as view_class -> control_key -> preset_id -> {title, values, level}. Pass view_class to get that class's presets with their full values (needed to copy one); omit it for an outline of all.

Create, change or delete preset modifies

exotool_store_preset

Create, overwrite, or delete a preset. operation: 'create' (new — the server generates the id, returned to you), 'store' (overwrite an existing preset_id), or 'delete' (remove preset_id). To COPY a preset into a new user preset: read its values via exotool_list_presets, then call create with where='user' and those values. where='system' edits the shared system presets and requires an admin login.

List resources read-only

exotool_list_resources

List the logged-in user's resources — reusable external-service accounts (FTP web server, MySQL database, SMTP email, PayPal e-commerce, …) shared across projects. Returns, for each resource, its guid, its category and sub_category, its name and its description when it has one; secrets are never returned. Resources are created and maintained only in the editor (call exotool_get_editor_url for the address and ask the user to add the resource on the editor's Resources page, then list again). Use a guid from this list with exotool_set_project_resources.

No parameters.

Set project resources modifies

exotool_set_project_resources

Point a project's resource roles at resources, then save+compile so it takes effect. Roles: database accepts 'heap' (the default Single File store), 'files' (the Multiple Files / file-per-object store) or the guid of one of your Database resources (MySQL); email_server, ecommerce_server and web_server accept 'none' or the guid of one of your E-mail Server, E-Commerce Server or Web Server resources respectively. Pass only the roles you want to change: a role you omit is left unchanged; a role passed with an empty value is an error. Every value is checked before anything is saved (the guid must be one of yours, from exotool_list_resources, and of the right category); if any value is invalid the whole call is rejected and nothing is saved or compiled. Only your own projects.

Get editor or upload link modifies

exotool_get_editor_url

Return an address of Exotool's to pass to the user: the editor, one project in the editor, or the UPLOAD PAGE for one file. Without arguments: the editor's address. Some things are done only in the editor, by design: creating or changing a resource (a database, mail, payment or web-server account, because it holds a secret that must not pass through this conversation), and deleting a project. Give the address, say where to go once inside (for example the Resources page), and continue when the user says it is done. With project (one of the user's own): the address opens that project's diagram once the user is logged in; give it when you want the user to look at, or change, the app you built. These two addresses carry no authentication. With open: "upload", project and upload: a link to the upload page, for a file too large for you to send (a photograph, a video, a document, an attachment). upload.slot is where the file goes: "app_icon", "app_background", "image", "file" or "library_file"; the last three need upload.name, the name to store it under, without extension (the same name you would give the matching exotool_upload_* tool, and the name the diagram refers to). The link lets whoever opens it upload ONE file into that one place and do nothing else; it works once, must be opened within two minutes, and the file must be sent within five minutes of opening. Before calling, tell the user what the link opens and ask; then give the link at once, exactly as returned, and ask them to say when the upload is done. The result gives a handoff id. With handoff: the state of that upload (waiting, opened, done, expired) and what was stored; no link is made. Call it when the user says they are done, before you use the file.

Upload app icon modifies

exotool_upload_app_icon

Calls the Exotool asset upload API to set the project's app icon (docs: https://www.exotool.com/help/mcp/#uploads). Send the file as data_base64 (small files only: you write base64 out at about 20 seconds for each kilobyte), or by url, a direct or pre-signed download link that Exotool downloads itself (up to 8 MB; a share page that opens in a browser is refused; the server instructions say when to ask the user about content rights first). A large file (a photograph, a video, a document, an attachment) is not sent by you: the user uploads it on Exotool's upload page, by a link from exotool_get_editor_url (see the server instructions). Exotool converts the image into every icon size the installed PWA (Add to Home Screen on iOS/Android), the desktop browser tab, and the iOS native-app build need, replacing any existing icon, so a small source is usually fine: Exotool makes every size from it. An icon that you DRAW goes as SVG text in svg (the SVG rules are in the server instructions); an SVG icon keeps its transparency, and one that is not square is centred on a transparent square, not stretched. Allowed types: svg, jpg, jpeg, gif, png. Only your own projects can be targeted.

Upload app background modifies

exotool_upload_app_background

Calls the Exotool asset upload API to set the project's background image (docs: https://www.exotool.com/help/mcp/#uploads). Send the file as data_base64 (small files only: you write base64 out at about 20 seconds for each kilobyte), or by url, a direct or pre-signed download link that Exotool downloads itself (up to 8 MB; a share page that opens in a browser is refused; the server instructions say when to ask the user about content rights first). A large file (a photograph, a video, a document, an attachment) is not sent by you: the user uploads it on Exotool's upload page, by a link from exotool_get_editor_url (see the server instructions). Exotool converts it into the project's background asset, replacing any existing one. An image that you DRAW goes as SVG text in svg (the SVG rules are in the server instructions). Allowed types: svg, jpg, jpeg, gif, png. Only your own projects.

Upload image modifies

exotool_upload_image

Calls the Exotool asset upload API to add an image asset to the project under a chosen name (docs: https://www.exotool.com/help/mcp/#uploads); Exotool generates sized versions (128/340/1024). Send the file as data_base64 (small files only: you write base64 out at about 20 seconds for each kilobyte), or by url, a direct or pre-signed download link that Exotool downloads itself (up to 8 MB; a share page that opens in a browser is refused; the server instructions say when to ask the user about content rights first). A large file (a photograph, a video, a document, an attachment) is not sent by you: the user uploads it on Exotool's upload page, by a link from exotool_get_editor_url (see the server instructions). With urls (a list of addresses, for instance one for each page of a Canva design) the files are stored as <name>_1, <name>_2, ... in the order given; an address that fails is reported by itself. Give a name (no extension; letters/digits/underscores, starts with a letter, min 4 chars). The sized versions are stored as JPEG, so transparency is lost: a PNG that must stay transparent is uploaded with exotool_upload_file instead, which stores a file as it arrives. An image that you DRAW goes as SVG text in svg (the SVG rules are in the server instructions); an SVG sent here is turned into those JPEG sizes too, so to keep it as an SVG use exotool_upload_file. Allowed types: svg, jpg, jpeg, gif, png. Only your own projects.

Upload file modifies

exotool_upload_file

Calls the Exotool asset upload API to add a file to the project under a chosen name (docs: https://www.exotool.com/help/mcp/#uploads), stored as "<name>.<ext>" (extension taken from fname). Send the file as data_base64 (small files only: you write base64 out at about 20 seconds for each kilobyte), or by url, a direct or pre-signed download link that Exotool downloads itself (up to 8 MB; a share page that opens in a browser is refused; the server instructions say when to ask the user about content rights first). A large file (a photograph, a video, a document, an attachment) is not sent by you: the user uploads it on Exotool's upload page, by a link from exotool_get_editor_url (see the server instructions). With urls (a list of addresses, for instance one for each page of a Canva design) the files are stored as <name>_1, <name>_2, ... in the order given; an address that fails is reported by itself. With data_base64 also pass fname so the type is known. Give a name (no extension; letters/digits/underscores, starts with a letter, min 4 chars). Allowed types: jpg jpeg gif png txt pdf xml mp4 mp3 wav svg tiff doc xls csv xlsx css html js glb. The file is stored as it arrives, with no conversion: use this tool for a PNG that must keep its transparency, and for an SVG that is to stay an SVG. Only your own projects.

Upload library file modifies

exotool_upload_library_file

Calls the Exotool asset upload API to add a backend library source file (PHP or JS) for a lib element (docs: https://www.exotool.com/help/mcp/#uploads), stored under a chosen name (no extension). Send the file as data_base64 (small files only: you write base64 out at about 20 seconds for each kilobyte). A large file (a photograph, a video, a document, an attachment) is not sent by you: the user uploads it on Exotool's upload page, by a link from exotool_get_editor_url (see the server instructions). With data_base64 also pass fname (.php/.js). Give a name (letters/digits/underscores, starts with a letter, min 4 chars). Allowed types: php, js. Only your own projects.

Get reference document read-only

exotool_docs

Return one of the Exotool reference documents as Markdown. topic is one of overview (what Exotool is), editor (screens, sheets, placeholders, connectors, symlinks, as the user sees them), language (the activity language), templates (HTML templates and parameters), diagrams (the JSON diagram that exotool_get_diagram returns and exotool_save takes: shape, workflow, containment, sheets, layout), elements (the catalogue of element types and their fields). Each is 12–25 kB except elements, which is about 55 kB; load only the one the current step needs. Load diagrams before your first load or save of a diagram in a session, and language before writing any activity code.