Cursor rule

1---
2description: "MCP 工具设计原则和完整工具清单"
3---
4 
5# MCP 工具设计指南
6 
7## 设计原则
8 
9**最小信息熵，最大能力覆盖。**
10 
111. 用最少的工具达成最完整的能力
122. 统一接口优于分散工具
133. 参数最小化：删除冗余参数，合并语义相同的参数
144. 返回结构化数据，包含足够上下文
155. 错误信息友好，帮助用户定位问题
16 
17## 工具清单（v0.4.0，共 11 个）
18 
19### 分析工具（8 个）
20 
21| 工具 | 参数 | 用途 |
22|------|------|------|
23| `search` | `query`, `domain`, `scope`, `type_filter`, `max_results` | 统一搜索 C++/Blueprint/Asset |
24| `get_hierarchy` | `name`, `domain`, `scope` | 获取继承层次 |
25| `get_references` | `path`, `domain`, `scope`, `direction` | 获取引用关系 |
26| `get_details` | `path`, `domain`, `scope` | 获取详细信息 |
27| `get_blueprint_graph` | `bp_path`, `graph_name`, `format` | 蓝图节点图（Mermaid/摘要/JSON） |
28| `detect_ue_patterns` | `file_path`, `format` | UE 宏检测（详细/摘要） |
29| `trace_reference_chain` | `start_asset`, `max_depth`, `direction` | 跨域引用链追踪 |
30| `find_cpp_class_usage` | `cpp_class`, `scope`, `max_results` | C++ 类使用查找 |
31 
32### 技能工具（3 个，v0.4.0 新增）
33 
34| 工具 | 参数 | 用途 |
35|------|------|------|
36| `list_unreal_skill` | `query?`, `include_hidden?` | 列出可用技能 |
37| `read_unreal_skill` | `skill_name`, `path?` | 读取技能文档/脚本 |
38| `run_unreal_skill` | `skill_name?`, `script?`, `args?`, `python?` | 执行技能脚本或内联 Python |
39 
40## 参数设计原则
41 
42### 已统一的参数命名
43 
44| 参数 | 可选值 | 说明 |
45|------|--------|------|
46| `domain` | `cpp`, `blueprint`, `asset`, `all` | 搜索/操作域 |
47| `scope` | `project`, `engine`, `plugin`, `all` | 搜索范围（含插件支持） |
48| `direction` | `outgoing`, `incoming`, `both` | 引用方向（统一命名） |
49| `format` | `mermaid`, `summary`, `json` / `detailed`, `summary` | 输出格式 |
50| `type_filter` | 字符串 | 类型过滤（合并了 asset_type 和 class_filter） |
51 
52### Scope 语义
53 
54| Scope | C++ 范围 | Blueprint/Asset 范围 |
55|-------|----------|---------------------|
56| `project` | Source/ + Plugins/*/Source/ | /Game/ + 插件资产 |
57| `engine` | Engine/Source/ + Engine/Plugins/ | /Engine/ + /Script/ |
58| `plugin` | 所有 Plugins/*/Source/ | 只有插件资产（非 /Game/、/Engine/、/Script/） |
59| `all` | 全部 | 全部 |
60 
61### 已删除的冗余参数
62 
63- `domains` → 合并到 `domain`（单值即可）
64- `asset_type` + `class_filter` → 合并为 `type_filter`
65- `include_comments` → 内部默认 `true`
66- `query_mode` → 内部默认 `smart`
67- `file_pattern` → 内部默认 `*.{h,cpp}`
68- `include_interfaces` → 内部默认 `true`
69- `include_cpp` → 内部默认 `true`
70- `aggregate_results` → 内部默认 `true`
71 
72## Skill 技能系统
73 
74### 设计理念
75 
76Skill 是可发现、有文档、可执行的编辑器能力：
77- **可发现**：`list_unreal_skill` 返回技能列表（name, description, tags）
78- **有文档**：`read_unreal_skill` 返回 SKILL.md + 目录树
79- **可执行**：`run_unreal_skill` 执行脚本或内联 Python
80 
81### 技能包结构
82 
83```
84skills/<skill_name>/
85├── SKILL.md              # 技能说明（YAML 题头 + Markdown）
86├── scripts/              # 可执行脚本
87│   └── *.py
88└── docs/                 # 详细文档（可选）
89    └── *.md
90```
91 
92### 执行模式
93 
941. **脚本模式**：`skill_name` + `script` → 执行 `skills/<skill_name>/scripts/<script>`
952. **内联模式**：`python` → 直接执行内联代码
96 
97### CppSkillApiSubsystem 原语
98 
99| 分类 | 操作 |
100|------|------|
101| **Asset** | RenameAsset, DuplicateAsset, DeleteAsset, SaveAsset |
102| **Blueprint** | CreateBlueprint, CompileBlueprint, SaveBlueprint, SetBlueprintCDOPropertyByString, AddBlueprintComponent, RemoveBlueprintComponent |
103| **World** | LoadMap, SpawnActorByClassPath, FindActorByName, DestroyActorByName, SetActorPropertyByString, SetActorTransformByName |
104| **Editor** | ListDirtyPackages, SaveDirtyPackages, UndoLastTransaction, RedoLastTransaction |
105| **Validation** | CompileAllBlueprintsSummary |
106 
107## 典型调用流程
108 
109### 场景：分析 GAS Ability
110 
111```python
112# 1. 搜索蓝图
113await search(query="GA_Hero_Dash", domain="blueprint")
114 
115# 2. 获取继承层次
116await get_hierarchy(name="/Game/.../GA_Hero_Dash", domain="blueprint")
117 
118# 3. 获取依赖
119await get_references(path="/Game/.../GA_Hero_Dash", direction="outgoing")
120 
121# 4. 获取节点图（Mermaid 格式）
122await get_blueprint_graph(bp_path="/Game/.../GA_Hero_Dash")
123```
124 
125### 场景：追踪资产引用
126 
127```python
128# 1. 搜索资产
129await search(query="SK_Mannequin", domain="asset")
130 
131# 2. 深度追踪（包含软引用）
132await trace_reference_chain(start_asset="/Game/.../SK_Mannequin", max_depth=3)
133```
134 
135### 场景：使用 Skill 批量操作
136 
137```python
138# 1. 发现可用技能
139await list_unreal_skill(query="asset")
140 
141# 2. 阅读技能文档
142await read_unreal_skill(skill_name="cpp_asset_api")
143 
144# 3. 阅读详细 API
145await read_unreal_skill(skill_name="cpp_asset_api", path="docs/overview.md")
146 
147# 4. 执行内联 Python
148await run_unreal_skill(python="""
149import unreal
150api = unreal.get_editor_subsystem(unreal.CppSkillApiSubsystem)
151success, error = api.rename_asset("/Game/Old", "/Game/New")
152RESULT = {"success": success, "error": error}
153""")
154```
155 
156## HTTP API（UE 插件）
157 
158```
159GET /health                           → 健康检查
160GET /blueprint/graph?bp_path=...      → 蓝图节点图
161GET /blueprint/soft-references?...    → 蓝图软引用（CDO 变量默认值）
162GET /analysis/reference-chain?...     → 引用链追踪（含软引用）
163GET /analysis/cpp-class-usage?...     → C++ 类使用
164GET /analysis/job/status?id=...       → 异步任务状态
165GET /analysis/job/result?id=...       → 异步任务结果
166```
167 
168## 版本变更
169 
170| 版本 | 工具数 | 变化 |
171|------|--------|------|
172| v0.2.0 | 22 | 原始工具 + unified |
173| v0.3.0 | 9 | 精简：unified + 必要特殊工具 |
174| v0.3.1 | 8 | 进一步精简：合并 detect_ue_patterns + get_cpp_blueprint_exposure |
175| v0.4.0 | 11 | 新增 Skill 工具：list/read/run_unreal_skill |
176 
177### v0.4.0 新增
178 
179- `list_unreal_skill`: 发现可用技能
180- `read_unreal_skill`: 读取技能文档
181- `run_unreal_skill`: 执行技能脚本或内联 Python
182- `CppSkillApiSubsystem`: C++ 编辑器原语（Asset/Blueprint/World/Editor/Validation）
183- 事件驱动 MCP 生命周期管理
184