# UnityTools-mcp

**Repository Path**: lithtech123_admin/unity-tools

## Basic Information

- **Project Name**: UnityTools-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-27
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Unity Tools MCP 服务器

这是一个基于 Go 语言开发的 MCP (Model Context Protocol) 服务器，专门用于查询和分析 Unity IL2CPP 导出的字符串字面量和脚本方法数据。该工具可以帮助开发者和逆向工程师快速查找和分析 Unity 游戏中的字符串和方法信息。

## 功能特性

- 📖 **字符串查询**: 通过名称查询字符串字面量
- 🔍 **批量查询**: 支持一次性查询多个字符串字面量
- 🔧 **方法查询**: 通过命名空间、类名、方法名查询脚本方法
- ⚡ **高性能**: 使用内存索引，快速查询
- 🔌 **MCP 协议**: 遵循 MCP 2024-11-05 协议标准

## 数据格式

### stringliteral.json
字符串字面量数组，每个对象包括：
```json
{
  "value": "字符串内容",
  "address": "内存地址",
  "name": "StringLiteral_X"
}
```

**示例数据：**
```json
[
  {
    "value": "Failed to merge ",
    "address": "0x4C11318",
    "name": "StringLiteral_1"
  },
  {
    "value": "XDG_DESKTOP_DIR",
    "address": "0x4C11320",
    "name": "StringLiteral_2"
  }
]
```

### script.json
脚本方法数组，每个对象包括：
```json
{
  "ScriptMethod": [
    {
      "Address": 6376208,
      "Name": "Namespace.ClassName$$MethodName",
      "Signature": "完整方法签名",
      "TypeSignature": "类型签名"
    }
  ]
}
```

**示例数据：**
```json
{
  "ScriptMethod": [
    {
      "Address": 6376208,
      "Name": "Microsoft.CodeAnalysis.EmbeddedAttribute$$.ctor",
      "Signature": "void Microsoft_CodeAnalysis_EmbeddedAttribute___ctor (Microsoft_CodeAnalysis_EmbeddedAttribute_o* __this, const MethodInfo* method);",
      "TypeSignature": "vii"
    },
    {
      "Address": 8424800,
      "Name": "System.Collections.Generic.List`1$$Add",
      "Signature": "void System_Collections_Generic_List_1_Add (System_Collections_Generic_List_1_o* __this, T item);",
      "TypeSignature": "vii"
    }
  ]
}
```

**数据说明：**
- `Address`: 方法在内存中的地址（十进制）
- `Name`: 完整方法名，格式为 `命名空间.类名$$方法名`
- `Signature`: 完整的方法签名，包含参数类型和返回类型
- `TypeSignature`: 类型签名，用于快速类型识别

## 安装和运行

### 构建

```bash
# 构建可执行文件
go build -o UnityTools-mcp.exe main.go

# 或者直接运行
go run main.go
```

### 运行

```bash
# 使用默认文件名 stringliteral.json 和 script.json
UnityTools-mcp.exe

# 指定字符串字面量文件路径
UnityTools-mcp.exe path/to/stringliteral.json

