MCP 工具参考

暴露给编码代理的每一个 Convai MCP 工具参考，包括默认启用状态和场景变更行为。

Unity 官方 MCP 服务器在以下位置公开 20 个 Convai 专用工具： Convai.* 命名空间，工具契约版本为 4，因此连接的编码代理可以检查、配置或诊断 Convai 组件，而不必由你在 Unity 编辑器中手动连线。Unity AI Assistant 通过其点分隔名称调用工具（例如 Convai.GetGuidance）；外部 MCP 客户端会以以下下划线规范化名称接收同一工具（Convai_GetGuidance）。本页使用点分隔名称，记录每个工具的用途、参数、默认启用状态以及对场景或项目的修改行为。

全部 20 个工具

工具	领域	默认启用	会修改
Convai.GetGuidance	指导	是	未
Convai.GetProjectStatus	基础	是	未
Convai.InspectScene	基础	是	未
Convai.ValidateSetup	基础	是	未
Convai.BootstrapScene	场景和对话设置	未	是 — dryRun 因调用方而异地设置默认值（见下文）
Convai.ConfigureRoom	场景和对话设置	是	是 — dryRun 默认为 true
Convai.ConfigurePlayer	场景和对话设置	是	是 — dryRun 默认为 true
Convai.ConfigureCharacter	场景和对话设置	是	是 — dryRun 默认为 true
Convai.SetupConversationScene	场景和对话设置	是	是 — dryRun 默认为 true
Convai.DiagnoseConversation	场景和对话设置	是	未
Convai.ConfigureActions	角色动作	是	是 — dryRun 默认为 true
Convai.DiagnoseActions	角色动作	是	未
Convai.SimulateAction	角色动作	是	仅限播放模式，通过分发器
Convai.ConfigureLipSync	口型同步	是	是 — dryRun 默认为 true
Convai.DiagnoseLipSync	口型同步	是	未
Convai.ConfigureTranscripts	转录	是	是 — dryRun 默认为 true
Convai.DiagnoseTranscripts	转录	是	未
Convai.ConfigureNarrative	叙事	是	是 — dryRun 默认为 true
Convai.DiagnoseNarrative	叙事	是	未
Convai.TraceRuntimeEvents	运行时诊断	是	否 — 仅管理编辑器专用的跟踪缓冲区

在以下位置切换任意工具： 编辑 > 项目设置 > AI > Unity MCP Server.

Convai.GetGuidance

领域： 指导 · 默认启用： 是 · 会修改： 未

为一个主题加载简明的 Convai SDK 工作流指导。在配置或调试 Convai 功能之前调用它；它不适用于通用 Unity 操作。响应包含摘要、先决条件、按顺序排列的工作流、相关的 Convai 和 Unity 工具，以及文档路径。

参数	类型	默认值	描述
主题	enum ConvaiGuidanceTopic	概览	要加载的工作流主题。

ConvaiGuidanceTopic 的值以及各自返回内容：

主题	返回摘要
概览 （默认）	仅将 Convai 工具用于了解 SDK 的操作；对通用项目更改请组合使用官方 Unity MCP 工具。
设置	主动完成可运行的 Convai 场景设置；显式的设置请求授权使用安全、可逆的默认值。
动作	创建显式动作能力并绑定本地执行器；切勿从场景元数据推断能力。
DynamicContext	通过角色动态上下文门面发送状态、事件和注意对象变更。
Vision	在启用视频模式之前，先在房间层级下配置一个视觉发布器和一个帧源。
叙事	将 Narrative 模块用于章节状态以及命名或内联触发器工作流。
具身化	通过各自品牌化组件和配置文件配置每个具身化模块；缺失的关联项必须优雅降级。
事件	优先使用 ConvaiManager.Events 用于类型化代码，并使用转接组件处理基于 Inspector 的 UnityEvent。
运行时	使用 ConvaiManager 用于会话所有权，Audio 用于房间音频，Transcripts 用于规范历史记录。

Convai.GetProjectStatus

领域： 基础 · 默认启用： 是 · 会修改： 未

读取 Convai SDK、Unity AI Assistant 以及非机密项目配置状态。绝不会返回 Convai API 密钥。

无输入参数。

返回 sdkVersion, unityVersion, assistantVersion, toolContractVersion, credentialsConfigured, serverUrl, transcriptSystemEnabled, notificationSystemEnabled, defaultMicrophoneDeviceId, connectionTimeoutSeconds, isPlaying, isCompiling，以及 packageRoot.

Convai.InspectScene

领域： 基础 · 默认启用： 是 · 会修改： 未

检查打开的场景中的 ConvaiManager, ConvaiRoomManager, ConvaiPlayer，以及 ConvaiCharacter 组件，并返回精确的实例 ID 供后续修改使用。

