AI Agents
MCP 工具参考
SimpliGen MCP 服务器暴露给 AI 代理的工具，以及它们背后的本地 Control API。
SimpliGen 附带一个 MCP 服务器（@simpligen/mcp），它通过本地、令牌认证的连接将 AI 代理连接到运行中的 SimpliGen 应用。代理调用 MCP 工具；服务器将它们转发到应用的本地 Control API。请参阅连接代理来设置此功能。
工具
| 工具 | 功能 |
|---|---|
list_capabilities | 列出代理可以生成的每个预设（图像或视频）、其输入和选项、它是否在本地就绪、云端资格和积分成本。 |
get_status | 报告引擎状态、云端是否连接、积分余额、活跃项目，以及 characters 功能块（启用标志、base/edit/i2v 的已安装预设数量，以及 enhancePresets，已安装放大预设的数量）。 |
start_engine | 启动本地引擎（如果尚未运行）。返回引擎状态；当冷启动超过调用时长时，engineStarting 为真，get_status 会报告何时启动完成。如果引擎已在运行则不执行任何操作，从不安装缺失的引擎（connector 0.3.0 或更新版本）。 |
stop_engine | 停止本地引擎并释放其 VRAM。云生成不受影响（connector 0.3.0 或更新版本）。 |
restart_engine | 重启本地引擎，在安装或移除自定义节点后，或当它卡住时使用（connector 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，作为顶级键（connector 0.2.0 或更新版本）。返回一个任务 id。 |
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 和 Product Studio 中的配方，或草稿）并填充其输入。subject 输入接受角色或产品 id，媒体输入接受上传句柄，文本和选择输入接受纯值。与在工作室中点击生成相同的管道。返回运行 id。 |
get_recipe_run | 配方运行的状态：总体状态、每个步骤的状态和结果，以及完成后的最终结果路径。 |
wait_for_recipe_run | 阻塞直到配方运行完成（或超时通过）并返回最终运行。 |
list_recipe_runs | 配方的最近运行及其状态和结果。 |
cancel_recipe_run | 停止运行中的配方。不再启动进一步的步骤；本地进行中的步骤被中断。 |
list_subjects | 配方的 subject 输入可以接受的每个 subject：角色和产品，带有它们的 id。 |
list_products | 保存在此设备上的产品。 |
create_product | 从上传的照片保存产品（名称、描述、类别），以便 Product Studio 和 UGC 配方可以使用它。返回产品 id。 |
remove_product | 删除产品及其照片。 |
list_characters | 列出角色工作室中的所有活跃角色。 |
get_character | 通过 id 获取单个角色的详细信息和图像。 |
list_character_features | 列出所有身份特征（肤色、头发等）及其选项，用于通过描述创建角色时使用。 |
list_character_presets | 列出为每个角色角色安装的预设：base 肖像生成、身份编辑、图像到视频动画和增强（放大）。每个增强预设包含一个 supportedScales 数组。 |
create_character | 创建新角色。支持三种路径：describe（从特征选择生成 base 肖像）、upload（使用自己的图像作为 base）和 vision-recreate（代理从用户照片描述的特征）。在生成模式中，工具在内部轮询直到 base 肖像就绪并返回就绪的角色对象。在上传模式中，角色立即就绪。 |
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 句柄）或角色 base 肖像（target: 'base'）。接受 scale（放大因子）、keepResolution（放大然后调整回源尺寸以获得更锐利的同尺寸结果）和 applyAsBase（用放大的结果替换角色 base 肖像）。返回任务 id。 |
regenerate_character_base | 在原地为现有角色重新生成 base 肖像，可以选择切换到不同的 base 预设或更新身份。不创建新角色。在内部轮询，自动接受新 base，并返回就绪的角色对象。代理之后不需要轮询任务 id。 |
remove_character | 永久删除角色及其关联数据。 |
它如何连接
代理使用 npx -y @simpligen/mcp 在 stdio 上运行 MCP 服务器。服务器使用配对令牌（SIMPLIGEN_TOKEN）认证到应用，并自动查找应用的本地端口。SimpliGen 应用必须在运行。在设置中的"连接代理"部分下铸造令牌。
构建自定义集成？
MCP 工具转发到本地 HTTP Control API，您可以从任何语言直接调用。请参阅 Control API 参考。
消费限制
每个令牌可以携带消费上限。空上限意味着无限云使用，0 意味着仅本地生成，正数将云消费限制为该数量的积分。本地生成总是允许的，从不计入上限。