storytold Crafting Apps

The storytold Crafting Apps are free, open-source, clean-room creative tools written in Rust (SolidCraft comes from Tangency Labs and installs the same way). Every release ships a desktop app <app> and an automation CLI <app>-cli. <app>-cli mcp is a stdio MCP server that can drive every menu item, tool, panel and export.

When to Use

• The user asks to install, update or set up any storytold / Crafting App (by name or "the craft apps").
• The user wants to create or edit vector art, photos, video, audio, documents, spreadsheets, slides, PDFs, CAD drawings, 3D parts, materials and textures or UI designs, and a Crafting App is the tool for it.
• A <app>-cli command is "not found", or a storytold MCP server fails to start.

Quick Reference

All of the setup goes through one stdlib-only helper (Python 3.9+, no packages):

python ${HERMES_SKILL_DIR}/scripts/storytold_tools.py status              # installed vs latest, PATH state
python ${HERMES_SKILL_DIR}/scripts/storytold_tools.py install [APP ...]   # download + checksum + link + PATH
python ${HERMES_SKILL_DIR}/scripts/storytold_tools.py path                # only add the bin dir to PATH
python ${HERMES_SKILL_DIR}/scripts/storytold_tools.py verify  [APP ...]   # MCP handshake per CLI
python ${HERMES_SKILL_DIR}/scripts/storytold_tools.py register [APP ...]  # hermes mcp add <app>
python ${HERMES_SKILL_DIR}/scripts/storytold_tools.py setup   [APP ...]   # install + verify + register

Leave APP out to act on all seventeen apps. Every command prints one JSON object per line.

To change the locations, set STORYTOLD_HOME (install root) and STORYTOLD_BIN (bin dir). Set GITHUB_TOKEN if the GitHub API rate limit (60 requests an hour without a token) gets in the way.

Procedure

1. Check first. Run status. An app counts as present when its <app>-cli is on PATH, whether this skill installed it or an MSI, .deb or Flatpak did. Don't reinstall an app that's already there unless the user asks, or latest is newer than installed.
2. Install. Run install with the apps the user wants. Leave APP out to install all seventeen, about 1.6 GB of downloads. For each app it finds the latest GitHub release, downloads the asset for this OS and CPU, checks it against the release's SHA256SUMS.txt, unpacks it and links <app> and <app>-cli into the bin dir. Then it adds the bin dir to the persistent PATH unless it's already there. Running it again does no harm: an up-to-date app is skipped, and a PATH entry that's already there isn't added twice.
3. Verify the MCP servers. Run verify. For each CLI it starts the MCP server with the same arguments Hermes will use (below), and sends initialize, notifications/initialized and tools/list. It reports the server name and version, the protocol, the number of tools and the args. The exit code is 0 only when every server answers with at least one tool.

