内容
# unity-asset-reference-mcp
[](https://github.com/JVinceW/uasset-reference-memory-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/unity-asset-reference-mcp)
将 **Unity** 项目的资源索引到可重用的 **SQLite 参考图** 中，然后通过三种方式查询：**CLI**、**MCP 服务器**（适用于 Claude 等代理）和本地 **Web 查看器**。仅限 Unity。
- **影响分析** — 在更改材质之前，“哪些引用了此材质？”
- **未使用资产检测** — 检测没有被加载的孤立资产（支持 Addressables）
- **依赖关系跟踪** — 场景/预制体所引用的完整闭包
- **损坏引用检测** — 对已删除/丢失资产的引用
- **可重用制品** — 一个可以由任何工具打开的纯 `.sqlite` 文件；无锁定
它读取 Unity 自己的序列化（`.meta` GUID + YAML `{fileID, guid}` 引用），
因此图是精确的 — 无启发式，无 AST。需要 **资产序列化：强制文本**（Unity 对版本控制的默认设置）。
## 要求
- Node.js ≥ 20
- 使用 **强制文本** 序列化的 Unity 项目
- `better-sqlite3` 通过安装时预构建的二进制文件构建（原生模块）
## 安装
```bash
npm install -g unity-asset-reference-mcp
```
这会在您的 `PATH` 中添加三个命令：
| 命令 | 说明 |
| --- | --- |
| `unity-asset-reference-mcp-index` | CLI 索引器 |
| `unity-asset-reference-mcp` | MCP 服务器 |
| `unity-asset-reference-mcp-web` | Web 查看器 |
**无需全局安装（npx）：** MCP 服务器的二进制名称与包名匹配，
因此 `npx -y unity-asset-reference-mcp …` 直接起作用。对于其他两个二进制文件，
使用 `-p` 指定包名：
```bash
npx -y unity-asset-reference-mcp --project /path/to/UnityProject # MCP 服务器
npx -y -p unity-asset-reference-mcp unity-asset-reference-mcp-index index /path # 索引器
npx -y -p unity-asset-reference-mcp unity-asset-reference-mcp-web --db <index.db> # 查看器
```
## 1. 索引项目
构建 `<project>/.asset-memory/index.db`。
```bash
unity-asset-reference-mcp-index index /path/to/UnityProject --force
```
将以下内容添加到您的 **Unity 项目** 的 `.gitignore` 中 — 忽略实时索引，但
提交配置和（可选的）共享快照：
```gitignore
# unity-asset-reference-mcp: 忽略实时索引，保持配置 + 共享快照
.asset-memory/index.db
.asset-memory/index.db-*
.asset-memory/*.building-*
.asset-memory/verify.json
.asset-memory/verify-report.json
```
## 2. 验证解析器准确性（可选）
验证是手动准确性检查。单独通过 Unity 包管理器安装 Unity 编辑器导出器，
保持 Node 工具和 Unity 集成可独立安装：
```text
https://github.com/JVinceW/uasset-reference-memory-mcp.git?path=/unity/com.jvincew.assetreferencememory#<release-tag>
```
在 Unity 中，运行 **工具 > 资产引用内存 > 导出验证**。它
写入 `<project>/.asset-memory/verify.json`。通过 CLI 将该导出与索引进行比较：
```bash
unity-asset-reference-mcp-index verify-index /path/to/UnityProject \
--verify /path/to/UnityProject/.asset-memory/verify.json
```
当找到差异时，命令成功退出。它打印一个有界的
摘要，并将每个遗漏/额外边写入
`<project>/.asset-memory/verify-report.json`。MCP 客户端使用
`verify_index(verifyJsonPath)` 并接收相同的摘要和报告
路径。
## 3. MCP 服务器（适用于任何 MCP 客户端）
这是一个标准的 **stdio MCP 服务器** — 它适用于任何 MCP 兼容的主机：
Claude Code/Desktop、Cursor、Windsurf、Cline、VS Code（Copilot 代理）、Zed 等。
没有任何特定于 Claude 的内容；只有配置的位置不同。
**通用配置**（Claude Desktop、Cursor、Windsurf、Cline 和大多数主机使用
此 `mcpServers` 形状）：
```json
{
"mcpServers": {
"unity-asset-graph": {
"command": "npx",
"args": ["-y", "unity-asset-reference-mcp", "--project", "/path/to/UnityProject"]
}
}
}
```
每个主机配置的位置：
| 主机 | 配置位置 |
| --- | --- |
| Claude Code | `claude mcp add unity-asset-graph -- npx -y unity-asset-reference-mcp --project /path/to/UnityProject` （或项目中的 `.mcp.json`） |
| Claude Desktop | `claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` （项目）或 `~/.cursor/mcp.json` （全局） |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Cline | `cline_mcp_settings.json` |
| VS Code（Copilot） | `.vscode/mcp.json` — 使用键 `servers` 代替 `mcpServers` |
**先决条件：** `PATH` 上有 Node ≥ 20（用于 `npx`），以及一个使用强制
文本序列化的 Unity 项目。您 **不需要** 预先索引 — 从代理调用 `index_project`
工具一次，它会构建 `<project>/.asset-memory/index.db`；读取工具在
直到您执行此操作之前返回一个明确的 `no-index` 错误。
**公开的工具：** `index_project`、`index_status`、`get_dependencies`、
`find_references`、`find_unused_assets`、`trace_path`、`search_assets`、
`get_overview`。
## 3. Web 查看器
```bash
# 服务器风格 — 提供查看器 + JSON API
unity-asset-reference-mcp-web --db /path/to/UnityProject/.asset-memory/index.db
# 打开 http://localhost:7777
```
还有一个 **静态** 风格：打开 `dist/web/public/viewer.html` 并在浏览器中选择一个 `.db` 文件
— 它在浏览器中运行相同的查询（WASM SQLite），无需服务器。两者共享一个查询层。
## 团队共享（快照）
与其让每个团队成员从头开始重新索引，不如提交一个 **压缩快照**，让他们恢复它
— 与 `codebase-memory` 的 `.codebase-memory/` 类似。
```bash
# 索引后，导出可共享的快照（或将 --snapshot 传递给 `index`）
unity-asset-reference-mcp-index snapshot /path/to/UnityProject
# -> .asset-memory/index.db.br （brotli，约 85% 更小）+ artifact.json + .gitattributes
# 克隆 + 拉取的团队成员在无需重新索引的情况下恢复实时索引：
unity-asset-reference-mcp-index restore /path/to/UnityProject
```
MCP 服务器和 Web 查看器 **自动从快照恢复**，如果缺少实时索引，
因此全新克隆 “直接有效”。**提交** 这些：
```
.asset-memory/config.json # 项目特定设置（如下）
.asset-memory/index.db.br # 压缩的共享索引
.asset-memory/artifact.json # 快照元数据（架构，提交，计数）
.asset-memory/.gitattributes # 标记 blob 二进制文件 + merge=ours
```
`artifact.json` 记录了 git 提交和快照构建的计数，
因此您可以知道何时它已过时并重新运行 `index --snapshot`。
## 配置
可选的项目特定 `.asset-memory/config.json`（参见
[docs/product/configuration.md](docs/product/configuration.md)）：
```json
{
"unused": { "addressableRoots": "auto" },
"scan": { "ignore": ["**/ThirdParty/**", "*.bak"], "ignoreDefaults": true }
}
```
- `unused.addressableRoots`（`auto`\|`on`\|`off`）— 将 Addressable 条目计为
未使用检测的根（查询时；`auto` = 如果项目使用 Addressables，则为 on）。可按调用覆盖。
- `scan.ignore` / `scan.ignoreDefaults` — 额外的忽略 glob（索引时）。
## SQLite 制品
使用任何 SQLite 工具打开 `.asset-memory/index.db`。核心表：`assets`
（节点），`edges`（引用），`unresolved_refs`（损坏的引用），
`addressable_entries`，`index_meta`。架构：
[docs/product/asset-graph-model.md](docs/product/asset-graph-model.md)。
## 已知限制
- **基于代码的引用未跟踪**：`Resources.Load("path")` 和 C# 中的硬编码
Addressable 地址字符串尚未被扫描，因此 `find_unused` 输出
是 *候选项* — 请对照加载代码进行验证。
- **资产级粒度**：边是资产→资产（不是每个 GameObject/fileID）。
- 增量重新索引按 mtime 进行；使用 `--force` 进行完全一致的重建。
## 开发
```bash
npm install
npm test # vitest
npm run build # tsc + 将 Web 资产复制到 dist/
```
此存储库还使用内部代理 **Harness** 进行开发过程（参见
[docs/HARNESS.md](docs/HARNESS.md)）；它不是已发布的包的一部分。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
