Unity Skilled MCP - Skill + MCP 渐进式发现

渐进式发现

目录 → 参数 → 执行，三步完成一次调用

1. 选目标

GET /groups — 有哪些标签组，各含多少项 GET /tools · /prompts · /resources — 名称与短说明

↓

2. 取参数

                            GET /tools/{name}/schema — 单个工具完整 Schema
                            POST /capabilities/schemas — 一次多个工具 Schema
                            POST /capabilities/details — 一组详情
                        

↓

3. 执行

POST /mcp — tools/call prompts/get · resources/read 保持原样

目录不带参数

描述压缩空白并截断到约 160 字符，工具目录同时给出标签，便于先筛选后读取

详情按需且有限

单次去重成员数不超过 max_details（默认 32，0 表示不限），响应硬上限 65536 字节

批量 Schema

一次 POST 取回多个工具定义，按请求顺序返回，可直接按 inputSchema 调用

禁止一次拉全量

覆盖全部可用能力的选择会被拒绝：请改用标签组或明确的动态成员，单项始终允许

错误语义清晰

参数错误 400、成员未知或已禁用 404、响应过大 413，均返回结构化 JSON，不静默截断

🔎 发现与详情接口

1. 连接与目录

GET /discovery - 连接元数据、脚本语言、数量上限

GET /groups - 标签组及工具/提示词/资源计数

GET /tools - 工具名称、短说明、标签

GET /prompts - 提示词目录

GET /resources - 资源目录（uri、名称、mimeType）

2. 详情

GET /tools/{name}/schema

POST /capabilities/schemas - 一次多个工具 Schema

POST /capabilities/details

// 方式一：批量取工具 Schema，按请求顺序返回
{ "tools": ["hierarchy_search", "hierarchy_apply"] }

// 方式二：固定标签组
{ "tag": "hierarchy-management" }

// 方式三：本次动态成员，可混合三类
{
  "members": [
    { "kind": "tool", "name": "hierarchy_search" },
    { "kind": "prompt", "name": "实际提示词名" },
    { "kind": "resource", "uri": "file://path/to/resource.yaml" }
  ]
}

3. 命名空间别名

/mcp/tools - 与 /tools 等价

/mcp/capabilities/schemas - 与 /capabilities/schemas 等价

/mcp/capabilities/details - 与 /capabilities/details 等价

🧾 MCP 协议接口（兼容保留）

1. 仍然完全可用

tools/list · tools/call

prompts/list · prompts/get

resources/list · resources/read

既有 MCP 客户端无需任何改动；技能链路只是额外提供了一套更省上下文的入口。

2. 调用示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hierarchy_search",
    "arguments": { "pattern": "Player" }
  }
}

3. 连接信息不含 MCP 地址

INI 与 /discovery 只发布 base_url、port 与各发现接口地址，不发布 /mcp 端点，避免 Agent 绕过技能直接拼协议地址。

轻量技能模块

一份 SKILL.md + 一个无依赖客户端，即可接入任意 Agent

技能目录位于 unity-package/Skills/unity-skilled-mcp/，只说明「服务怎么连、先取什么、再取什么、参数怎么传」，不枚举任何工具的参数；工具参数始终按需从服务端读取，替代过去一次性灌入全部 Schema 的做法。

安装方式

一键提示词：Unity 菜单 Window/MCP/Status → 点击「复制技能安装提示词」，把剪贴板内容粘贴到任意 Agent，即可按提示完成安装。
技能路径自动解析：窗口按技能目录 .meta 的 GUID 反向查找真实磁盘路径，无论是工程内、嵌入式包还是 PackageCache 中的包都能定位。
手动安装：把整个 unity-skilled-mcp 文件夹复制到目标 Agent 的 skills 目录（如 ~/.workbuddy/skills/），目录名保持不变。

文件结构与运行方式

SKILL.md：唯一入口说明，只写连接、发现、调用与安全边界，不内联具体工具能力。
scripts/unity_bridge.js 与 scripts/unity_bridge.py：两个等价客户端（Node.js 18+ / Python 3.8+），只用标准库，子命令、选项、退出码与函数名一致。
工具名、参数与可用性必须由 discover → list / find → schema 现场发现；文档中的名字不代表当前服务存在。
INI 不再发布 script_language，Unity 端也没有脚本语言选项。