4. Register with Hermes (if the user wants the tools in Hermes). Run register. It runs hermes mcp add <app> --command <abs path to bin>/<app>-cli --args <mcp args> and enables all tools. Hermes probes the server before saving, so this is a second end-to-end check. Then tell the user to start a new session or run /reload-mcp. hermes mcp test <app> re-checks a single server later. An entry registered before these args existed is left alone: update it with register <app> --replace.

   App	MCP args	Why
   most apps	mcp	headless in-process engine
   pdfcraft	mcp --compact	17 tools instead of 184 (about 3.5k tokens of schemas instead of 48k). The rest run through tool_call
   vectorcraft	mcp --headless	bare mcp attaches to anything on port 7979, even another Crafting App
   photocraft	mcp --automation-read-root <HOME> --automation-write-root <HOME>	without roots it can't open or save files. Paths are relative to HOME. Override HOME with STORYTOLD_PHOTOCRAFT_ROOT
   materialcraft	mcp --read-root <HOME> --write-root <HOME>	without roots it can't open, save or export files. Paths are relative to HOME. Override HOME with STORYTOLD_MATERIALCRAFT_ROOT
   texturecraft	mcp --read-root <HOME> --write-root <HOME>	the same as MaterialCraft. Override HOME with STORYTOLD_TEXTURECRAFT_ROOT
   solidcraft	mcp --allow-path <HOME> --param-check strict	without an allowed folder it can't save or export outside its own folders. Strict checks make a misspelt key an error instead of wrong geometry. Override HOME with STORYTOLD_SOLIDCRAFT_ROOT
   craft-anything	mcp	Clean room, 29 tools. Its website tools also need --allow-run, which approves everything that runs code or changes a device: add it only after the user agrees (register craft-anything --replace won't add it; use hermes mcp add by hand). Never run Craft Anything's own setup --client hermes: it installs a second skill named craft-anything
   lightcraft	mcp --library <install root>/lightcraft-library	without a library the catalog lives in memory only. Override with STORYTOLD_LIGHTCRAFT_LIBRARY

5. Report. List the installed versions, PATH changes, MCP results and anything that failed, with its error.

Using the apps

• App skills. Each app has its own skill (vectorcraft, photocraft, …), and the storytold skill picks the right app for a task. Load the app's skill before you work in it.
• MCP modes. Bare <app>-cli mcp starts every app and runs an in-process engine (bare VectorCraft mcp first tries a desktop app on 127.0.0.1:7979, so it's registered with --headless). To watch a live desktop app instead, start it with <app> --control <port> and pass the app's own flag. The flags differ from app to app: --connect (vectorcraft, designcraft, wordcraft, gridcraft, deckcraft, soundcraft, cadcraft), --bridge (photocraft, effectcraft, filmcraft) or --attach (figcraft). Check <app>-cli help for the exact form before relying on it.
• Without MCP. Most CLIs have run (headless batch of commands plus exports), convert IN OUT, info FILE, commands (the command catalog as JSON) and bench. <app>-cli --help lists them for each app.
• Each repository's docs/mcp.md and docs/control-protocol.md document the tools, resources and prompts, e.g. https://github.com/storytold/vectorcraft/blob/main/docs/mcp.md.

Pitfalls

• PATH changes don't reach running processes. New terminals see the updated PATH. Hermes and its terminal tool keep the PATH they started with, so call the CLI by its absolute path (as status and verify print it) until Hermes restarts. MCP registration always stores the absolute path.
• Updating while a server runs (Windows). Windows can't delete an exe that's running. install renames the busy link to <name>.old-<timestamp> and puts the new one in place. Restart the MCP server, or Hermes, to pick up the new version.
• Microsoft Store Python (Windows) redirects everything written under %LOCALAPPDATA% into its own package folder, where no other program sees it. The helper detects this and re-runs itself with the first regular python.exe on PATH, or refuses to run if there isn't one. Prefer Hermes' own Python.
• macOS releases have only the CLI as a zip. The desktop app is a .dmg, so point the user to https://github.com/storytold/<app>/releases/latest to install the GUI.
• MSI installs aren't on PATH (Windows). The .msi puts <app>.exe and <app>-cli.exe in C:\Program Files\<App>\ and doesn't add that folder to PATH. If this skill's bin dir also has the app, the bin copy wins on PATH and in every MCP registration, even when the MSI is newer. status reports the bin copy. Run install <app> to bring the bin copy up to date. Running --version on both copies shows which is newer.
• Name clash. register won't overwrite an existing Hermes MCP entry with the same name. Pass --replace to update it.
• Stdout is protocol-only. The servers log to stderr. When verify fails it includes stderr_tail, so read that before retrying.

Verification

python ${HERMES_SKILL_DIR}/scripts/storytold_tools.py verify --json   # every app: "ok": true
<app>-cli --version                                                  # from a NEW shell: PATH works
hermes mcp list                                                       # registered servers show as enabled
hermes mcp test vectorcraft                                           # Hermes-side handshake