@machinal/mcp 0.0.0-stage → 0.4.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 +361 -2
- package/bin/machinal-mcp.mjs +19 -0
- package/bin/machinal-stdio.mjs +14 -0
- package/package.json +47 -4
- package/skills/machinal-cinema/SKILL.md +18 -0
- package/skills/machinal-cinema/references/film-library/DIRECTOR.md +149 -0
- package/skills/machinal-cinema/references/film-library/LICENSE +21 -0
- package/skills/machinal-cinema/references/film-library/MY-STYLES.md +139 -0
- package/skills/machinal-cinema/references/film-library/README.md +13 -0
- package/skills/machinal-cinema/references/film-library/TECHNIQUE.md +162 -0
- package/skills/machinal-cinema/references/film-library/core/lib.js +44 -0
- package/skills/machinal-cinema/references/film-library/core/post/crt.js +144 -0
- package/skills/machinal-cinema/references/film-library/core/three/post.js +102 -0
- package/skills/machinal-cinema/references/film-library/manifest.json +394 -0
- package/skills/machinal-cinema/references/film-library/styleboard/catalog.json +1128 -0
- package/skills/machinal-cinema/references/film-library/styles/README.md +126 -0
- package/skills/machinal-cinema/references/film-library/styles/archive-lighttable/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/art-deco/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/ascii-crt/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/backrooms/STYLE.md +123 -0
- package/skills/machinal-cinema/references/film-library/styles/blueprint/STYLE.md +118 -0
- package/skills/machinal-cinema/references/film-library/styles/brick-toy/STYLE.md +112 -0
- package/skills/machinal-cinema/references/film-library/styles/briefing-board/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/caption-news/STYLE.md +135 -0
- package/skills/machinal-cinema/references/film-library/styles/cel-anime-80s/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/chalkboard/STYLE.md +153 -0
- package/skills/machinal-cinema/references/film-library/styles/circuit-board/STYLE.md +149 -0
- package/skills/machinal-cinema/references/film-library/styles/city-symphony/STYLE.md +140 -0
- package/skills/machinal-cinema/references/film-library/styles/countdown/STYLE.md +130 -0
- package/skills/machinal-cinema/references/film-library/styles/crayon-book/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/dark-keynote/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/data-physical/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/dataviz/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/desktop-flythrough/STYLE.md +145 -0
- package/skills/machinal-cinema/references/film-library/styles/engraving/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/game-show/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/glass-product/STYLE.md +108 -0
- package/skills/machinal-cinema/references/film-library/styles/halftone-dossier/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/hd-2d/STYLE.md +109 -0
- package/skills/machinal-cinema/references/film-library/styles/hologram-hud/STYLE.md +127 -0
- package/skills/machinal-cinema/references/film-library/styles/impasto/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/ink-wash/STYLE.md +118 -0
- package/skills/machinal-cinema/references/film-library/styles/iso-infographic/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/isometric-picture-book/STYLE.md +130 -0
- package/skills/machinal-cinema/references/film-library/styles/kino-montage/STYLE.md +149 -0
- package/skills/machinal-cinema/references/film-library/styles/lidar-survey/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/living-screencast/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/lowpoly-island/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/memphis-diorama/STYLE.md +142 -0
- package/skills/machinal-cinema/references/film-library/styles/microgame/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/microscope/STYLE.md +106 -0
- package/skills/machinal-cinema/references/film-library/styles/midcentury-toon/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/news-package/STYLE.md +156 -0
- package/skills/machinal-cinema/references/film-library/styles/newsreel/STYLE.md +134 -0
- package/skills/machinal-cinema/references/film-library/styles/one-line/STYLE.md +112 -0
- package/skills/machinal-cinema/references/film-library/styles/paper-lantern/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/paper-popup/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/papercut-red/STYLE.md +108 -0
- package/skills/machinal-cinema/references/film-library/styles/pictogram-motion/STYLE.md +119 -0
- package/skills/machinal-cinema/references/film-library/styles/pixel-rpg/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/printed-long-take/STYLE.md +141 -0
- package/skills/machinal-cinema/references/film-library/styles/risograph/STYLE.md +123 -0
- package/skills/machinal-cinema/references/film-library/styles/rubber-hose/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/satellite-briefing/STYLE.md +114 -0
- package/skills/machinal-cinema/references/film-library/styles/scifi-toon/STYLE.md +119 -0
- package/skills/machinal-cinema/references/film-library/styles/shadow-puppet/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/silent-film/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/silkscreen-poster/STYLE.md +138 -0
- package/skills/machinal-cinema/references/film-library/styles/spy-titles/STYLE.md +114 -0
- package/skills/machinal-cinema/references/film-library/styles/stained-glass/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/swiss-motion/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/teardown/STYLE.md +125 -0
- package/skills/machinal-cinema/references/film-library/styles/telestrator/STYLE.md +135 -0
- package/skills/machinal-cinema/references/film-library/styles/tilt-shift/STYLE.md +105 -0
- package/skills/machinal-cinema/references/film-library/styles/transit-map/STYLE.md +194 -0
- package/skills/machinal-cinema/references/film-library/styles/ukiyoe/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/urban-sketch/STYLE.md +124 -0
- package/skills/machinal-cinema/references/film-library/styles/visual-investigation/STYLE.md +138 -0
- package/skills/machinal-cinema/references/film-library/styles/watercolor/STYLE.md +111 -0
- package/skills/machinal-cinema/references/film-library/styles/white-model/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/whiteboard/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/woodcut/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/upstream-skill.md +13 -0
- package/skills/machinal-cinema/references/film-styles.json +1322 -0
- package/skills/machinal-cinema/references/film-techniques.json +107 -0
- package/skills/machinal-cinema/references/workflow.md +58 -0
- package/skills/machinal-credits/SKILL.md +24 -0
- package/skills/machinal-editing/SKILL.md +43 -0
- package/skills/machinal-editing/references/brief.md +98 -0
- package/skills/machinal-editing/references/effects.md +58 -0
- package/skills/machinal-editing/references/looks-motion.md +37 -0
- package/skills/machinal-editing/references/styles.json +15 -0
- package/skills/machinal-editing/references/styles.md +16 -0
- package/skills/machinal-editing/references/transitions.md +46 -0
- package/skills/machinal-editing/references/workflow.md +43 -0
- package/skills/machinal-media/SKILL.md +23 -0
- package/skills/machinal-media/references/workflow.md +160 -0
- package/skills/machinal-recipes/SKILL.md +32 -0
- package/skills/machinal-recipes/references/catalog.v1.json +10445 -0
- package/skills/machinal-recipes/references/commands.md +45 -0
- package/skills/machinal-recipes/references/example.edit.yaml +26 -0
- package/skills/machinal-recipes/references/examples/caption-audio.yaml +28 -0
- package/skills/machinal-recipes/references/examples/cinematic-sequence.yaml +21 -0
- package/skills/machinal-recipes/references/examples/client-scene.yaml +26 -0
- package/skills/machinal-recipes/references/examples/generated-media.yaml +25 -0
- package/skills/machinal-recipes/references/examples/modify-snapshot.yaml +22 -0
- package/skills/machinal-recipes/references/examples/montage-v3.yaml +28 -0
- package/skills/machinal-recipes/references/examples/narrated-documentary.yaml +112 -0
- package/skills/machinal-recipes/references/examples/narration-timing.yaml +43 -0
- package/skills/machinal-recipes/references/examples/scene-edit.yaml +19 -0
- package/skills/machinal-recipes/references/examples/scene-generated-image.yaml +36 -0
- package/skills/machinal-recipes/references/examples/scene-generation.yaml +35 -0
- package/skills/machinal-recipes/references/examples/scene-image-insert.yaml +41 -0
- package/skills/machinal-recipes/references/examples/scene-three-explainer.yaml +38 -0
- package/skills/machinal-recipes/references/examples/social-hook.yaml +26 -0
- package/skills/machinal-recipes/references/examples/tutorial-clean.yaml +19 -0
- package/skills/machinal-recipes/references/examples.md +28 -0
- package/skills/machinal-recipes/references/jobs-scenes.md +206 -0
- package/skills/machinal-recipes/references/text-audio.md +118 -0
- package/skills/machinal-recipes/references/yaml.md +72 -0
- package/skills/machinal-review/SKILL.md +18 -0
- package/skills/machinal-review/references/production.md +146 -0
- package/skills/machinal-scenes/SKILL.md +44 -0
- package/skills/machinal-scenes/references/authoring.md +97 -0
- package/skills/machinal-scenes/references/runtime.md +136 -0
- package/skills/machinal-scenes/references/scene-templates/blueprint-mechanism.svelte +62 -0
- package/skills/machinal-scenes/references/scene-templates/glitch-handoff.svelte +30 -0
- package/skills/machinal-scenes/references/scene-templates/image-reveal.svelte +33 -0
- package/skills/machinal-scenes/references/scene-templates/kinetic-type.svelte +38 -0
- package/skills/machinal-scenes/references/scene-templates/layered-parallax.svelte +31 -0
- package/skills/machinal-scenes/references/scene-templates/lens-assembly-3d.svelte +57 -0
- package/skills/machinal-scenes/references/scene-templates/paper-stage-3d.svelte +83 -0
- package/skills/machinal-scenes/references/scene-templates/signal-diagram.svelte +43 -0
- package/skills/machinal-scenes/references/scene-templates/swiss-grid-motion.svelte +54 -0
- package/skills/machinal-scenes/references/scene-templates.json +178 -0
- package/skills/machinal-scenes/references/scene-templates.md +50 -0
- package/skills/machinal-scenes/references/workflow.md +206 -0
- package/skills/machinal-support/SKILL.md +42 -0
- package/src/bridge.mjs +285 -0
- package/src/cli.mjs +155 -0
- package/src/configuration.mjs +148 -0
- package/src/connection.mjs +187 -0
- package/src/credential-store.mjs +61 -0
- package/src/credits.mjs +86 -0
- package/src/docker.mjs +93 -0
- package/src/download.mjs +90 -0
- package/src/errors.mjs +9 -0
- package/src/formats.mjs +140 -0
- package/src/keys.mjs +127 -0
- package/src/launch.mjs +29 -0
- package/src/local-setup.mjs +109 -0
- package/src/opencode-auth.mjs +246 -0
- package/src/opencode-checkpoints.mjs +90 -0
- package/src/opencode-configuration.mjs +53 -0
- package/src/opencode-media.mjs +139 -0
- package/src/opencode-plugin/index.mjs +7 -0
- package/src/opencode-plugin/package.json +5 -0
- package/src/opencode-recipes.mjs +130 -0
- package/src/opencode-routing.mjs +154 -0
- package/src/opencode-tools.mjs +30 -0
- package/src/opencode-workflow.mjs +32 -0
- package/src/presentation.mjs +30 -0
- package/src/prompts.mjs +32 -0
- package/src/reference-files.json +127 -0
- package/src/runtime.mjs +51 -0
- package/src/setup-options.mjs +64 -0
- package/src/setup-stdio.mjs +114 -0
- package/src/setup.mjs +173 -0
- package/src/skills.mjs +68 -0
- package/src/transfer-http.mjs +109 -0
- package/src/version.mjs +3 -0
- package/src/windows-key-prompt.mjs +37 -0
- package/src/windows-key-prompt.ps1 +77 -0
package/README.md
CHANGED
|
@@ -1,3 +1,362 @@
|
|
|
1
|
-
#
|
|
1
|
+
# machinal MCP installer
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Set up **Codex, Claude Code or OpenCode V2** with a resilient stdio adapter. Choose an independent local backend with your own OpenRouter key, or an existing server with a Machinal application key. A private stable runtime outside npm's cache runs with Node directly, including on Windows.
|
|
4
|
+
|
|
5
|
+
See the repository's [testing guide](../../docs/TESTING.md) for source-package and pre-publish checks.
|
|
6
|
+
|
|
7
|
+
## Quick start
|
|
8
|
+
|
|
9
|
+
Requires **Node.js 22.13+ (22.x) or 24+** and an installed agent client. Server needs the actual API URL and a Machinal key with account/API access, but no Docker or provider key on the client. Independent local needs Docker/Compose v2, this version's Machinal 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
|
+
|
|
11
|
+
**Server: one Machinal key. Local: your OpenRouter key.** Hidden entry and opt-in Windows Credential Manager storage are supported for server keys. All three adapters can read the saved Windows key without a launcher. On macOS/Linux use your client environment/secret manager or optional keyed launcher. No key belongs in chat or command arguments.
|
|
12
|
+
|
|
13
|
+
**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
|
+
|
|
15
|
+
**Release status:** the source package is ready for testing; it has not been published by this change. The following registry commands become available only after publishing `@machinal/mcp` to npm under an authorized scope:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npx @machinal/mcp setup
|
|
19
|
+
# After publishing 0.4.0 (replace with the real API URL):
|
|
20
|
+
npx --yes @machinal/mcp@0.4.0 setup --client codex --mode server --url https://YOUR-API/mcp
|
|
21
|
+
npx --yes @machinal/mcp@0.4.0 setup --client claude --scope global --mode server --url https://YOUR-API/mcp
|
|
22
|
+
# Independent local; the wizard asks for OpenRouter and model IDs:
|
|
23
|
+
npx --yes @machinal/mcp@0.4.0 setup --client codex --mode local --docker-dir /path/to/machinal
|
|
24
|
+
npx --yes @machinal/mcp@0.4.0 setup --client claude --mode local --docker-dir /path/to/machinal
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The wizard asks for:
|
|
28
|
+
|
|
29
|
+
1. **OpenCode V2**, **Claude Code**, or **Codex**.
|
|
30
|
+
2. Project or global scope (**Codex defaults to global**, because untrusted project config is ignored; other clients default to project).
|
|
31
|
+
3. **Server or Local**. Server never manages Docker. Local builds an independent backend, with loopback-only host port publishing and separate persistent volumes. Default local URL: `http://127.0.0.1:8080/mcp`; choose a free port if another API is already running. Server needs the deployed HTTPS API origin, **not the frontend URL**.
|
|
32
|
+
4. Whether to install bundled editing, YAML recipe, scene and credit-awareness skills, and a default editing style.
|
|
33
|
+
5. **Server:** hidden Machinal key, reuse environment/saved key, or login later (`--defer-login`). Create keys at <https://direction.al/api-keys> or your self-hosted 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.
|
|
34
|
+
6. Windows Server mode: optionally remember a verified key in Credential Manager (default: no).
|
|
35
|
+
7. Optional client launch. `--no-launch` works even when login is deferred.
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
The hosted API URL is deliberately not guessed. `MACHINAL_API_ORIGIN` can provide the prompt default. HTTP is accepted only on `localhost`, `127.0.0.1`, and `[::1]`; all other endpoints require HTTPS. Redirects are refused, including same-origin redirects: configure the final `/mcp` URL and preserve that route in your proxy. `--mode hosted` remains an alias for `--mode server`. URL-only scripts now mean an existing server, even for loopback URLs; they never start Docker implicitly.
|
|
40
|
+
|
|
41
|
+
**Independent local does not mean free upstream AI.** Rendering uses your hardware; AI usage is charged directly by OpenRouter. Provider/device secrets live under `~/.config/machinal/local/` (or `$XDG_CONFIG_HOME/machinal/local/`), never `api/.env` or client config. Protect these files and backups: POSIX modes are private; Windows uses your filesystem ACLs. Reuse preserves the token/volumes; `--configure-local` explicitly changes provider settings. Installation grants no media-access, upload or AI-spending permission. Source-folder mounts still need separate approval.
|
|
42
|
+
|
|
43
|
+
### Connection status, not a broken MCP
|
|
44
|
+
|
|
45
|
+
The local stdio handshake does not depend on login/network. The always-available **`connection_status`** tool reports `login_required`, `connection_unavailable`, `account_access_required`, `rate_limited` or `connected`, separately from `transport: connected`. Reconnect reloads credentials and tool discovery, never submitted jobs. A cached verified catalog supports discovery during outages; it is not proof that the service is online. Successful recovery publishes MCP list-change notifications.
|
|
46
|
+
|
|
47
|
+
**UI badges belong to the client.** An API-key adapter cannot force Codex/Claude/OpenCode's native **Needs authentication** badge; that requires real OAuth, which this API does not implement. Real process/configuration errors can still show MCP failure. No availability guarantee is made during network/Node failures.
|
|
48
|
+
|
|
49
|
+
Uncertain tool submissions are **never retried automatically**. Recover existing jobs/idempotency keys before resubmitting. Auto-reconnection performs free initialization/catalog discovery only. Terminal diagnostics: `npx @machinal/mcp doctor --url https://YOUR-API/mcp` (exit 0 only after successful service discovery). No credentials are accepted as tool arguments.
|
|
50
|
+
|
|
51
|
+
### Friendly recovery and local Docker
|
|
52
|
+
|
|
53
|
+
The following bullets describe **advanced direct-HTTP compatibility** (`--transport http`) for existing authenticated self-host deployments. Its historical `--mode local` helper is not the independent default above: it still requires that deployment's account/configuration. Prefer stdio for new installations. Independent local uses a private generated Compose profile, separate disk-backed jobs, loopback host publishing, and no `api/.env`/PocketBase. `--yes` alone never authorizes Docker startup; `--start-docker` is explicit approval. Containers/volumes are never deleted automatically.
|
|
54
|
+
|
|
55
|
+
- URL and key prompts validate inline. A malformed saved/environment key no longer blocks interactive setup/launch: choose hidden replacement or create a new key without deleting the old one first. Missing/invalid keys and HTTP 401/402/403 show key or membership links. For self-hosting, use the corresponding page of your own website/account backend.
|
|
56
|
+
- Transient network failures and HTTP 502/503/504 retry at most three times per request within a 15-second verification budget. Authentication, redirects and rate limits are not automatically retried. After HTTP 401, interactive setup can enter a different key, follow the direct creation link, retry the current key, or cancel without repeating the wizard, with at most three verification rounds. Replacement credentials are not saved if setup verification fails.
|
|
57
|
+
- Optional credit lookup failures become one unavailable warning; authentication loss still aborts. No unverified configuration/skill changes or key storage are committed. An interactive Windows vault outage can fall back to hidden entry.
|
|
58
|
+
- OpenCode on Windows reads a saved key directly through the bundled authentication integration, including in the existing shared service. It does not need `MACHINAL_API_KEY` or immediate keyed startup for a vault-only key. Other clients and unsaved prompt-only keys still require a keyed launch or a verified environment value. Saving a key does not set a shell environment variable.
|
|
59
|
+
- Only explicit **Local** mode attempts Docker recovery when MCP cannot be reached. A running API is reused without inspecting Docker. Setup searches the current folder and ancestors for `compose.editengine.yaml`, `api/Dockerfile`, and `services/scene-renderer/Dockerfile`; `--docker-dir PATH` selects a separate checkout. No published image name is guessed.
|
|
60
|
+
- 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.
|
|
61
|
+
- **`--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.
|
|
62
|
+
- 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.
|
|
63
|
+
- The terminal interface follows your terminal's background and text colors. Cyan marks only the selected option; amber/red mark warning/error labels, not entire paragraphs. Short menus show up to five choices and collapse to a one-line answer. Completed key prompts show `[hidden]`, not the key or its length; visibility toggling is disabled. `NO_COLOR` (including an empty value) and `TERM=dumb` disable theme colors. Piped output stays plain.
|
|
64
|
+
- Interactive setup finishes with one compact verification/configuration/credit summary. Use `setup --verbose` for full authentication explanations, credit breakdowns, reset dates and configured rates. Unattended setup retains the detailed plain-text report. Important compatibility, billing, low-balance and backup warnings are never hidden. Backup details remain grouped into **one summary**, with file count, root/config path, sibling filename pattern and restoration instructions rather than a line per skill.
|
|
65
|
+
|
|
66
|
+
From this repository (no npm publication required):
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
# Maintainer's existing Docker API is a Server, not the user's local runtime:
|
|
70
|
+
node packages/mcp-installer/bin/machinal-mcp.mjs setup --mode server --url http://127.0.0.1:8080/mcp
|
|
71
|
+
# User's local Docker: offer build/start from this checkout if the API is offline:
|
|
72
|
+
node packages/mcp-installer/bin/machinal-mcp.mjs setup --mode local --docker-dir .
|
|
73
|
+
# Independent local, with OPENROUTER_API_KEY and OPENROUTER_MODEL supplied securely:
|
|
74
|
+
node packages/mcp-installer/bin/machinal-mcp.mjs setup --client opencode --mode local --docker-dir . --start-docker --yes --no-launch
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Live credits
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
Setup calls only MCP initialization, tool discovery and the read-only `get_credits` tool. It shows a concise balance and billing notice; `--verbose` or unattended setup 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.
|
|
82
|
+
|
|
83
|
+
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.
|
|
84
|
+
|
|
85
|
+
### Bundled editing skills
|
|
86
|
+
|
|
87
|
+
**Current-client scene authoring:** after deploying the updated API, the AI already connected in OpenCode/Claude/Codex writes Svelte and uses `compile_scene` for free server validation/compilation. `get_scene_source` supports edits preserving embedded attachments. No server scene-model call or paid repair/fallback is made. Put the returned asset directly in YAML video tracks. Read `get_editing_reference(topic: scene-authoring)` or the bundled `machinal-scenes/references/authoring.md`; example `client-scene` is a compiler fixture, not real project media.
|
|
88
|
+
|
|
89
|
+
Through MCP, scene CODE written/repaired by the current client avoids the server-model generation fee. Source compilation/storage is not an encoded scene export. Server scene frame rendering AND final video encoding are billed at the configured render tariff, alongside approved image/TTS/caption usage, with separate scene/video cost fields. The host AI's own subscription limits remain separate. Rebuild/restart the API and reconnect to discover the updated tools/rules. Reinstall skills only after approving replacement of customized bundled files.
|
|
90
|
+
|
|
91
|
+
- **`machinal-editing`**: editing brief plus exact transition/effect/look/motion choices, with profiles `auto`, `cinematic`, `social`, `tutorial`, `minimal`, `documentary`, `travel`, `product`, `noir`, `retro`, `cyberpunk`, `dreamy`, `sports`.
|
|
92
|
+
- **`machinal-recipes`**: the full YAML envelope/field map, versions, selectors/commands, source and timeline times, metadata, typography/verified captions/audio, deterministic examples, validation and compilation. Styles become supported commands, not invented YAML keys.
|
|
93
|
+
- **`machinal-scenes`**: proactive beat planning with footage/still/animated Svelte scene choices, independent moving objects, real images in animated layouts, concrete scene briefs, supported generation/edit fields and staged jobs. Honors no-generation briefs and avoids scenes that add no value.
|
|
94
|
+
- **`machinal-cinema`**: 66 cinematic film-style prompts, directing guides, portable visual-code references and a runtime translation workflow. Includes MIT copyright notice/checksums and offline sources; uses native Swiss-grid, blueprint-mechanism and paper-stage Svelte/Three.js examples without installing an external local rendering/audio pipeline. Existing captions, consent and paid rendering rules remain unchanged. See [film-style integration](../../docs/MCP.md#cinematic-film-style-library).
|
|
95
|
+
- **`machinal-credits`**: live balances, spending approval, uncertain AI charges, idempotent recovery and pending/final costs.
|
|
96
|
+
- **`machinal-media`**: separate media consent, volume-only source uploads, approved S3 reuse/hydration, opaque expiring/revocable delivery links, bounded job waits and explicitly requested client-local downloads. A Docker/server volume is not the MCP client's filesystem; expired links never require rerendering.
|
|
97
|
+
|
|
98
|
+
The editing skill reads an installed `references/preferences.md`; the user's current brief overrides that default. **`get_editing_reference`** provides targeted live lookup of styles, full preset entries (including parameters/algorithms), YAML/scene/job semantics and complete compiler-tested examples. Use `id` for an exact entry, `query` for literal discovery and `nextOffset` for pagination. The live API wins over an offline snapshot; guidance never guarantees a particular LLM response or visual quality.
|
|
99
|
+
|
|
100
|
+
The package ships synchronized offline guides, all named profiles, the complete catalog and YAML examples beside the skills. The scene skill includes its own offline workflow; `scene-image-insert` demonstrates footage, a timed animated scene, a real image attachment and independently moving objects. These are real usage references, not merely a list of preset names. Example metadata/transcripts/revisions are synthetic and must not be presented as user assets. Pending scene/image/speech/caption examples do not execute providers or authorize spending.
|
|
101
|
+
|
|
102
|
+
Scene jobs use the editor's existing backend Svelte pipeline, not an image-only MCP bridge. Guidance asks the host to identify useful scene moments from supplied copy, verified narration/cues or approved source inspection, and author `scene.generate` plus `placements`. It does not add automatic video vision/transcription, inline component fields or spending permission. Rebuild/reconnect the API and reinstall updated skills after changing this guidance.
|
|
103
|
+
|
|
104
|
+
Detailed resources also exist at `machinal://reference/<topic>`, `machinal://examples/<id>`, `machinal://skills/editing`, `machinal://skills/credits`, `machinal://skills/media` and `machinal://recipes/guide`. `get_editing_reference(topic: media)` returns the live media workflow and exact argument examples. Setup warns when required media tools are missing, without listing or downloading any customer files. Rebuild the Go API to expose updated resources; reconnect existing clients to refresh initialization instructions. Rerun setup to install the expanded skills; changing customized files still requires separate approval/`--replace-skills`. This source change does not publish a new npm release or replace skills already installed in a user's client.
|
|
105
|
+
|
|
106
|
+
These are real `SKILL.md` files in each client's native discovery directory, not an always-injected prompt or an enforcement mechanism. Clients load relevant skills on demand; permissions, trust and explicit user instructions still apply. Use `--no-skills` to configure MCP only. Existing modified bundled files require separate approval or `--replace-skills`; server `--replace` does not authorize replacing skill files. Only the named bundled files are touched, with backups, and unrelated skills are preserved.
|
|
107
|
+
|
|
108
|
+
### Collaborative video brief
|
|
109
|
+
|
|
110
|
+
For an open-ended new video, editing, recipe and scene skills instruct the agent to ask a short round of unanswered questions about type/goal, duration, destination/aspect **and output resolution**, visual sources/style and audio/text. They use the host's native question tool (OpenCode: `question`) with all unanswered choices in one interactive multi-question form, not a numbered chat questionnaire. Options include relevant existing-photo/footage, generated-image or animated-scene choices and recommendations. After the user's answers, the agent summarizes briefly and starts authorized work immediately, without a separate plan-confirmation round or approval of every covered stage. Known media/spending permissions can be distinct explicit questions in the same form after their scope is explained and live credits checked for paid work; creative choices and cancelled forms grant no permission. Ask again only for a blocker, changed scope or missing permission. Complete briefs, small edits and “you decide” delegation skip unnecessary intake. Clients without an interactive question tool use a compact unnumbered chat fallback; the MCP itself does not render or enforce the host UI, and tool approvals remain enabled.
|
|
111
|
+
|
|
112
|
+
The guide is available live through `get_editing_reference(topic: brief)` / `machinal://reference/brief` and offline in `machinal-editing/references/brief.md`. The instructions discourage automatic production labels in titles/captions/watermarks and repeated AI disclaimers in chat, while preserving honest representation and any requested or specifically required disclosure. The narrated-documentary example uses a subject-relevant chapter heading, not a default production banner.
|
|
113
|
+
|
|
114
|
+
Use the current local source with `node packages/mcp-installer/bin/machinal-mcp.mjs setup` from the repository root to update other installed skills. Rebuild/restart the API and reconnect MCP for new live instructions/topics. Skill installation does not deploy the API, and these instructions guide the host agent rather than enforcing a conversation form on the server.
|
|
115
|
+
|
|
116
|
+
### Persistent MCP defaults
|
|
117
|
+
|
|
118
|
+
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.
|
|
119
|
+
|
|
120
|
+
Connection settings remain separate: rerun setup with `--mode server|local` and the correct `--url`. Server keys come from environment, Windows Credential Manager or hidden entry; independent local uses its own provider profile/device token. Neither connection proves upstream provider credit. Rebuild/reconnect for new API tools.
|
|
121
|
+
|
|
122
|
+
### Later sessions
|
|
123
|
+
|
|
124
|
+
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.
|
|
125
|
+
|
|
126
|
+
The agent has a local **`machinal_connection`** tool even when the remote API is disconnected:
|
|
127
|
+
|
|
128
|
+
- **`status`** discovers approved MCP names/endpoints, actual connection states and credential diagnostics, including the exact Windows 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.
|
|
129
|
+
- **`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.
|
|
130
|
+
- **`replace`** opens a native Windows window with masked entry, a direct <https://direction.al/api-keys> link, **Use saved key**, **Verify and connect**, and Cancel. Saving a replacement requires a separate unchecked-by-default consent checkbox. Verification happens before any overwrite. Cancellation or rejection preserves the previous saved key. No credential is passed through chat, tool inputs, command arguments, plaintext files, or logs.
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
The integration injects discovery/recovery guidance even while the remote MCP is down. Agents use directly exposed tools first, search Code Mode's catalog once for missing tools before declaring them absent, discover the registered server with `status` and immediately try `reconnect` once on discovery/connection/authentication failure, without asking users to find a key or restart OpenCode. Structured `code`/`nextAction` results distinguish rejected/missing keys from unreadable vaults, network failures, rate limits and account restrictions. Only missing/invalid/rejected keys call for offering secure replacement; an unreadable vault is not an absent key. Explicit session-only keys survive reconnects. Recover ambiguous paid jobs before retrying; reconnection is not spending or media consent.
|
|
135
|
+
|
|
136
|
+
The portable **`machinal-support`** skill ships this troubleshooting workflow for later sessions, with client-specific fallbacks when the local tool is not installed. The agent learns the credential's location, not its value; native integration performs the read, never a credential dump or file search.
|
|
137
|
+
|
|
138
|
+
### Native downloads and faster tool access in OpenCode
|
|
139
|
+
|
|
140
|
+
The same OpenCode integration registers **`machinal_download`** as a native tool. It streams files without PowerShell, curl, generated scripts or subprocesses, and displays compact progress rather than source code. This is a client-side integration tool, not a claim that the remote MCP server can write to the user's computer. Other clients retain their own approved transfer mechanisms.
|
|
141
|
+
|
|
142
|
+
After explicit download/destination permission, use one of these argument shapes (replace the illustrative IDs, URL and directory):
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{"projectId":"owned-project","jobId":"0123456789abcdef0123456789abcdef","directory":"C:\\Users\\Alice\\Videos","userApproved":true}
|
|
146
|
+
{"projectId":"owned-project","file":"photo.png","storage":"s3","directory":"C:\\Users\\Alice\\Pictures","userApproved":true}
|
|
147
|
+
{"url":"https://example.org/photo.png","directory":"C:\\Users\\Alice\\Pictures","filename":"photo.png","userApproved":true}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Project downloads can reuse the saved directory; internet downloads require an explicit absolute directory and plain filename. `server` selects an approved MCP registration and is required when several are configured. Project credentials and temporary delivery descriptors stay in integration memory; links and redirects receive no application key. A requested clickable link still uses `get_video_result(delivery:link)` and is never downloaded unasked.
|
|
151
|
+
|
|
152
|
+
Transfers enforce a 2 GiB limit, bounded redirects/timeouts, cancellation, safe filenames, byte-count checks and a SHA-256 digest. Complete files are published atomically without overwriting; interrupted partial files are cleaned up. Internet URLs and every redirect must use HTTPS with public IP addresses, checked during DNS resolution at connection time. Only the exact approved machinal origin may use its configured private/loopback address. Downloads never execute files, import them into a project, bypass authentication, authorize media use or spend credits.
|
|
153
|
+
|
|
154
|
+
Eight small, frequently used MCP tools are exposed directly instead of requiring Code Mode search: `list_projects`, `get_workflow_preferences`, `get_credits`, `get_capabilities`, `get_recipe_schema`, `get_editing_reference`, `wait_for_job`, `get_job_result`. The remaining tools stay in Code Mode to avoid injecting every large schema into every request. Native exposure preserves the existing executor, schema and permission action, and survives MCP catalog refreshes. Agents reuse discovery, cache unchanged schema/reference knowledge and read independent guides concurrently. This removes discovery round trips; it does not accelerate the host's web-search provider or guarantee an overall latency.
|
|
155
|
+
|
|
156
|
+
Each native tool description names its exact effective ID (including custom registration prefixes) and warns against calling it inside `execute`. The prompt hook attaches installed production skills, including `machinal-cinema`, through OpenCode's native skill resolver for explicit English/Romanian video creation/edit requests or selected production skills. It does not rewrite the brief, enable absent skills or grant permissions. Ambiguous requests still require agent judgment; renderer/MCP debugging does not automatically start production. Read the exact chosen film-style source before writing the production contract.
|
|
157
|
+
|
|
158
|
+
Local source plugin updates reload through OpenCode's plugin lifecycle; use `/reload` if its tool list is stale, not a service restart. These changes neither publish npm nor deploy a different Go API.
|
|
159
|
+
|
|
160
|
+
### Recipe files without transfer workarounds
|
|
161
|
+
|
|
162
|
+
The OpenCode integration augments the existing MCP tools while preserving their original executor and permission action:
|
|
163
|
+
|
|
164
|
+
- `get_job_result(..., recipeFile: "D:\\project\\resolved.edit.yaml")` saves the returned `recipeYaml` verbatim as UTF-8 in a **new** file, with a byte-count/SHA-256 receipt. Existing files are never overwritten. A local save failure retains the intact tool result; it never reruns generation.
|
|
165
|
+
- `validate_recipe`, `compile_recipe`, `generate_assets` and `render_video` accept `compositionFile` with an absolute existing `.edit.yaml` path instead of `composition`/`sourceJobId`. The integration reads the exact text with normal host permission and calls the original MCP executor. Existing idempotency, spending approval and stale-review guards remain unchanged.
|
|
166
|
+
- `get_job_result`, `validate_recipe` and `compile_recipe` can save a **new** `checkpointFile` ending in `.checkpoint.json`: compact project/job IDs, automatic composition/text fingerprints and diagnostics. Save the timing result with both `recipeFile` and `checkpointFile`.
|
|
167
|
+
- `captionBaselineFile` on later preflight/generation/render calls reads that checkpoint and applies `expectedCaptionVersion` automatically. This conservative fingerprint covers **all** recipe text entries (not just caption-marked entries) and resolved caption result IDs; scene-internal text is separate. Deliberate recipe text changes require an explicitly authorized updated baseline.
|
|
168
|
+
- Paid calls can read a successful preflight `checkpointFile` and apply `expectedCompositionVersion` automatically. Changed YAML is rejected by the server before submission. Pending generation requirements are allowed for `generate_assets`, not final rendering. Checkpoints never override `userApproved`, idempotency, host permissions or the critic's findings.
|
|
169
|
+
|
|
170
|
+
The API's preflight tools return compact diagnostics, requirements, plan summary, versions and reviews by default. Use `fullResult:true` only for the normalized document/plan/recovery. Targeted reference searches/IDs/pagination omit the repeated guide; `includeGuide:true` restores it, and `guideUri` remains readable separately.
|
|
171
|
+
|
|
172
|
+
This transfers recipe text, not local media. The limit is 2 MiB of valid UTF-8, matching the MCP composition limit. Patch the saved recipe instead of reconstructing captions, passing a path as `composition`, inventing compression codecs or changing namespaces. Other clients retain their normal composition-string/unchanged-`sourceJobId` workflow. `/reload` refreshes the local plugin; deploying API changes remains separate.
|
|
173
|
+
|
|
174
|
+
Conversational approval for the explained workflow is reused through its covered stages. Host tool-permission dialogs remain a separate control and are not disabled by the integration. Intermediate successful stages are not completion or a reason to ask the user to say “continue”; persistent infrastructure errors must identify the exact blocker rather than imply an unexplained model/tool limitation.
|
|
175
|
+
|
|
176
|
+
### Optional Jev intent routing in OpenCode
|
|
177
|
+
|
|
178
|
+
The existing backend router can also select one next tool with Jev's **Choice** primitive. This is an opt-in command in the OpenCode orchestrator, not another tool that the main model must discover and call. Ordinary prompts, job continuations, downloads and the free MCP `suggest_tools` catalog keep their existing behavior.
|
|
179
|
+
|
|
180
|
+
Both Jev strategies and the free MCP catalog share the same video-aware tool intents: choose `generate_assets` for approved missing illustrative artwork when SVG/CSS would be complex or overly simplistic, and `compile_scene` for composing/animating approved images. `image.generate` is a YAML job type, not a callable MCP tool. The production guidance allows 5–10 distinct images across a video when the story needs them (not a quota or cap); four image attachments is a per-scene limit, not a video-wide budget. Routing does not create an image plan, write scenes or authorize generation; the current client still follows the measured timing checkpoint, coverage plan, approved budget and media/spending permissions. No paid router request is needed to read this guidance or use an obvious tool.
|
|
181
|
+
|
|
182
|
+
Add the following **inside the existing plugin's `options`**, preserving `servers` and other settings:
|
|
183
|
+
|
|
184
|
+
```json
|
|
185
|
+
"toolRouting": { "enabled": true, "server": "machinal" }
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Use the actual approved registration name for `server`; it is required when multiple endpoints are registered. Then use, for example:
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
/machinal-route Validate the current recipe before rendering
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Only this command's text is sent to the authenticated backend's existing `/v1/ai/tool-selection` endpoint, then to its configured router provider. Do not include secrets, signed URLs or private file contents. Attachments, conversation history, media bytes, tool results and the application key are not included in the provider's routing state. Existing backend `OPENROUTER_API_KEY` and optional `OPENROUTER_JEV_BASE_URL` / `OPENROUTER_JEV_MODEL` settings are reused; no provider key is stored in OpenCode configuration.
|
|
195
|
+
|
|
196
|
+
The integration checks live credits/pricing, uses the native `machinal_route` permission action and refreshes credits after submission. **Jev routing consumes API credits**, separately from production work; an exact existing tool name such as `/machinal-route wait_for_job` is handled deterministically without a provider call. Paid calls have a three-second client request window, make no automatic retries and return to the main model on outage, invalid output or ambiguity. A timeout can still incur provider usage.
|
|
197
|
+
|
|
198
|
+
Choice includes an explicit `defer` option. A recommendation is accepted only for a registered tool with both provider confidence and selected probability at least 0.8; this is a conservative policy, not a correctness guarantee. Decisions (including failed submissions) are cached in bounded memory for five minutes per session, credential, intent and catalog. Concurrent identical commands share one submission. A new command is required for a new selection: continuations do not call the router or repeatedly inject the same action.
|
|
199
|
+
|
|
200
|
+
The resulting tool ID is supplied once to the main model's context before it runs. The model still resolves the actual schema, arguments and prerequisites. **No tool is executed, hidden, redefined or granted permission by this decision**; it is not an autonomous executor or a replacement for media/spending consent. Pending routing usage remains explicitly pending. This can avoid an explicit `suggest_tools` exchange and reduce main-model selection work, but adds a provider request: it does not eliminate the main-model call or guarantee lower end-to-end latency.
|
|
201
|
+
|
|
202
|
+
Disabled by default. Installing/updating the package does not enable recurring provider calls or change an existing project's configuration. Deploy the updated Go API to support `strategy: "choice"`, then reload the local plugin with `/reload` if necessary. No OpenCode service restart, npm publication or live paid probe is performed by the source change.
|
|
203
|
+
|
|
204
|
+
Optional launchers remain available for Server mode and legacy environment-based setups. Independent local needs no keyed launcher:
|
|
205
|
+
|
|
206
|
+
```sh
|
|
207
|
+
npx @machinal/mcp launch opencode
|
|
208
|
+
npx @machinal/mcp launch claude
|
|
209
|
+
npx @machinal/mcp launch codex
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
`launch` checks sources in order: `MACHINAL_API_KEY`, the saved Windows 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. Newly supplied keys can optionally be remembered on Windows. It launches the already installed client; it does not install that client or modify configuration. Optional client arguments follow `--`:
|
|
213
|
+
|
|
214
|
+
```sh
|
|
215
|
+
npx @machinal/mcp launch codex -- --help
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
OpenCode launches with **`--standalone`** so its private server inherits the key, instead of using an already running shared service with an older environment. `--server` is not supported by this launcher. This does not change global OpenCode service settings.
|
|
219
|
+
|
|
220
|
+
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.
|
|
221
|
+
|
|
222
|
+
### Save, replace, or delete a key on Windows
|
|
223
|
+
|
|
224
|
+
```sh
|
|
225
|
+
npx @machinal/mcp key set
|
|
226
|
+
npx @machinal/mcp key set --url https://YOUR-API/mcp
|
|
227
|
+
npx @machinal/mcp key delete
|
|
228
|
+
npx @machinal/mcp key delete --yes
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
- **`key set`** always asks for a new key with hidden entry, even if `MACHINAL_API_KEY` or a saved key exists, and shows the direct website link for creating one. Confirm to save/replace the credential. Cancelling or entering an invalid key leaves the previous credential unchanged. Replacement writes the new credential directly; it does not delete the old one first.
|
|
232
|
+
- **`key set --url URL`** verifies MCP authentication, tool discovery and read-only live credits **before** offering to overwrite the saved key. A failed check or declined confirmation preserves the existing credential. Use this form to replace a broken/revoked key safely. Without `--url`, only the key's format is checked; `setup` also verifies live API access. No paid operation is submitted.
|
|
233
|
+
- The automatic OpenCode integration detects saved-key changes and reconnects in the existing service. No separate `launch` or OpenCode restart is needed. Other/legacy clients retain their current process environment until restarted through their launcher.
|
|
234
|
+
- **`key delete`** asks before deleting the saved credential. `--yes` explicitly confirms removal for scripts. Deleting an already absent key is a successful no-op. Failure to access the vault is reported as an error, not as successful deletion.
|
|
235
|
+
- There is one saved key per Windows user, shared by this launcher's clients and projects, under service `Machinal/mcp`, account `MACHINAL_API_KEY` (Windows target: `Machinal/mcp.MACHINAL_API_KEY`). It is not scoped to an API URL. Connect only to trusted local/hosted endpoints. Never store a key for someone else's account on a shared Windows login.
|
|
236
|
+
- Deletion removes **only the local saved copy**. It does not revoke the application key, change configuration, clear environment variables, or remove a key from already running clients. Revoke compromised keys on the website.
|
|
237
|
+
- An existing **`MACHINAL_API_KEY` takes precedence**, including after replacement/deletion. Unset it if you want subsequent launcher sessions to use the saved credential.
|
|
238
|
+
- **`--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.
|
|
239
|
+
|
|
240
|
+
Credential Manager is accessed through the optional, pinned `@napi-rs/keyring` native binding. No key is sent through `cmdkey`, subprocess arguments, or plaintext files. If the binding/vault is unavailable, interactive setup/launch offers hidden entry; unattended reads fail with recovery guidance, and `--session-key` or an environment-supplied key still works. A failed optional save is reported and session-only use remains possible. macOS/Linux retain environment/hidden-entry behavior; these commands do not write a plaintext fallback there.
|
|
241
|
+
|
|
242
|
+
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.
|
|
243
|
+
|
|
244
|
+
### Key handling
|
|
245
|
+
|
|
246
|
+
- **Server application keys** are never written to plaintext files, client arguments or output. Persistence is opt-in through Windows Credential Manager. Independent local provider/device secrets are deliberately stored in a private external Docker profile, never client config or the npm tarball.
|
|
247
|
+
- 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.
|
|
248
|
+
- `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.
|
|
249
|
+
- 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.
|
|
250
|
+
- Server login accepts Machinal keys, not PocketBase/service/OpenRouter tokens. Independent local uses its generated device token; OpenRouter is configured on that local backend. Neither implements OAuth.
|
|
251
|
+
|
|
252
|
+
### Scripted setup
|
|
253
|
+
|
|
254
|
+
With `MACHINAL_API_KEY` already supplied securely in the environment:
|
|
255
|
+
|
|
256
|
+
```sh
|
|
257
|
+
npx @machinal/mcp setup --client opencode --scope project --mode hosted --url https://YOUR-API/mcp --style cinematic --yes --no-launch
|
|
258
|
+
npx @machinal/mcp setup --client claude --scope global --mode hosted --url https://YOUR-API/mcp --no-skills --yes --no-launch
|
|
259
|
+
npx @machinal/mcp setup --client codex --mode local --docker-dir /path/to/machinal --start-docker --style tutorial --yes --no-launch
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
For `setup`, `--yes` skips confirmations without launching a client or saving a Server key. It **does not authorize replacing an existing, different server**. Use a new `--name` or explicitly add `--replace`; changed skills need separate `--replace-skills`. Default stdio setup may succeed with Login required/Connection unavailable, explicitly reporting unverified service status. `doctor` exits nonzero until discovery succeeds. Invalid configuration/local provisioning fails nonzero. `key set` is interactive; `key delete --yes` explicitly confirms local credential removal.
|
|
263
|
+
|
|
264
|
+
Unattended setup installs the bundled skills with style `auto` unless `--style` or `--no-skills` is supplied. Changing a previously installed style also changes a bundled preferences file and requires approval or `--replace-skills`. Each file is saved atomically; the whole configuration-plus-skills installation is not one filesystem transaction. If a skill write fails after configuration was saved, setup explicitly reports a partial installation and can be rerun.
|
|
265
|
+
|
|
266
|
+
## Configuration locations
|
|
267
|
+
|
|
268
|
+
| Client | Project | Global |
|
|
269
|
+
| --- | --- | --- |
|
|
270
|
+
| OpenCode V2 | Existing `.opencode/opencode.json(c)` if present; otherwise existing root `opencode.json(c)`, or new `opencode.jsonc` | `$XDG_CONFIG_HOME/opencode/opencode.json(c)` or `~/.config/opencode/opencode.json(c)` |
|
|
271
|
+
| Claude Code | `.mcp.json` | `~/.claude.json` |
|
|
272
|
+
| Codex | `.codex/config.toml` | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` |
|
|
273
|
+
|
|
274
|
+
Defaults: OpenCode `mcp.servers` with `type:local`; Claude `mcpServers` with `type:stdio`; Codex `[mcp_servers.machinal]` with `command`, `args`, `env_vars` and 30/180-second startup/tool timeouts. The command is the resolved Node executable, not `npx.cmd` or a shell; its private runtime survives npm cache cleanup. `--transport http` retains native HTTP/environment syntax. `machinal` is the default name.
|
|
275
|
+
|
|
276
|
+
When setting up `machinal`, a same-endpoint legacy `directional` registration is removed from that configuration and the authentication plugin options. The runtime also suppresses an inherited same-endpoint duplicate and duplicate legacy skills when their machinal replacements exist. Other servers and different endpoints are left untouched. OpenCode merges ancestor and global configuration, so verify the effective registration with `machinal_connection(status)` instead of checking only the project file.
|
|
277
|
+
|
|
278
|
+
| Skill destination | Project | Global |
|
|
279
|
+
| --- | --- | --- |
|
|
280
|
+
| OpenCode V2 | `.opencode/skills` | `$XDG_CONFIG_HOME/opencode/skills` or `~/.config/opencode/skills` |
|
|
281
|
+
| Claude Code | `.claude/skills` | `~/.claude/skills` |
|
|
282
|
+
| Codex | `.agents/skills` | `~/.agents/skills` (not `$CODEX_HOME/skills`) |
|
|
283
|
+
|
|
284
|
+
JSONC comments and unrelated TOML text are preserved. Modified files get a sibling `.machinal-backup-…` copy and are replaced via a temporary file; observed concurrent changes abort the write. New files and backups use mode `0600` on POSIX. Windows access follows filesystem ACLs. Backups may contain credentials that were already in a pre-existing config: protect them as you would that config. Idempotent setup creates no extra backup.
|
|
285
|
+
|
|
286
|
+
Safety limitations:
|
|
287
|
+
|
|
288
|
+
- Existing configurations must be regular files, not symlinks, and at most 2 MiB.
|
|
289
|
+
- Bundled skill files must also be regular files; symlinked skill directories are refused rather than modified through their target.
|
|
290
|
+
- Ambiguous `opencode.json` + `opencode.jsonc` pairs, duplicate JSON keys, and legacy V1 MCP sections must be resolved first. This installer configures V2; it does not migrate V1.
|
|
291
|
+
- Codex edits support standard `[mcp_servers.NAME]` tables and nested tables. Complex inline/dotted server definitions that cannot be changed safely are refused, not rewritten wholesale.
|
|
292
|
+
- Custom `CLAUDE_CONFIG_DIR` is refused for global setup; use project setup or the Claude CLI instead.
|
|
293
|
+
- Higher-precedence ancestor/project/global/managed settings can still override the edited configuration. Verify the effective connection in your client's MCP panel.
|
|
294
|
+
- Claude may require project MCP approval; Codex requires project trust for project configuration.
|
|
295
|
+
|
|
296
|
+
See the repository's [MCP guide](../../docs/MCP.md) for workflows. Independent local is a separate explicit backend profile, not an authorization or billing bypass on existing hosted deployments.
|
|
297
|
+
|
|
298
|
+
## Develop and test without publishing
|
|
299
|
+
|
|
300
|
+
From this directory:
|
|
301
|
+
|
|
302
|
+
```sh
|
|
303
|
+
npm ci --ignore-scripts
|
|
304
|
+
npm run sync:reference
|
|
305
|
+
npm test
|
|
306
|
+
npm run test:clients
|
|
307
|
+
npm run test:package
|
|
308
|
+
node bin/machinal-mcp.mjs --help
|
|
309
|
+
node bin/machinal-mcp.mjs setup
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
Run the last command from the directory whose project configuration you want to edit, using an absolute path to the script if necessary. All automated connection tests use local mock HTTP servers and fake keys, never paid providers or real customer credentials.
|
|
313
|
+
|
|
314
|
+
For project scope, prefer a dedicated project/test folder rather than `D:\` or another filesystem root. OpenCode discovers ancestor configuration, so root-level settings may affect every descendant project. Setup warns when this happens. Version 0.3.1 fixes the Windows `EPERM` caused by attempting `mkdir` on an existing drive root; configuration-write failures now report a specific, sanitized diagnostic after MCP verification.
|
|
315
|
+
|
|
316
|
+
With the package's dependencies installed, you can also start the local wizard from the repository root with `npx --yes ./packages/mcp-installer setup`, without publishing anything.
|
|
317
|
+
|
|
318
|
+
For saved-key management and launch directly from the repository root:
|
|
319
|
+
|
|
320
|
+
```sh
|
|
321
|
+
node packages/mcp-installer/bin/machinal-mcp.mjs key set
|
|
322
|
+
node packages/mcp-installer/bin/machinal-mcp.mjs key set --url http://127.0.0.1:8080/mcp
|
|
323
|
+
node packages/mcp-installer/bin/machinal-mcp.mjs key delete
|
|
324
|
+
node packages/mcp-installer/bin/machinal-mcp.mjs launch opencode
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Automated tests mock credential storage and never read/write the production vault entry. To additionally test the real Windows API with a unique fake credential that is deleted afterward, run in PowerShell:
|
|
328
|
+
|
|
329
|
+
```powershell
|
|
330
|
+
$env:MACHINAL_TEST_CREDENTIAL_MANAGER = '1'
|
|
331
|
+
node --test test/credential-store.test.mjs
|
|
332
|
+
Remove-Item Env:MACHINAL_TEST_CREDENTIAL_MANAGER
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
`sync:reference` vendors the authoritative Go guides/profiles/examples and edit catalog into the self-contained npm package, and generates its reference-file manifest. `npm run check:reference`, tests and `prepack` detect stale/missing copies. Run synchronization after updating the Go knowledge source; do not edit vendored copies independently. Runtime installations need no Go source checkout.
|
|
336
|
+
|
|
337
|
+
`npm run test:package` additionally packs the actual tarball and runs its setup through offline `npx` against a local mock API, checking that styles, scene guidance, catalog and examples are all installed. Install dependencies first so npm's dependency cache is available; the smoke test uses fake keys and never invokes paid tools or publishes to npm.
|
|
338
|
+
|
|
339
|
+
Test the npm executable/tarball path without publishing:
|
|
340
|
+
|
|
341
|
+
```sh
|
|
342
|
+
npm pack --dry-run
|
|
343
|
+
npm pack
|
|
344
|
+
npx --yes --package ./machinal-mcp-0.4.0.tgz machinal-mcp --help
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
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.
|
|
348
|
+
|
|
349
|
+
## Publish
|
|
350
|
+
|
|
351
|
+
An npm account authorized to publish to **`@machinal`** is required. Confirm the package name/scope and intended licensing before the first release (`UNLICENSED` currently makes no open-source license grant). If that scope is unavailable, choose an authorized machinal scope before publishing. Do not substitute a different package with a similar name.
|
|
352
|
+
|
|
353
|
+
```sh
|
|
354
|
+
npm ci --ignore-scripts
|
|
355
|
+
npm test
|
|
356
|
+
npm run test:clients
|
|
357
|
+
npm run test:package
|
|
358
|
+
npm pack --dry-run
|
|
359
|
+
npm publish --access public
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Publishing is a separate, explicit maintainer action. Do not publish credentials, and do not claim the package is available until the registry release succeeds.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { run } from '../src/cli.mjs';
|
|
4
|
+
import { InstallerError } from '../src/errors.mjs';
|
|
5
|
+
import { createLogger } from '../src/presentation.mjs';
|
|
6
|
+
|
|
7
|
+
try {
|
|
8
|
+
process.exitCode = await run();
|
|
9
|
+
} catch (error) {
|
|
10
|
+
if (error?.name === 'ExitPromptError') {
|
|
11
|
+
console.error('Cancelled.');
|
|
12
|
+
process.exitCode = 130;
|
|
13
|
+
} else {
|
|
14
|
+
createLogger({ write: console.error, stream: process.stderr })(error instanceof InstallerError
|
|
15
|
+
? error.message
|
|
16
|
+
: 'Unable to complete setup. Check file permissions, Node.js, and client installation, then retry.', 'error');
|
|
17
|
+
process.exitCode = 1;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { parseArgs } from 'node:util';
|
|
3
|
+
import { serveBridge } from '../src/bridge.mjs';
|
|
4
|
+
|
|
5
|
+
try {
|
|
6
|
+
const { values, positionals } = parseArgs({ allowPositionals: true, options: {
|
|
7
|
+
url: { type: 'string' }, 'local-config': { type: 'string' }, 'catalog-file': { type: 'string' },
|
|
8
|
+
} });
|
|
9
|
+
if (positionals.length !== 1 || positionals[0] !== 'serve' || !values.url) throw new Error('Invalid configuration');
|
|
10
|
+
process.exitCode = await serveBridge({ url: values.url, localConfig: values['local-config'], catalogFile: values['catalog-file'] });
|
|
11
|
+
} catch {
|
|
12
|
+
console.error('Machinal adapter configuration is invalid. Rerun npx @machinal/mcp setup. No credentials were printed.');
|
|
13
|
+
process.exitCode = 1;
|
|
14
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,49 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@machinal/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "Resilient Machinal MCP setup for Codex, Claude Code and OpenCode: independent local or hosted server",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/opencode-plugin/index.mjs"
|
|
8
|
+
},
|
|
9
|
+
"license": "UNLICENSED",
|
|
10
|
+
"engines": {
|
|
11
|
+
"node": "^22.13.0 || >=24.0.0"
|
|
12
|
+
},
|
|
13
|
+
"bin": {
|
|
14
|
+
"machinal-mcp": "bin/machinal-mcp.mjs"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"bin/*.mjs",
|
|
18
|
+
"src/*.mjs",
|
|
19
|
+
"src/*.ps1",
|
|
20
|
+
"src/reference-files.json",
|
|
21
|
+
"src/opencode-plugin/*.mjs",
|
|
22
|
+
"src/opencode-plugin/package.json",
|
|
23
|
+
"skills/",
|
|
24
|
+
"README.md"
|
|
25
|
+
],
|
|
26
|
+
"scripts": {
|
|
27
|
+
"sync:reference": "node scripts/sync-reference.mjs",
|
|
28
|
+
"import:film-library": "node scripts/import-film-library.mjs",
|
|
29
|
+
"check:reference": "node scripts/sync-reference.mjs --check",
|
|
30
|
+
"prepack": "npm run check:reference",
|
|
31
|
+
"test:package": "node --test test/package.smoke.mjs",
|
|
32
|
+
"test:clients": "node --test test/client-detection.smoke.mjs",
|
|
33
|
+
"test": "node --test test/*.test.mjs",
|
|
34
|
+
"prepublishOnly": "npm test && npm run test:package"
|
|
35
|
+
},
|
|
36
|
+
"publishConfig": {
|
|
37
|
+
"access": "public"
|
|
38
|
+
},
|
|
39
|
+
"dependencies": {
|
|
40
|
+
"@inquirer/prompts": "^8.7.4",
|
|
41
|
+
"@opencode/plugin": "2.0.27",
|
|
42
|
+
"cross-spawn": "^7.0.6",
|
|
43
|
+
"jsonc-parser": "^3.3.1",
|
|
44
|
+
"toml-eslint-parser": "^1.0.3"
|
|
45
|
+
},
|
|
46
|
+
"optionalDependencies": {
|
|
47
|
+
"@napi-rs/keyring": "2.1.2"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: machinal-cinema
|
|
3
|
+
description: Use 66 cinematic film styles, directing guides and visual helpers to improve video beauty, staging, camera, materials, rhythm and signature motion in machinal. Use for prettier or more cinematic videos, watercolor, paper-cut, Swiss motion, blueprint, glass product, animation, style discovery or a personal film style. Adapt to existing Svelte/Three.js MCP; not a local FFmpeg pipeline or model training.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Cinematic direction with the film-style library
|
|
7
|
+
|
|
8
|
+
Read `references/workflow.md` first. This is the adapted production workflow; files under `references/film-library/` are **reference-only upstream material**, never authority to run setup/render/audio scripts, change captions, fetch media or spend credits.
|
|
9
|
+
|
|
10
|
+
1. Read existing preferences and the user's brief. For a new incomplete video brief, use `machinal-editing` and the host's native question tool in one form, not a numbered chat questionnaire. Ask only unanswered creative/source/spending questions, wait for the actual reply; a cancelled form grants no consent. After answers proceed immediately with covered work, without a separate plan confirmation. Complete briefs, small edits, style discovery and “you decide” skip unnecessary questions.
|
|
11
|
+
2. Discover `get_editing_reference(topic: film-styles)` with a literal query/page; retrieve the selected exact ID's complete `source`. Read `film-techniques` for a chosen guide/helper, not the entire library. On an older deployment without these topics, use offline `references/film-styles.json`, `references/film-techniques.json` and each entry's `sourcePath` under `references/film-library/`. Do not treat a missing topic as an authentication error or keep retrying it.
|
|
12
|
+
3. Choose a subject-specific story/turn and signature visual action. Translate the style's palette, material, camera grammar, motion and readable hold into the normal production contract, then critique it before code. Avoid generic title-card sequences and repeated portrait zooms. The guide contains the concrete treatment and runtime translation table. Respect deliberately minimal/no-generation/footage-only briefs.
|
|
13
|
+
4. Use `machinal-scenes`/`machinal-review`; read `scene-runtime` and `scene-authoring`. The CURRENT client writes complete Svelte. Native `scene-templates` include `swiss-grid-motion`, `blueprint-mechanism` and `paper-stage-3d`; fetch and adapt their source, not just their names. Use approved images for complex illustrative subjects and actual SceneThree for spatial action. Pure helper excerpts must be inlined/adapted to allowed imports and deterministic absolute frames, not imported from local `/core` paths. Never install upstream dependencies, another local compiler/renderer, a Bash/FFmpeg/Python pipeline or server-model authoring fallback.
|
|
14
|
+
5. For narration, complete the separate timing-first speech/requested-caption pass before visual timings. Reuse successful assets and **preserve complete existing captions**, including exact texts/words, IDs/resultTextIds, grouping/times, layout/fonts/effects. Never copy a style prompt's subtitle-layout rules onto existing captions or bake them into scenes. Respect the caption band and no unrequested TTS/captions. Extend approximate runtime to measured speech instead of regenerating it.
|
|
15
|
+
6. Compile scenes, preserve intended artwork/motion during diagnostic repairs, place actual pinned assets in YAML and implement promised supported effects/transitions. Validate the exact resolved recipe and compare source/editorialReview to the production contract. Review approved diagnostic frames when available; source/plan review is not visual inspection. No automatic paid preview/render loop or claim of verified beauty/audio from a link.
|
|
16
|
+
7. Source lookup and compilation avoid a server-model fee, but server scene-frame rendering AND final encoding remain billed, alongside providers. Check credits and explicit source/spending approval; selection/import is not authorization. Music generation is unsupported: mix only approved existing music. Carry existing approval through completion and requested delivery without asking for “continue”. Host approvals remain enabled.
|
|
17
|
+
|
|
18
|
+
Upstream code/docs: MIT, copyright 2026 LemoLab; pinned revision, file SHA-256 manifest and LICENSE are bundled. No demo footage/stills/voices/music/fonts/models were imported. Keep source attribution outside visible content; no borrowed demo sign-off or AI-production labels. This library does not train the model or guarantee the demo's visual quality. A film-style ID is not a YAML preset, workflow-preference style or compile_scene argument.
|