客户端命令

# 1. 核对连接（读 INI，再验证 /discovery）
node scripts/unity_bridge.js discover

# 2. 先看有哪些组和目录
node scripts/unity_bridge.js groups
node scripts/unity_bridge.js list --kind tools

# 3. 取参数：按标签组，或本次动态成员（名称来自目录）
node scripts/unity_bridge.js details --tag TAG_FROM_GROUPS
node scripts/unity_bridge.js details --members-file selection.json

# 4. 取工具 Schema（单个或批量）后调用
node scripts/unity_bridge.js schema NAME_FROM_LIST
node scripts/unity_bridge.js schemas NAME1 NAME2
node scripts/unity_bridge.js call NAME_FROM_LIST --args-file args.json

# 5. 目录检索与正文读取，多步访问由库 API 编排
node scripts/unity_bridge.js find QUERY --kind tools
node scripts/unity_bridge.js prompt NAME
node scripts/unity_bridge.js resource URI

# 6. 文档不预设能力：任何工具都先发现、再取定义
node scripts/unity_bridge.js list --kind tools
node scripts/unity_bridge.js schemas NAME1 NAME2

检索与正文读取

find QUERY：只取一次目录摘要，在本地按名称 / URI / 说明 / 标签做大小写不敏感过滤，工具再多也不必灌入整份目录；不取详情、不读正文。
prompt NAME / resource URI：详情接口只给注册定义，这两条命令先校验名称或 URI 在目录中，再走 prompts/get / resources/read 取正文。资源 URI 必须是已注册项，禁止借服务端对任意 http://、file:// 的兼容读取绕过外发授权。
多步访问由调用方以库 API 编排：每步先取 schema 再 call，技能不提供批量调用接口；循环次序、遇错是否继续与重放范围皆由代码决定。每次调用仍独立校验 INI 与 discovery。

作为代码库调用（程序化访问）

脚本既是 CLI 也是零依赖 CommonJS 库。require 后可用原生对象直接调用，让 AI 自己写代码组织多步访问；库函数复用 CLI 的全部校验与安全边界。

// Node.js 18+（CommonJS）；先从目录与 schema 决定工具
const unity = require('./scripts/unity_bridge.js');
unity.configure({ timeout: 15 });
const catalog = await unity.listCapabilities('tools');
const { name, args } = pickFrom(catalog, await unity.getSchema(name));
const summary = await unity.workflowContext('TASK', 'DESCRIPTION', async function (wf) {
  await unity.callSkill(name, args);
  return wf.summary();
});

call_skill / callSkill 返回 MCP result；call_tool / callTool 返回完整 JSON-RPC 信封；*_text / *_json 提取并解析 content[*].text。
workflowContext 只记录调用与耗时（wf.calls / wf.summary()），不重试、不回滚；失败照常抛出。工具名与参数须来自 find / list 与 schema，示例不含任何真实工具名。
多连接用 new Client({...})；所有方法均为 async，异常为带 .code 的 ClientError；库模式默认静默 stderr。
Windows Git Bash 把 request /ROUTE 转成本地路径的问题已修复：客户端按 EXEPATH 自动还原，也支持裸路由 request groups。

发现优先，不预设能力

SKILL.md 只写连接、发现、取定义、调用与安全边界，不描述任何具体工具、动作或参数。
当前服务注册了哪些工具，取决于 Unity 版本、工程、已安装包与启动设置；文档或旧会话里出现过的名字不代表它现在可用。
固定顺序：discover → groups / list / find → details / schema / schemas → call。
参数语义只以该工具本次 schema 为准；返回未启用、未安装或未知时如实告知并停止，不换名猜、不重试、不用 request 绕过。
INI 不发布 MCP 端点；客户端固定为 scripts/unity_bridge.js（Node.js 18+），不再有脚本语言选项。

连接信息（服务启动时发布）

