أدوات MCP وواجهة REST
لدى ReelForge سجل أدوات واحد (packages/studio/src/tools/، ADR-014) يُقدَّم بثلاث طرق: MCP عبر stdio (reelforge mcp)، وMCP Streamable HTTP على /mcp، وREST على /api/v1 في لوحة التحكم (reelforge studio، والعنوان الافتراضي http://127.0.0.1:4310). هذه الصفحة مولّدة من ذلك السجل وتضم 24 أداة. أسماء الأدوات ووسائطها تتبع الإصدار الدلالي (semver). راجع التكامل مع الذكاء الاصطناعي للإعداد والأمان.
ملاحظة: هذه الصفحة مولّدة من الكود. العناوين والشرح بالعربية، أما الأوصاف داخل الجداول فتُقرأ من الكود وتبقى بالإنجليزية.
نقاط وصول REST
| الطريقة والمسار | النتيجة |
|---|---|
GET /api/v1/health | اسم الخادم وإصداره وعدد الأدوات وروابط MCP وOpenAPI وهل الـ token مطلوب |
GET /api/v1/tools | كل أداة مع schema مدخلاتها (وتعيد ?format=openai تعريفات دوال بصيغة OpenAI) |
POST /api/v1/tools/<name> | تشغيل أداة واحدة؛ جسم الطلب هو الوسائط بصيغة JSON. الرد: { ok, result, text, error, images } |
GET /api/v1/openapi.json | مستند OpenAPI 3.1 بعملية واحدة لكل أداة (GPT Actions واستدعاء الدوال) |
POST /mcp | MCP Streamable HTTP (JSON-RPC 2.0) |
GET /.well-known/mcp.json | بطاقة الخادم: طرق الاتصال والـ toolsets والأدوات والمصادقة |
GET /llms.txt, /llms-full.txt | فهرس التوثيق والتوثيق الكامل للنماذج |
أضف ?toolsets=basic,design إلى /mcp و/api/v1/tools و/api/v1/openapi.json للحصول على عدد أقل من الأدوات. عندما يطلب الخادم token، أرسل الترويسة Authorization: Bearer <token> إلى /mcp و/api/v1.
مجموعات الأدوات (toolsets)
| Toolset | الأدوات |
|---|---|
basic | list_episodes, get_episode, create_episode, validate_episode, preview_frames, suggest_scene, set_cues, draft_cues, align_cues, get_render_status, get_guide, list_templates, create_from_template, list_blueprints, add_scene, suggest_scenes |
design | get_episode, edit_episode, write_episode_yaml, list_components, get_component_schema, suggest_scene, get_guide, list_blueprints, add_scene, suggest_scenes |
render | render_episode, get_render_status, cancel_render, open_editor, doctor, get_guide |
all | كل الأدوات |
الأدوات
| الأداة | Toolsets | النوع | العنوان |
|---|---|---|---|
list_episodes | basic | قراءة فقط | List episodes |
get_episode | basic, design | قراءة فقط | Read an episode |
create_episode | basic | يكتب | Create an episode |
edit_episode | design | يكتب | Edit an episode (structured) |
write_episode_yaml | design | قد يحذف أو يستبدل | Replace episode.yaml |
validate_episode | basic | قراءة فقط | Validate an episode |
preview_frames | basic | قراءة فقط | Preview frames |
list_components | design | قراءة فقط | List components |
get_component_schema | design | قراءة فقط | Component props schema |
suggest_scene | basic, design | قراءة فقط | Suggest elements for a line |
set_cues | basic | يكتب | Set cues |
draft_cues | basic | يكتب | Draft cues |
align_cues | basic | يكتب | Align cues to the recording |
render_episode | render | يكتب | Render an episode |
get_render_status | basic, render | قراءة فقط | Render status |
cancel_render | render | يكتب | Cancel the render |
open_editor | render | يكتب | Open the visual editor |
doctor | render | قراءة فقط | Check the environment |
get_guide | basic, design, render | قراءة فقط | Read a guide |
list_templates | basic | قراءة فقط | List episode templates |
create_from_template | basic | يكتب | Create an episode from a template |
list_blueprints | basic, design | قراءة فقط | List scene blueprints |
add_scene | basic, design | يكتب | Add a scene from a blueprint |
suggest_scenes | basic, design | قراءة فقط | Suggest a plan for every line |
list_episodes
List episodes · toolsets: basic · قراءة فقط · POST /api/v1/tools/list_episodes
List every episode in the project (episodes/ and examples/) with title, language, duration, voice/cue status and error count.
بلا وسائط.
get_episode
Read an episode · toolsets: basic, design · قراءة فقط · POST /api/v1/tools/get_episode
Return the full episode.yaml text plus a compiled outline: script lines with ids, start times and words; scenes and elements with their YAML paths, resolved times and boxes; voice/cue status and lint issues. Read this before editing.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") |
create_episode
Create an episode · toolsets: basic · يكتب · POST /api/v1/tools/create_episode
Create episodes/<id>/episode.yaml from the commented template. Optionally give the script (one spoken sentence per entry) to replace the template lines; estimated (draft) cues are written so the episode previews immediately. Then design scenes with edit_episode or write_episode_yaml.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
id | string | نعم | Slug, e.g. "ep10" | |
title | string | |||
series | string | Series name shown in the header | ||
lang | en | ar | Language of the voice-over (default en) | ||
script | string[] | Spoken sentences, one per line |
edit_episode
Edit an episode (structured) · toolsets: design · يكتب · POST /api/v1/tools/edit_episode
Apply structured edits to episode.yaml. Comments and formatting of untouched parts are kept. Operations (applied in order):
- {"op":"set","path":[...],"value":...} sets a value (missing parents are created);
- {"op":"delete","path":[...]} removes a key or list item;
- {"op":"insert","path":[...list],"index":n?,"value":...} inserts into a list (appends without index);
- {"op":"move","path":[...list],"from":i,"to":j} reorders a list. Paths are arrays of keys and 0-based indexes, e.g. ["scenes",0,"elements",2,"props","text"] or ["scenes",1,"elements"] to add an element. Get paths from get_episode. Returns the compile result (errors/warnings) with fix hints and the next step.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
ops | object[] | نعم |
write_episode_yaml
Replace episode.yaml · toolsets: design · قد يحذف أو يستبدل · POST /api/v1/tools/write_episode_yaml
Replace the whole episode.yaml with new YAML text (use for large rewrites; prefer edit_episode for small changes). The file is only written when it parses and has no schema errors, unless force is true.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
yaml | string | نعم | ||
force | boolean | false |
validate_episode
Validate an episode · toolsets: basic · قراءة فقط · POST /api/v1/tools/validate_episode
Run every check (V-1…V-14: schema, cues, timing, pacing, overlaps, off-screen elements, platform safe zones, text overflow measured in the real browser, caption length). Each issue has a line, time and fix hint.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
measure | boolean | true | Measure text overflow headless (slower) |
preview_frames
Preview frames · toolsets: basic · قراءة فقط · POST /api/v1/tools/preview_frames
Render still frames of the episode and return them as images so you can see the result, each with a text layout description (visible elements and their canvas boxes, layers, overlaps between base elements, platform UI zones they touch). Times: seconds (12.5), line ids ("l7" = when line 7 starts), words ("l7:'Idempotency'"), or offsets ("l7+0.8"). Tip: check a moment shortly after elements enter.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
times | string | number[] | نعم | ||
width | integer | 360 | Image width in pixels (height is 16/9 × width; frames are 9:16) |
list_components
List components · toolsets: design · قراءة فقط · POST /api/v1/tools/list_components
Every animated component (name, description, default size). Use get_component_schema for the props of one component.
بلا وسائط.
get_component_schema
Component props schema · toolsets: design · قراءة فقط · POST /api/v1/tools/get_component_schema
JSON Schema of a component's props (types, enums, defaults, required fields).
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
name | icon name (list) | نعم |
suggest_scene
Suggest elements for a line · toolsets: basic, design · قراءة فقط · POST /api/v1/tools/suggest_scene
Suggest on-screen elements for one script line: component, valid props and an enter time on the word that names it (e.g. "race" → lanes, "token bucket" → bucket, numbers → counter). Instant keyword dictionary by default; llm: true asks the configured language model (local or cloud, REELFORGELLM*; optional). Insert a suggestion with edit_episode (op insert into ["scenes", i, "elements"]).
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
line | string | نعم | Script line id, e.g. "l3" | |
llm | boolean | false |
set_cues
Set cues · toolsets: basic · يكتب · POST /api/v1/tools/set_cues
Set the start time (seconds in the voice recording) of script lines, e.g. {"l1": 0.2, "l2": 3.4}. Normally a person marks cues by ear in the studio; use this to apply known timings. Use draft_cues for estimates. Without a recording (silent videos), duration sets the total length; otherwise it grows to fit the last line.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
cues | map | نعم | ||
duration | number | Total length in seconds. Only used when there is no voice recording. |
draft_cues
Draft cues · toolsets: basic · يكتب · POST /api/v1/tools/draft_cues
Write estimated cues (from the text length, scaled to the voice recording if there is one) so the episode can be previewed and rendered before cues are marked by ear.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
overwrite | boolean | false |
align_cues
Align cues to the recording · toolsets: basic · يكتب · POST /api/v1/tools/align_cues
Mark cues automatically from the voice recording: every line start and every word (cues.json, flagged auto). Engine "auto" uses Whisper word timings matched to the known script when the optional speech models are installed (reelforge align --setup), otherwise pause detection (fast, no model). Lines with confidence < 0.5 deserve a listen. Refuses to replace cues marked by hand unless force: true.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
engine | auto | dsp | whisper | "auto" | ||
words | boolean | true | Also place every word | |
force | boolean | false | Replace cues marked by hand |
render_episode
Render an episode · toolsets: render · يكتب · POST /api/v1/tools/render_episode
Start rendering the final videos (master MP4, share MP4, SRT, contact sheet, publish.md in <episode>/out/). Rendering takes minutes: it runs in the background; poll get_render_status. Use silent: true when there is no voice recording.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
preset | string | Platform preset: tiktok, reels, shorts or a preset in presets/ (default: meta.preset) | ||
silent | boolean | false | ||
fast | boolean | false | Quick lower-quality draft | |
shareMb | number | |||
sfx | boolean | true | ||
denoise | boolean | Remove background noise from the voice (default: audio.denoise in episode.yaml) |
get_render_status
Render status · toolsets: basic, render · قراءة فقط · POST /api/v1/tools/get_render_status
Progress of the current/last render, and the files in the episode's out/ folder.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") |
cancel_render
Cancel the render · toolsets: render · يكتب · POST /api/v1/tools/cancel_render
Cancel the running render.
بلا وسائط.
open_editor
Open the visual editor · toolsets: render · يكتب · POST /api/v1/tools/open_editor
Start the ReelForge visual editor for an episode on 127.0.0.1 and return its URL, so a person can review or fine-tune what you made (and mark cues by ear).
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") |
doctor
Check the environment · toolsets: render · قراءة فقط · POST /api/v1/tools/doctor
Check Node.js, FFmpeg, the rendering Chromium and fonts.
بلا وسائط.
get_guide
Read a guide · toolsets: basic, design, render · قراءة فقط · POST /api/v1/tools/get_guide
Task guides for working with ReelForge (writing scripts, designing scenes, layout, cues, rendering…). detail false (default) gives the short version: what the guide is for and its first section or checklist; detail true gives the whole guide and lists its references ("<topic>/<reference>" reads one). Call without a topic (or with an unknown one) to list the topics.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
topic | string | Guide name, e.g. "make-video"; "<topic>/<reference>" for a reference | ||
detail | boolean | false | Return the full guide instead of the summary |
list_templates
List episode templates · toolsets: basic · قراءة فقط · POST /api/v1/tools/list_templates
Ready-made episodes by industry (healthcare, real estate, ports, education, finance…). Each template has a few slots (short texts and numbers). Pick one, then call create_from_template with the slot values: the easiest way to make a good video.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
pack | string | Only this pack (industry id) | ||
lang | en | ar | "en" | Language of the episode (en or ar) |
create_from_template
Create an episode from a template · toolsets: basic · يكتب · POST /api/v1/tools/create_from_template
Create episodes/<id>/ from an industry template by filling its slots (a flat object of short texts, numbers or colors; see list_templates). Missing slots keep their defaults. Draft cues are written so it previews immediately.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
id | string | نعم | ||
pack | string | نعم | ||
template | string | نعم | ||
lang | en | ar | "en" | Language of the episode (en or ar) | |
slots | map | {} | Slot values by name, e.g. |
list_blueprints
List scene blueprints · toolsets: basic, design · قراءة فقط · POST /api/v1/tools/list_blueprints
Named scene designs (hook, problem-solution, stat-reveal, comparison, process-steps, timeline, before-after, quote, cta…) with their parameters and an example. Use one with add_scene.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
name | string | Only this blueprint, with its full schema |
add_scene
Add a scene from a blueprint · toolsets: basic, design · يكتب · POST /api/v1/tools/add_scene
Add a complete scene to an episode from a named blueprint (see list_blueprints) and a few parameters. params.line is the script line the scene starts on; the scene is placed in time order and replaces an existing scene on the same line when replace is true.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") | |
blueprint | string | نعم | ||
params | map | نعم | Blueprint parameters, including "line" (e.g. "l3") | |
replace | boolean | false | Replace a scene that starts on the same line |
suggest_scenes
Suggest a plan for every line · toolsets: basic, design · قراءة فقط · POST /api/v1/tools/suggest_scenes
A deterministic scene plan for the whole script (no model needed): for each line, a fitting blueprint for add_scene and the best single element for edit_episode. Good first step after create_episode.
| الوسيط | النوع | إلزامي | الافتراضي | الوصف |
|---|---|---|---|---|
episode | string | نعم | Episode id (e.g. "ep10") or path relative to the project root (e.g. "examples/season1/ep02") |