AI Agents
MCP 工具参考
SimpliGen MCP 服务器暴露给 AI 代理的工具，以及它们后面的本地控制 API。
SimpliGen 搭配一个 MCP 服务器（@simpligen/mcp），通过本地的令牌认证连接将 AI 代理连接到运行中的 SimpliGen 应用。代理调用 MCP 工具；服务器将它们转发到应用的本地控制 API。请参阅连接一个代理来设置此功能。
工具
| 工具 | 功能 |
|---|---|
list_capabilities | 列出代理可以生成的每个预设（图像或视频），其输入和选项，是否已在本地准备好，以及云端资格和信用成本。 |
get_status | 报告引擎状态、云端是否已连接、信用余额、活跃项目，以及 characters 能力块（启用标志、基础/编辑/i2v 的已安装预设计数，以及 enhancePresets，已安装的升级预设数量）。 |
start_engine | 启动本地引擎（如果尚未运行）。返回引擎状态；当冷启动超过调用时间时，engineStarting 为真，get_status 报告何时启动完成。如果引擎已在运行，则不执行任何操作，从不安装缺失的引擎（连接器 0.3.0 或更新版本）。 |
stop_engine | 停止本地引擎并释放其 VRAM。云生成不受影响（连接器 0.3.0 或更新版本）。 |
restart_engine | 重启本地引擎，在安装或移除自定义节点后，或当其卡住时（连接器 0.3.0 或更新版本）。 |
list_projects | 列出项目（保存生成内容的容器）。 |
create_project | 创建新项目。 |
upload_file | 上传本地图像或视频，获得一个句柄以传递给 generate。 |
list_loras | 列出已安装的用户 LoRA（名称、基础模型、触发词），以便您可以将它们传递给 generate。 |
generate | 开始图像或视频生成。选择 local、cloud 或 auto。可选择传递 loras: [{ name, weight }]（本地后端，预设中 inputs.supportsLoras 为真的预设；使用 list_loras 获取名称）和 negativePrompt（额外术语，添加在预设默认负提示之后；在云运行中使用预设默认值）。options 接受命名字段（steps、cfg、seed、resolution、aspectRatio、durationSeconds）和预设在 list_capabilities → options.controls 下声明的任何高级控制，例如 unlock、shift 或 high_steps，作为顶级键（连接器 0.2.0 或更新版本）。返回作业 id。 |
get_prompt_guide | 在编写预设提示之前，读取该预设（presetId）的提示指南：模型如何读取提示、结构、长度、摄像机和运动措辞、负提示、角色措辞和示例。回复包含 family、generic（当不存在模型特定指南时为真）和指南 text。连接器 0.6.0 或更新版本；generate 告诉代理先调用它。 |
get_job | 获取作业的状态和结果，包括完成后的输出路径。 |
wait_for_result | 等待作业完成、失败或超时。 |
list_jobs | 列出最近的生成作业。 |
cancel_job | 取消已排队或正在运行的作业。 |
prepare_preset | 开始下载本地预设的模型，使其准备好运行。 |
get_result_image | 返回完成作业的图像用于内联查看。视频结果返回文件路径。 |
list_recipe_blocks | 列出制作食谱的构建块：入口点（创建图像或视频、编辑图像、升级）和每个可用作步骤的预设，各自具有其端口协议（所需的输入、生成的内容、适配的入口点）。 |
compose_recipe | 从高级规格（固定到预设的有序步骤，加任何输入）编写新食谱并另存为草稿。SimpliGen 自动连接端口、步骤间媒体链和每步的提示输入，然后验证。返回食谱 id 加验证。 |
validate_recipe | 试运行食谱规格（或原始配置）而不保存，获取要修复的精确错误。 |
list_recipes | 列出此设备上保存的食谱草稿。 |
get_recipe | 按 id 获取已保存的食谱及其完整配置。 |
publish_recipe | 向创意者市场提交已保存的食谱（排队等待人工审查）。需要已连接的账户；默认免费发布，除非设置了一次性令牌价格。 |
run_recipe | 运行已安装的食谱（UGC Studio 和产品 Studio 中的，或草稿）并填写其输入。主题输入采用角色或产品 id，媒体输入采用上传句柄，文本和选择输入采用普通值。与在 studio 中单击生成相同的管道。返回运行 id。 |
get_recipe_run | 食谱运行的状态：整体状态、每个步骤及其状态和结果、完成后的最终结果路径。 |
wait_for_recipe_run | 阻塞直到食谱运行完成（或超时）并返回最终运行。 |
list_recipe_runs | 食谱的最近运行及其状态和结果。 |
cancel_recipe_run | 停止正在运行的食谱。不再开始进一步的步骤；本地运行中的步骤被中断。 |
list_subjects | 食谱的主题输入可以采用的每个主题：角色和产品，带其 id。 |
list_products | 此设备上保存的产品。 |
create_product | 从上传的照片保存产品（名称、描述、类别），以便产品 Studio 和 UGC 食谱可以使用它。返回产品 id。 |
remove_product | 删除产品及其照片。 |
list_characters | 列出角色 Studio 中的所有活跃角色。 |
get_character | 按 id 获取单个角色的详情和图像。 |
list_character_features | 列出所有身份特征（肤色、头发等）及其选项，用于按描述创建角色。 |
list_character_presets | 列出为每个角色角色安装的可用预设：基础肖像生成、身份编辑、图像转视频动画和增强（升级）。每个增强预设包含一个 supportedScales 数组。 |
create_character | 创建新角色。支持三种路径：描述（从特征选择生成基础肖像）、上传（使用您自己的图像作为基础）和 vision-recreate（代理从用户照片描述的特征）。在生成模式中，工具内部轮询直到基础肖像准备好并返回就绪的角色对象。在上传模式中，角色立即就绪。 |
generate_character_image | 按提示为现有角色生成场景图像。接受可选的 presetId 为此调用选择要使用的身份编辑预设。返回一个或多个作业 id 以通过 wait_for_result 轮询。 |
generate_character_video | 为现有角色生成动画视频剪辑。接受可选的 framePresetId（帧步骤的身份编辑预设）和 videoPresetId（动画步骤的 i2v 预设）。返回帧和动画步骤的作业 id。 |
generate_character_frame | 为角色生成单个静止帧而不对其进行动画处理。在动画之前想要查看或增强帧时很有用。接受可选的 presetId。返回 { jobIds: [...] }；使用 jobIds[0] 作为帧作业 id。 |
animate_character | 从完成的帧或任何完成的图像作业为角色生成动画。传递 jobId（来自任何完成生成的作业 id）或 filePath（绝对本地图像路径）。接受可选的 videoPresetId。返回视频作业 id。 |
set_character_preset | 为每个角色设置粘性默认预设用于图像生成（imagePresetId）和/或视频生成（videoPresetId）。传递 null 以清除默认值。对 generate_character_image 和 generate_character_video 的后续调用会使用这些默认值，除非按调用覆盖。 |
enhance_character_media | 升级或增强角色图像或视频。源可以是完成的作业（jobId）、上传的文件（filePath 句柄）或角色基础肖像（target: 'base'）。接受 scale（升级因子）、keepResolution（升级然后调整大小回源尺寸以获得更锐利的相同尺寸结果）和 applyAsBase（用升级的结果替换角色基础肖像）。返回作业 id。 |
regenerate_character_base | 就地重新生成现有角色的基础肖像，可选择切换到不同的基础预设或更新身份。不创建新角色。内部轮询、自动接受新基础并返回就绪的角色对象。代理之后不需要轮询作业 id。 |
remove_character | 永久删除角色及其关联数据。 |
list_films | 列出项目的视频 Studio 电影（连接器 0.5.0 或更新版本，所有下面的电影工具也一样）。 |
create_film | 创建空电影：形状、分辨率、渲染位置、每种镜头类型的预设。回答其时间线。 |
get_film | 读取电影的时间线：速度、演员、每个剪辑及其数量、开始和秒数和小节长度、镜头和录制状态、轨道、标记和导出范围。 |
update_film_settings | 更改电影的形状、分辨率、渲染位置、预设、主题和风格以及每个剪辑继承的演员和位置。 |
add_track | 将上传的音频文件放在时间线上：唱歌、音乐、对话或音效。 |
move_track | 移动轨道的音频、将其静音或设置其音量。 |
detect_tempo | 从歌曲设置电影的速度和小节线。之后，时间可以以小节给出。 |
add_clip | 在某个时刻添加空剪辑，持续时间。 |
update_clip | 一步写入剪辑：镜头（提示、长度、说出或唱出的台词、谁说的、取景）、演员、位置、如何开始（新鲜或从前一个剪辑继续；也接受 none 和 frame，作为新鲜和继续）、它听的轨道、预设。 |
move_clip | 将剪辑移动到新的开始时间或另一个视频车道。 |
trim_clip | 改变剪辑的长度，或它在录制中的开始位置。 |
remove_clip | 移除剪辑。 |
apply_film_plan | 一步完成整个草稿布局：剪辑在小节上及其镜头、演员和链接。每个问题一次性返回；除非全部有效，否则不改变任何内容。 |
set_fades | 淡入淡出剪辑或轨道。 |
add_marker | 在标尺上放置命名标记。 |
set_export_range | 仅导出电影的一部分，或全部。 |
render_clips | 渲染需要它的剪辑，或指定的剪辑。立即回答启动的内容、所持内容和云成本。 |
wait_for_renders | 等待直到没有剪辑在渲染并回答时间线。 |
list_takes | 列出剪辑的录制。 |
use_take | 使剪辑的一个录制成为它显示的那个。 |
export_film | 将电影缝合成带有音乐的一个视频并回答文件路径。 |
list_locations | 列出库的位置。 |
create_location | 从上传的图片或完成的图像作业保存位置。 |
在视频 Studio 中打开电影时，代理进行的每项更改立即出现并使用 Ctrl+Z 撤销。请参阅代理制作音乐视频了解完整的演练。
它如何连接
代理通过 stdio 使用 npx -y @simpligen/mcp 运行 MCP 服务器。服务器使用配对令牌（SIMPLIGEN_TOKEN）认证到应用，并自动查找应用的本地端口。SimpliGen 应用必须在运行。在设置中的"连接代理"部分下生成令牌。
构建自定义集成？
MCP 工具转发到本地 HTTP 控制 API，您可以从任何语言直接调用它。请参阅控制 API 参考。
支出限制
每个令牌可以携带支出上限。空上限意味着无限制云使用，0 意味着仅本地生成，正数将云支出上限设为该多个信用。本地生成始终允许，从不计入上限。