参数	类型	默认值	描述
includeInactive	bool	true	包含已禁用的 GameObject和组件参与检查。

Convai.ValidateSetup

领域： 基础 · 默认启用： 是 · 会修改： 未

验证 Convai 项目和场景的就绪状态，而不更改资源或场景。在 Convai 编写操作之前和之后调用。返回 错误, 警告，以及 下一步.

参数	类型	默认值	描述
范围	enum ConvaiValidationScope	全部	验证范围： 全部, 项目，或 场景.

Convai.BootstrapScene

领域： 场景和对话设置 · 默认启用： 否 · 会修改： 是

幂等地将所需的 ConvaiManager 和 ConvaiRoomManager 添加到活动场景中。不会添加玩家、角色、保存场景或设置凭据。仅在编辑模式下可用 — 如果在播放模式下调用，则返回 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
dryRun	bool	true 通过 Unity AI Assistant； false 通过外部 MCP 工具契约	在不修改场景的情况下预览所需更改。

Convai.BootstrapScene 是 20 个工具中唯一默认禁用的一个。它的 dryRun 默认值还取决于代理如何调用它：Unity AI Assistant 的点命名包装器默认 dryRun 设置为 true 与其他所有会修改的工具一样，但外部 MCP 客户端使用的底层 MCP 工具契约（以下划线命名的 Convai_BootstrapScene）默认 dryRun 设置为 false —— 这些客户端会立即应用更改，除非它们显式传递 dryRun: true 。优先用于 Convai.SetupConversationScene 端到端设置；仅用于管理器/仅房间的工作。 Convai.BootstrapScene 预览或配置 Convai 房间 —

Convai.ConfigureRoom

领域： 场景和对话设置 · 默认启用： 是 · 会修改： 是

— 在显式目标上 ConvaiManager 和 ConvaiRoomManager — 使用内联设置或现有的 GameObject, ConvaiRoomManagerProfile。使用 Unity 的 Undo 系统，绝不会保存场景，也绝不会更改凭据。仅在编辑模式下可用 — 返回 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
targetInstanceId	long	—（必填）	拥有或将要拥有 ConvaiManager 和 ConvaiRoomManager.
configurationMode	enum ConvaiToolConfigurationMode	内联	内联 或 ExistingProfile.
profileAssetPath	string	""	现有 ConvaiRoomManagerProfile 资源路径。在 ExistingProfile 模式下必填。
connectionType	enum ConvaiConnectionType	音频	内联连接类型。
inputMode	enum ConversationInputMode	免提	内联对话输入模式。
connectOnStart	bool	true	在场景启动时自动连接。
serverEndpoint	enum ConvaiServerEndpoint	连接	核心服务端点。
visionMode	enum ConvaiVisionContextMode	Auto	动态视觉策略。
pushToTalkKey	string	"T"	Unity KeyCode 推按讲话使用的名称。
dryRun	bool	true	在不修改场景的情况下预览更改。

Convai.ConfigurePlayer

领域： 场景和对话设置 · 默认启用： 是 · 会修改： 是

预览或添加并配置 ConvaiPlayer 在显式目标上 GameObject，然后绑定一个无歧义的管理器。绝不修改 Main Camera。仅在编辑模式下可用 — 返回 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
targetInstanceId	long	—（必填）	目标玩家 GameObject 的实例 ID。
managerInstanceId	long	0	可选的管理器 GameObject 实例 ID。为零时会在目标场景中自动解析一个管理器。
playerName	string	"Player"	玩家显示名称。
playerId	string	""	可选的本地转录归属 ID。默认为玩家名称。
dryRun	bool	true	在不修改场景的情况下预览更改。

Convai.ConfigureCharacter

领域： 场景和对话设置 · 默认启用： 是 · 会修改： 是

预览或添加并配置 ConvaiCharacter 并附带推荐的音频输出 — AudioSource 和 ConvaiAudioOutput — 使用内联设置或现有的 GameObject。缺失的 Character ID 仍然是明确的就绪阻塞项：工具返回 complete=false 和 requiredInputs=["characterId"] ，而不是猜测一个。仅在编辑模式下可用 — 返回 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
targetInstanceId	long	—（必填）	目标角色 GameObject 的实例 ID。
managerInstanceId	long	0	可选的管理器 GameObject 实例 ID。为零时会在目标场景中自动解析一个管理器。
configurationMode	enum ConvaiToolConfigurationMode	内联	内联 或 ExistingProfile.
profileAssetPath	string	""	现有 ConvaiCharacterProfile 资源路径。在 ExistingProfile 模式下必填。
characterId	string	""	Convai 控制台中的 Character ID。在编写不完整的占位符时可以省略。
characterName	string	""	角色显示名称。默认为目标 GameObject 的名称。
addAudioOutput	bool	true	确保 AudioSource 和 ConvaiAudioOutput 同伴。
dryRun	bool	true	在不修改场景的情况下预览更改。