# ~/.unity-mcp/skill.ini
[project:YourUnityProject]
base_url=http://localhost:8000
port=8000
project_path=E:/YourUnityProject
unity_version=2021.3.45f2c1
render_pipeline=Built-in
process_id=12345
started_at=2026-10-30T02:00:00.0000000Z
updated_at=2026-10-30T02:00:00.0000000Z
max_details=32

[project:AnotherProject]
base_url=http://localhost:8001
port=8001
project_path=E:/AnotherProject
project_name=AnotherProject
instance_id=8c2b71e0-...
unity_version=2021.3.45f2c1
render_pipeline=URP
process_id=23456
started_at=2026-10-30T03:00:00.0000000Z
updated_at=2026-10-30T03:00:00.0000000Z
max_details=32

每个端只写自己的 [project:工程名] 节，不再发布 [unity3d-skilled-mcp] 兼容节；started_at 是该端服务启动时刻，值最大者即最新启动的端。启动或改端口重启都会重写本端节，其它在线端的节保持不变。unity_version 与 render_pipeline 是启动时捕获的 Unity 版本与生效渲染管线（Built-in / URP / HDRP / 自定义类型全名）。客户端每次命令都重新读取，不扫描端口，也不自动重试写操作。

实际应用示例

通过自然语言指令完成复杂的 Unity 开发任务；示例中的工具名仅为演示，实际以发现结果为准

🔧

智能问题修复

"修复控制台中的所有警告和报错"

AI 自动分析控制台日志，识别问题类型，提供修复建议并执行修复操作

console.get code.execute

🎨

程序化网格生成

"创建一个 60 顶点的圆形雨伞网格，保存到 Meshes 目录"

使用 Python 脚本生成复杂 3D 网格，自动导入 Unity 并保存为资源文件

python.execute mesh.get_info

📦

自动化插件管理

"安装 android-logcat 插件到 Unity"

通过 Package Manager 自动搜索、下载并安装 Unity 插件包，无需手动操作

package.add_registry http.get

📊

代码架构可视化

"分析 Scripts 目录下的代码，用 Matplotlib 绘制架构图"

扫描项目代码结构，分析类依赖关系，生成专业的 UML 架构图

project.find_asset python.execute

🏠

智能场景布置

"基于 Prefabs 下的美术资源及文档，在场景中布置一个房间"

AI 理解资源说明文档，自动选择合适的预制体，按照设计规范摆放场景物体

project.find_prefab hierarchy.create_cube gameobject.modify

🎯

规则驱动 UI 构建

"使用规则文件，在场景中构建 UGUI 界面"

根据 JSON/YAML 规则文件自动创建 UI 层级结构，设置布局和样式

ui_rule.record_modify ugui.do_layout

🖼️

自动图集生成

"将 LoginView 界面引用的图片打包为 LoginViewAtlas"

自动收集 UI 引用的所有 Sprite，创建 Sprite Atlas 并优化纹理打包

hierarchy_search edit_sprite_atlas

🔍

按需探查能力

"看看场景相关都有哪些工具，把参数给我"

先取 groups 与目录定位标签，再一次性取该组完整定义，避免逐个试错

groups details --tag

📦

一键构建出包

"切到 Windows 平台，用开发配置构建到 Builds/Windows"

先确认构建设景，再切换平台并排队构建，最后轮询构建状态与错误数

engine_control get_build_status

🎞️

搭一套移动状态机

"给角色做一个 Idle→Run 的状态机，按 Speed 切过去"

建控制器、加参数与状态、连线过渡条件，播放时直接切状态验证

edit_animator edit_anim_clip

🖥️

UI Toolkit 界面落地

"做一个主菜单 UXML，标题文字改成中文并接上 PanelSettings"

生成 UXML/USS，改元素属性，再给场景对象挂 UIDocument 并截图确认

ui_toolkit manage_camera

🧪

改完就跑测试

"跑一遍 EditMode 里 Fast 类别的测试，把失败项列出来"

启动测试任务后轮询状态，读取通过/失败计数与失败用例清单

run_tests get_status

Resources & Prompts 支持

目录看摘要，详情按组取，正文由 prompt / resource 命令显式读取