# 指定两个文件的路径
UnityTools-mcp.exe path/to/stringliteral.json path/to/script.json
```

## 配置 MCP 客户端

### 在 Claude Desktop 中使用

在 `claude_desktop_config.json` 中添加配置：

```json
{
  "mcpServers": {
    "unitytools": {
      "command": "D:\\work\\UnityTools-mcp\\UnityTools-mcp.exe",
      "args": [
        "D:\\work\\UnityTools-mcp\\Data\\stringliteral.json",
        "D:\\work\\UnityTools-mcp\\Data\\script.json"
      ]
    }
  }
}
```

配置文件位置：
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

### 在 Cursor 中使用

在 Cursor 的 MCP 设置中添加：

```json
{
  "mcpServers": {
    "unitytools": {
      "command": "D:\\work\\UnityTools-mcp\\UnityTools-mcp.exe",
      "args": [
        "D:\\work\\UnityTools-mcp\\Data\\stringliteral.json",
        "D:\\work\\UnityTools-mcp\\Data\\script.json"
      ]
    }
  }
}
```

## 可用工具

### 1. query_string_literal

查询单个字符串字面量。

**参数:**
- `name` (string): 字符串字面量的名称，例如 "StringLiteral_1"

**示例:**
```
查询 StringLiteral_1
```

### 2. query_string_literals_batch

批量查询多个字符串字面量。

**参数:**
- `names` (array): 字符串字面量名称数组

**示例:**
```
批量查询 StringLiteral_1, StringLiteral_2, StringLiteral_3
```

### 3. query_script_method

通过关键字搜索脚本方法，返回方法名包含所有指定关键字的方法。

**参数:**
- `keywords` (array): 关键字数组，方法名必须包含所有关键字才会被返回

**返回:**
返回所有匹配方法的完整信息，包括：
- 完整名称 (Name)
- 地址 (Address)
- 方法签名 (Signature) - 包含所有参数类型
- 类型签名 (TypeSignature)

**示例:**
```
搜索包含 OOI、CoroutineHelper、_waitForSeconds 的方法
查询包含 GameObject 和 AddComponent 的方法
```

**注意:**
- 如果匹配结果超过 50 个，将只显示前 50 个
- 关键字区分大小写

## AI 使用示例

连接 MCP 后，您可以直接询问 AI：

1. **字符串查询**:
   - "查询 StringLiteral_100 的值"
   - "StringLiteral_1 是什么内容？"
   - "批量查询 StringLiteral_1 到 StringLiteral_10"

2. **方法查询**:
   - "搜索包含 OOI、CoroutineHelper、_waitForSeconds 的方法"
   - "查找包含 GameObject 和 AddComponent 的方法"
   - "搜索名字中有 NotifyCollectionChanged 和 Invoke 的方法"

## 技术说明

### MCP 协议实现

服务器实现了以下 MCP 方法：
- `initialize`: 初始化连接
- `tools/list`: 列出可用工具
- `tools/call`: 调用工具执行查询

### 通信方式

使用 JSON-RPC 2.0 over stdio 进行通信：
- 输入 (stdin): 接收 JSON-RPC 请求
- 输出 (stdout): 返回 JSON-RPC 响应
- 日志 (stderr): 输出日志信息

## 开发

### 项目结构

```
UnityTools-mcp/
├── main.go                           # MCP 服务器主程序
├── go.mod                            # Go 模块配置
├── README.md                         # 说明文档
├── claude_desktop_config.example.json # Claude Desktop 配置示例
└── Data/                             # 数据文件目录
    ├── stringliteral.json            # 字符串字面量数据
    └── script.json                   # 脚本方法数据
```

### 主要组件

- **数据结构**:
  - `StringLiteral`: 字符串字面量数据结构，包含 value、address、name
  - `ScriptMethod`: 脚本方法数据结构，包含 Address、Name、Signature、TypeSignature
  - `ParsedMethod`: 解析后的方法信息，包含命名空间、类名、方法名

- **服务类**:
  - `StringLiteralService`: 字符串字面量数据加载和查询服务，提供单查和批量查询功能
  - `ScriptMethodService`: 脚本方法数据加载和查询服务，支持精确查询和多关键字搜索
  - `MCPServer`: MCP 协议处理服务器，处理所有 MCP 请求和响应

- **核心功能**:
  - 数据加载与索引构建（使用 map 索引提升查询性能）
  - 字符串字面量查询（单条和批量）
  - 方法精确查询和多关键字模糊搜索
  - MCP 协议通信处理

## 故障排查

### 服务器无法启动
- 检查 `stringliteral.json` 文件是否存在
- 确认 JSON 文件格式正确
- 查看 stderr 输出的错误日志

### 查询无结果
- 确认使用正确的字符串字面量名称（区分大小写）
- 检查数据文件是否正确加载

### MCP 连接失败
- 验证配置文件路径是否正确
- 确认可执行文件路径使用绝对路径
- 重启 AI 客户端（Claude Desktop / Cursor）

## 许可证

MIT License

## 作者

由 AI 助手创建，用于 Unity 工具开发。