Convai.SetupConversationScene

领域： 场景和对话设置 · 默认启用： 是 · 会修改： 是

在活动场景中使用安全占位符和推荐默认值，预览或执行端到端音频对话设置。选择顺序为：显式实例 ID，然后是一个无歧义的现有组件，然后是一个安全占位符——一个独立的 Convai Player 以及一个可见的 Capsule Convai Character ——如果不存在则创建。绝不会保存场景、进入播放模式或设置凭据。仅在编辑模式下可用 — 返回 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
managerInstanceId	long	0	可选的管理器目标实例 ID。
playerInstanceId	long	0	可选的玩家目标实例 ID。
characterInstanceId	long	0	可选的角色目标实例 ID。
roomProfileAssetPath	string	""	可选的现有 ConvaiRoomManagerProfile 路径。
characterProfileAssetPath	string	""	可选的现有 ConvaiCharacterProfile 路径。
characterId	string	""	Convai 控制台中的 Character ID。在所有独立设置完成之前可以省略。
characterName	string	"Convai Character"	角色显示名称。
playerName	string	"Player"	玩家显示名称。
playerId	string	""	可选的本地转录归属 ID。
inputMode	enum ConversationInputMode	免提	推荐的房间输入模式。
connectOnStart	bool	true	在场景启动时自动连接。
createPlaceholders	bool	true	当不存在时，创建独立的玩家和 Capsule 角色占位符。
dryRun	bool	true	在不修改场景的情况下预览更改。

Convai.DiagnoseConversation

领域： 场景和对话设置 · 默认启用： 是 · 会修改： 未

通过带有排序证据和建议修复方案的方式，诊断活动场景中的 Convai 对话就绪状态和运行时状态。可在编辑模式和播放模式下工作。绝不修改项目或返回 API 密钥。

参数	类型	默认值	描述
characterInstanceId	long	0	可选的重点角色 GameObject 实例 ID。
includeInactive	bool	true	包含非活动场景对象。

返回 readyToRun、配置和运行时快照，以及一个 问题 数组，包含稳定代码、证据、 autoFixable，以及 suggestedTool/suggestedArguments 对应每个问题。

Convai.ConfigureActions

领域： 角色动作 · 默认启用： 是 · 会修改： 是

预览或安全地按名称更新类型化动作定义以及 Convai 角色上的显式对象或角色目标。使用 Undo，绝不会保存。未绑定执行器的定义会收到一个未接线的 UnityEvent 占位符，并保持不完整，直到完成接线。仅在编辑模式下可用 — 返回 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
characterInstanceId	long	—（必填）	角色 GameObject 或组件实例 ID。
definitions	数组	[]	要按名称更新的类型化动作定义。请参见 角色动作脚本参考 获取完整字段集。
objects	数组	[]	要按名称更新的显式可动作 GameObject。
characters	数组	[]	要按名称更新的显式可动作角色。
initialAttentionObject	string	""	可选的已创作对象名称，用作初始注意对象。
dryRun	bool	true	在不修改场景的情况下预览更改。

Convai.DiagnoseActions

领域： 角色动作 · 默认启用： 是 · 会修改： 未

在不修改的情况下，诊断动作定义、执行器、目标、注意对象、分发器存在情况以及运行时可用性。

参数	类型	默认值	描述
characterInstanceId	long	0	可选的角色实例 ID。
includeInactive	bool	true	包含非活动对象。

Convai.SimulateAction

领域： 角色动作 · 默认启用： 是 · 会修改： 仅限播放模式

在编辑模式下验证动作负载，或在播放模式下通过真实运行时 ConvaiActionDispatcher 进行分发。绝不会更改播放模式本身。

参数	类型	默认值	描述
characterInstanceId	long	—（必填）	角色实例 ID。
actionName	string	—（必填）	已配置的动作名称。
目标	string	""	可选目标名称。
parameters	dictionary<string, string>	{}	由已创作参数名称作为键的可选动作参数值。
timeoutSeconds	float	10	完成超时，夹在 0.1 和 60 秒之间。

在编辑模式下，工具返回 executed=false 和 requiresPlayMode=true ，并在验证负载后返回。在播放模式下，它会将命令排入角色的分发器并等待 ConvaiActionStepReport，返回 SIMULATION_TIMEOUT 如果该步骤未在 timeoutSeconds.

Convai.ConfigureLipSync

领域： 口型同步 · 默认启用： 是 · 会修改： 是

