MCP

本页面为自动翻译，可能包含错误。如果发现问题，请通过“编辑此页面”链接帮助修正。

模型上下文协议（MCP） 集成让 Claude Code、Cursor 等 AI 助手能够实时检查和与正在运行的 Turian 游戏交互。LLM 无需猜测状态，即可查询实际的场景、实体、组件和性能指标。

工作原理

Claude Code / Cursor
      │  MCP（stdio，JSON-RPC 2.0）
      ▼
turian-cli mcp
      │ 远程调试协议（TCP，端口 7777）
      ▼
  正在运行的游戏（已启用调试服务器）

turian-cli mcp 桥接两种协议。它从 stdin 读取 MCP 请求，通过 TCP 转发到游戏的调试服务器，并返回结构化结果。

快速开始

1 — 在游戏中启用调试服务器

在游戏的入口点，在主循环之前启动调试服务器：

const debug = @import("debug");

var srv = debug.Server.init(allocator, .{});
defer srv.deinit(io);
try srv.start(io, .{ .ctx = &world, .getFn = myWorldProvider });

服务器默认监听 127.0.0.1:7777。

2 — 配置 MCP 客户端

Claude Code（~/.claude/mcp.json 或项目 .mcp.json）：

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp"]
    }
  }
}

带认证令牌（如果调试服务器使用 --token 启动）：

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp", "--token", "my-secret"]
    }
  }
}

自定义主机/端口：

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp", "--host", "192.168.1.10", "--port", "7778"]
    }
  }
}

3 — 启动游戏并提问

游戏运行且 Claude Code 连接后，您可以询问：

"当前加载了哪些场景？" "检查 Player 实体。" "当前 FPS 和内存使用率是多少？" "列出所有带有 Camera 组件的实体。"

可用工具

读取工具

工具 描述
list_scenes 所有当前已加载的场景及其状态
inspect_scene 场景中的每个实体及组件摘要
find_entities 按名称子串或组件类型筛选实体
scene_summary 为 LLM 方向定位提供的紧凑完整快照
inspect_entity 单个实体的 Transform 及所有组件字段
get_component 实体上特定组件的字段值
get_metrics FPS、帧时间、内存、绘制调用、ECS 计数
get_schema 所有内置组件类型的模式
list_assets 项目资源（guid、路径、类型）
inspect_material 按 GUID 检查单个资源
capture_profiler 最新的分析器帧（计数器 + 区域）
inspect_memory 分配器内存使用情况
list_errors 最近的引擎警告/错误

写入工具（读写服务器 + confirm: true）

工具 描述
modify_component 设置组件字段
set_transform 设置位置/旋转/缩放
spawn_entity 创建新实体
destroy_entity 移除实体
reload_asset 热重载资源

写入工具使用确认门控：首次调用返回预览；传入 confirm: true 以实际应用更改。

CLI 参考

turian-cli mcp [--host <addr>] [--port <n>] [--token <secret>]
标志 默认值 描述
--host 127.0.0.1 调试服务器主机名或 IP
--port 7777 调试服务器端口
--token （空） 认证令牌（必须与服务器的 --token 匹配）

turian-cli mcp 在 stdin 关闭时退出——MCP 客户端控制其生命周期。

协议详情

  • 传输：基于 stdio 的 JSON-RPC 2.0，换行分隔
  • MCP 版本：2024-11-05
  • 能力：tools（列表 + 调用）
  • 默认只读：除非调试服务器以读写模式启动，否则修改工具返回错误

相关文档

← 所有文档 编辑此页面