@vibeframe/mcp-server 0.113.0 → 0.113.3
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 +131 -120
- package/dist/index.js +1852 -660
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,18 +1,29 @@
|
|
|
1
1
|
# @vibeframe/mcp-server
|
|
2
2
|
|
|
3
|
-
The MCP (Model Context Protocol) **server** for [VibeFrame](https://github.com/vericontext/vibeframe). This package is
|
|
3
|
+
The MCP (Model Context Protocol) **server** for [VibeFrame](https://github.com/vericontext/vibeframe). This package is _only_ the MCP adapter — it exposes VibeFrame's operations as typed MCP tools so an MCP-capable host can call them by natural language.
|
|
4
4
|
|
|
5
5
|
VibeFrame is CLI-first, not terminal-only. The CLI is the stable runtime; MCP is the app-host surface for clients that prefer typed tools over shell commands.
|
|
6
6
|
|
|
7
7
|
Confirmed MCP hosts today: **Claude Desktop**, **Cursor**, and **Claude Code**. Codex can drive `vibe` natively via shell + `AGENTS.md`, and can also load a project-scoped MCP server through `.codex/config.toml`. For other shell-capable hosts, use [`@vibeframe/cli`](https://www.npmjs.com/package/@vibeframe/cli) directly — same operations.
|
|
8
8
|
|
|
9
|
+
For long-running video builds, use the host's native goal mode as the outer
|
|
10
|
+
loop: Codex `/goal`, Claude Code `/goal`, Cursor's agent loop, or the host
|
|
11
|
+
equivalent. VibeFrame's MCP tools provide the inner video runtime: JSON-style
|
|
12
|
+
results, dry-run/cost gates, `build-report.json`, `review-report.json`,
|
|
13
|
+
`retryWith`, `fixOwner`, deterministic repair, and render inspection.
|
|
14
|
+
|
|
9
15
|
> **Just want a CLI?** Use [`@vibeframe/cli`](https://www.npmjs.com/package/@vibeframe/cli) instead — same operations, invoked directly in your shell as `vibe <command>`. This package and the CLI wrap the same underlying engine; pick whichever fits your workflow. Many users install both.
|
|
10
16
|
|
|
11
|
-
| Surface
|
|
12
|
-
|
|
13
|
-
| MCP host (Claude Desktop / Cursor / OpenCode / Claude Code)
|
|
14
|
-
| Shell / scripts (any agent host: Codex / Aider / Gemini CLI / etc.) | `@vibeframe/cli`
|
|
15
|
-
| Optional standalone agent REPL
|
|
17
|
+
| Surface | Package | How you call it |
|
|
18
|
+
| ------------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------- |
|
|
19
|
+
| MCP host (Claude Desktop / Cursor / OpenCode / Claude Code) | `@vibeframe/mcp-server` _(this)_ | host calls tool by name, for example `mcp__vibeframe__build({...})` |
|
|
20
|
+
| Shell / scripts (any agent host: Codex / Aider / Gemini CLI / etc.) | `@vibeframe/cli` | `vibe init my-video && vibe build my-video && vibe render my-video` |
|
|
21
|
+
| Optional standalone agent REPL | `@vibeframe/cli` (`vibe agent`) | natural language -> CLI calls when you do not already use Claude Code/Codex/Cursor/etc. |
|
|
22
|
+
|
|
23
|
+
Native goal stop rules should be explicit: final MP4 path exists, duration and
|
|
24
|
+
aspect ratio match the brief, render inspection has no errors, any AI review score
|
|
25
|
+
meets the goal threshold when AI review is requested, and every `fixOwner:"host-agent"` issue is fixed,
|
|
26
|
+
accepted with rationale, or reported as blocked.
|
|
16
27
|
|
|
17
28
|
The tool list below is what the MCP host sees. The same operations exist as `vibe <verb> <noun>` subcommands in the CLI — see `vibe --help`.
|
|
18
29
|
|
|
@@ -147,13 +158,13 @@ The server prefers asking over silently picking defaults:
|
|
|
147
158
|
Once connected, your MCP host can resolve prompts like these into typed tool calls:
|
|
148
159
|
|
|
149
160
|
> "Scaffold a 12-second Swiss-Pulse promo project, three beats, and render it"
|
|
150
|
-
>
|
|
161
|
+
> _→ `init` + 3× `scene_add` + `render`_
|
|
151
162
|
|
|
152
163
|
> "Generate a cinematic backdrop image, animate it for 5 seconds, add narration"
|
|
153
|
-
>
|
|
164
|
+
> _→ `generate_image` + `generate_video` + `generate_speech`_
|
|
154
165
|
|
|
155
166
|
> "Remove silent segments and add captions to my interview"
|
|
156
|
-
>
|
|
167
|
+
> _→ `edit_silence_cut` + `edit_caption`_
|
|
157
168
|
|
|
158
169
|
## Available Tools
|
|
159
170
|
|
|
@@ -161,165 +172,165 @@ Tool names are MCP-side. Your host typically prefixes them (e.g. Claude shows th
|
|
|
161
172
|
|
|
162
173
|
### Project flow (top-level)
|
|
163
174
|
|
|
164
|
-
| Tool
|
|
165
|
-
|
|
166
|
-
| `project_list` | List workspace video projects with build/render status (`_archive/` skipped)
|
|
167
|
-
| `init`
|
|
168
|
-
| `build`
|
|
169
|
-
| `render`
|
|
175
|
+
| Tool | Description |
|
|
176
|
+
| -------------- | ------------------------------------------------------------------------------- |
|
|
177
|
+
| `project_list` | List workspace video projects with build/render status (`_archive/` skipped) |
|
|
178
|
+
| `init` | Scaffold a video project with `STORYBOARD.md` + `DESIGN.md` |
|
|
179
|
+
| `build` | Build a storyboard project: narration TTS, image assets, scene HTML composition |
|
|
180
|
+
| `render` | Deterministic Hyperframes render → MP4/WebM/MOV |
|
|
170
181
|
|
|
171
182
|
### Scene authoring (lower-level)
|
|
172
183
|
|
|
173
|
-
| Tool
|
|
174
|
-
|
|
175
|
-
| `scene_list_styles`
|
|
176
|
-
| `scene_add`
|
|
177
|
-
| `scene_install_skill`
|
|
178
|
-
| `scene_lint`
|
|
179
|
-
| `scene_compose_prompts` | Emit the per-beat compose plan without making an LLM call
|
|
184
|
+
| Tool | Description |
|
|
185
|
+
| ----------------------- | ------------------------------------------------------------------------------- |
|
|
186
|
+
| `scene_list_styles` | List the 8 vendored visual identities (Swiss Pulse, Data Drift, …) or fetch one |
|
|
187
|
+
| `scene_add` | Append a beat (narration + backdrop + composed HTML) |
|
|
188
|
+
| `scene_install_skill` | Install the Hyperframes skill bundle into a scene project |
|
|
189
|
+
| `scene_lint` | Validate composition HTML against the visual identity |
|
|
190
|
+
| `scene_compose_prompts` | Emit the per-beat compose plan without making an LLM call |
|
|
180
191
|
|
|
181
192
|
### Generation (13)
|
|
182
193
|
|
|
183
|
-
| Tool
|
|
184
|
-
|
|
185
|
-
| `generate_image`
|
|
186
|
-
| `generate_background`
|
|
187
|
-
| `generate_video`
|
|
188
|
-
| `generate_video_status` / `_cancel` / `_extend` | Manage long-running video jobs
|
|
189
|
-
| `generate_motion`
|
|
190
|
-
| `generate_speech`
|
|
191
|
-
| `generate_music`
|
|
192
|
-
| `generate_music_status`
|
|
193
|
-
| `generate_sound_effect`
|
|
194
|
-
| `generate_thumbnail`
|
|
195
|
-
| `generate_storyboard`
|
|
194
|
+
| Tool | Description | Providers |
|
|
195
|
+
| ----------------------------------------------- | --------------------------------------------- | ---------------------------------------------------- |
|
|
196
|
+
| `generate_image` | Text-to-image | OpenAI, Google, Stability |
|
|
197
|
+
| `generate_background` | Cinematic backdrop image (video-tuned prompt) | OpenAI |
|
|
198
|
+
| `generate_video` | Text/image-to-video (long-running) | Seedance via fal.ai, Grok, Kling, Runway, Google Veo |
|
|
199
|
+
| `generate_video_status` / `_cancel` / `_extend` | Manage long-running video jobs | (provider-specific) |
|
|
200
|
+
| `generate_motion` | Generate standalone designed motion graphics | Claude or Gemini + Remotion |
|
|
201
|
+
| `generate_speech` | Text-to-speech | ElevenLabs |
|
|
202
|
+
| `generate_music` | AI background music | Suno, ElevenLabs, Replicate MusicGen |
|
|
203
|
+
| `generate_music_status` | Poll Replicate music task | Replicate |
|
|
204
|
+
| `generate_sound_effect` | SFX from prompt | ElevenLabs |
|
|
205
|
+
| `generate_thumbnail` | AI thumbnail composition | OpenAI, Google |
|
|
206
|
+
| `generate_storyboard` | Multi-beat storyboard frames | OpenAI, Google |
|
|
196
207
|
|
|
197
208
|
### Editing (16)
|
|
198
209
|
|
|
199
|
-
| Tool
|
|
200
|
-
|
|
201
|
-
| `edit_silence_cut`
|
|
202
|
-
| `edit_jump_cut`
|
|
203
|
-
| `edit_caption` / `edit_animated_caption` | Burn styled / animated captions
|
|
204
|
-
| `edit_text_overlay`
|
|
205
|
-
| `edit_motion_overlay`
|
|
206
|
-
| `edit_fade`
|
|
207
|
-
| `edit_grade`
|
|
208
|
-
| `edit_speed_ramp`
|
|
209
|
-
| `edit_reframe`
|
|
210
|
-
| `edit_interpolate`
|
|
211
|
-
| `edit_upscale`
|
|
212
|
-
| `edit_image`
|
|
213
|
-
| `edit_noise_reduce`
|
|
214
|
-
| `edit_translate_srt`
|
|
215
|
-
| `edit_fill_gaps`
|
|
210
|
+
| Tool | Description |
|
|
211
|
+
| ---------------------------------------- | -------------------------------------------------------------------------------- |
|
|
212
|
+
| `edit_silence_cut` | Remove silent segments (FFmpeg or Gemini) |
|
|
213
|
+
| `edit_jump_cut` | Remove filler words (Whisper) |
|
|
214
|
+
| `edit_caption` / `edit_animated_caption` | Burn styled / animated captions |
|
|
215
|
+
| `edit_text_overlay` | Simple static text burn-in |
|
|
216
|
+
| `edit_motion_overlay` | Designed animated overlays or user-provided Lottie overlays |
|
|
217
|
+
| `edit_fade` | Fade in/out |
|
|
218
|
+
| `edit_grade` | Color grading |
|
|
219
|
+
| `edit_speed_ramp` | Variable-speed segments |
|
|
220
|
+
| `edit_reframe` | Aspect-ratio reframe (e.g. 16:9 → 9:16) |
|
|
221
|
+
| `edit_interpolate` | Frame interpolation / slow-mo |
|
|
222
|
+
| `edit_upscale` | AI upscaling |
|
|
223
|
+
| `edit_image` | Image editing (gpt-image-2, Gemini) |
|
|
224
|
+
| `edit_noise_reduce` | Audio/video denoise |
|
|
225
|
+
| `edit_translate_srt` | Translate SRT subtitles |
|
|
226
|
+
| `edit_fill_gaps` | Detect & fill missing video segments via TTS narration timing (Plan G — Phase 4) |
|
|
216
227
|
|
|
217
228
|
### Audio (5)
|
|
218
229
|
|
|
219
|
-
| Tool
|
|
220
|
-
|
|
221
|
-
| `audio_dub`
|
|
222
|
-
| `audio_clone_voice` | Voice clone from sample
|
|
223
|
-
| `audio_isolate`
|
|
224
|
-
| `audio_duck`
|
|
225
|
-
| `audio_transcribe`
|
|
230
|
+
| Tool | Description |
|
|
231
|
+
| ------------------- | ------------------------------------------- |
|
|
232
|
+
| `audio_dub` | AI voice dubbing (ElevenLabs) |
|
|
233
|
+
| `audio_clone_voice` | Voice clone from sample |
|
|
234
|
+
| `audio_isolate` | Vocal / background isolation |
|
|
235
|
+
| `audio_duck` | Auto-duck BGM under speech |
|
|
236
|
+
| `audio_transcribe` | Transcript with word-level timing (Whisper) |
|
|
226
237
|
|
|
227
238
|
### Detection (3)
|
|
228
239
|
|
|
229
|
-
| Tool
|
|
230
|
-
|
|
240
|
+
| Tool | Description |
|
|
241
|
+
| ---------------- | -------------------- |
|
|
231
242
|
| `detect_silence` | Find silent segments |
|
|
232
|
-
| `detect_scenes`
|
|
233
|
-
| `detect_beats`
|
|
243
|
+
| `detect_scenes` | Find shot boundaries |
|
|
244
|
+
| `detect_beats` | Find music beats |
|
|
234
245
|
|
|
235
246
|
### Inspection (4)
|
|
236
247
|
|
|
237
|
-
| Tool
|
|
238
|
-
|
|
239
|
-
| `inspect_media`
|
|
240
|
-
| `inspect_video`
|
|
241
|
-
| `inspect_review`
|
|
248
|
+
| Tool | Description |
|
|
249
|
+
| ----------------- | ----------------------------------------------------------------------- |
|
|
250
|
+
| `inspect_media` | Unified image / video / YouTube analysis (Gemini) |
|
|
251
|
+
| `inspect_video` | Temporal video understanding (Gemini) |
|
|
252
|
+
| `inspect_review` | AI video review + auto-fix suggestions |
|
|
242
253
|
| `inspect_suggest` | Natural-language project edit suggestions (Gemini); optional auto-apply |
|
|
243
254
|
|
|
244
255
|
### Timeline (10)
|
|
245
256
|
|
|
246
|
-
| Tool
|
|
247
|
-
|
|
248
|
-
| `timeline_create` / `timeline_info`
|
|
249
|
-
| `timeline_add_source`
|
|
250
|
-
| `timeline_add_clip` / `_split_clip` / `_trim_clip`
|
|
251
|
-
| `timeline_move_clip` / `_duplicate_clip` / `_delete_clip` | Arrange clips
|
|
252
|
-
| `timeline_add_track`
|
|
253
|
-
| `timeline_add_effect`
|
|
254
|
-
| `timeline_list`
|
|
257
|
+
| Tool | Description |
|
|
258
|
+
| --------------------------------------------------------- | ----------------------------------------------- |
|
|
259
|
+
| `timeline_create` / `timeline_info` | Create or inspect low-level timeline JSON state |
|
|
260
|
+
| `timeline_add_source` | Import media (video/audio/image) |
|
|
261
|
+
| `timeline_add_clip` / `_split_clip` / `_trim_clip` | Build & shape clips |
|
|
262
|
+
| `timeline_move_clip` / `_duplicate_clip` / `_delete_clip` | Arrange clips |
|
|
263
|
+
| `timeline_add_track` | Add video/audio track |
|
|
264
|
+
| `timeline_add_effect` | Apply effect (fade, blur, …) |
|
|
265
|
+
| `timeline_list` | List all project contents |
|
|
255
266
|
|
|
256
267
|
### Compatibility & Export
|
|
257
268
|
|
|
258
|
-
| Tool
|
|
259
|
-
|
|
269
|
+
| Tool | Description |
|
|
270
|
+
| --------------------------------- | -------------------------------------------------------- |
|
|
260
271
|
| `project_create` / `project_info` | Deprecated compatibility aliases for timeline JSON state |
|
|
261
|
-
| `export_video`
|
|
272
|
+
| `export_video` | Export timeline JSON to MP4/WebM/MOV via FFmpeg |
|
|
262
273
|
|
|
263
274
|
### Remix & pipelines (4)
|
|
264
275
|
|
|
265
|
-
| Tool
|
|
266
|
-
|
|
267
|
-
| `run`
|
|
268
|
-
| `remix_highlights`
|
|
269
|
-
| `remix_auto_shorts`
|
|
276
|
+
| Tool | Description |
|
|
277
|
+
| ------------------------ | ------------------------------------------------------------------- |
|
|
278
|
+
| `run` | Execute a multi-stage YAML pipeline (`vibe run pipeline.yaml`) |
|
|
279
|
+
| `remix_highlights` | Long-form → highlight clips |
|
|
280
|
+
| `remix_auto_shorts` | Long-form → vertical shorts |
|
|
270
281
|
| `remix_regenerate_scene` | Re-render a single scene against an existing storyboard.{yaml,json} |
|
|
271
282
|
|
|
272
283
|
### Guides (1)
|
|
273
284
|
|
|
274
|
-
| Tool
|
|
275
|
-
|
|
285
|
+
| Tool | Description |
|
|
286
|
+
| ------- | ------------------------------------------------------------------------- |
|
|
276
287
|
| `guide` | Cross-host guides for motion, scene, pipeline, and architecture workflows |
|
|
277
288
|
|
|
278
289
|
> **CLI ↔ MCP sync**: `packages/mcp-server/src/tools/cli-sync.test.ts` is a vitest hook that fails CI when a CLI subcommand is added/removed/renamed without the matching MCP change. Open the test file to see the live mapping table — `null` rows mark CLI-only commands (e.g. `vibe audio list-voices`, `vibe timeline set`) that are intentionally not exposed via MCP.
|
|
279
290
|
|
|
280
291
|
## Resources
|
|
281
292
|
|
|
282
|
-
| URI
|
|
283
|
-
|
|
284
|
-
| `vibe://project/current`
|
|
285
|
-
| `vibe://project/clips`
|
|
286
|
-
| `vibe://project/sources`
|
|
287
|
-
| `vibe://project/tracks`
|
|
288
|
-
| `vibe://project/settings` | Project settings
|
|
293
|
+
| URI | Description |
|
|
294
|
+
| ------------------------- | ------------------ |
|
|
295
|
+
| `vibe://project/current` | Full project state |
|
|
296
|
+
| `vibe://project/clips` | All clips |
|
|
297
|
+
| `vibe://project/sources` | Media sources |
|
|
298
|
+
| `vibe://project/tracks` | Track list |
|
|
299
|
+
| `vibe://project/settings` | Project settings |
|
|
289
300
|
|
|
290
301
|
## Prompts
|
|
291
302
|
|
|
292
|
-
| Prompt
|
|
293
|
-
|
|
294
|
-
| `edit_video`
|
|
295
|
-
| `create_montage`
|
|
296
|
-
| `add_transitions`
|
|
297
|
-
| `color_grade`
|
|
298
|
-
| `generate_subtitles` | Subtitles via AI transcription
|
|
299
|
-
| `create_shorts`
|
|
300
|
-
| `sync_to_music`
|
|
303
|
+
| Prompt | Description |
|
|
304
|
+
| -------------------- | ------------------------------------- |
|
|
305
|
+
| `edit_video` | Natural-language editing instructions |
|
|
306
|
+
| `create_montage` | Montage with automatic pacing |
|
|
307
|
+
| `add_transitions` | Add transitions between clips |
|
|
308
|
+
| `color_grade` | Apply color grading |
|
|
309
|
+
| `generate_subtitles` | Subtitles via AI transcription |
|
|
310
|
+
| `create_shorts` | Short-form from longer video |
|
|
311
|
+
| `sync_to_music` | Cut to music beats |
|
|
301
312
|
|
|
302
313
|
## Environment Variables
|
|
303
314
|
|
|
304
315
|
API keys are read from the host's environment (`~/.zshrc`, MCP config `env` block, etc.). All optional — only set the ones whose providers you use.
|
|
305
316
|
|
|
306
|
-
| Variable
|
|
307
|
-
|
|
308
|
-
| `OPENAI_API_KEY`
|
|
309
|
-
| `ANTHROPIC_API_KEY`
|
|
310
|
-
| `GOOGLE_API_KEY`
|
|
311
|
-
| `ELEVENLABS_API_KEY`
|
|
312
|
-
| `XAI_API_KEY`
|
|
313
|
-
| `FAL_API_KEY`
|
|
314
|
-
| `RUNWAY_API_SECRET`
|
|
315
|
-
| `KLING_API_KEY`
|
|
316
|
-
| `IMGBB_API_KEY`
|
|
317
|
-
| `VIBE_UPLOAD_PROVIDER`
|
|
318
|
-
| `VIBE_UPLOAD_S3_BUCKET`
|
|
319
|
-
| `VIBE_UPLOAD_S3_PREFIX`
|
|
320
|
-
| `VIBE_UPLOAD_TTL_SECONDS`
|
|
321
|
-
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` | S3 upload host credentials
|
|
322
|
-
| `VIBE_PROJECT_PATH`
|
|
317
|
+
| Variable | Used by |
|
|
318
|
+
| ------------------------------------------------------------ | -------------------------------------------------------------- |
|
|
319
|
+
| `OPENAI_API_KEY` | gpt-image-2, Whisper, GPT |
|
|
320
|
+
| `ANTHROPIC_API_KEY` | Claude (translate-srt, highlights, build compose pipeline) |
|
|
321
|
+
| `GOOGLE_API_KEY` | Gemini (analyze, review, silence-cut, narrate) |
|
|
322
|
+
| `ELEVENLABS_API_KEY` | TTS, voice-clone, dubbing, SFX |
|
|
323
|
+
| `XAI_API_KEY` | Grok |
|
|
324
|
+
| `FAL_API_KEY` | Seedance image-to-video |
|
|
325
|
+
| `RUNWAY_API_SECRET` | Runway video |
|
|
326
|
+
| `KLING_API_KEY` | Kling video |
|
|
327
|
+
| `IMGBB_API_KEY` | Default temporary image host for Seedance/Kling image-to-video |
|
|
328
|
+
| `VIBE_UPLOAD_PROVIDER` | `imgbb` (default) or `s3` for temporary image uploads |
|
|
329
|
+
| `VIBE_UPLOAD_S3_BUCKET` | S3 bucket when `VIBE_UPLOAD_PROVIDER=s3` |
|
|
330
|
+
| `VIBE_UPLOAD_S3_PREFIX` | Optional S3 key prefix for temporary image uploads |
|
|
331
|
+
| `VIBE_UPLOAD_TTL_SECONDS` | Optional TTL hint for temporary upload URLs |
|
|
332
|
+
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` | S3 upload host credentials |
|
|
333
|
+
| `VIBE_PROJECT_PATH` | Default timeline JSON path for resources |
|
|
323
334
|
|
|
324
335
|
## Requirements
|
|
325
336
|
|