使用现有网格、随附配置文件以及可选的现有口型同步映射资源，预览或配置 Convai 口型同步。绝不会创建或修改资源。仅在编辑模式下可用 — 返回 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
characterInstanceId	long	—（必填）	角色 GameObject 实例 ID。
meshInstanceIds	long[]	[]	目标网格实例 ID。为空则解析该角色下的每一个 SkinnedMeshRenderer 。
配置文件	string	"Auto"	Auto, arkit, cc4_extended，或 metahuman. Auto 要求在目标网格之间存在唯一的 blendshape 名称匹配。
mappingAssetPath	string	""	现有 ConvaiLipSyncMapAsset 路径。
latencyMode	enum LipSyncLatencyMode	均衡	均衡, 超低延迟, 网络安全，或 自定义.
dryRun	bool	true	在不修改场景的情况下预览更改。

参见 添加口型同步 用于该工具自动化的 Inspector 工作流。

Convai.DiagnoseLipSync

领域： 口型同步 · 默认启用： 是 · 会修改： 未

诊断 ConvaiLipSyncComponent、目标网格、blendshape 兼容性、映射、配置文件以及净化后的运行时缓冲状态。

参数	类型	默认值	描述
characterInstanceId	long	0	角色 GameObject 实例 ID。
includeRuntimeMetrics	bool	true	包含 isPlaying, isTalking, isFadingOut, engineState、缓冲和流式时长，以及余量。

Convai.ConfigureTranscripts

领域： 转录 · 默认启用： 是 · 会修改： 是

预览或配置规范的转录门面、事件转接器或随附聊天 UI。绝不会更改 ConvaiSettings 或暴露转录文本。仅在编辑模式下可用 — 返回 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
managerInstanceId	long	0	可选的管理器实例 ID。
hostInstanceId	long	0	可选的主机 GameObject 实例 ID。
模式	enum ConvaiTranscriptToolMode	EventRelay	EventRelay, ChatUI，或 WorldSpaceChatUI.
finalOnly	bool	false	仅转发最终更新。
ignoreInterim	bool	true	忽略中间更新。
characterIdFilter	string	""	可选的角色 ID 过滤器。
dryRun	bool	true	在不修改场景的情况下预览更改。

参见 Transcript API 用于该工具挂接的运行时门面。

Convai.DiagnoseTranscripts

领域： 转录 · 默认启用： 是 · 会修改： 未

诊断转录启用状态、门面就绪状态、转接器、UI 以及净化后的运行时时间线元数据。

参数	类型	默认值	描述
managerInstanceId	long	0	可选的管理器实例 ID。
包含文本	bool	false	仅在明确请求时包含转录文本。

Convai.ConfigureNarrative

领域： 叙事 · 默认启用： 是 · 会修改： 是

预览或配置 Unity 端的叙事部分映射、模板键和触发器 — ConvaiNarrativeDesignManager 和 ConvaiNarrativeDesignTrigger. 保留无关条目并 UnityEvent并且绝不联系 Convai。仅在编辑模式下可用 — 返回一个 PLAY_MODE_ACTIVE 失败代码。

参数	类型	默认值	描述
characterInstanceId	long	—（必填）	角色 GameObject 实例 ID。
managerHostInstanceId	long	0	叙事管理器的可选宿主 GameObject 实例 ID。
部分	数组	[]	要插入或更新的叙事部分，每个 { sectionId, sectionName }.
模板键	数组	[]	要插入或更新的模板键，每个 { key, value }.
触发器	数组	[]	要插入或更新的触发器。参见 叙事设计脚本参考 以查看完整的触发器字段集。
dryRun	bool	true	在不修改场景的情况下预览更改。

Convai.DiagnoseNarrative

领域： 叙事 · 默认启用： 是 · 会修改： 未

诊断 Unity 端的叙事角色绑定、重复或孤立的部分、模板键、触发器、玩家过滤器、缓存的同步错误以及运行时触发器状态。

参数	类型	默认值	描述
characterInstanceId	long	0	角色 GameObject 实例 ID。
includeInactive	bool	true	包含非活动对象。
包含内容	bool	false	包含模板值和触发器名称。内容默认保持隐藏。

Convai.TraceRuntimeEvents

领域： 运行时诊断 · 默认启用： 是 · 会修改： 否（仅管理一个仅限编辑器的追踪缓冲区）

启动、读取、清除或停止一个最多 256 条记录的有限编辑器专用 Convai 运行时事件追踪。追踪会在退出播放模式和域重新加载时清除。转录捕获默认关闭。

参数	类型	默认值	描述
操作	枚举 ConvaiRuntimeTraceOperation	读取	Start, 读取, 清除，或 Stop.
managerInstanceId	long	0	可选的活动场景管理器实例 ID。
characterInstanceId	long	0	可选的活动场景角色实例 ID 过滤器。
事件过滤器	string[]	[]	可选的事件类型或类别过滤器。
限制	int	100	要返回的条目数，限制在 1 和 256.
捕获转录文本	bool	false	捕获转录事件和文本。默认关闭。

下一步

AI 编码助手受支持的编码代理AI 编码助手设置故障排除