星火 2.0 开发文档

主题

SCE Editor MCP 接入指南 ​

本文档说明如何将 SCE Editor 的 MCP Server 接入 Cursor 或其他支持 MCP 的 AI 工具。当前支持两种常见接入方式：

需要不依赖图形窗口的宿主时，参阅无头编辑器指南。SCE.HeadlessEditor 使用 HTTP/WebSocket，启动和授权方式与下文图形编辑器的 stdio 模式不同；该指南提供登录复用、单客户端连服和发布操作说明。

  • stdio 模式：由 AI 工具拉起并管理编辑器进程
  • WebSocket / HTTP 模式：先手动启动编辑器，再由 AI 工具连接现有端点

前置条件 ​

  1. 已编译带 MCP 模块的 SCE Editor
  2. 已安装支持 MCP 的 AI 客户端，例如 Cursor
  3. 确认要加载的地图或工程目录可正常打开

如何找到编辑器路径 ​

不要直接照抄其他项目里的绝对路径。应先在当前项目里检查相对路径 docs/.editor-root：

  • 这个文件存在时，文件内容通常就是当前项目对应的编辑器根目录
  • 你可以直接基于这个目录去定位本机真实的 SCE.exe
  • 之后再根据你本机的安装结构，填写 SCE.exe 的真实路径

示例：

text
docs/.editor-root

文件内容可能类似：

text
C:/SCE_pure/version-2000

这说明当前项目已经被编辑器打开过，并且记录了本机使用的编辑器根目录。你应基于这份本地记录去找对应的 SCE.exe，而不是使用文档中的固定绝对路径。

如果 docs/.editor-root 不存在，通常说明：

  • 这个项目还没有被编辑器成功打开过，或
  • 相关本地编辑器根目录信息还没有生成

此时应先用编辑器打开一次项目，再继续配置 MCP；否则用户需要手动确认自己机器上的编辑器安装路径。

连接模式对比 ​

模式适用场景特点
stdio快速开始、单项目开发AI 客户端负责拉起编辑器，配置简单
WebSocket / HTTP长时间开发、调试、多次重连编辑器独立运行，不受 AI 客户端重启影响

方式一：stdio 模式 ​

配置 mcp.json ​

在工作区的 .cursor/mcp.json 中配置。下面的 command 和 -map_path=... 都是占位写法，请替换成你自己机器上的真实路径：

json
{
  "mcpServers": {
    "sce-editor": {
      "command": "<请改成你本机的 SCE.exe 路径>",
      "args": [
        "--mcp-stdio",
        "-map_path=<请改成当前项目或地图目录>"
      ],
      "env": {}
    }
  }
}

建议顺序：

  1. 先查看项目内 docs/.editor-root
  2. 根据其中记录的编辑器根目录，确认实际编辑器路径
  3. 再把 command 填成真实的 SCE.exe
  4. 把 -map_path=... 参数填成当前项目的工程目录

使用方式 ​

  1. 重启 AI 客户端
  2. 客户端会自动拉起编辑器
  3. 在对话中直接调用 data_*、trigger_*、ui_* 等 MCP 工具

结构 ​

text
AI 客户端  <== stdin/stdout JSON-RPC ==>  SCE Editor

方式二：WebSocket / HTTP 模式 ​

第一步：手动启动编辑器 ​

bash
# 默认：同时支持 WebSocket 和 HTTP
<你的 SCE.exe 路径> --mcp-port=8765 -map_path="<你的项目目录>"

# 仅 WebSocket
<你的 SCE.exe 路径> --mcp-port=8765 --mcp-mode=ws -map_path="<你的项目目录>"

# 仅 HTTP
<你的 SCE.exe 路径> --mcp-port=8765 --mcp-mode=http -map_path="<你的项目目录>"

--mcp-mode 可选值通常为 both、ws、http。编辑器启动后会在对应地址监听：

  • ws://localhost:8765/
  • http://localhost:8765/

访问 http://localhost:8765/ 通常可以查看当前连接状态或状态页。

第二步：配置 mcp.json ​

WebSocket 示例：

json
{
  "mcpServers": {
    "sce-editor": {
      "url": "ws://localhost:8765/"
    }
  }
}

HTTP 示例：

json
{
  "mcpServers": {
    "sce-editor": {
      "url": "http://localhost:8765/"
    }
  }
}

第三步：重连客户端 ​

修改完 mcp.json 后，通常需要重启客户端，或让客户端重新加载 MCP 配置。

结构 ​

text
SCE Editor  <== WebSocket / HTTP JSON-RPC ==>  AI 客户端

