
beatdesign
Operate a local BeatDesign Canvas and video Editor through MCP.
- version
- 0.2.5
- GitHub stars
- 366
Install
/plugin install beatdesign@beatdesignRun it inside Claude Code after adding the marketplace with /plugin marketplace add BeatAPI/BeatDesign.
Contents
Discovered from sourceSkills 1
BeatDesign workspace
Use BeatDesign MCP as the semantic control plane and the BeatDesign browser workspace as the review surface. Both operate the same local Project, Assets, Canvas, Timeline, and command history.
Establish the visible project
- If BeatDesign tools are unavailable, tell the user to run
pnpm dev:agentin their BeatDesign clone, then reconnect the plugin from/mcp. - Call
bdesign_project_listwhen the target project is not unambiguous. - Call
bdesign_project_targetonce. Later project-scoped tools may omitprojectIdfor this MCP session. - Call
bdesign_project_opennear the start with the view that matches the task. Preserve itsworkspaceUrlas the visible review handoff. - For Canvas review, call
bdesign_canvas_viewwith the changedcardId. For timeline review, callbdesign_editor_viewat the relevant time.
Open the returned workspaceUrl when the host provides a browser or preview
surface. Otherwise return the exact URL to the user; do not claim the page was
opened when the host cannot open it.
Change the shared project safely
- Read the current Canvas or Editor state before editing.
- Use incremental Canvas and Editor operations with stable IDs and one stable idempotency key. Never replace a complete Canvas or Timeline document.
- If a result still includes
retry, read the newest state and follow that instruction once. Do not busy-loop. - Import local media through
bdesign_asset_importbefore referencing it from Canvas or Editor. - Treat generation as asset-first: output becomes a Project Asset before it is placed on Canvas or Editor.
Update project settings
- Call
bdesign_project_getand usesettings.settingsRevisionas the expected revision forbdesign_project_update. Settings revisions are separate from Canvas and Editor revisions. - Update only the requested name, description or cover. A manual cover must be
an image Asset in this Project; import a local image first when needed. Use
cover: { "mode": "auto" }to restore automatic cover selection. - Reuse the command ID and idempotency key when delivery is uncertain. On a revision conflict, read the latest settings and resolve the conflicting edit before submitting again; do not overwrite another change blindly.
- Read the saved settings back and inspect the project card or workspace header. Project settings refresh while visible within about five seconds.
Organize assets and reuse workflows
- Discover the installed tool catalog first; organization tools are available in current source and are not included in the published v0.2.5 runtime.
- Use
bdesign_organization_get/bdesign_asset_queryfor folders and versioned Elements. Folder changes are logical; they do not move media files. - Apply semantic operations with explicit command ID, idempotency key and the correct expected revision. Organization, Canvas and template revisions are separate. On a semantic conflict, read and review again; do not adopt a newer revision automatically. Reuse the original envelope if delivery is uncertain.
- Element references pin exact Asset/version IDs. Changing the current version does not silently replace existing references or Timeline clips.
- Use
bdesign_workflow_template_previewbefore capture/instantiation, thenbdesign_workflow_template_apply. Keep the reviewed digest and source revision. Insertions create editable drafts only; missing required slots block generation. - Inspect the result in Canvas/Assets. Use
bdesign_timeline_usageto check actual pinned Timeline usage. Organizing, previewing or loading a template must never trigger generation or upload.
Import captions
- Prefer
bdesign_editor_import_srtfor a file or complete SRT text. Usebdesign_editor_editwithupsert_captiononly for targeted cue changes. - A malformed SRT import leaves saved captions unchanged. Report the parse error instead of clearing or partially replacing the track.
- After import, call
bdesign_editor_viewat the first relevant cue and ask the user to inspect text, timing, wrapping, and line breaks in the Editor.
Continue from a video's tail frame
- Call
bdesign_canvas_continue_from_tailwith one stable command ID. Reuse that ID if delivery is uncertain so retries reuse the derived frame Asset and continuation node. - Call the returned review tool before generation so the extracted frame and continuation node can be inspected.
- If frame extraction reports that
ffmpegis unavailable, stop and explain that the BeatDesign MCP process needsffmpegonPATHor an absoluteBEATDESIGN_FFMPEGvalue. - Tail-frame extraction and Canvas placement are local deterministic work. The returned generation request is a separate remote action: submit it only when the user authorized that generation and its provider cost.
- A successful generation creates an Asset but does not place itself. Update
the returned generation card with that output through
bdesign_canvas_apply, then focus the same card withbdesign_canvas_view.
Export the authoritative timeline
- When the user authorizes an export, call
bdesign_editor_get, then callbdesign_editor_renderwith the returned revision. The result is a project-owned MP4 Asset containing visible clips, image overlays, caption burn-in, and mixed audio. - If rendering reports that
ffmpegorffprobeis unavailable, stop and explain that the MCP process needs those binaries onPATH, or absoluteBEATDESIGN_FFMPEGandBEATDESIGN_FFPROBEpaths. - Render-affecting edits invalidate the previous current render without deleting its historical Asset. If the timeline changes while rendering, read the latest revision and ask before starting another render.
Verify the visible result
After a write, read the returned revision and changed IDs. Canvas and Editor
currently refresh external revisions within about two seconds and on focus.
Use the relevant view tool and leave the user with the exact workspaceUrl.
A database revision alone is not proof of a successful visible operation.
Do not export, submit a paid generation, or create extra variants unless the user's request clearly authorizes that exact action.
MCP servers 1
Sponsors
Details
- Marketplace
- BeatAPI/BeatDesign
- Source
- integrations/claude-code/beatdesign
- Author
- BeatAPI
- Category
- Community