configure-canvas-mcp

配置 Canvas Authoring MCP 服务

此技能用于为用户当前的 Power Apps 共同创作会话配置 Canvas Authoring MCP 服务。MCP 服务由插件自动注册——此技能会将其连接到特定的应用会话。

说明

1. 询问工作室 URL

询问用户：

你的画布应用工作室会话 URL 是什么？

在 Power Apps Designer 中打开应用时，从浏览器地址栏复制 URL（格式应类似于 https://make.powerapps.com/e/Default-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/canvas/?action=edit&app-id=...）。

确保已在应用中启用共同创作（Settings → Updates → Coauthoring）。

在整个会话期间保持此浏览器标签页打开。 MCP 服务通过与该标签页关联的共同创作会话与 Power Apps 通信。关闭标签页会结束共同创作会话，导致 compile_canvas 和 sync_canvas 无法正常工作，也意味着你无法查看或保存生成的更改。

2. 从 URL 中提取参数

从工作室 URL 中解析以下内容：

• ENV_ID：/e/ 与其后的下一个 / 之间的路径段（例如 Default-91bee3d9-0c15-4f17-8624-c92bb8b36ead）。
• APP_ID：对 app-id 查询参数值进行 URL 解码，然后取最后一个 / 之后的最后一段（例如 6fc3e3d1-292b-4281-8826-577f78512e56）
• MAKER_HOSTNAME：URL 的主机名（例如 make.powerapps.com）
• ENVIRONMENT_CATEGORY：根据 MAKER_HOSTNAME 确定（见下表）

根据 MAKER_HOSTNAME 确定 ENVIRONMENT_CATEGORY：

MAKER_HOSTNAME	ENVIRONMENT_CATEGORY
make.powerapps.com	prod
make.preview.powerapps.com	prod
make.preprod.powerapps.com	preprod
make.gov.powerapps.us	gov
make.high.powerapps.us	high
make.apps.appsplatform.us	dod
make.powerapps.cn	china
任何其他主机名	test

示例：

示例 URL：https://make.powerapps.com/e/Default-91bee3d9-0c15-4f17-8624-c92bb8b36ead/canvas/?action=edit&app-id=%2Fproviders%2FMicrosoft.PowerApps%2Fapps%2F6fc3e3d1-292b-4281-8826-577f78512e56

• ENV_ID → Default-91bee3d9-0c15-4f17-8624-c92bb8b36ead
• APP_ID → 6fc3e3d1-292b-4281-8826-577f78512e56
• MAKER_HOSTNAME → make.powerapps.com
• ENVIRONMENT_CATEGORY → prod

3. 配置 MCP 服务

调用 canvas-authoring 服务上的 connect MCP 工具，连接到用户的协作编辑会话。

connect(
  environment_id: ENV_ID,
  app_id: APP_ID,
  environment_category: ENVIRONMENT_CATEGORY,
  // Optional — include only if the user has expressed a preference or a prior sign-in failed (see below):
  auth_flow: "broker" | "browser" | "devicecode",
  login_hint: "[email protected]",
  tenant_id: "00000000-0000-0000-0000-000000000000",
  force_account_select: true
)

可选参数——不要向用户询问这些参数。 仅当用户在此前的对话中已经表达过偏好，或之前的连接尝试失败时，才包含这些参数：

• login_hint：仅当用户明确表示希望以特定的其他用户身份连接时（例如“以 [email protected] 登录”），才传入用户的 UPN 或电子邮件地址。这些值无法从创作者门户 URL 推断出来——切勿猜测。否则请省略，以使用第一个已登录的用户。重新连接以切换环境或应用时，如果已知之前成功连接所用的 login_hint 值，请重复使用，以便复用同一用户，而无需再次提示。
• auth_flow：如果用户明确指定了首选身份验证流程（例如“使用浏览器登录”），则传入 "browser"、"broker" 或 "devicecode"；对于下文所述的 404 恢复流程，使用 "browser"。在无法弹出界面的无头/SSH 主机上，如果 broker 和 browser 流程都无法弹出界面，则使用 "devicecode"——验证 URL 和用户代码会通过 MCP elicitation 请求提供，因此需要支持 elicitation 的客户端。否则请省略，以使用默认值。
• tenant_id：仅用于 Entra B2B 来宾访问时，传入租户 GUID——将其设为用户所属来宾的主机/资源租户，以便令牌由该租户而非用户的主租户颁发。与 login_hint（来宾的主 UPN）结合使用可预先填入帐户。对于正常的同租户登录，请省略。
• force_account_select：仅当需要强制显示帐户选择器而非静默复用缓存帐户时，才传入 true——在下文所述的 404 恢复流程中，或之前的连接因 401/403 失败且未提供 login_hint 时设置此项，以便用户选择正确的帐户。否则请省略。

如果当前主机名称下没有可用的 Canvas Authoring connect 工具，请运行以下命令，检查服务是否因缺少 .NET 10 SDK 而启动失败。不要因为其他主机名称下没有该工具，就认定服务启动失败。

dotnet --list-sdks

如果未列出版本为 10.x.y 或更高的版本，请告知用户：

⚠️ 运行 Canvas Authoring MCP 服务需要 .NET 10 SDK。看来你尚未安装它。请从 https://dotnet.microsoft.com/download/dotnet/10.0 下载并安装，然后重试。

如果 connect 返回 HTTP 404 错误，可能是因为登录所用的帐户与 Studio 会话所用的帐户不同。请报告错误，并按以下顺序恢复：

1. 提醒用户使用其 Power Apps Studio 浏览器会话所用的同一帐户登录。
2. 使用相同的环境/应用参数再次运行 connect，并设置 force_account_select: true，以便用户选择该帐户。
3. 如果重试仍然失败，再次运行 connect，并设置 auth_flow: "browser" 和 force_account_select: true，同时保留相同的环境/应用参数。提醒用户在浏览器登录时选择其 Studio 帐户。在无法使用浏览器登录的无头/SSH 主机上，请改用上文所述的 auth_flow: "devicecode"。

连接成功后，请停止重试。如果两次恢复尝试都失败，请报告最终错误并按照以下检查项进行排查；不要声称服务已配置完成。

对于其他连接错误，或 404 恢复失败的情况，请报告错误，并建议检查以下事项：

1. Studio URL 是否正确，以及浏览器标签页是否仍处于打开状态
2. 应用设置中是否已启用协作编辑
3. 如果登录失败，用户可能需要指定 auth_flow（broker、browser 或 devicecode）或 login_hint（UPN/电子邮件），以便使用正确的帐户进行身份验证。在无头/SSH 主机上，请使用 auth_flow: "devicecode"。如果系统一直选择缓存帐户，请使用 force_account_select: true 重试。对于 Entra B2B 来宾访问，请将 tenant_id 设为主机租户。

4. 确认

只有在 connect 成功后，才告知用户：

✅ 已为你的协作会话配置 Canvas Authoring MCP 服务。

现在，你可以使用 /canvas-app 等 Canvas App 技能来创建或编辑应用。