📦

Resources 资源系统

实现 IRes 即可注册资源；目录接口只返回 uri、名称与 mimeType，详情返回注册定义，不隐式读取正文

文件访问配置管理按组取详情

💬

Prompts 提示词系统

实现 IPrompts 注册模板；目录给出名称与短说明，需要参数时按名称或标签组取完整定义

模板化参数化可扩展

🔧 Resources 配置方法

1. 实现 IRes 接口

public class ProjectTreeRes : IRes
{
    public string Url => "file://path/to/resource.yaml";
    public string Name => "project_tree";
    public string Description => "工程文件夹树型结构";
    public string MimeType => "application/yaml";
}

2. 支持的 URI 方案

file:// - 本地文件访问

http:// - HTTP 资源访问

mcp:// - MCP 自定义协议

data: - 内联数据

3. 使用方式

// 目录：只看摘要
GET /resources

// 详情：按标签组或指定 URI
POST /capabilities/details
{ "members": [{ "kind": "resource", "uri": "file://path/to/resource.yaml" }] }

// 读取正文：沿用原协议
{ "method": "resources/read", "params": { "uri": "file://path/to/resource.yaml" } }

// 技能命令：先校验目录，再读取正文
node scripts/unity_bridge.js resource file://path/to/resource.yaml

💡 Prompts 配置方法

1. 实现 IPrompts 接口

public class TestTalkStepPrompts : IPrompts
{
    public string Name => "test_talk_step";
    public string Description => "测试对话步骤";
    public string PromptText => "请描述一个对话步骤的内容，包括角色的台词和情感。";
    public MethodKey[] Keys => new MethodKey[]
    {
        new MethodKey("step", "对话步骤", false)
        .AddExample("角色A：你好，我是A。角色B：你好，我是B。")
    };
}

2. 参数配置

Name - 提示词唯一标识符

Description - 功能描述（目录中的短说明）

PromptText - 实际提示词内容

Keys - 参数定义和示例

3. 使用方式

// 目录
GET /prompts

// 调用：沿用原协议
{ "method": "prompts/get", "params": { "name": "test_talk_step" } }

// 技能命令：先校验目录，再取模板正文
node scripts/unity_bridge.js prompt test_talk_step

Unity Skilled MCP Skill 与 MCP 结合的 Unity 工作流

核心特性

渐进式发现

端口自动发现

按组取详情

上下文可控

原协议零改动

单一 JS 客户端

文档只写契约

批量 Schema

按需取定义

轻量上下文

程序化调用

启动配置可管

系统架构

职责分离

主线程安全

单一端口

自动纳入新工具

渐进式发现

目录不带参数

详情按需且有限

批量 Schema

禁止一次拉全量

错误语义清晰

🔎 发现与详情接口

1. 连接与目录

2. 详情

3. 命名空间别名

🧾 MCP 协议接口（兼容保留）

1. 仍然完全可用

2. 调用示例

3. 连接信息不含 MCP 地址

轻量技能模块

安装方式

文件结构与运行方式

客户端命令

检索与正文读取

作为代码库调用（程序化访问）

发现优先，不预设能力

连接信息（服务启动时发布）

实际应用示例

智能问题修复

程序化网格生成

自动化插件管理

代码架构可视化

智能场景布置

规则驱动 UI 构建

自动图集生成

按需探查能力

一键构建出包

搭一套移动状态机

UI Toolkit 界面落地

改完就跑测试

扩展应用场景

AI 图片生成

批量爬取资源

架构图生成

性能分析

测试数据生成

本地化翻译

快速开始

导入 Unity Package

启动 MCP 服务

安装技能 / 接入 MCP

开始使用

Resources & Prompts 支持

Resources 资源系统

Prompts 提示词系统

🔧 Resources 配置方法

1. 实现 IRes 接口

2. 支持的 URI 方案

3. 使用方式

💡 Prompts 配置方法

1. 实现 IPrompts 接口

2. 参数配置

3. 使用方式

工具生态

场景层级 scene

资源资产 assets

Unity Skilled MCP
Skill 与 MCP 结合的 Unity 工作流