优点 ​

  • 编辑器单独运行，不受客户端生命周期影响
  • 可以随时关闭和重连客户端
  • 更适合长时间调试、多人协作或反复测试

快速验证连接 ​

在 AI 客户端中发送类似请求：

text
使用 data_list_tables 列出所有数据表

如果 MCP 已正确接入，AI 会直接调用对应工具并返回结果。

SDK HTTP Helper ​

如果当前 AI 客户端没有把编辑器 MCP 工具直接暴露出来，但编辑器已经以 --mcp-port=8765 运行，可以使用项目生成的薄入口：

powershell
.\ai\tools\Invoke-SceEditorMcp.ps1 -HealthOnly -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -Context -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -ListTools -ToolPrefix uiauthoring_ -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -Tool editor_get_context -Pretty

这个脚本会解析项目 src/WasiCoreSDK.props，调用 SDK 中的版本化实现 tools/editor-mcp/Invoke-SceEditorMcpClient.ps1。它会先执行 MCP initialize 与 notifications/initialized，再做 tools/list 或 tools/call，因此可以用于 schema 发现和多步验证，不需要每个 AI Agent 手写 JSON-RPC 客户端。

默认行为是 RequireFullEditor：如果端口上是独立 TriggerMcpHost，脚本会以 service_identity 失败，避免把 editor_get_context、debug_*、runtime_*、resource_catalog_*、uiauthoring_*、ui_* 等完整编辑器工具错误地发给 Trigger Host。旧的 Invoke-SceMcp.ps1 仍保留给 trigger_* / data_* fallback 工作流使用。

常用诊断：

powershell
# 发现完整工具和 schema
.\ai\tools\Invoke-SceEditorMcp.ps1 -ListTools -Pretty

# 单次调用，参数必须是 JSON object
.\ai\tools\Invoke-SceEditorMcp.ps1 -Tool uiauthoring_get_state -ArgumentsJson '{"include_hierarchy_flat":true}' -Pretty

# 从请求文件调用，兼容 { "tool": "...", "arguments": { ... } }
.\ai\tools\Invoke-SceEditorMcp.ps1 -RequestJsonPath .\ai\tools\editor-mcp-call.json -Pretty

# 可重复 smoke，适合没有直接 MCP 工具暴露的 AI 环境
.\ai\tools\Invoke-SceEditorMcp.ps1 -Smoke UiauthoringP0 -Pretty
.\ai\tools\Invoke-SceEditorMcp.ps1 -Smoke RuntimeMcp -RuntimeDebugStartMode NoCompile -Pretty

失败输出会保留结构化 stage：常见值包括 connect（端口/编辑器未就绪）、service_identity（连到了 TriggerMcpHost 或非完整编辑器）、tool_discovery（工具名不存在）、json_rpc_error、tool_result、json_rpc_http 与 argument_validation。外层 JSON-RPC error、MCP result.isError 和 content[0].text 中可解析的 JSON payload 都会保留在输出里，便于 AI 继续定位。

常见问题 ​

客户端没有调用 MCP 工具 ​

可能原因：

  • .cursor/mcp.json 路径不对
  • command 或 url 配置错误
  • 编辑器进程启动失败

建议排查：

  1. 手动运行启动命令确认编辑器能正常启动
  2. 检查 AI 客户端是否加载了当前工作区的 .cursor/mcp.json
  3. 确认端口、传输方式与配置一致
  4. 回到当前项目的 docs/.editor-root，确认你填写的编辑器路径是否对应这份本地编辑器目录记录

编辑器启动了，但 MCP 没响应 ​

可能原因：

  • 地图尚未加载完成
  • 编辑器内 MCP 模块初始化失败
  • 端口已被占用，实际连接到了错误服务

建议排查：

  1. 查看编辑器日志
  2. 访问 http://localhost:<port>/ 检查状态页
  3. 确认 -map_path=... 指向的是正确工程目录
  4. 如果连编辑器路径本身都不确定，先检查当前项目里是否存在 docs/.editor-root；没有的话，先用编辑器打开一次项目

工具调用报错 ​

可能原因：

  • 传入的表、条目、路径或字段不存在
  • 参数格式与工具约定不匹配
  • 当前编辑器状态不支持该操作

建议排查：

  1. 先用 data_list_tables、data_list_entries、trigger_list_files 探路
  2. 再调用 data_get_*、trigger_get_* 查看详情
  3. 对修改型操作，确保最后调用 data_save 或 trigger_save

推荐阅读 ​