@machinal/mcp 0.4.3 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +59 -22
- package/package.json +3 -2
- package/skills/machinal-choreography/SKILL.md +42 -0
- package/skills/machinal-motion/SKILL.md +29 -0
- package/skills/machinal-motion/references/catalog.json +7 -0
- package/skills/machinal-motion/references/index.md +17 -0
- package/skills/machinal-recipes/SKILL.md +1 -1
- package/skills/machinal-recipes/references/yaml.md +2 -0
- package/skills/machinal-review/SKILL.md +1 -1
- package/skills/machinal-review/references/production.md +3 -1
- package/skills/machinal-scenes/SKILL.md +2 -0
- package/skills/machinal-scenes/references/authoring.md +4 -2
- package/skills/machinal-scenes/references/scene-templates/comparison-wipe.svelte +40 -0
- package/skills/machinal-scenes/references/scene-templates/piston-cycle.svelte +50 -0
- package/skills/machinal-scenes/references/scene-templates/route-journey.svelte +41 -0
- package/skills/machinal-scenes/references/scene-templates.json +32 -0
- package/skills/machinal-scenes/references/scene-templates.md +4 -0
- package/skills/machinal-sound/SKILL.md +26 -0
- package/skills/machinal-spatial/SKILL.md +25 -0
- package/skills/machinal-support/SKILL.md +6 -2
- package/skills/machinal-visual-review/SKILL.md +27 -0
- package/src/bridge.mjs +7 -2
- package/src/cli.mjs +49 -18
- package/src/commands.mjs +89 -0
- package/src/configuration.mjs +15 -5
- package/src/credential-store.mjs +22 -0
- package/src/formats.mjs +6 -1
- package/src/keys.mjs +27 -20
- package/src/local-setup.mjs +13 -4
- package/src/opencode-auth.mjs +36 -14
- package/src/opencode-configuration.mjs +83 -20
- package/src/opencode-media.mjs +5 -3
- package/src/opencode-upgrade.mjs +40 -0
- package/src/opencode-workflow.mjs +10 -9
- package/src/paths.mjs +8 -0
- package/src/presentation.mjs +1 -1
- package/src/private-json.mjs +86 -0
- package/src/prompts.mjs +3 -5
- package/src/reference-files.json +11 -1
- package/src/runtime.mjs +11 -5
- package/src/settings.mjs +26 -0
- package/src/setup-stdio.mjs +27 -9
package/README.md
CHANGED
|
@@ -4,31 +4,60 @@ Set up **Codex, Claude Code or OpenCode V2** with a resilient stdio adapter. Cho
|
|
|
4
4
|
|
|
5
5
|
See the repository's [testing guide](../../docs/TESTING.md) for source-package and pre-publish checks.
|
|
6
6
|
|
|
7
|
+
### Version 0.5.0: animation crafts and sound library
|
|
8
|
+
|
|
9
|
+
Version 0.5.0 bundles five additional on-demand skills: `machinal-motion`, `machinal-choreography`, `machinal-spatial`, `machinal-visual-review` and `machinal-sound`. Their source of truth is the API's `reference/animation-skills`; `npm run sync:reference` synchronizes identical native skills for all supported clients. Updated APIs expose the same content through `get_editing_reference(topic: animation-skills)` and MCP resources. Startup still loads editing/cinema only, not every craft.
|
|
10
|
+
|
|
11
|
+
API MCP **1.10.0** adds phase-based `plan_scene_review`, provisional review plans on synchronous compilation, three native templates, and approved Openverse/Freesound sound search/import with persisted licence attribution. See [the API workflow and activation boundaries](../../docs/MCP.md#animation-crafts-phase-based-review-and-licensed-sound-effects-mcp-1100). Source changes do not publish npm or deploy the API; use the checkout's setup command for source installations and normal customized-skill replacement approval. No unrequested sound, media download, provider generation or paid preview is authorized by installing a skill.
|
|
12
|
+
|
|
7
13
|
## Quick start
|
|
8
14
|
|
|
9
15
|
Requires **Node.js 22.13+ (22.x) or 24+** and an installed agent client. **Machinal Server** needs only a Machinal key with account/API access: its official endpoint is selected automatically, with no address question and no Docker/provider key on the client. **Custom server** is the advanced option for your own API URL. Independent local needs Docker/Compose v2, this version's source checkout, and your OpenRouter key/model settings: **no Machinal account, subscription, credits or PocketBase**. The npm package does not bundle the Go backend or guess an unpublished container image.
|
|
10
16
|
|
|
11
|
-
**Server: one Machinal key. Local: your OpenRouter key.** Hidden entry and opt-in Windows Credential Manager
|
|
17
|
+
**Server: one Machinal key. Local: your OpenRouter key.** Hidden entry and opt-in persistent storage are supported: Windows Credential Manager on Windows; a private plaintext credentials file on Linux. All three stdio adapters read the saved key without a launcher. macOS retains environment/hidden-entry behavior. No key belongs in chat or command arguments.
|
|
18
|
+
|
|
19
|
+
### Short commands (0.4.4)
|
|
20
|
+
|
|
21
|
+
Install version 0.4.4 or later for these commands. From a source checkout, use `node packages/mcp-installer/bin/machinal-mcp.mjs <command>`:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
npx @machinal/mcp set-key # Hidden entry, verify, then confirm saving
|
|
25
|
+
npx @machinal/mcp getcredit # Live balance; no spending
|
|
26
|
+
npx @machinal/mcp place # Processing, source folder and download locations
|
|
27
|
+
npx @machinal/mcp place --uploads /home/me/Media --downloads /home/me/Videos
|
|
28
|
+
npx @machinal/mcp local status
|
|
29
|
+
npx @machinal/mcp local install --docker-dir /path/to/machinal
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`npm install -g @machinal/mcp` also provides `machinal set-key`, `machinal getcredit`, `machinal place`, `machinal local status` and `machinal local install`. The existing `machinal-mcp` binary and `key set` / `key delete` remain compatible. `npx machinal` would resolve a different npm package; use `npx @machinal/mcp` (or `npx --package @machinal/mcp machinal`) instead.
|
|
33
|
+
|
|
34
|
+
Linux saves a key only after explicit approval to `$XDG_CONFIG_HOME/machinal/credentials.json`, or `~/.config/machinal/credentials.json`. Directory mode is `0700`, file mode `0600`; the file is **not encrypted** and other processes running as that user can read it. Saves are atomic, do not create secret backups, and never fall back to a project file. Incorrect ownership, exposed permissions, symlinks, corrupt data or an unreadable file produce a sanitized diagnostic, not a missing-key assumption. The CLI, stable adapter and Linux OpenCode companion use the same location. `MACHINAL_API_KEY` (then legacy `DIRECTION_API_KEY`) takes precedence on Linux; remove a stale environment override to use the saved replacement.
|
|
35
|
+
|
|
36
|
+
`set-key` uses the last configured hosted endpoint (or the official service for a new setup) and verifies before saving. `key set` without `--url` retains its legacy format-only behavior. Linux OpenCode's `replace` directs the **user** to hidden terminal entry; it never requests a key through chat or launches Windows UI. Changes are picked up automatically or with `machinal_connection reconnect`.
|
|
37
|
+
|
|
38
|
+
`place` stores only host-side folder preferences in `machinal/config.json`, separately from credentials. Uploads still go to the named project's volume; the source folder is a suggestion, not automatic browsing or transfer permission. Native OpenCode project downloads prefer an explicit destination, then this host's saved folder, then the API's saved preference. Internet downloads still require an explicit destination. Setting a folder transfers nothing and does not change the server's preferences.
|
|
39
|
+
|
|
40
|
+
Local mode detects a saved profile and reuses a running backend. With permission it builds missing Docker images from a detected checkout, or starts installed images without rebuilding. `--yes` alone does not authorize Docker startup; use `--start-docker` for unattended installation. Docker/Compose and a source checkout are prerequisites: no Engine installation with administrator privileges, guessed public image or private source publication is performed. Choosing Server never inspects or installs Docker.
|
|
12
41
|
|
|
13
42
|
**Migration compatibility:** existing `dal_…` keys, `DIRECTION_API_KEY` / `DIRECTION_API_ORIGIN` environment variables, and the previous Windows Credential Manager entry continue to work. New setups use `mach_…`, `MACHINAL_API_KEY` / `MACHINAL_API_ORIGIN`, and `Machinal/mcp.MACHINAL_API_KEY`; when both environment names are set, `MACHINAL_API_KEY` takes precedence. New keys are issued with the `mach_` prefix.
|
|
14
43
|
|
|
15
|
-
**Version 0.
|
|
44
|
+
**Version 0.5.0:** after registry publication, use the pinned commands below to install this release from the `@machinal` scope:
|
|
16
45
|
|
|
17
|
-
This release adds native approved client-file uploads and language-independent video preparation. `machinal_prepare_video` loads
|
|
46
|
+
This release adds focused animation/sound skills and richer scene review guidance/templates, retaining native approved client-file uploads and language-independent video preparation. `machinal_prepare_video` loads editing/cinema startup skills; other crafts stay on demand, and scene compilation/final rendering are guarded until startup context is loaded. No keyword classifier, extra model call or automatic spending is introduced.
|
|
18
47
|
|
|
19
48
|
OpenCode compatibility: production startup accepts the V2 skill-list response (`{ location, data }`) and legacy arrays. If optional skill discovery fails or changes shape, it emits a sanitized warning instead of preventing session setup. Regression tests cover both response shapes and discovery failures; the release gate tests the packed artifact as well.
|
|
20
49
|
|
|
21
50
|
```sh
|
|
22
51
|
npx @machinal/mcp setup
|
|
23
52
|
# Machinal Server: no URL entry, only your Machinal key:
|
|
24
|
-
npx --yes @machinal/mcp@0.
|
|
25
|
-
npx --yes @machinal/mcp@0.
|
|
26
|
-
npx --yes @machinal/mcp@0.
|
|
53
|
+
npx --yes @machinal/mcp@0.5.0 setup --client opencode --mode server
|
|
54
|
+
npx --yes @machinal/mcp@0.5.0 setup --client codex --mode server
|
|
55
|
+
npx --yes @machinal/mcp@0.5.0 setup --client claude --scope global --mode server
|
|
27
56
|
# Independent local; the wizard asks for OpenRouter and model IDs:
|
|
28
|
-
npx --yes @machinal/mcp@0.
|
|
29
|
-
npx --yes @machinal/mcp@0.
|
|
57
|
+
npx --yes @machinal/mcp@0.5.0 setup --client codex --mode local --docker-dir /path/to/machinal
|
|
58
|
+
npx --yes @machinal/mcp@0.5.0 setup --client claude --mode local --docker-dir /path/to/machinal
|
|
30
59
|
# Your own deployment, explicitly selected:
|
|
31
|
-
npx --yes @machinal/mcp@0.
|
|
60
|
+
npx --yes @machinal/mcp@0.5.0 setup --client opencode --mode custom --url https://YOUR-API/mcp
|
|
32
61
|
```
|
|
33
62
|
|
|
34
63
|
The wizard asks for:
|
|
@@ -38,7 +67,7 @@ The wizard asks for:
|
|
|
38
67
|
3. **Machinal Server**, **Local**, or **Custom server (advanced)**. Machinal Server automatically uses `https://api.machinal.app/mcp` and never asks for an address or starts Docker. Local builds an independent backend with loopback host publishing and separate volumes; its default is `http://127.0.0.1:8080/mcp`. Custom server asks for your own API URL, **not the frontend URL**, without offering localhost as a guessed hosted default.
|
|
39
68
|
4. Whether to install bundled editing, YAML recipe, scene and credit-awareness skills, and a default editing style.
|
|
40
69
|
5. **Machinal Server:** hidden Machinal key, reuse environment/saved key, or login later (`--defer-login`). Create keys at <https://machinal.app/api-keys>; custom deployments use their own account website. **Local:** hidden `OPENROUTER_API_KEY`, required `OPENROUTER_MODEL`, optional scene/transcription model IDs, source checkout and explicit Docker approval. A device token is generated automatically; no local Machinal key is requested.
|
|
41
|
-
6.
|
|
70
|
+
6. Server mode on Windows/Linux: optionally remember a verified key in the platform's storage (default: no; Linux explicitly identifies plaintext storage).
|
|
42
71
|
7. Optional client launch. `--no-launch` works even when login is deferred.
|
|
43
72
|
|
|
44
73
|
Setup preserves unrelated settings, backs up changed files and installs optional skills. Missing login/offline Server still permits adapter installation, with an explicit **unverified** service status. Verification uses initialization, tool discovery and read-only billing mode, never generation, rendering, provider calls or credit purchases. An API probe is never reported as a running client connection.
|
|
@@ -67,8 +96,8 @@ The following bullets describe **advanced direct-HTTP compatibility** (`--transp
|
|
|
67
96
|
- It checks Docker/Compose, refuses remote Docker contexts, requires an existing `api/.env`, and inspects containers/images. With approval, it reuses existing images or builds missing ones, then runs the checkout's `api` and `scene-renderer` services with readiness waiting. Build/start may download base images, use disk/CPU, create persistent volumes and expose port 8080 according to the checkout's Compose configuration. Readiness is not proof of API authentication or provider credit.
|
|
68
97
|
- **`--yes` alone never authorizes build/start.** Interactive confirmation defaults to no; unattended use needs explicit `--start-docker`. No Docker Engine installation, context switching, secret creation, volume deletion, or registry publication happens automatically. A missing Docker executable links to <https://docs.docker.com/get-started/get-docker/>. Nonstandard local ports require a deployment started by the user.
|
|
69
98
|
- Container/build output is not dumped into the terminal because it may include secrets. Failures suggest checks for the daemon, context, ports, disk and network. Services keep running after setup, even if later MCP verification fails; manage them from the reported checkout. No destructive automatic rollback is performed.
|
|
70
|
-
- The terminal interface follows your terminal's background and text
|
|
71
|
-
-
|
|
99
|
+
- The terminal interface follows your terminal's background and neutral text color (white on a dark terminal), with purple headings, prompt marks and selected options. Amber/red mark warning/error labels, not paragraphs. Menus show at most five choices and collapse to one answer. Completed key prompts show `[hidden]`, not the key or its length; visibility toggling is disabled. `NO_COLOR` (including an empty value), `TERM=dumb` and piped output disable theme colors.
|
|
100
|
+
- Default stdio setup finishes with a compact verification/configuration/credit summary, including unattended output. Use `setup --verbose` for full credit breakdowns and diagnostics; `--help --verbose` shows all flags. Important compatibility, billing, low-balance and backup warnings remain visible. Advanced direct-HTTP compatibility retains its detailed unattended report. Backup details remain grouped into **one summary**, rather than a line per skill.
|
|
72
101
|
|
|
73
102
|
From this repository (no npm publication required):
|
|
74
103
|
|
|
@@ -87,7 +116,7 @@ node packages/mcp-installer/bin/machinal-mcp.mjs setup --client opencode --mode
|
|
|
87
116
|
|
|
88
117
|
This section describes Server mode. Independent local returns `mode:local` / `machinalCreditsRequired:false`, not a wallet: there are no hosted credit thresholds or render tariffs to check. Direct provider charges still need user permission.
|
|
89
118
|
|
|
90
|
-
Setup calls only MCP initialization, tool discovery and the read-only `get_credits` tool. It shows a concise balance and billing notice; `--verbose`
|
|
119
|
+
Setup calls only MCP initialization, tool discovery and the read-only `get_credits` tool. It shows a concise balance and billing notice; `--verbose` also shows the breakdown, next reset and configured pricing. Credits are charged after actual usage, not reserved for current work. Pending provider costs are informational, not a wallet lock. A brief low-balance warning appears below 30 credits; estimates are approximate. No wallet values are stored in skill files or configuration.
|
|
91
120
|
|
|
92
121
|
Older APIs without `get_credits`, unavailable ledgers and malformed balances produce a clear “unavailable” warning, not a fabricated zero. Authentication loss aborts setup. An unavailable wallet does not prevent free recipe preparation, but the agent is instructed to verify credits before submitting paid work. AI charges are not known exactly in advance, and a shared wallet delta is not an exact per-job charge.
|
|
93
122
|
|
|
@@ -126,17 +155,23 @@ Use the current local source with `node packages/mcp-installer/bin/machinal-mcp.
|
|
|
126
155
|
|
|
127
156
|
The API now exposes `get_workflow_preferences` and approved `set_workflow_preferences`. They persist per application key: `style`, `sceneMode` (`auto`, `2d`, `3d`), `imagePolicy` (`auto`, `prefer-images`, `procedural-only`) and `captionMaxWords` (default 4). Omitted fields are preserved. Current briefs override defaults; preferences never grant media access or spending permission. Three.js/font/image contracts are available through `get_editing_reference(topic: scene-runtime)` and the bundled scene runtime reference.
|
|
128
157
|
|
|
129
|
-
Connection settings remain separate: rerun setup with `--mode server|local` and the correct `--url`. Server keys come from environment,
|
|
158
|
+
Connection settings remain separate: rerun setup with `--mode server|local` and the correct `--url`. Server keys come from environment, platform storage or hidden entry; independent local uses its own provider profile/device token. Neither connection proves upstream provider credit. Rebuild/reconnect for new API tools.
|
|
130
159
|
|
|
131
160
|
### Later sessions
|
|
132
161
|
|
|
133
|
-
For OpenCode on Windows, **start OpenCode normally**. The integration reads the same saved machinal key automatically and supplies it only to the exact MCP name/endpoint approved during setup. Project overrides cannot silently redirect that saved key to another API origin. Configuration contains the plugin registration and trusted endpoint, never the key. Source checkouts reference the local plugin directory; published npm installations register the matching pinned package version rather than an expendable `npx` cache path.
|
|
162
|
+
For OpenCode on Windows or Linux, **start OpenCode normally**. The integration reads the same saved machinal key automatically and supplies it only to the exact MCP name/endpoint approved during setup. Project overrides cannot silently redirect that saved key to another API origin. Configuration contains the plugin registration and trusted endpoint, never the key. Source checkouts reference the local plugin directory; published npm installations register the matching pinned package version rather than an expendable `npx` cache path.
|
|
163
|
+
|
|
164
|
+
### Synchronized OpenCode upgrades (0.4.4)
|
|
165
|
+
|
|
166
|
+
Rerunning stdio setup from an updated package synchronizes its companion version and managed runtime in existing applicable global, ancestor and project configs, including `.opencode` configs. It does not recursively scan other projects. Matching local-development/npm duplicate entries are consolidated, while unrelated plugins, endpoints, routing options and server settings remain intact. Each changed file gets an exact backup; invalid configs, conflicting duplicate options and unapproved command overrides stop the upgrade with an actionable diagnostic. A version-only managed-runtime change does not require `--replace`; endpoint or other server changes still do.
|
|
167
|
+
|
|
168
|
+
When OpenCode loads an updated companion package, it also prepares that package's private runtime and substitutes it in memory **only after** matching the exact approved MCP command. This covers package-manager/plugin updates without a separate setup run; it does not change endpoints, write credentials, fetch another release or retry work. `machinal_connection status` includes the loaded package version, and a configuration mismatch is explicitly distinguished from a rejected API key. These changes require 0.4.4 or later.
|
|
134
169
|
|
|
135
170
|
The agent has a local **`machinal_connection`** tool even when the remote API is disconnected:
|
|
136
171
|
|
|
137
|
-
- **`status`** discovers approved MCP names/endpoints, actual connection states and credential diagnostics
|
|
172
|
+
- **`status`** discovers approved MCP names/endpoints, actual connection states and credential diagnostics: Linux reports the private file path; Windows reports target `Machinal/mcp.MACHINAL_API_KEY` (service `Machinal/mcp`, account `MACHINAL_API_KEY`), never the key. Missing, redirected or incompatible MCP configurations are reported separately; keys are not sent to them.
|
|
138
173
|
- **`reconnect`** reloads the one saved key, checks access and reconnects the existing MCP without restarting OpenCode. Transient failures retry; a network or subscription failure is not a reason to generate more keys.
|
|
139
|
-
- **`replace`** opens a native
|
|
174
|
+
- **`replace`** on Windows opens a native window with masked entry, a direct <https://machinal.app/api-keys> link, **Use saved key**, **Verify and connect**, and Cancel. Saving requires a separate unchecked-by-default consent checkbox. Verification precedes overwrite; cancellation/rejection preserves the saved key. Linux returns terminal instructions for `set-key` instead. Neither platform passes a key through chat, tool inputs, command arguments or logs; only Linux explicitly persists it to its private plaintext file.
|
|
140
175
|
|
|
141
176
|
Only one key is stored per Windows user and reused across the configured projects/clients. A replacement is read by running automatic integrations without a separate relaunch. The plugin uses the saved key before an incidental environment value; the optional legacy launcher marks its explicitly chosen environment key so `--session-key` and intentional per-session choices still work. Secure entry requires an interactive Windows desktop; it is not promised for a headless/remote service.
|
|
142
177
|
|
|
@@ -224,7 +259,7 @@ npx @machinal/mcp launch claude
|
|
|
224
259
|
npx @machinal/mcp launch codex
|
|
225
260
|
```
|
|
226
261
|
|
|
227
|
-
`launch` checks sources in order: `MACHINAL_API_KEY`, the saved
|
|
262
|
+
`launch` checks sources in order: `MACHINAL_API_KEY`, the platform's saved credential, then hidden entry. Interactive sessions ask whether to keep, replace, or create a key; unattended sessions retain automatic first-available selection. Keeping a saved key does not require typing it again. New keys can optionally be remembered on Windows/Linux. It launches the already installed client; it does not install that client or modify configuration. Optional client arguments follow `--`:
|
|
228
263
|
|
|
229
264
|
```sh
|
|
230
265
|
npx @machinal/mcp launch codex -- --help
|
|
@@ -234,7 +269,9 @@ OpenCode launches with **`--standalone`** so its private server inherits the key
|
|
|
234
269
|
|
|
235
270
|
The setup API probe alone never proves a running client connection. On Windows the installed integration lets the shared OpenCode service authenticate directly from the vault; inspect `machinal_connection(status)` or the MCP panel for the actual state. Without that integration, legacy environment-based setups still need a client/server started with the verified key.
|
|
236
271
|
|
|
237
|
-
|
|
272
|
+
<a id="save-replace-or-delete-a-key-on-windows"></a>
|
|
273
|
+
|
|
274
|
+
### Save, replace, or delete a key on Windows or Linux
|
|
238
275
|
|
|
239
276
|
```sh
|
|
240
277
|
npx @machinal/mcp key set
|
|
@@ -252,13 +289,13 @@ npx @machinal/mcp key delete --yes
|
|
|
252
289
|
- An existing **`MACHINAL_API_KEY` takes precedence**, including after replacement/deletion. Unset it if you want subsequent launcher sessions to use the saved credential.
|
|
253
290
|
- **`--session-key`** on `setup` or `launch` bypasses the vault entirely and suppresses the save offer. It still accepts `MACHINAL_API_KEY` or hidden entry. Without saving, the key is kept only for the current installer/client processes.
|
|
254
291
|
|
|
255
|
-
Credential Manager is accessed through the optional, pinned `@napi-rs/keyring` native binding
|
|
292
|
+
On Windows, Credential Manager is accessed through the optional, pinned `@napi-rs/keyring` native binding; there is no plaintext fallback. Linux deliberately uses the private file described above, without D-Bus/keyring dependencies. macOS retains environment/hidden-entry behavior. A failed optional save is reported; no alternate storage is silently used.
|
|
256
293
|
|
|
257
294
|
Windows protects stored credentials at rest, but this is **not isolation from applications running under the same Windows account**, an administrator, or a compromised client. Automatic OpenCode authentication holds the key in its server memory. Legacy launcher sessions also pass it in the child's environment. Normal OpenCode startup reads the vault through the installed integration, not through shell initialization.
|
|
258
295
|
|
|
259
296
|
### Key handling
|
|
260
297
|
|
|
261
|
-
- **Server application keys**
|
|
298
|
+
- **Server application keys** never enter client configuration, arguments or output. Opt-in persistence uses Windows Credential Manager or a private **plaintext** file on Linux. Independent local provider/device secrets use a separate private Docker profile, never client config or the npm tarball.
|
|
262
299
|
- Keys are kept in installer memory and passed in the launched child's environment. As with other environment-held secrets, the client and its subprocesses can access them. Use a dedicated, revocable key for each trusted client.
|
|
263
300
|
- `npx` cannot change its parent shell's environment. If you decline immediate launch, the key you typed does **not** become available to clients started elsewhere. If saved, `launch` reads it from Credential Manager next time; otherwise supply it again or use your own environment/secret manager.
|
|
264
301
|
- Do not pass a key through CLI arguments, paste it in chat, or put it in your shell history. There is deliberately no `--api-key` option.
|
|
@@ -356,7 +393,7 @@ Test the npm executable/tarball path without publishing:
|
|
|
356
393
|
```sh
|
|
357
394
|
npm pack --dry-run
|
|
358
395
|
npm pack
|
|
359
|
-
npx --yes --package ./machinal-mcp-0.
|
|
396
|
+
npx --yes --package ./machinal-mcp-0.5.0.tgz machinal-mcp --help
|
|
360
397
|
```
|
|
361
398
|
|
|
362
399
|
The publish allowlist includes only selected `bin/*.mjs`, runtime/plugin source, portable skills, package metadata and this README. Package smoke tests reject project configs, nested agent installs, `.env`, media and old archives. No tests, local preferences or credentials are packaged.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@machinal/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Resilient Machinal MCP setup for Codex, Claude Code and OpenCode: independent local or hosted server",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
"node": "^22.13.0 || >=24.0.0"
|
|
12
12
|
},
|
|
13
13
|
"bin": {
|
|
14
|
-
"machinal-mcp": "bin/machinal-mcp.mjs"
|
|
14
|
+
"machinal-mcp": "bin/machinal-mcp.mjs",
|
|
15
|
+
"machinal": "bin/machinal-mcp.mjs"
|
|
15
16
|
},
|
|
16
17
|
"files": [
|
|
17
18
|
"bin/*.mjs",
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: machinal-choreography
|
|
3
|
+
description: Implement deterministic Svelte motion with anticipation, staged action, restrained easing, secondary movement and readable holds; repair timing without changing captions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Choreography, not animation wallpaper
|
|
7
|
+
|
|
8
|
+
The current client writes and repairs complete source; do not invoke another model or a local production renderer.
|
|
9
|
+
|
|
10
|
+
Read the live `scene-runtime` contract. Drive every pose from `scene.frame.time` or progress with `$derived` in Svelte and `update(frame)` in SceneThree. Same frame must produce the same state after a backward seek. Never accumulate deltas, use wall clocks, random values, CSS keyframes, timers, external animation loops or unapproved animation libraries.
|
|
11
|
+
|
|
12
|
+
## Score the action
|
|
13
|
+
|
|
14
|
+
| Phase | Question | Implementation |
|
|
15
|
+
| --- | --- | --- |
|
|
16
|
+
| Reveal | What must be understood before the change? | Already-visible context, motivated mask or a brief entrance |
|
|
17
|
+
| Anticipation | What prepares the action? | Small purposeful opposing travel or a pause, only if it helps |
|
|
18
|
+
| Action | What object changes and why? | A causal path/state change, not entire-frame zoom |
|
|
19
|
+
| Settle | Where should attention land? | Decelerate to the intended alignment; restrained overshoot for soft things only |
|
|
20
|
+
| Hold | Can the viewer understand/read the result? | Keep the hero visible and stable for the required reading time |
|
|
21
|
+
| Exit/handoff | What continues into the next shot? | Shared edge, direction, object or an intentional cut |
|
|
22
|
+
|
|
23
|
+
Retain four production-contract phases (reveal/action/hold/exit); anticipation and settle are sub-beats, not invented tool fields. Use measured speech cues when available. Do not invent word timings; no narration means scene-local design timing, not fabricated cues.
|
|
24
|
+
|
|
25
|
+
Useful deterministic smoothstep for a bounded interval:
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
function phase(time, start, duration) {
|
|
29
|
+
const t = Math.min(1, Math.max(0, (time - start) / duration));
|
|
30
|
+
return t * t * (3 - 2 * t);
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Use positive duration, shared geometry for linked parts and separate envelopes for independent objects. Easing should express material: precise mechanical engagement does not bounce; a soft object may settle. Stagger by meaningful processing/depth order, not a default cascade on every scene. Secondary motion supports the main action and stops before reading. Avoid constant pulsing, spinning or flashing.
|
|
35
|
+
|
|
36
|
+
Use normalized staging only for unvoiced demos. For narrated sections map measured global cues to scene-local seconds, account for clip overlap and transition handles, and preserve the successful speech/caption baseline. A transition must not erase a scene's whole reveal or hold; avoid double-fades.
|
|
37
|
+
|
|
38
|
+
## Check
|
|
39
|
+
|
|
40
|
+
Plan samples at reveal, action midpoint, settled state and exit. Compare annotated object bounds/registered semantic state with actual pixels; neither alone proves visible causal motion. Sample a moving object at two distinct times. Validate backward-seek determinism with synthetic service tests. Only a genuinely played preview can verify fluidity/audio sync. One bounded revision, not an automatic paid review loop.
|
|
41
|
+
|
|
42
|
+
For incomplete new video intake use the native question tool, not a numbered chat questionnaire. A cancelled form is not consent; after actual authorization proceed immediately without a separate plan confirmation. Never alter existing captions or add unrequested media/audio. Free code compilation does not make server scene/final rendering free.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: machinal-motion
|
|
3
|
+
description: Design subject-specific animated scenes from short briefs; choose real assets, references, transformations, composition and shot handoffs before writing Svelte.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Motion direction
|
|
7
|
+
|
|
8
|
+
Use the existing machinal engine and current-client source authoring. Read `scene-runtime` and the exact selected template/style. No external runtime, server model or local production renderer.
|
|
9
|
+
|
|
10
|
+
## Commit to a visible idea
|
|
11
|
+
|
|
12
|
+
1. Write one sentence: **subject → action → changed understanding**. If changing the heading makes the same scene fit any topic, redesign it.
|
|
13
|
+
2. Separate reference roles: look controls palette/material/light; motion controls a particular mechanism or camera move; assets are the actual approved subject. State exactly which beat uses which quality. Existing user references take precedence; no arbitrary reference count or mandatory browsing. A still does not demonstrate motion.
|
|
14
|
+
3. Consider two concise staging ideas in text, choose the clearer one, implement only it. This does not authorize generating alternative paid assets.
|
|
15
|
+
4. Choose the medium by the subject: Svelte/SVG for truthful diagrams; approved raster cutouts for detailed subjects; genuine SceneThree for spatial relationships; approved footage for complex realistic action. Never turn every subject into rounded cards, a spinning cube or a single-image zoom.
|
|
16
|
+
5. Design one main transformation for an expressive beat: separation reveals assembly, an occluder exposes a relevant detail, a route joins known places, or two supplied states align for comparison. Minimal briefs may need only a quiet hold. No invented facts, maps or 3D reconstruction inside flat photos.
|
|
17
|
+
6. Make the hero recognizable at thumbnail size, with foreground/midground/background only where meaningful. Reserve the existing caption band. Short labels support the subject; they do not replace it.
|
|
18
|
+
|
|
19
|
+
## Compact shot contract
|
|
20
|
+
|
|
21
|
+
Record measured start/end, supplied message, actual asset IDs, independent objects, reveal/action/hold/exit times, camera, next-shot relationship and evidence needed. Distinguish global timeline time from scene-local seconds and normalized progress. Keep source-level artwork choices separate from supported exposed parameter fields.
|
|
22
|
+
|
|
23
|
+
Example: an approved transparent product lands; a supplied detail crop moves independently beside it; the connector remains attached as the product turns in **2D**; both settle for reading. This is not reconstruction of hidden product geometry. A mechanism instead needs the actual relevant schematic parts and causal linked movement, not that same product treatment with another title.
|
|
24
|
+
|
|
25
|
+
After compilation use `plan_scene_review` with actual output fps/duration and action phases. Inspect approved frames; close major findings with a targeted patch, preserving ambition, artwork and successful audio/captions. Do not add movement merely to pass a motion check.
|
|
26
|
+
|
|
27
|
+
## Permissions and continuity
|
|
28
|
+
|
|
29
|
+
For an incomplete new-video brief use the host native question tool in one form, not a numbered chat questionnaire. A cancelled form grants no permission. With the agreed authorized scope, proceed immediately without a separate plan confirmation. Reuse approvals; ask only for missing scope, a hard budget or a blocker. Never add unrequested narration/captions/music/sound effects. Preserve exact caption entries, timings, IDs and styling. Source compilation is free; provider assets, server scene frames and final encoding retain normal approval/billing.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
[
|
|
2
|
+
{"id":"machinal-motion","version":"1","label":"Visual motion direction","description":"Subject-specific scene ideas, reference roles, medium and asset selection; signature transformations rather than generic cards.","templates":["image-reveal","comparison-wipe","route-journey"]},
|
|
3
|
+
{"id":"machinal-choreography","version":"1","label":"Deterministic choreography","description":"Anticipation, stagger, easing, overlap, settle and reading holds driven by absolute frame time.","templates":["signal-diagram","piston-cycle","kinetic-type"]},
|
|
4
|
+
{"id":"machinal-spatial","version":"1","label":"Spatial staging and camera","description":"Genuine Three.js geometry, stable camera framing, motivated light and material hierarchy for spatial explanations.","templates":["lens-assembly-3d","paper-stage-3d"]},
|
|
5
|
+
{"id":"machinal-visual-review","version":"1","label":"Evidence-bound visual review","description":"Plan reveal/action/hold/exit samples, inspect approved scene pixels and make bounded timestamped repairs without claiming motion or audio verification.","templates":[]},
|
|
6
|
+
{"id":"machinal-sound","version":"1","label":"Action-led sound design","description":"Openverse CC0/Freesound discovery, licence-preserving project import, action synchronization and restrained sound mixing.","templates":[]}
|
|
7
|
+
]
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Animation direction: load only the current craft
|
|
2
|
+
|
|
3
|
+
Use `get_editing_reference(topic=animation-skills)` for compact discovery, then an exact `id` for the complete skill. These same authored instructions ship as native OpenCode/Claude/Codex skills. The MCP exposes content; the CURRENT client reads and applies it. No server model, external agent, engine replacement or new provider is involved.
|
|
4
|
+
|
|
5
|
+
| Need | Skill ID |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| Turn a vague idea into a subject-specific visual sequence; select assets | machinal-motion |
|
|
8
|
+
| Deterministic timing, anticipation, easing, secondary motion and holds | machinal-choreography |
|
|
9
|
+
| Genuine spatial staging, materials, camera and lighting | machinal-spatial |
|
|
10
|
+
| Sampled-frame feedback, bounded revision and evidence ledger | machinal-visual-review |
|
|
11
|
+
| Licensed sound effects tied to actions, not unsolicited music | machinal-sound |
|
|
12
|
+
|
|
13
|
+
Read motion direction plus only the relevant specialty before authoring. Fetch `scene-runtime` as the implementation contract and one relevant `scene-templates` source, not every guide/template. Keep existing production/caption/spending invariants. These skills do not authorize new media access, downloading, image generation, narration, sound or paid previews. Follow a complete brief without another plan confirmation.
|
|
14
|
+
|
|
15
|
+
Quality path: measured timing → visual contract → relevant craft skill/template → current-client source → compile → consent-bound `inspect_scene` → one targeted revision if useful → exact recipe preflight → authorized final render. `plan_scene_review` returns valid sample frame indices and a checklist; it does not inspect anything. A quiet/minimal hold can be the right design. Never impose an effect count or claim that compilation is aesthetic approval.
|
|
16
|
+
|
|
17
|
+
The reference method distinguishes **look** (palette/material/composition), **motion** (mechanism/timing/camera), and **asset** (the actual subject). Record what each supplied reference contributes; only use inspected, approved assets and never pretend to have watched motion from a still. No required internet reference quota. This is an original machinal workflow, not a vendored Stewdio skill, script or runtime.
|
|
@@ -27,6 +27,6 @@ Before authoring a new video, use `machinal-editing` and `get_editing_reference(
|
|
|
27
27
|
8. Enumerate pending provider actions, check live credits and get explicit source-use/spending authorization before `generate_assets`/`render_video(userApproved:true)`. Keep returned resolved assets/documents, then finish/revalidate treatments on actual track IDs after generation. Inspect jobs/media before new paid work and reuse stable exact-operation idempotency keys.
|
|
28
28
|
9. After completion and receiving approval, `get_video_result(delivery:link,userApproved:true)` returns an opaque one-hour application download link: give the requested clickable link/expiry, not raw S3 credentials or a local path. Only an explicitly requested client-local file uses `delivery:local` and approved download preferences; ask if unset, never overwrite and verify the full file. The Docker/server volume is not the client's filesystem and the server never writes to that client directory. Never attach the application key to links/redirects, print underlying signed S3 URLs or embed them in visible commands. Permission flags report an actual user reply; never self-approve.
|
|
29
29
|
|
|
30
|
-
`
|
|
30
|
+
A project means the saved editable timeline plus all used assets, not a JSON/YAML download or just a populated Media Bin. Successful generation/final rendering on the updated API publish the resolved edit into an empty/media-only or untouched prepared project; manual edits are preserved and can be explicitly replaced using Open prepared/rendered timeline in the editor. Verify saved tracks/clips, audio, exact captions, treatments and pinned asset references with `get_project` before claiming project completion. Do not regenerate/rerender merely to save/reopen an edit. `save_project` still needs complete editor state and the current version, never YAML; preserve unrelated fields and reconcile 409 conflicts. Keep API keys, authorization headers and private credential paths out of recipes, filenames, output and chat.
|
|
31
31
|
|
|
32
32
|
Keep generation, scene compilation, text preparation and rendering in Directional. Do not build local Python/FFmpeg pipelines or HTTP bridges. For unchanged continuation use sourceJobId; use get_job_result once for resolved recipeYaml when editing is needed. Prefer wait_for_job(timeoutSeconds:120), not repetitive progress lookups or sleep scripts. For left-edge titles use anchor:left and align:left; x/y are design pixels, not percentages. Preserve the approved final delivery separately from processing-location preferences. Do not promise music generation when capabilities say unsupported. Scene YAML prompts are concrete storyboards, not generic headings or vague CSS: specify subject/action, medium, composition/depth, palette/light, exact copy and local reveal/action/hold/exit. Use visualMode:3d with real SceneThree for requested spatial scenes. Never put AI-production labels/disclaimers/watermarks on screen, including in image prompts or textures.
|
|
@@ -42,6 +42,8 @@ An asset identifies `{id, file, version, kind, duration, width?, height?, hasAud
|
|
|
42
42
|
|
|
43
43
|
`snapshot` has `{revision, tracks, effects, transitions, textItems, selectedIds}` and captures the **compiler timeline**. `get_project` returns editor state, not automatically a ready compiler snapshot; obtain/construct an appropriate current snapshot rather than treating `state.timeline` as this object verbatim. `save_project` takes full editor state and its numeric current project `version`, never raw recipe YAML. `preparedText` is renderer-produced text preparation; do not fabricate its hashes/images.
|
|
44
44
|
|
|
45
|
+
A project is the saved **editable timeline and its source assets**, not a recipe download. Successful generation and final rendering publish their resolved composition into that owned project's editor state when it is empty/media-only or still matches the untouched previous preparation. Tracks/clips, narration, exact captions and resolved job IDs, effects, transitions, output settings and pinned assets are retained. Manual edits (including intentionally cleared documents) are not silently replaced; **Open prepared timeline / Open rendered timeline** in Projects explicitly restores a retained edit with confirmation and keeps the project's media. `get_project` also repairs legacy media-only states from retained snapshots without paid work. Check the saved project after production; a local `.edit.yaml` checkpoint alone is not project delivery. Free validation/compilation is not a save operation, and no recipe file substitutes for the editor timeline.
|
|
46
|
+
|
|
45
47
|
## Sequence and clips
|
|
46
48
|
|
|
47
49
|
`sequence.each`: `take: {from, duration}`; duration is **timeline** duration. A rate of 2 consumes twice that much source. `rate` is 0.25–4. `source_audio` is `keep|remove` (default keep). `volume` is 0–200 **percent**, not 0–1 gain. `look` and `motion` are exact catalog IDs. A clip must have at least 100ms timeline time and fit the real source (images can be held without a finite source duration).
|
|
@@ -15,4 +15,4 @@ Read `get_editing_reference(topic: production)` (offline: `references/production
|
|
|
15
15
|
|
|
16
16
|
Where deployed, compile_recipe's optional productionContract/productionReview bind beat promises to exact YAML and pinned source versions; reconcile revision_required findings and use expectedCompositionVersion before paid submission. After actual permission to inspect the named scene and return images, get_scene_source → inspect_scene supplies 1–6 explicit sampled frames as MCP images, with sourceVersion, timestamps and optional data-scene-object bounds. This bounded diagnostic costs zero machinal credits, not full scene/video rendering. Samples exclude timeline captions/final compositing and do not verify motion/audio or aesthetic quality. Read the current production reference for schemas/limits; never invent support on an older deployment or launch automatic inspection/render loops.
|
|
17
17
|
|
|
18
|
-
Where deployed, render_preview produces a short final-composition MP4 with mixed audio
|
|
18
|
+
Where deployed, render_preview produces a short final-composition MP4 with mixed audio. Check the deployed compositionPreview capabilities and topic=production for its processing/billing basis: interval-aware versions process the excerpt plus conservative temporal dependencies and needed original scene frame ranges; older versions process the full timeline. Explain the verified basis before separate preview spending/source approval and check credits. It requires fully resolved assets and expectedCompositionVersion; never rerun successful generation or rewrite captions/timing for a preview. Normal job waits/delivery apply. An excerpt is not the complete final delivery, and receiving its link is not proof of playback or aesthetic review. For small scene adjustments, edit_scene_parameters can preserve Svelte/media/config when the named source explicitly exposes that parameter surface; read scene-authoring and respect sourceVersion/consent.
|
|
@@ -10,6 +10,8 @@ For authorized spelling/name corrections, keep the intact resolved baseline and
|
|
|
10
10
|
|
|
11
11
|
## 1. Director: define observable success before code
|
|
12
12
|
|
|
13
|
+
For focused craft read `get_editing_reference(topic=animation-skills)` and only the relevant exact skill: `machinal-motion`, `machinal-choreography`, `machinal-spatial`, `machinal-visual-review`, or `machinal-sound`. Keep the runtime contract and one useful template in context; do not preload the whole skill library. After compilation, `plan_scene_review` converts actual duration/fps and optional scene-local phase anchors into up to six valid frame indices. Its defaults and synchronous `compile_scene.reviewPlan` are provisional planning evidence, never pixel inspection or source-use permission. Inspect approved frames, record timestamped findings and make one focused design revision when useful, not an automatic paid loop.
|
|
14
|
+
|
|
13
15
|
After the timing-first checkpoint when narration is involved, write a compact **production contract** in a local Markdown artifact (or one compact in-context table when workspace tools are unavailable). This is not recipe YAML or additional on-screen copy. Keep the resolved audio/captions and approved assets. Before measured timing exists, label times provisional.
|
|
14
16
|
|
|
15
17
|
Specify one visual thesis for the whole video: what the viewer should understand/feel, its visual language (palette, type, image treatment, framing), and the subject-specific signature action. Avoid generic adjectives such as “premium”, “cinematic” or “spectacular” without describing what is visible.
|
|
@@ -131,7 +133,7 @@ Annotate relevant DOM/SVG groups with `data-scene-object="stable-id"` to receive
|
|
|
131
133
|
|
|
132
134
|
`render_preview` renders an MP4 excerpt using the SAME final scene/layer/effect/transition/caption/audio pipeline, not a simulated browser view. It requires a fully resolved valid recipe, no pending generation, checked live credits and explicit source/spending approval that covers the cost basis below. Keep existing voice/images/caption results and the exact recipe/caption entries. Do not trim, shift or rebuild the YAML to produce a short review clip.
|
|
133
135
|
|
|
134
|
-
**
|
|
136
|
+
**Cost/processing boundary:** the preview selects the requested timeline interval plus conservative temporal dependencies. Plain isolated clips are trimmed; connected transition groups and clips with temporal effects, animated transforms, speed changes or fades retain their necessary original history. Unrelated sources are not staged/materialized. Scene rendering captures only the needed original frame ranges, while keeping the original scene duration/configuration and absolute animation time. Only intersecting caption rasters are prepared, without editing the recipe/caption entries. Final rendering is billed using the actual processing-window duration, with rendered scene ranges billed separately under the existing tariff/rounding. Dependencies can exceed the excerpt's seconds; explain this before preview spending approval. The requested interval is selected at final encoding after compositing/audio mixing. No reduced-resolution shortcut, provider probe or automatic review loop is authorized. A render failure follows existing refunds: successful scene/provider work is not refunded merely because final encoding failed.
|
|
135
137
|
|
|
136
138
|
After validation/compilation, call:
|
|
137
139
|
|
|
@@ -5,6 +5,8 @@ description: Integrate approved images into ambitious animated Svelte scenes, de
|
|
|
5
5
|
|
|
6
6
|
# Plan footage, stills and animated Svelte scenes
|
|
7
7
|
|
|
8
|
+
**Focused animation crafts.** Use `get_editing_reference(topic: animation-skills)` or installed `machinal-motion`, `machinal-choreography`, `machinal-spatial`, `machinal-visual-review` and `machinal-sound`. Load only the relevant craft, runtime contract and template. Before rendering, use `plan_scene_review` with actual duration/fps and scene-local phases, then consent-bound `inspect_scene` for real frame feedback. A compiled scene/review plan is not visual approval; keep one focused revision, no automatic paid loop. New templates include `comparison-wipe`, `route-journey`, `piston-cycle`. Sound search is metadata only; separately approved `import_sound_effect` preserves licence/attribution and returns the actual project filename. Never add unrequested audio.
|
|
9
|
+
|
|
8
10
|
**Film-style library.** Use `machinal-cinema` for 66 cinematic visual languages and directing/helpers reference. Discover `film-styles`/`film-techniques`; native `scene-templates` now include `swiss-grid-motion`, `blueprint-mechanism` and `paper-stage-3d`. Adapt real subject/action/material/camera, not just the demo label. The imported sources do not authorize local rendering, media access, caption changes or paid work; existing runtime and production-review rules win.
|
|
9
11
|
|
|
10
12
|
**Visual coverage, not minimum cost.** Overly simplistic SVG/CSS is also a reason to use images. For documentary/biography work, plan distinct people, geographic context, environments and period-grounded illustrative scenes from verified copy rather than one reused portrait plus text, lines and nodes. Keep an image-coverage list linking each asset to its measured beat, purpose and scene. 5–10 distinct images per video can be appropriate, not a quota or cap; the four-image attachment limit is per scene, not per video. Reuse suitable successful assets, but do not simplify solely to make the video cheap. Respect the approved budget and ask if necessary coverage exceeds it; minimal/no-generation/procedural-only briefs still win. `image.generate` is a YAML job type, not an MCP tool: select `generate_assets` for approved missing artwork after the timing-first checkpoint, then `wait_for_job` and `get_job_result` before composing its actual filenames with `compile_scene`. Tool selection grants no consent and does not authorize changes to narration, captions, pacing or transitions. See `references/workflow.md` for coverage and tool-selection details.
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Client-authored scenes through MCP
|
|
2
2
|
|
|
3
|
+
Focused craft is available through `get_editing_reference(topic=animation-skills)` and exact IDs `machinal-motion`, `machinal-choreography`, `machinal-spatial`, `machinal-visual-review`, `machinal-sound`. Load only useful references. Synchronous successful `compile_scene` responses add a provisional `reviewPlan`; no images were inspected. Use `plan_scene_review` with actual scene-local phases when the default sample timing is not representative, then `inspect_scene` within named-source/image-inspection scope. Preserve meaningful artwork/action while applying one focused visual revision. No automatic paid preview loop or aesthetic approval is implied.
|
|
4
|
+
|
|
3
5
|
The AI currently connected in OpenCode, Claude Code, Codex or another MCP host writes the Svelte source itself. machinal does not call another AI to author, plan or repair these scenes. No model API key or subscription credential is sent from the host to machinal.
|
|
4
6
|
|
|
5
7
|
Client-side scene CODE authoring/repair, `compile_scene` source validation/storage and `get_scene_source` cost **zero machinal credits**. This does NOT make server rendering free: scene frames rendered by scene-engine AND final video encoding are billed at the configured rendering rate, in addition to requested image generation, TTS and captions/transcription. A compiled live source is not an encoded scene video. The host AI's own provider/subscription limits remain separate. Server rendering requires configured pricing, sufficient credit, active API access and spending/source-use approval. Only source authoring/validation can proceed without a render tariff or positive balance.
|
|
@@ -19,9 +21,9 @@ Existing YAML captions are read-only unless the user explicitly requests a capti
|
|
|
19
21
|
1. Agree on the brief, output dimensions/resolution, visual materials and audio/captions. Read `get_workflow_preferences`, `get_editing_reference(topic=scene-runtime)` and `topic=scenes`. Use a concrete beat sheet, not a generic title card.
|
|
20
22
|
2. For narration, first run only approved speech and requested captions through `generate_assets`. Wait for completion and read `get_job_result` once. Derive scene cuts and local actions from measured audio/cue times. Preserve those audio assets and caption texts; do not regenerate them.
|
|
21
23
|
3. Write a complete standalone Svelte 5 component in the **current client**. Use JavaScript, allowed runtime imports, `$derived` frame-time animation, embedded fonts and actual approved image/video/model props. Save source locally as `.svelte` when workspace tools are available. No local compilation/rendering is needed.
|
|
22
|
-
4. Call `compile_scene` with `projectId`, `component` (source text, not a path), a stable `idempotencyKey`, `userApproved=true`, `duration` in seconds (1–60), even `width`/`height` (2–1920), and `fps` (1–60). Optional fields: `
|
|
24
|
+
4. Call `compile_scene` with `projectId`, `component` (source text, not a path), a stable `idempotencyKey`, `userApproved=true`, `duration` in seconds (1–60), even `width`/`height` (2–1920), and `fps` (1–60). Always supply a concise, subject-specific `title` for a new scene, ideally 2–6 words, such as `Roots unfold` or `City at dusk`; never use a filename, extension, job ID or generic `Generated scene`. This is the media-bin name, not on-screen copy. The title is retained in the immutable source and survives reopening; edits preserve it when omitted. Optional fields: `explanation` (outside the picture), exact-copy `text`, `visualMode: auto|2d|3d`, `transparent`, `captionSafeArea`, approved `images`/`videos`/`models` and exposed `parameters` as described below. Source is at most 64000 UTF-8 bytes. With separate captions set `captionSafeArea=true` to reserve the bottom 24 percent.
|
|
23
25
|
5. Images use `{id: image_1, file: actual-project-image.png, name: Subject}` (maximum four JPEG/PNG/WebP, 5 MiB each). Generate any approved new image first, wait for its actual filename, then attach it here. Do not use an image job ID as a filename or put base64/URLs in tool arguments. Videos use the implemented `SceneVideo` runtime and approved project filenames; see the runtime contract. Media metadata is not visual inspection.
|
|
24
|
-
6.
|
|
26
|
+
6. Simple new-source compilation returns the pinned asset directly (HTTP 200), with durable free-operation idempotency receipts and no background job. A busy compiler returns 429 before work, so retry that same free request later rather than starting rendering. Source-file edits and handoffs retain persistent recovery jobs (HTTP 202): only for those responses use `wait_for_job` until terminal and `get_job_result` once. Inspect `status` and `statusCode`; a successful lookup is not successful compilation. The server checks syntax, imports, runtime and layout in its existing sandbox and saves a reusable live `.scene.json` source. It does **not** encode a video during compilation.
|
|
25
27
|
7. On success, keep the returned pinned `asset` exactly. Add it to recipe `assets` and place its `id` in ordinary video `tracks[].clips[].assetId`. Example: `get_editing_reference(topic=examples,id=client-scene)`. No new YAML inline `component`, scene job, invented resultAssetId or local upload is needed. Use the actual measured asset duration.
|
|
26
28
|
8. On a 422 compilation result, read `result.diagnostics`, correct source using the **same current client AI**, and submit the corrected code with a new idempotency key. Reuse an unchanged key/source only for an uncertain transport retry. Never invoke a server model for repair, silently replace animation with stills, or delete meaningful artwork merely to pass checks. Preserve successful audio/images/captions.
|
|
27
29
|
9. Validate the final YAML, check `get_credits` and reuse explicit spending/source-use approval already granted for `render_video`; ask only if that scope is missing or changed. Scene frames and final video encoding both run on the server and are charged at the configured render tariff. Successful scene exports are deduplicated per source within the operation and reported as `cost.sceneRenderCredits`, separately from final `cost.renderCredits` and provider `cost.aiCredits`. A failed final video refunds its final encoding debit, not successful server scene work or provider usage. No hardcoded commercial rate is introduced.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
<script>
|
|
2
|
+
import { SceneCanvas, useScene } from '@direction/scene-svelte';
|
|
3
|
+
import { clamp } from '@direction/scene-runtime';
|
|
4
|
+
|
|
5
|
+
let { images = {} } = $props();
|
|
6
|
+
const scene = useScene();
|
|
7
|
+
const design = { before: 'Înainte', after: 'După', accent: '#d6f575', split: 0.5 };
|
|
8
|
+
const progress = $derived(scene.frame.progress);
|
|
9
|
+
const safeHeight = $derived(scene.frame.config.height * (1 - (scene.frame.config.captionSafeBottom ?? 0)));
|
|
10
|
+
const reveal = $derived(smooth((progress - 0.2) / 0.45));
|
|
11
|
+
const split = $derived(850 - (850 - 800 * design.split) * reveal);
|
|
12
|
+
const marker = $derived(1 - smooth((progress - 0.92) / 0.08));
|
|
13
|
+
|
|
14
|
+
function smooth(value) {
|
|
15
|
+
const t = clamp(value, 0, 1);
|
|
16
|
+
return t * t * (3 - 2 * t);
|
|
17
|
+
}
|
|
18
|
+
</script>
|
|
19
|
+
|
|
20
|
+
<SceneCanvas background="#182125">
|
|
21
|
+
<svg width="100%" height={safeHeight} viewBox="0 0 1000 700" aria-label="Aligned supplied states with a moving comparison boundary">
|
|
22
|
+
<defs><clipPath id="comparison-after"><rect x={100 + split} y="110" width={Math.max(0, 800 - split)} height="440" /></clipPath></defs>
|
|
23
|
+
<rect x="100" y="110" width="800" height="440" fill="#26363a" />
|
|
24
|
+
<image data-scene-object="before" href={images.image_1} x="100" y="110" width="800" height="440" preserveAspectRatio="xMidYMid meet" />
|
|
25
|
+
<image data-scene-object="after" href={images.image_2} x="100" y="110" width="800" height="440" preserveAspectRatio="xMidYMid meet" clip-path="url(#comparison-after)" />
|
|
26
|
+
<g data-scene-object="comparison" opacity={reveal * marker}>
|
|
27
|
+
<path d="M{100 + split} 100 V560" stroke={design.accent} stroke-width="4" />
|
|
28
|
+
<circle cx={100 + split} cy="330" r="18" fill={design.accent} />
|
|
29
|
+
<path d="M{93 + split} 330 H{107 + split}" stroke="#182125" stroke-width="3" />
|
|
30
|
+
</g>
|
|
31
|
+
<g fill="#eef2e8" font-size="38" font-weight="700">
|
|
32
|
+
<text x="100" y="640">{design.before}</text>
|
|
33
|
+
<text x="900" y="640" text-anchor="end" opacity={reveal}>{design.after}</text>
|
|
34
|
+
</g>
|
|
35
|
+
</svg>
|
|
36
|
+
</SceneCanvas>
|
|
37
|
+
|
|
38
|
+
<style>
|
|
39
|
+
svg { display: block; font-family: 'Direction Sans'; }
|
|
40
|
+
</style>
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
<script>
|
|
2
|
+
import { SceneCanvas, useScene } from '@direction/scene-svelte';
|
|
3
|
+
import { clamp } from '@direction/scene-runtime';
|
|
4
|
+
|
|
5
|
+
const scene = useScene();
|
|
6
|
+
const design = { title: 'Pompare, în două faze', accent: '#6cd2e5', stroke: 125 };
|
|
7
|
+
const progress = $derived(scene.frame.progress);
|
|
8
|
+
const safeHeight = $derived(scene.frame.config.height * (1 - (scene.frame.config.captionSafeBottom ?? 0)));
|
|
9
|
+
const intake = $derived(smooth((progress - 0.18) / 0.23));
|
|
10
|
+
const discharge = $derived(smooth((progress - 0.49) / 0.23));
|
|
11
|
+
const pistonY = $derived(295 + design.stroke * (intake - discharge));
|
|
12
|
+
const intakeOpen = $derived(progress >= 0.18 && progress < 0.44);
|
|
13
|
+
const outletOpen = $derived(progress >= 0.49 && progress < 0.75);
|
|
14
|
+
const caption = $derived(progress < 0.46 ? 'Admisie' : 'Evacuare');
|
|
15
|
+
|
|
16
|
+
function smooth(value) {
|
|
17
|
+
const t = clamp(value, 0, 1);
|
|
18
|
+
return t * t * (3 - 2 * t);
|
|
19
|
+
}
|
|
20
|
+
</script>
|
|
21
|
+
|
|
22
|
+
<SceneCanvas background="#172a36">
|
|
23
|
+
<svg width="100%" height={safeHeight} viewBox="0 0 1000 700" aria-label="Schematic piston pump with separate intake and outlet check valves">
|
|
24
|
+
<text x="90" y="112" fill="#f1eee5" font-size="43" font-weight="700">{design.title}</text>
|
|
25
|
+
<path d="M380 225 H620 V520 H380 Z M380 260 H170 V350 M620 260 H830 V350" fill="none" stroke="#b2c9d0" stroke-width="6" />
|
|
26
|
+
<rect x="386" y="231" width="228" height={pistonY - 231} fill={design.accent} opacity="0.22" />
|
|
27
|
+
<g data-scene-object="piston">
|
|
28
|
+
<path d="M500 550 V{pistonY + 15}" stroke="#f1eee5" stroke-width="14" />
|
|
29
|
+
<rect x="388" y={pistonY} width="224" height="23" rx="3" fill="#f1eee5" />
|
|
30
|
+
</g>
|
|
31
|
+
<g data-scene-object="intake-valve" transform="translate(300 260) rotate({intakeOpen ? -38 : 0})">
|
|
32
|
+
<path d="M0 -23 V23" stroke={intakeOpen ? design.accent : '#e5b86e'} stroke-width="9" />
|
|
33
|
+
</g>
|
|
34
|
+
<g data-scene-object="outlet-valve" transform="translate(700 260) rotate({outletOpen ? -38 : 0})">
|
|
35
|
+
<path d="M0 -23 V23" stroke={outletOpen ? design.accent : '#e5b86e'} stroke-width="9" />
|
|
36
|
+
</g>
|
|
37
|
+
{#each [0, 1, 2] as index}
|
|
38
|
+
<circle cx={180 + ((intake * 1.8 + index / 3) % 1) * 190} cy="260" r="6" fill={design.accent} opacity={intakeOpen ? 1 : 0} />
|
|
39
|
+
<circle cx={630 + ((discharge * 1.8 + index / 3) % 1) * 190} cy="260" r="6" fill={design.accent} opacity={outletOpen ? 1 : 0} />
|
|
40
|
+
{/each}
|
|
41
|
+
<g fill="#f1eee5" font-size="30">
|
|
42
|
+
<text x="150" y="410">Intrare</text><text x="740" y="410">Ieșire</text>
|
|
43
|
+
<text x="500" y="640" text-anchor="middle">{caption}</text>
|
|
44
|
+
</g>
|
|
45
|
+
</svg>
|
|
46
|
+
</SceneCanvas>
|
|
47
|
+
|
|
48
|
+
<style>
|
|
49
|
+
svg { display: block; font-family: 'Direction Sans'; }
|
|
50
|
+
</style>
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
<script>
|
|
2
|
+
import { SceneCanvas, useScene } from '@direction/scene-svelte';
|
|
3
|
+
import { clamp } from '@direction/scene-runtime';
|
|
4
|
+
|
|
5
|
+
const scene = useScene();
|
|
6
|
+
const design = { labels: ['Pornire', 'Legătură', 'Destinație'], accent: '#f3bd63', title: 'Un traseu schematic' };
|
|
7
|
+
const points = [{ x: 160, y: 450 }, { x: 500, y: 250 }, { x: 840, y: 450 }];
|
|
8
|
+
const progress = $derived(scene.frame.progress);
|
|
9
|
+
const safeHeight = $derived(scene.frame.config.height * (1 - (scene.frame.config.captionSafeBottom ?? 0)));
|
|
10
|
+
const travel = $derived(smooth((progress - 0.2) / 0.5) * 2);
|
|
11
|
+
const segment = $derived(Math.min(1, Math.floor(travel)));
|
|
12
|
+
const fraction = $derived(travel - segment);
|
|
13
|
+
const position = $derived({ x: points[segment].x + (points[segment + 1].x - points[segment].x) * fraction, y: points[segment].y + (points[segment + 1].y - points[segment].y) * fraction });
|
|
14
|
+
|
|
15
|
+
function smooth(value) {
|
|
16
|
+
const t = clamp(value, 0, 1);
|
|
17
|
+
return t * t * (3 - 2 * t);
|
|
18
|
+
}
|
|
19
|
+
</script>
|
|
20
|
+
|
|
21
|
+
<SceneCanvas background="#eee8dc">
|
|
22
|
+
<svg width="100%" height={safeHeight} viewBox="0 0 1000 700" aria-label="Schematic route between three supplied places, not a geographic map">
|
|
23
|
+
<text x="90" y="120" fill="#243b3d" font-size="44" font-weight="700">{design.title}</text>
|
|
24
|
+
<path d="M160 450 L500 250 L840 450" fill="none" stroke="#a6b4ad" stroke-width="5" stroke-dasharray="5 12" />
|
|
25
|
+
<path d="M160 450 L500 250 L840 450" fill="none" stroke="#243b3d" stroke-width="7" pathLength="2" stroke-dasharray="2" stroke-dashoffset={2 - travel} />
|
|
26
|
+
{#each points as point, index}
|
|
27
|
+
<g data-scene-object={'stop-' + index} opacity={smooth((progress - index * 0.05) / 0.12)}>
|
|
28
|
+
<circle cx={point.x} cy={point.y} r={travel >= index ? 18 : 11} fill={travel >= index ? design.accent : '#eee8dc'} stroke="#243b3d" stroke-width="4" />
|
|
29
|
+
<text x={point.x} y={point.y + 64} fill="#243b3d" font-size="31" text-anchor="middle">{design.labels[index]}</text>
|
|
30
|
+
</g>
|
|
31
|
+
{/each}
|
|
32
|
+
<g data-scene-object="traveler" transform="translate({position.x} {position.y})" opacity={smooth((progress - 0.16) / 0.06)}>
|
|
33
|
+
<circle r="29" fill={design.accent} stroke="#243b3d" stroke-width="3" />
|
|
34
|
+
<path d="M-8 0 H8 M2 -6 L8 0 L2 6" fill="none" stroke="#243b3d" stroke-width="3" />
|
|
35
|
+
</g>
|
|
36
|
+
</svg>
|
|
37
|
+
</SceneCanvas>
|
|
38
|
+
|
|
39
|
+
<style>
|
|
40
|
+
svg { display: block; font-family: 'Direction Sans'; }
|
|
41
|
+
</style>
|