# cocos mpc server

**Repository Path**: lutery/cocos-mpc-server

## Basic Information

- **Project Name**: cocos mpc server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: feature/self
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cocos MCP Server（CreatorFramework Fork）

**[English](README.EN.md) | [中文](README.md)**

本仓库是 `DaxianLee/cocos-mcp-server` 的维护分支，当前文档已与代码状态对齐到 **v1.5.4**。

## 项目定位

- 面板技术栈：`Vue 3 + Element Plus + Vite`
- 后端构建：`tsc`
- 传输协议：`Streamable HTTP (MCP 2025-03-26)`
- MCP 对外工具：`59`（22 类，本期新增 8 个工具、9 个分类键，包含高风险写入与确认令牌流程）
- `sceneAdvanced`：已完全移除，不在工具暴露面

## 快速开始

```bash
cd extensions/cocos-mcp-server
npm install
npm run build
```

只构建面板：

```bash
npm run build:panel
```

只构建后端 TypeScript：

```bash
npm run build:ts
```

## MCP 连接地址

默认地址：

```text
http://127.0.0.1:3000/mcp
```

## AI 客户端配置概览

- 自动写入：`Cursor`、`Windsurf`、`Trea CN`、`Codex CLI`
- 手动命令：`Claude CLI`、`Gemini CLI`
- 面板能力：状态查询、配置片段生成、CLI 命令生成、单客户端/批量写入与移除、配置文件打开

主进程消息（文档可见接口）：

- `get-config-status`
- `generate-cli-commands`
- `generate-client-config`
- `add-to-client` / `remove-from-client`
- `add-to-all-clients` / `remove-from-all-clients`
- `open-config-file`
- `open-tool-manager`

## 工具能力概览（59）

| 类别 | 数量 | 备注 |
|---|---:|---|
| scene | 5 | `scene_query_system` 本期新增 `query_scene_bounds` / `query_component` / `query_is_native` |
| node | 8 | |
| component | 4 | |
| prefab | 4 | |
| project | 2 | |
| debug | 3 | |
| preferences | 3 | |
| server | 2 | |
| broadcast | 2 | |
| sceneView | 5 | |
| referenceImage | 4 | |
| assetAdvanced | 5 | |
| validation | 3 | |
| selection | 1 | 新增 `selection_manage`（节点/资源选区） |
| editor | 3 | 新增 `editor_dialog_manage` / `editor_utility_manage` / `editor_clipboard_manage` |
| engineProgram | 1 | 新增 `engineProgram_program_manage`（引擎/设备/URL/外部程序） |
| assetDiagnostics | 1 | 新增 `assetDiagnostics_asset_diagnostics`（缺失资源诊断） |
| projectConfig | 1 | 新增 `projectConfig_config_manage`（项目配置 dry-run + token） |
| extensionTemplate | 1 | 新增 `extensionTemplate_template_manage`（扩展模板 dry-run + token） |

调用命名规范：使用 `分类_工具名`（例如 `node_node_query`、`scene_scene_management`）。

### 本期新增工具典型调用

```jsonc
// 选区
{ "name": "selection_manage", "arguments": { "action": "select", "type": "node", "uuids": ["<uuid>"] } }
{ "name": "selection_manage", "arguments": { "action": "get_selected", "type": "node" } }

// 场景扩展查询
{ "name": "scene_scene_query_system", "arguments": { "action": "query_scene_bounds" } }
{ "name": "scene_scene_query_system", "arguments": { "action": "query_component", "uuid": "<componentUuid>" } }
{ "name": "scene_scene_query_system", "arguments": { "action": "query_is_native" } }

// 编辑器对话框（tag 必须以 ai. 前缀）
{ "name": "editor_dialog_manage", "arguments": { "action": "has_dialog", "tag": "ai.flow-test" } }

// 引擎与外部程序（open_url 仅放行 http/https；open_program 走白名单 + token）
{ "name": "engineProgram_program_manage", "arguments": { "action": "query_engine_info" } }
{ "name": "engineProgram_program_manage", "arguments": { "action": "open_url", "url": "https://docs.cocos.com" } }

// 资源缺失诊断
{ "name": "assetDiagnostics_asset_diagnostics", "arguments": { "urlOrPath": "db://assets/scene/main.scene" } }

// 项目配置（必须先 dry-run 拿 token 再 set）
{ "name": "projectConfig_config_manage", "arguments": { "action": "set_config_dry_run", "module": "general", "key": "inspector.refresh-frequency", "value": 200 } }
{ "name": "projectConfig_config_manage", "arguments": { "action": "set_config", "module": "general", "key": "inspector.refresh-frequency", "value": 200, "confirmationToken": "<token>" } }

// 剪贴板（写入需 token；返回体只回显 length，不回显 value）
{ "name": "editor_clipboard_manage", "arguments": { "action": "write", "type": "text", "value": "<text>" } }
{ "name": "editor_clipboard_manage", "arguments": { "action": "write", "type": "text", "value": "<text>", "confirmationToken": "<token>" } }
{ "name": "editor_clipboard_manage", "arguments": { "action": "read", "type": "text" } }

// 通用编辑器工具（只读直接返回；变更类需先 dry-run）
{ "name": "editor_utility_manage", "arguments": { "action": "get_language" } }
{ "name": "editor_utility_manage", "arguments": { "action": "query_ip_list" } }

// 扩展模板（dry-run 返回 token + targetPath + fileSummary，再 create_template 落盘）
{ "name": "extensionTemplate_template_manage", "arguments": { "action": "create_template_dry_run", "name": "mcp-depth-test", "templateId": "default", "templateType": "extension" } }
```

## 文档导航

- 安装说明（中文）：[INSTALL.md](INSTALL.md)
- Installation (English): [INSTALL.EN.md](INSTALL.EN.md)
- 功能指南（中文）：[FEATURE_GUIDE_CN.md](FEATURE_GUIDE_CN.md)
- Feature Guide (English): [FEATURE_GUIDE_EN.md](FEATURE_GUIDE_EN.md)

## 变更摘要（相对旧文档）

- 工具数量与分类已按当前实现重新对齐（50→59、13→22 类）。
- 删除已下线工具分类的对外暴露描述。
- 增加 AI 客户端配置能力说明。
- 保持当前仓库前端与构建事实（`Vue + Element Plus + Vite` + `tsc`）。

### v1.5.4 本期发布说明

**高风险操作确认令牌**

以下写入操作默认需要两步流程（先 dry-run 获取 confirmationToken，再携带 token 执行），防止 AI 客户端误操作：

| 工具 | 风险等级 | 操作 |
|------|---------|------|
| `editor_clipboard_manage` | medium | `write` |
| `editor_utility_manage` | medium~high | `clear_logs`, `set_config`/`set_project`/`set_temp`, `remove_*`, `enable`, `disable`, `enter` |
| `projectConfig_config_manage` | high | `set_config`（必须先 `set_config_dry_run`） |
| `extensionTemplate_template_manage` | high | `create_template`（必须先 `create_template_dry_run`） |
| `engineProgram_program_manage` | high | `open_program`（路径白名单校验 + token） |

令牌机制：
- 一次性 UUID，绑定 SHA-256(payload+timestamp)，5 分钟 TTL
- 返回体不泄露 payload 内容（剪贴板写入不回显 value，仅返回 `changed / type / length`）
- URL 操作仅放行 `http://` / `https://`；外部程序仅限白名单路径（项目根 / 系统 temp）

## 上游关系

- Upstream: `https://github.com/DaxianLee/cocos-mcp-server`
- 如与上游文档不一致，以本仓库代码与本文档为准。